**English** | [한국어](README.ko.md)

# Repro Capsule MCP

[![CI](https://github.com/efficjump/repro-capsule-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/efficjump/repro-capsule-mcp/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-2ea44f.svg)](LICENSE)

Turn a bug report into a portable, reviewable reproduction capsule without silently copying a
repository or executing model-generated shell text. Every report, command plan, transcript, artifact,
and export stays evidence-linked and redacted.

```mermaid
flowchart LR
    A[Bug report] --> B[Dynamic project profile]
    B --> C[Evidence-based hypotheses]
    B --> D[Reviewed command plan]
    D --> E[One-time approval]
    E --> F[Bounded execution]
    C --> G[Portable capsule]
    F --> G
```

## Highlights

- Dynamic command discovery from current project manifests
- Secret-redacted reports, text artifacts, stdout, and stderr
- Binary artifacts represented by metadata and hashes instead of unreviewed content
- Direct argv execution without a shell
- One-time plan tokens with separate workspace-write and network approvals
- Process-group timeout cleanup and bounded output capture
- Run-to-run transcript comparison without guessing whether a fix is correct
- ZIP export containing a versioned manifest and reproduction guide
- Stdio and Streamable HTTP transports

## Install

```bash
uv tool install "git+https://github.com/efficjump/repro-capsule-mcp.git"
repro-capsule-mcp --transport stdio
```

For source development:

```bash
git clone https://github.com/efficjump/repro-capsule-mcp.git
cd repro-capsule-mcp
uv sync --all-extras --locked
uv run repro-capsule-mcp --transport stdio
```

## Generic MCP client configuration

```json
{
  "mcpServers": {
    "repro-capsule": {
      "command": "repro-capsule-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}
```

The installed command avoids embedding any local checkout path in client configuration.

## Tool workflow

| Tool | Purpose |
| --- | --- |
| `start_case` | Create a bounded case with a redacted bug report |
| `list_cases` / `get_case` | Browse persisted case state and evidence |
| `inspect_project` | Discover manifests, environment names, Git state, and commands |
| `analyze_case` | Produce host-model hypotheses from current evidence |
| `add_artifact` | Add reviewed text or hash-only binary evidence |
| `plan_command` | Prepare an exact non-shell command and one-time token |
| `execute_plan` | Run one approved plan with bounds and redaction |
| `compare_runs` | Compare two execution transcripts |
| `export_capsule` | Create a portable ZIP and manifest |

## Safety model

- Project roots must remain inside `REPRO_CAPSULE_ALLOWED_ROOTS`.
- Sensitive filenames, symlinks, oversized files, and unreviewed binary content are excluded.
- Commands not discovered from current project files are denied by default.
- Network intent and workspace-write intent require separate approval.
- Environment values and approval tokens are not written into capsule exports.
- Every process uses a timeout, bounded output, and redaction before persistence.

This server is not an operating-system sandbox. Inspect and execute untrusted projects only in an
isolated container or virtual machine.

## Streamable HTTP

```bash
repro-capsule-mcp --transport streamable-http --host 127.0.0.1 --port 8766
```

The default endpoint is `http://127.0.0.1:8766/mcp`.

## Development

```bash
uv sync --all-extras --locked
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest --cov --cov-report=term-missing
uv build
```

See [architecture](docs/architecture.md), [security policy](SECURITY.md), and
[contribution guide](CONTRIBUTING.md).

## License

[MIT](LICENSE)