MCP context compression

One bounded surface for the context Codex actually needs.

MCP servers can save a round trip only when they also control the shape of the result. Capsule keeps a single action surface and applies task-specific, exact-recoverable views instead of injecting every tool catalogue and every old result into every turn.

The action map

`run` / `batch`

Execute commands with bounded stdout/stderr projections and preserved failure evidence.

`file` / `project`

Read files or understand a codebase through ranges, symbols, impact cones, and exact expansion.

`fetch` / `execute`

Keep web text and generated data bounded while retaining real URLs and structured recovery paths.

`index` / `search`

Recall durable local facts without replaying an unbounded memory store into the model.

Codex plugin and MCP packaging checklist

Capsule keeps the bundled skill, plugin manifest, and MCP server configuration as explicit components. The manifest points to ./skills/ and ./.mcp.json; the JSON file contains a camel-case mcpServers map. Keeping those contracts visible prevents a common failure mode where a plugin installs successfully but its bundled skill or server is not discovered.

// .codex-plugin/plugin.json
{"name":"capsule","version":"1.0.7+codex.BUILD","skills":"./skills/","mcpServers":"./.mcp.json"}

// .mcp.json
{"mcpServers":{"capsule":{"command":"node","args":["--no-warnings","./mcp/server.cjs"],"cwd":"."}}}

Verify the two layers

Run npm run audit:public after installation and inspect codex mcp list for the expected server name. A plugin card alone is not proof that the runtime exposed the tools.

Test path resolution

Do not assume every Codex build resolves relative MCP arguments from the plugin root. Keep bundled commands portable, test the installed archive on the target OS, and use the release-pinned fallback when path resolution differs.

Keep one surface

Do not register a second manually copied Capsule server when the plugin already owns the entry. Duplicate registrations add startup work and make tool discovery ambiguous.

For the current platform-level packaging contract, compare this example with the official Codex plugin packaging documentation; runtime behavior can change between Codex builds, so keep the local verification step.

Why exact recovery matters

A small output is useful only when the omitted evidence is still available and the model can request the right portion. Capsule writes content-addressed local capsules, emits a compact proof marker, and invalidates replay when the source changes.

Compatibility and fallbacks

Complex shell syntax, unknown encodings, wildcard reads, explicit full-output requests, unsafe operations, low-confidence matches, and token-negative candidates stay on the normal route. Compression is opt-in by evidence and never a requirement for correctness.

{"action":"project","payload":{"operation":"query","root":"."}}
{"action":"file","payload":{"path":"README.md","question":"installation"}}
{"action":"expand","payload":{"capsule_id":"cap_..."}}

Start with the installation guide, then inspect the README and benchmarks.