{"id":46615906,"url":"https://github.com/jack-chaudier/tropical-mcp","last_synced_at":"2026-03-07T20:05:35.680Z","repository":{"id":340699470,"uuid":"1167216676","full_name":"jack-chaudier/tropical-mcp","owner":"jack-chaudier","description":"Installable MCP server for guarded context compaction in Codex and Claude-style clients","archived":false,"fork":false,"pushed_at":"2026-03-06T18:41:43.000Z","size":246,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-06T18:42:24.575Z","etag":null,"topics":["claude-code","codex","context-engineering","llm","mcp","memory-compression","model-context-protocol"],"latest_commit_sha":null,"homepage":"https://dreams-dun.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jack-chaudier.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-26T03:59:39.000Z","updated_at":"2026-03-06T18:41:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jack-chaudier/tropical-mcp","commit_stats":null,"previous_names":["jack-chaudier/tropical-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jack-chaudier/tropical-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jack-chaudier%2Ftropical-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jack-chaudier%2Ftropical-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jack-chaudier%2Ftropical-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jack-chaudier%2Ftropical-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jack-chaudier","download_url":"https://codeload.github.com/jack-chaudier/tropical-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jack-chaudier%2Ftropical-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30229590,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T19:01:10.287Z","status":"ssl_error","status_checked_at":"2026-03-07T18:59:58.103Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","codex","context-engineering","llm","mcp","memory-compression","model-context-protocol"],"created_at":"2026-03-07T20:05:35.110Z","updated_at":"2026-03-07T20:05:35.667Z","avatar_url":"https://github.com/jack-chaudier.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tropical-mcp\n\nSource-available MCP server for **guarded context compaction** in Codex, Claude Code, and similar tool-calling clients.\n\n`tropical-mcp` is the evaluation implementation for the MirageKit research program. The public research showcase, working papers, replay artifacts, and live demo live in [`dreams`](https://github.com/jack-chaudier/dreams).\n\nThis package addresses a long-context reliability failure mode: an agent can remain answer-valid while silently switching the governing task intent under naive memory compression. `tropical-mcp` exposes explicit MCP tools that preserve pivot-critical structure when feasible and emit auditable artifacts when they cannot.\n\n## Who This Is For\n\n- Researchers evaluating long-context compaction or eviction behavior.\n- Agent teams using Codex, Claude Code, or similar clients that can register an MCP server and call tools deliberately.\n- Anyone who wants checkable artifacts such as `runtime_info()`, telemetry records, and `certificate(...)` outputs instead of opaque compression behavior.\n\n## What It Ships\n\n- `compact(messages, token_budget, policy, k)`\n  - `l2_guarded` for protected pivot + predecessor retention\n  - `l2_iterative_guarded` for iterative safe-removal checks\n  - `recency` as the baseline comparison policy\n- `diagnose(...)` for a one-call tagged horizon view\n- `context_anchor(...)` for paste-ready objective + constraint anchors\n- `inspect(...)` and `inspect_horizon(...)` for feasibility and witness inspection\n- `compact_auto(...)` for adaptive `k` selection\n- `certificate(...)` for portable memory-safety artifacts\n- `telemetry_summary(...)` for run-scoped telemetry rollups\n- `runtime_info()` for client/runtime/telemetry introspection\n- `retention_floor(...)` and `tag(...)` for operational analysis and role diagnostics\n\n## Integration Boundary\n\nThis server does **not** replace a host client's internal compactor automatically.\n\nThe supported pattern is:\n\n1. Register `tropical-mcp` as an MCP server in Codex, Claude Code, or a similar client.\n2. Keep compact-prompt guidance and durable memory files near the project when the host supports them.\n3. Call `runtime_info()`, `diagnose(...)`, `context_anchor(...)`, `compact_auto(...)`, `certificate(...)`, `telemetry_summary(...)`, and related tools explicitly during long runs.\n\nNot supported:\n\n- automatic interception of Codex or Claude Code host compaction events\n- magical drop-in replacement of client-owned compression internals\n\n## Install For Evaluation\n\nCurrent public evaluation path: clone this repository and install from source for academic research, peer review, or internal evaluation.\n\n```bash\ngit clone https://github.com/jack-chaudier/tropical-mcp.git ~/tropical-mcp\ncd ~/tropical-mcp\nuv venv\nsource .venv/bin/activate\nuv pip install -e '.[dev]'\n```\n\nBuilt artifacts are validated too: the packaged wheel now ships the public golden fixtures used by `tropical-mcp-full-validate`, so installed-artifact checks match source-checkout checks.\n\n## License Boundary\n\nThis repository is currently **source-available for evaluation**.\n\nYou may clone, install, run, reproduce, and create private local modifications to this repository for academic research, peer review, internal evaluation, and preparation of upstream patches. Public redistribution, hosted-service use, and commercial production use still require prior written consent.\n\nSee [`LICENSE`](./LICENSE) for the full terms. For broader rights, contact `jackgaff@umich.edu`.\n\n## Codex Quick-Start\n\nProject-scoped config file:\n\n`.codex/config.toml`\n\n```toml\n[mcp_servers.tropical-mcp]\ncommand = \"uv\"\nargs = [\"--directory\", \"/absolute/path/to/tropical-mcp\", \"run\", \"tropical-mcp\"]\nenv = { TROPICAL_MCP_CLIENT = \"codex\" }\nstartup_timeout_sec = 10\ntool_timeout_sec = 60\n```\n\nOr register from the CLI:\n\n```bash\ncodex mcp add tropical-mcp --env TROPICAL_MCP_CLIENT=codex -- \\\n  uv --directory /absolute/path/to/tropical-mcp run tropical-mcp\ncodex mcp list\n```\n\nAfter registration, the recommended first sequence is:\n\n1. `runtime_info()`\n2. `diagnose(...)`\n3. `context_anchor(...)`\n4. `compact_auto(...)`\n5. `certificate(...)`\n6. `telemetry_summary(...)`\n\nUse the full example bundle in [`examples/codex/`](./examples/codex/) for:\n\n- `config.toml`\n- `compact_prompt.md`\n- durable memory templates (`Prompt.md`, `Plan.md`, `Implement.md`, `Documentation.md`)\n\n## Claude Code Quick-Start\n\n```bash\nclaude mcp add tropical-mcp --scope user -- \\\n  uv --directory /absolute/path/to/tropical-mcp run tropical-mcp\n```\n\nThe same boundary applies in Claude Code: register the server, keep any durable context files current, and call the MCP tools explicitly.\n\n## Minimal Verification Snippet\n\nThis direct local smoke test exercises the same workflow you should use from the client.\n\n```bash\nuv run python - \u003c\u003c'PY'\nfrom tropical_mcp.server import certificate, compact_auto, context_anchor, runtime_info, telemetry_summary\n\nmessages = [\n    {\"id\": \"goal\", \"role\": \"user\", \"content\": \"Build a long-running coding agent workflow for Codex.\", \"role_hint\": \"pivot\"},\n    {\"id\": \"constraint_stdio\", \"role\": \"user\", \"content\": \"Use stdio transport and never emit JSON-RPC data to stdout logs.\", \"role_hint\": \"predecessor\"},\n    {\"id\": \"constraint_clients\", \"role\": \"user\", \"content\": \"Support Codex and Claude-style clients through explicit MCP tool calls.\", \"role_hint\": \"predecessor\"},\n    {\"id\": \"status\", \"role\": \"assistant\", \"content\": \"I am wiring the verification flow and docs.\", \"role_hint\": \"noise\"},\n]\n\ninfo = runtime_info()\nanchor = context_anchor(messages, k=2)\nauto = compact_auto(messages, token_budget=45, k_target=2, mode=\"adaptive\")\ncert = certificate(messages, token_budget=45, k=2)\nsummary = telemetry_summary(limit=20)\n\nprint(info[\"client\"], info[\"telemetry_path\"], info[\"run_id\"])\nprint(anchor[\"k_selected\"], anchor[\"anchor_text\"].splitlines()[0])\nprint(auto[\"audit\"][\"policy_selected\"], auto[\"audit\"][\"k_selected\"], auto[\"audit\"][\"guard_effective\"])\nprint(cert[\"policies\"][\"recency\"][\"audit\"][\"dropped_ids\"])\nprint(cert[\"policies\"][\"l2_guarded\"][\"audit\"][\"contract_satisfied\"])\nprint(summary[\"tool_counts\"])\nPY\n```\n\nWhat to expect:\n\n- `runtime_info()` resolves the client, package version, supported tools, telemetry path, and run ID.\n- `context_anchor(...)` emits a paste-ready objective/constraint restatement before compaction.\n- `compact_auto(...)` selects `l2_guarded` on the sample and reports the chosen `k`.\n- `certificate(...)` emits a portable recency-vs-guarded artifact with kept/dropped IDs and audit flags.\n- `telemetry_summary(...)` rolls up the current run so you can inspect what actually happened.\n\n## Artifacts And Telemetry\n\n- `runtime_info()` reports the resolved client, telemetry path, and active run ID before you rely on any tool output.\n- Every tool call appends telemetry to a client-aware JSONL path.\n- `telemetry_summary(...)` summarizes the active run by default, so the JSONL log is operational instead of opaque.\n- `certificate(...)` produces a shareable artifact that can be compared against public fixtures in `dreams/results/`.\n\nFor Codex, telemetry defaults to `${CODEX_HOME:-~/.codex}/state/tropical-mcp/telemetry.jsonl`. For Claude-style clients it defaults to `~/.claude/compactor-telemetry.jsonl`. See [`docs/GUIDE.md`](./docs/GUIDE.md) and [`docs/configuration.md`](./docs/configuration.md) for the full workflow.\n\nQuick CLI summary:\n\n```bash\nuv run tropical-mcp-telemetry --limit 25\n```\n\n## Validation And Release Signals\n\n```bash\nuv run --extra dev ruff check .\nuv run --extra dev mypy src/tropical_mcp\nuv run --extra dev pytest\nuv build\n./scripts/validate_installed_wheel.sh\nuv run tropical-mcp-full-validate\n```\n\nOr run the bundled script:\n\n```bash\n./scripts/full_validation.sh\n```\n\n## Replay Benchmark\n\n```bash\nuv run tropical-mcp-replay \\\n  --fractions 1.0,0.8,0.65,0.5,0.4 \\\n  --policies recency,l2_guarded \\\n  --k 3 \\\n  --line-count 200 \\\n  --output-dir artifacts/cyberops_mcp_replay\n```\n\n## Migration Note\n\nTemporary compatibility aliases remain for one release cycle:\n\n- `tropical-compactor`\n- `tropical-compactor-replay`\n- `tropical-compactor-full-validate`\n\n## Project Signals\n\n- CI on push and pull request: lint, type-check, tests, build, and functional validation\n- Installed-artifact validation: `./scripts/validate_installed_wheel.sh`\n- Research showcase and launch updates: [`dreams`](https://github.com/jack-chaudier/dreams) and \u003chttps://x.com/J_C_Gaffney\u003e\n- Citation metadata: [`CITATION.cff`](./CITATION.cff)\n- Client configuration guide: [`docs/configuration.md`](./docs/configuration.md)\n- Full usage guide: [`docs/GUIDE.md`](./docs/GUIDE.md)\n- Maintainer map: [`docs/MAINTAINER_MAP.md`](./docs/MAINTAINER_MAP.md)\n- Release checklist: [`docs/RELEASE.md`](./docs/RELEASE.md)\n- Contribution guide: [`CONTRIBUTING.md`](./CONTRIBUTING.md)\n- Code of conduct: [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)\n- Security policy: [`SECURITY.md`](./SECURITY.md)\n- Version history: [`CHANGELOG.md`](./CHANGELOG.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjack-chaudier%2Ftropical-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjack-chaudier%2Ftropical-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjack-chaudier%2Ftropical-mcp/lists"}