context-pack (MCP)

Your agents spend fewer tokens on handoffs and deliver more accurate context.

EN

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:

curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | bash

Windows (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:

[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:

{
  "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       |

The agent writes a pack via input — sections, code anchors (file + line range), comments, diagrams.
The agent calls output read to get the rendered markdown.
The agent sends pack_id + short summary in chat — nothing more.
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):

{
  "name": "output",
  "arguments": {
    "action": "read",
    "id": "pk_abcd2345"
  }
}

Full drill-down read (complete snippets for review):

{
  "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.

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>" }.

All install methods

One-line install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | bash

Pin a specific version:

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:

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)

iwr https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.ps1 -UseBasicParsing | iex

Homebrew (macOS/Linux)

brew install --formula https://github.com/AmirTlinov/context_pack/releases/latest/download/mcp-context-pack.rb

Scoop (Windows)

scoop install https://github.com/AmirTlinov/context_pack/releases/latest/download/mcp-context-pack.json

Manual install

Open GitHub Releases and download the archive for your OS/CPU.
Unpack mcp-context-pack (.exe on Windows).
Put it into your PATH (for example ~/.local/bin on Linux/macOS).

Build from source

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.

RU

Проблема

Когда агенты передают работу друг другу, они обычно пишут пересказы в чат: "Я нашёл баг в файле X примерно на строке Y, выглядит как Z." Это тратит output-токены, теряет точность и заставляет получающего агента заново открывать исходники, чтобы проверить сказанное.

Чем больше агентов в цепочке — тем больше потери.

Решение

context-pack даёт агентам общее структурированное рабочее пространство. Вместо того чтобы описывать код словами, агент ставит якоря (путь к файлу + диапазон строк) в пакет. Сервер превращает якоря в реальные вырезки кода. Агент отправляет в чат только pack_id + короткий summary — получающий агент открывает пакет и видит полную картину: точный код, комментарии, диаграммы, вердикты.

Ключевые преимущества

Меньше output-токенов: агенты фиксируют находки в структурированном пакете вместо прозы — размер handoff-сообщений значительно сокращается.
Выше точность: контекст привязан к конкретным строкам кода, а не к пересказу — никаких "доверься мне".
Меньше дублирующей работы: получающий агент читает один пакет, а не заново открывает несколько исходных файлов.

Быстрый старт

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | bash

Windows (PowerShell):

iwr https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.ps1 -UseBasicParsing | iex

Инсталлеры проверяют скачанный архив по checksums.sha256 из того же релиза.

Затем добавьте сервер в ваш MCP-конфиг:

Codex config.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"

Универсальный mcp.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"
      }
    }
  }
}

Перезапустите MCP-клиент. Smoke-проверка: input { "action": "list" }.

Как это работает

Агент                    context-pack сервер           Оркестратор
  |                            |                            |
  |-- input write (якоря) ---->|                            |
  |   { путь, диапазон строк,  |                            |
  |     секции, комментарии }  |                            |
  |                            |-- рендерит вырезки кода    |
  |-- output read ------------>|                            |
  |                            |-- отдаёт отрендеренный  -->|
  |                            |   пакет                    |
  |-- чат: pack_id + summary ----------------------->|     |
                                                      |     |
                                           читает пакет,    |
                                           получает полный   |
                                           контекст         |

Агент записывает пакет через input — секции, якоря кода (файл + диапазон строк), комментарии, диаграммы.
Агент вызывает output read и получает отрендеренный markdown.
Агент отправляет в чат pack_id + короткий summary — и только это.
Оркестратор открывает пакет и получает полный, фактический контекст.

Настройка

Справка по параметрам

