Metadata-Version: 2.4
Name: repoctx-mcp
Version: 0.1.1
Summary: Local repository intelligence for coding agents
Author: Gal
License-Expression: MIT
Project-URL: Homepage, https://github.com/gald33/repoctx
Project-URL: Repository, https://github.com/gald33/repoctx
Project-URL: Issues, https://github.com/gald33/repoctx/issues
Keywords: developer-tools,repository-analysis,mcp,coding-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: mcp
Requires-Dist: mcp<1.7,>=1.6; extra == "mcp"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: mcp<1.7,>=1.6; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# RepoCtx

Local repository intelligence for coding agents.

## What It Does

`repoctx` inspects a local repository and returns a compact task context pack:

- relevant docs and agent guidance files
- relevant source files
- likely related tests
- nearby graph neighbors from local imports
- a readable markdown pack plus structured JSON

## Installation

Install the published package from PyPI:

```bash
python3 -m pip install repoctx-mcp
```

The installed CLI command remains `repoctx`.

Install MCP support from PyPI when you want to run the MCP server:

```bash
python3 -m pip install "repoctx-mcp[mcp]"
```

Install the package from the standalone repository root:

```bash
python3 -m pip install -e .
```

This installs the core CLI without MCP server support.

Install MCP support when you want to run the MCP server:

```bash
python3 -m pip install -e ".[mcp]"
```

Install development dependencies for tests, including the MCP-related test coverage:

```bash
python3 -m pip install -e ".[dev]"
```

## CLI

Run the CLI against any local repository by passing its path with `--repo`:

```bash
repoctx "add retry jitter to webhook delivery" --repo /path/to/target-repo --format markdown
```

The module entry point stays available too:

```bash
python3 -m repoctx "Sync local env with Vercel" --repo /path/to/target-repo --format json
```

## MCP Server

Install the MCP extra first, then start the MCP server and point it at the repository you want to inspect:

```bash
python3 -m pip install -e ".[mcp]"
python3 -m repoctx.mcp_server --repo /path/to/target-repo
```

The server exposes `get_task_context(task: string)`.

## Telemetry

`repoctx` writes local JSONL telemetry to `~/.repoctx/telemetry` by default. CLI and MCP usage record `repoctx_invocation` events automatically. The default telemetry payload stores hashed free-form task text and hashed repo identifiers. CLI runs can also preserve explicit experiment keys such as `session_id`, `task_id`, and `variant`; MCP runs currently generate those identifiers automatically.

Use the CLI flags below to keep paired experiments aligned across control and treatment runs:

```bash
repoctx "add retry jitter to webhook delivery" \
  --repo /path/to/target-repo \
  --format json \
  --session-id bench-001 \
  --task-id task-001 \
  --variant repoctx
```

External experiment harnesses can record downstream agent costs with the Python helper:

```python
from pathlib import Path

from repoctx.telemetry import record_agent_run

record_agent_run(
    session_id="bench-001",
    task_id="task-001",
    variant="control",
    surface="cli",
    query="add retry jitter to webhook delivery",
    repo_root=Path("/path/to/target-repo"),
    runner="cursor-agent",
    success=True,
    completion_status="completed",
    agent_duration_ms=18420,
    tool_calls=6,
    prompt_tokens=12450,
    completion_tokens=1730,
    total_tokens=14180,
    estimated_cost_usd=0.19,
    task_completed=True,
    quality_score=0.9,
)
```

Use the same `session_id` and `task_id` for both `control` and `repoctx` runs so you can compare token, cost, and latency deltas later.

## Tests

```bash
python3 -m pytest -q
```

## PyPI Publishing

This repository is set up to publish to PyPI from GitHub Actions using trusted publishing.

### One-Time PyPI Setup

In PyPI, add a trusted publisher with these values:

- project name: `repoctx-mcp`
- owner: `gald33`
- repository: `repoctx`
- workflow file: `publish-pypi.yml`

No PyPI API token needs to be stored in GitHub when trusted publishing is configured.

### Release Flow

1. Bump `version` in `pyproject.toml`.
2. Commit and push the version change to `main`.
3. Create and push a version tag that matches `project.version`, like `v0.1.1`.

```bash
git tag v0.1.1
git push origin v0.1.1
```

Pushing the tag triggers `.github/workflows/publish-pypi.yml`, which builds the sdist and wheel and publishes them to PyPI.
