pasr

<!-- mcp-name: io.github.Apheironn/pasr -->

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Apheironn/pasr/main/docs/assets/logo-dark.svg">
    <img alt="PASR — Provenance-Aware Span Recall" src="https://raw.githubusercontent.com/Apheironn/pasr/main/docs/assets/logo.svg" width="300">
  </picture>
</p>

<p align="center">
  <b>Provenance-Aware Span Recall</b> — local, token-budgeted,
  source-traceable context for coding agents.
</p>

[![PyPI](https://img.shields.io/pypi/v/pasr-mcp)](https://pypi.org/project/pasr-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/pasr-mcp)](https://pypi.org/project/pasr-mcp/)
[![CI](https://github.com/Apheironn/pasr/actions/workflows/ci.yml/badge.svg)](https://github.com/Apheironn/pasr/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/Apheironn/pasr/blob/main/LICENSE)

<p align="center"><img src="https://raw.githubusercontent.com/Apheironn/pasr/main/docs/assets/demo.svg" alt="Historical CLI source-selection example with file:line provenance; not an answer-quality comparison" width="820"></p>

## The problem

Agents need enough source to answer correctly, while every retrieved observation can
be carried into later model requests. Native grep and bounded file reads already
provide useful source and provenance. PASR must justify its additional retrieval,
selection, and tool-catalog complexity against that baseline—not against dumping
the entire repository.

## What PASR does

### Budgeted

Live `select_context` budgets the **returned context**, including labels, headings,
separators, and redaction—not the MCP JSON envelope or cumulative conversation.
Whole computed spans are admitted only when that final representation fits; spans
are not necessarily complete functions. Lossless selection uses the exact rendered
cost, and optional headers cannot displace source that already fits.

<p align="center"><img src="https://raw.githubusercontent.com/Apheironn/pasr/main/docs/assets/concept-budgeted.svg" width="760" alt="a budget bar: 2,718 tokens kept under a 3,000-token ceiling, 282 free"></p>

### Traceable

Selection receipts record each span's `file:line`, token count, retrieval signals,
and why it was kept or dropped. Receipts are saved under `.pasr/receipts`; persistence
is best-effort, and the response reports whether a receipt was written. They cover
PASR-delivered context, not everything an agent reads or does.

<p align="center"><img src="https://raw.githubusercontent.com/Apheironn/pasr/main/docs/assets/concept-traceable.svg" width="760" alt="anatomy of one returned span: where it is (file:line), what it costs (tokens), why it was kept (retrieval signals + score)"></p>

### Honest

Receipts expose heuristic query classifications, keyword coverage, and routing
advice. These are **not calibrated correctness probabilities or proof that all
necessary evidence was retrieved**. Advice must not replace checking the source.

<p align="center"><img src="https://raw.githubusercontent.com/Apheironn/pasr/main/docs/assets/concept-honest.svg" width="760" alt="Heuristic query routing and coverage scores, not correctness or completeness guarantees"></p>

### Local by default

No daemon, vector database, or manual index setup is required. Offline selection
needs installed dependencies and cached tokenizer data; optional model weights are
separate. The client can still forward returned source to a cloud model. Default
redaction is a no-op, not automatic secret detection.

## Install

**Install version 0.4.0 from [PyPI](https://pypi.org/project/pasr-mcp/0.4.0/).**
Install [`uv`](https://docs.astral.sh/uv/) and make `uvx` available on your PATH;
use Python **3.10+** or allow uv to provision it. No PASR checkout is required.
Replace `/absolute/path/to/project` with the repository to inspect, then choose
the command for your client:

```bash
claude mcp add pasr -- uvx --from pasr-mcp==0.4.0 pasr-mcp --workspace /absolute/path/to/project
codex mcp add pasr -- uvx --from pasr-mcp==0.4.0 pasr-mcp --workspace /absolute/path/to/project
```

Alternatively, merge this MCP configuration into your client's config. Update any
existing `pasr` entry rather than registering the same server twice:

```json
{ "mcpServers": { "pasr": { "command": "uvx", "args": ["--from", "pasr-mcp==0.4.0", "pasr-mcp", "--workspace", "/absolute/path/to/project"] } } }
```

For the separate [v0.4.0 GitHub release](https://github.com/Apheironn/pasr/releases/tag/v0.4.0)
wheel instead, use:

```bash
python -m pip install https://github.com/Apheironn/pasr/releases/download/v0.4.0/pasr_mcp-0.4.0-py3-none-any.whl
```

After installing that wheel, configure your client to run the installed `pasr-mcp`
executable with `--workspace /absolute/path/to/project` instead of the `uvx` launch.

**Developers only — source checkout:** replace `pasr-mcp==0.4.0` after `--from`
in your existing registration with `/absolute/path/to/pasr`. For example:

```bash
uvx --from /absolute/path/to/pasr pasr-mcp --workspace /absolute/path/to/project
```

Use this instead of the published-package launch, not a second `pasr` registration.
It runs that checkout, which may differ from the release; editing it does not update
an existing global installation.

After installation, PASR's tools are available alongside the agent's native tools.
The model decides when to search, select context, or read files directly. Smaller
selected context does not by itself establish cheaper or more accurate answers.

<p align="center"><img src="https://raw.githubusercontent.com/Apheironn/pasr/main/docs/assets/concept-mcp.svg" width="760" alt="Configure PASR alongside native tools; the host chooses tools and stopping policy"></p>

Per-client setup notes: [Claude Code](https://github.com/Apheironn/pasr/blob/main/docs/install/claude-code.md) ·
[Cursor](https://github.com/Apheironn/pasr/blob/main/docs/install/cursor.md) · [Windsurf](https://github.com/Apheironn/pasr/blob/main/docs/install/windsurf.md).

**Without an agent:** run `uvx --from pasr-mcp==0.4.0 pasr explain "<question>"`
from the project to inspect to print a selection receipt.
Five historical CLI examples against pinned public repos are in
[`examples/`](https://github.com/Apheironn/pasr/blob/main/examples/README.md).

### 0.4.0 diagnostics

Version 0.4.0 includes `pasr doctor`. To diagnose this package installation,
use the same version as your registered server:

```bash
uvx --from pasr-mcp==0.4.0 pasr --workspace /absolute/path/to/project doctor --json --timeout 30
```

Omit `--json` for a readable report. Exit codes are `0` for success, `1` for a
failed diagnostic, and `2` for invalid options. The protocol deadline must be a
finite positive number; subprocess shutdown can take a few additional seconds.
The command checks that the workspace is a directory, then starts a real MCP
server in a disposable fixture to inspect its catalog and select known source.
It never scans or writes the project or its `.pasr/` state. Reports contain runtime
versions and check outcomes, not source, absolute paths, environment values or raw
exception messages. It makes no paid model call or automatic report upload;
initial setup/tokenizer encoding downloads can require network access.
A pass does not verify your client's registration, approval settings or answers.

Optional public reports: [installation trouble](https://github.com/Apheironn/pasr/issues/new?template=installation-trouble.yml)
or [real-task feedback](https://github.com/Apheironn/pasr/issues/new?template=real-task-feedback.yml).
Review before posting; do not include secrets, private source or raw transcripts.
Doctor is optional; you can report without running it.

### Verified Codex onboarding, with explicit limits

On 2026-10-04, **Codex CLI 0.160.0 + GPT-6 Luna** used an installed 0.3.0 wheel
to answer a source-reading question in an isolated workspace containing one
unmodified PASR source file. The final recipe used three model-selected PASR calls,
364 selected-context tokens, and source-checked relative line citations.
This is a controlled integration smoke, not independent user adoption or evidence
of lower total model cost. Setup failures and earlier model turns are retained in
the [integration record](https://github.com/Apheironn/pasr/blob/main/eval/agent_bench/client_smoke_20261004.json).

For interactive use, approve the known PASR server when the client prompts.
In unattended Codex runs, `approval_policy = "never"` does **not** grant MCP tool
permission: the initial model call was blocked. Only for a reviewed, trusted
server/workspace, set `default_tools_approval_mode = "approve"` inside the existing
`[mcp_servers.pasr]` table. This is explicit preapproval of that server, not a reason
to disable global safeguards. PASR may write receipts/cache in its workspace;
the host's read-only shell sandbox does not sandbox the MCP process.

Ask for **workspace-relative `file:line` ranges copied from PASR output, as plain
text rather than invented absolute links**. The earlier answer added a nonexistent
`/workspace` prefix; the revised citation instruction produced matching references.
When scripting `codex exec`, close unused stdin; otherwise it can wait for
additional prompt input. None of these observations proves another client/model
will behave identically.

To repeat this controlled task, build a wheel and run the checked-in driver from
the checkout root. Install Codex first and supply `OPENAI_API_KEY` through your
normal secret mechanism; **this makes paid API requests**.

```bash
python -m build --outdir dist/demo
python scripts/demo_client.py --codex /absolute/path/to/codex --wheel dist/demo/pasr_mcp-0.4.0-py3-none-any.whl --output eval/agent_bench/results/client-demo
```

On Windows, pass the actual `codex.exe`, not its shell wrapper. The output directory
must be new. The driver installs the wheel into a temporary environment, copies
onl