Параметр	Назначение
`command`	Путь к бинарнику или имя команды в `PATH` (рекомендуется: `mcp-context-pack`)
`args`	Опциональные аргументы CLI (обычно `[]`)
`CONTEXT_PACK_ROOT`	Корень хранилища (`{root}/packs/*.json`)
`CONTEXT_PACK_SOURCE_ROOT`	Корень исходников для превращения якорей в вырезки (`__SESSION_CWD__`, `session_cwd`, `cwd`, `.` = текущая директория сессии)
`CONTEXT_PACK_LOG`	Фильтр логов (stderr)
`CONTEXT_PACK_INITIALIZE_TIMEOUT_MS`	Таймаут ожидания первого MCP `initialize`
`CONTEXT_PACK_MAX_PACK_BYTES`	Максимальный размер файла пакета в байтах
`CONTEXT_PACK_MAX_SOURCE_BYTES`	Максимальный размер исходного файла при рендеринге вырезок
`CONTEXT_PACK_EXPIRED_GRACE_SECONDS`	Сколько секунд истекший pack остаётся доступен как `expired` перед purge/not_found (по умолчанию `900`)

Задавайте CONTEXT_PACK_ROOT как корневую папку, не как .../packs.

Формат хранения — JSON (packs/*.json). Старые markdown-пакеты не поддерживаются.

Чтение пакета

Compact handoff-чтение (по умолчанию — bounded, профиль orchestrator):

{
  "name": "output",
  "arguments": {
    "action": "read",
    "id": "pk_abcd2345"
  }
}

Полный drill-down для ревью (полные snippets):

{
  "name": "output",
  "arguments": {
    "action": "read",
    "id": "pk_abcd2345",
    "profile": "reviewer"
  }
}

Полный контракт инструментов, постраничное чтение, профили, коды ошибок и примеры миграции — в TECHNICAL.md.

Диагностика

revision_conflict — перечитайте пакет (input get), получите текущий revision, повторите мутацию с expected_revision из перечитанного пакета.
stale_ref — обновите или удалите устаревший якорь.
not_found — пакет, скорее всего, истёк по TTL.
tool output too large — разбейте пакет на более мелкие секции.
ambiguous — имя совпало с несколькими пакетами; используйте точный id из details.candidate_ids.
Повреждённые или oversized-файлы пакетов удаляются автоматически при операциях list. Для точечного удаления: input { "action": "delete", "id": "<pack_id>" }.

Все способы установки

Установка одной командой (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | bash

Зафиксировать конкретную версию:

curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | CONTEXT_PACK_VERSION=v0.1.0 bash

Установить в нестандартную директорию:

curl -fsSL https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.sh | CONTEXT_PACK_INSTALL_DIR="$HOME/bin" bash

Установка одной командой (Windows PowerShell)

iwr https://raw.githubusercontent.com/AmirTlinov/context_pack/main/scripts/install.ps1 -UseBasicParsing | iex

Homebrew (macOS/Linux)

brew install --formula https://github.com/AmirTlinov/context_pack/releases/latest/download/mcp-context-pack.rb

Scoop (Windows)

scoop install https://github.com/AmirTlinov/context_pack/releases/latest/download/mcp-context-pack.json

Ручная установка

Откройте GitHub Releases и скачайте архив под вашу ОС/архитектуру.
Распакуйте mcp-context-pack (.exe на Windows).
Положите бинарник в PATH (например, ~/.local/bin на Linux/macOS).

Сборка из исходников

cargo build --release
# бинарник: target/release/mcp-context-pack

Release-артефакты публикуются на каждый тег v* через .github/workflows/release.yml. Для сопровождающих: сценарий релиза описан в RELEASE.md.

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.github		.github
scripts		scripts
skills/explorer-context-pack		skills/explorer-context-pack
src		src
tests		tests
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
RELEASE.md		RELEASE.md
TECHNICAL.md		TECHNICAL.md

Folders and files

Latest commit

History

Repository files navigation

context-pack (MCP)

The Problem

The Solution

Key Benefits

Quick Start

How It Works

Configuration

Parameter reference

Reading a Pack

Troubleshooting

One-line install (Linux/macOS)

One-line install (Windows PowerShell)

Homebrew (macOS/Linux)

Scoop (Windows)

Manual install

Build from source

Проблема

Решение

Ключевые преимущества

Быстрый старт

Как это работает

Настройка

Справка по параметрам

Чтение пакета

Диагностика

Установка одной командой (Linux/macOS)

Установка одной командой (Windows PowerShell)

Homebrew (macOS/Linux)

Scoop (Windows)

Ручная установка

Сборка из исходников

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages