Content
<h1 align="center">context-pack (MCP)</h1>
<p align="center">
<b>Your agents spend fewer tokens on handoffs and deliver more accurate context.</b>
</p>
<p align="center">
<a href="#en">EN</a>
•
<a href="#ru">RU</a>
</p>
---
<a id="en"></a>
<details open>
<summary><b>EN</b></summary>
## The Problem
When agents hand off work to each other, they typically write free-form summaries in chat: "I found a bug in file X around line Y, it looks like Z." This wastes output tokens, loses precision, and forces the receiving agent to re-read source files to verify what was said.
The more agents collaborate, the worse this gets.
## The Solution
context-pack gives agents a shared, structured workspace. Instead of describing code in prose, an agent places anchors (file path + line range) into a pack. The server renders those anchors into real code excerpts. The agent then sends only `pack_id + short summary` in chat — the receiving agent opens the pack and gets the full picture: exact code, comments, diagrams, verdicts.
## Key Benefits
- **Fewer output tokens**: agents describe findings in a structured pack instead of prose, cutting handoff message size significantly.
- **Higher accuracy**: context is anchored to actual code lines, not paraphrased — no "trust me" summaries.
- **Less redundant work**: the receiving agent reads one pack instead of re-opening multiple source files.
---
## Quick Start
**Linux / macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | bash
```
**Windows (PowerShell):**
```powershell
iwr https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.ps1 -UseBasicParsing | iex
```
> Installers verify downloaded artifacts against `checksums.sha256` from the same release.
Then add the server to your MCP config:
**Codex `config.toml`:**
```toml
[mcp_servers.context_pack]
command = "mcp-context-pack"
args = []
[mcp_servers.context_pack.env]
CONTEXT_PACK_ROOT = "/absolute/path/to/context-pack-data"
CONTEXT_PACK_SOURCE_ROOT = "__SESSION_CWD__"
CONTEXT_PACK_LOG = "mcp_context_pack=info"
CONTEXT_PACK_INITIALIZE_TIMEOUT_MS = "20000"
CONTEXT_PACK_MAX_PACK_BYTES = "524288"
CONTEXT_PACK_MAX_SOURCE_BYTES = "2097152"
CONTEXT_PACK_EXPIRED_GRACE_SECONDS = "900"
```
**Generic `mcp.json`:**
```json
{
"mcpServers": {
"context_pack": {
"command": "mcp-context-pack",
"args": [],
"env": {
"CONTEXT_PACK_ROOT": "/absolute/path/to/context-pack-data",
"CONTEXT_PACK_SOURCE_ROOT": "__SESSION_CWD__",
"CONTEXT_PACK_LOG": "mcp_context_pack=info",
"CONTEXT_PACK_INITIALIZE_TIMEOUT_MS": "20000",
"CONTEXT_PACK_MAX_PACK_BYTES": "524288",
"CONTEXT_PACK_MAX_SOURCE_BYTES": "2097152",
"CONTEXT_PACK_EXPIRED_GRACE_SECONDS": "900"
}
}
}
}
```
Restart your MCP client. Smoke-check with `input { "action": "list" }`.
---
## How It Works
```
Agent context-pack server Orchestrator
| | |
|-- input write (anchors) -->| |
| { path, line range, | |
| sections, comments } | |
| |-- renders code excerpts |
|-- output read ------------>| |
| |-- returns rendered pack -->|
| | |
|-- chat: pack_id + summary ----------------------->| |
| |
reads pack, |
gets full |
context |
```
1. The agent writes a pack via `input` — sections, code anchors (file + line range), comments, diagrams.
2. The agent calls `output read` to get the rendered markdown.
3. The agent sends `pack_id + short summary` in chat — nothing more.
4. The orchestrator opens the pack and gets complete, factual context.
---
## Configuration
### Parameter reference
| Parameter | Meaning |
|---|---|
| `command` | Binary path or executable name in `PATH` (recommended: `mcp-context-pack`) |
| `args` | Optional CLI args (usually `[]`) |
| `CONTEXT_PACK_ROOT` | Storage root (`{root}/packs/*.json`) |
| `CONTEXT_PACK_SOURCE_ROOT` | Source root used to resolve anchors into code excerpts (`__SESSION_CWD__`, `session_cwd`, `cwd`, `.` = current session dir) |
| `CONTEXT_PACK_LOG` | Log filter (stderr) |
| `CONTEXT_PACK_INITIALIZE_TIMEOUT_MS` | Wait timeout for first MCP `initialize` |
| `CONTEXT_PACK_MAX_PACK_BYTES` | Max bytes per stored pack file |
| `CONTEXT_PACK_MAX_SOURCE_BYTES` | Max bytes per source file when rendering excerpts |
| `CONTEXT_PACK_EXPIRED_GRACE_SECONDS` | Grace window (seconds) for `expired` packs before purge/not_found (default `900`) |
> Set `CONTEXT_PACK_ROOT` to a **root directory**, not to `.../packs`.
>
> Storage format is JSON (`packs/*.json`). Legacy markdown packs are not supported.
---
## Reading a Pack
Compact handoff read (default — bounded, orchestrator profile):
```json
{
"name": "output",
"arguments": {
"action": "read",
"id": "pk_abcd2345"
}
}
```
Full drill-down read (complete snippets for review):
```json
{
"name": "output",
"arguments": {
"action": "read",
"id": "pk_abcd2345",
"profile": "reviewer"
}
}
```
For the full tool contract, paging, profiles, error codes, and migration notes — see [TECHNICAL.md](TECHNICAL.md).
---
## Troubleshooting
- `revision_conflict` — re-read the pack (`input get`) to get the current revision, then retry with `expected_revision` set to the value from the re-read.
- `stale_ref` — update or remove the outdated anchor.
- `not_found` — pack has likely expired by TTL.
- `tool output too large` — split the pack into smaller sections.
- `ambiguous` — name matched multiple packs; use exact `id` from `details.candidate_ids`.
- Corrupted or oversized pack files are removed automatically during list operations. To remove a specific pack: `input { "action": "delete", "id": "<pack_id>" }`.
---
<details>
<summary>All install methods</summary>
### One-line install (Linux/macOS)
```bash
curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | bash
```
Pin a specific version:
```bash
curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | CONTEXT_PACK_VERSION=v0.1.0 bash
```
Install to a custom directory:
```bash
curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | CONTEXT_PACK_INSTALL_DIR="$HOME/bin" bash
```
### One-line install (Windows PowerShell)
```powershell
iwr https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.ps1 -UseBasicParsing | iex
```
### Homebrew (macOS/Linux)
```bash
brew install --formula https://github.com/AmirTlinov/context_pack/releases/latest/download/mcp-context-pack.rb
```
### Scoop (Windows)
```powershell
scoop install https://github.com/AmirTlinov/context_pack/releases/latest/download/mcp-context-pack.json
```
### Manual install
1. Open **GitHub Releases** and download the archive for your OS/CPU.
2. Unpack `mcp-context-pack` (`.exe` on Windows).
3. Put it into your PATH (for example `~/.local/bin` on Linux/macOS).
### Build from source
```bash
cargo build --release
# binary: target/release/mcp-context-pack
```
> Release artifacts are published on each tag `v*` via `.github/workflows/release.yml`.
> Maintainers: release playbook is in `RELEASE.md`.
</details>
</details>
---
<a id="ru"></a>
<details>
<summary><b>RU</b></summary>
## Problem
When agents hand off work to each other, they typically write free-form summaries in chat: "I found a bug in file X around line Y, it looks like Z." This wastes output tokens, loses precision, and forces the receiving agent to re-read source files to verify what was said.
The more agents collaborate, the worse this gets.
## Solution
context-pack gives agents a shared, structured workspace. Instead of describing code in prose, an agent places anchors (file path + line range) into a pack. The server renders those anchors into real code excerpts. The agent then sends only `pack_id + short summary` in chat — the receiving agent opens the pack and gets the full picture: exact code, comments, diagrams, verdicts.
## Key Benefits
- **Fewer output tokens**: agents describe findings in a structured pack instead of prose, cutting handoff message size significantly.
- **Higher accuracy**: context is anchored to actual code lines, not paraphrased — no "trust me" summaries.
- **Less redundant work**: the receiving agent reads one pack instead of re-opening multiple source files.
---
## Quick Start
**Linux / macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | bash
```
**Windows (PowerShell):**
```powershell
iwr https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.ps1 -UseBasicParsing | iex
```
> Installers verify the downloaded archive against `checksums.sha256` from the same release.
Then add the server to your MCP config:
**Codex `config.toml`:**
```toml
[mcp_servers.context_pack]
command = "mcp-context-pack"
args = []
[mcp_servers.context_pack.env]
CONTEXT_PACK_ROOT = "/absolute/path/to/context-pack-data"
CONTEXT_PACK_SOURCE_ROOT = "__SESSION_CWD__"
CONTEXT_PACK_LOG = "mcp_context_pack=info"
CONTEXT_PACK_INITIALIZE_TIMEOUT_MS = "20000"
CONTEXT_PACK_MAX_PACK_BYTES = "524288"
CONTEXT_PACK_MAX_SOURCE_BYTES = "2097152"
CONTEXT_PACK_EXPIRED_GRACE_SECONDS = "900"
```
**Universal `mcp.json`:**
```json
{
"mcpServers": {
"context_pack": {
"command": "mcp-context-pack",
"args": [],
"env": {
"CONTEXT_PACK_ROOT": "/absolute/path/to/context-pack-data",
"CONTEXT_PACK_SOURCE_ROOT": "__SESSION_CWD__",
"CONTEXT_PACK_LOG": "mcp_context_pack=info",
"CONTEXT_PACK_INITIALIZE_TIMEOUT_MS": "20000",
"CONTEXT_PACK_MAX_PACK_BYTES": "524288",
"CONTEXT_PACK_MAX_SOURCE_BYTES": "2097152",
"CONTEXT_PACK_EXPIRED_GRACE_SECONDS": "900"
}
}
}
}
```
Restart the MCP client. Smoke test: `input { "action": "list" }`.
---
## How it Works
```
Agent context-pack server Orchestrator
| | |
|-- input write (anchors) ---->| |
| { path, line range, | |
| sections, comments } | |
| |-- renders code snippets |
|-- output read ------------>| |
| |-- serves rendered -->|
| | package |
|-- chat: pack_id + summary ----------------------->| |
| |
reads package, |
gets full context |
```
1. Agent writes a package via `input` — sections, code anchors (file + line range), comments, diagrams.
2. Agent calls `output read` and gets rendered markdown.
3. Agent sends to chat `pack_id + short summary` — and only this.
4. Orchestrator opens the package and gets full, actual context.
---
## Configuration
### Parameter Reference
| Parameter | Purpose |
|---|---|
| `command` | Path to the binary or command name in `PATH` (recommended: `mcp-context-pack`) |
| `args` | Optional CLI arguments (usually `[]`) |
| `CONTEXT_PACK_ROOT` | Storage root (`{root}/packs/*.json`) |
| `CONTEXT_PACK_SOURCE_ROOT` | Source root for turning anchors into snippets (`__SESSION_CWD__`, `session_cwd`, `cwd`, `.` = session current directory) |
| `CONTEXT_PACK_LOG` | Log filter (stderr) |
| `CONTEXT_PACK_INITIALIZE_TIMEOUT_MS` | Timeout for waiting for the first MCP `initialize` |
| `CONTEXT_PACK_MAX_PACK_BYTES` | Maximum package file size in bytes |
| `CONTEXT_PACK_MAX_SOURCE_BYTES` | Maximum source file size when rendering snippets |
| `CONTEXT_PACK_EXPIRED_GRACE_SECONDS` | How many seconds an expired pack remains accessible as `expired` before purge/not_found (default `900`) |
> Set `CONTEXT_PACK_ROOT` as **root folder**, not as `.../packs`.
>
> Storage format is JSON (`packs/*.json`). Old markdown packages are not supported.
---
## Reading a Package
Compact handoff reading (default — bounded, orchestrator profile):
```json
{
"name": "output",
"arguments": {
"action": "read",
"id": "pk_abcd2345"
}
}
```
Full drill-down for review (full snippets):
```json
{
"name": "output",
"arguments": {
"action": "read",
"id": "pk_abcd2345",
"profile": "reviewer"
}
}
```
Full tool contract, paginated reading, profiles, error codes, and migration examples — in [TECHNICAL.md](TECHNICAL.md).
---
## Diagnostics
- `revision_conflict` — re-read the package (`input get`), get the current revision, repeat the mutation with `expected_revision` from the re-read package.
- `stale_ref` — update or delete the stale anchor.
- `not_found` — the package likely expired by TTL.
- `tool output too large` — split the package into smaller sections.
- `ambiguous` — the name matched multiple packages; use the exact `id` from `details.candidate_ids`.
- Damaged or oversized packages are automatically removed during list operations. For targeted removal: `input { "action": "delete", "id": "<pack_id>" }`.
---
<details>
<summary>All Installation Methods</summary>
### One-Line Installation (Linux/macOS)
```bash
curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | bash
```
Pin a specific version:
```bash
curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | CONTEXT_PACK_VERSION=v0.1.0 bash
```
Install to a non-standard directory:
```bash
curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | CONTEXT_PACK_INSTALL_DIR="$HOME/bin" bash
```
### One-Line Installation (Windows PowerShell)
```powershell
iwr https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.ps1 -UseBasicParsing | iex
```
### Homebrew (macOS/Linux)
```bash
brew install --formula https://github.com/AmirTlinov/context_pack/releases/latest/download/mcp-context-pack.rb
```
### Scoop (Windows)
```powershell
scoop install https://github.com/AmirTlinov/context_pack/releases/latest/download/mcp-context-pack.json
```
### Manual Installation
1. Open **GitHub Releases** and download the archive for your OS/architecture.
2. Unpack `mcp-context-pack` (`.exe` on Windows).
3. Place the binary in `PATH` (e.g., `~/.local/bin` on Linux/macOS).
### Build from Source
```bash
cargo build --release
# binary: target/release/mcp-context-pack
```
> Release artifacts are published on every `v*` tag via `.github/workflows/release.yml`.
> For maintainers: the release script is described in `RELEASE.md`.
</details>
</details>
