# agent-context-mcp

**One privacy-first MCP server for developers who work across AI coding agents.**

Move between Claude Code, Codex, and Hermes without re-explaining what happened. `agent-context-mcp` reads the useful parts of your **local** agent history, sanitizes them, and returns structured Markdown through one MCP interface.

> **Local-first. Read-only. Sanitized before output.**

## Why this exists

When you switch AI coding tools, each one starts without the decisions, failures, and next steps from the others. This server gives a selected client a safe, read-only view of local context from:

- **Claude Code**
- **Codex**
- **Hermes**

It also discovers local AI harnesses, MCP configurations, and CLI runtimes — and can generate **dry-run proposals** for skills or MCP migration.

## Your sessions stay local

`agent-context-mcp` is not a session-sync product.

- No hosted service by default
- No telemetry or analytics
- No background uploads
- No writes to source session stores
- No secrets, raw configuration values, or auth headers returned
- No remote network connection unless you explicitly enable and deploy one

Before output, source adapters exclude system/developer instructions, bootstrap dumps, encrypted/internal reasoning, and secret-shaped values. Tool output is opt-in and bounded. Active JSONL files with a partial trailing line are tolerated.

**Never commit your agent data.** This repository ignores session stores, JSONL files, local databases, credentials, and `.env` files. Its tests check for personal Windows paths and project-specific markers.

## Install

### From source (current)

```bash
git clone https://github.com/mosafly/agent-context-mcp.git
cd agent-context-mcp
python -m pip install .
```

Requires Python 3.10+.

### Claude Code

```bash
claude mcp add --scope user agent_context -- agent-context-mcp
```

### Codex CLI

```bash
codex mcp add agent_context -- agent-context-mcp
```

### Hermes

```bash
hermes mcp add agent_context --command agent-context-mcp
```

### Claude Desktop

Add this to `claude_desktop_config.json` and restart Claude Desktop:

```json
{
  "mcpServers": {
    "agent_context": {
      "command": "agent-context-mcp",
      "args": []
    }
  }
}
```

Start a new client session after installing so the MCP tool cache refreshes.

## One unified interface

All conversation tools take a source:

```text
hermes | codex | claude_code
```

| Tool | Purpose |
| --- | --- |
| `agent_list_conversations` | List sanitized local conversations |
| `agent_search_conversations` | Search sanitized text |
| `agent_read_conversation` | Read one selected conversation |
| `agent_read_latest_conversation` | Read the latest conversation |
| `agent_export_context_bundle` | Produce a bounded handoff bundle without writing a file |
| `agent_detect_harnesses` | Detect known local AI harnesses |
| `agent_detect_harness_mcps` | Discover MCP names without secret values |
| `agent_detect_harness_runtimes` | Locate CLI runtimes without launching desktop apps |
| `agent_propose_skill_installs` | Produce a skill migration dry-run |
| `agent_propose_mcp_installs` | Produce a sanitized MCP migration dry-run |

Migration proposals never edit configuration, copy skills, install packages, or transfer credentials.

## Supported clients

| Client | Local `stdio` | Remote HTTPS |
| --- | ---: | ---: |
| Claude Code | ✅ | — |
| Codex CLI | ✅ | — |
| Hermes / Hermes CLI | ✅ | — |
| Claude Desktop | ✅ | — |
| Claude Cowork / claude.ai | ❌ | ✅ via an authenticated gateway |
| ChatGPT Desktop / Web | ❌ | ✅ via an authenticated gateway |

Cloud clients cannot access your `localhost` or execute a local `stdio` command. Do not expose this server directly to the public internet.

## Optional local HTTP mode

The default transport is `stdio`. A local Streamable HTTP server is available only after an explicit opt-in:

```bash
AGENT_CONTEXT_ALLOW_HTTP=1 agent-context-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000
```

For Cowork, claude.ai, ChatGPT, or any cloud client, place an authenticated HTTPS gateway in front of the service. Require OAuth or equivalent authentication, rate limits, and a deliberate deployment decision. Never publish a direct session reader without those controls.

## Configuration

The bundled adapters use local defaults for common session locations. Set these environment variables only when your stores live elsewhere:

```text
CODEX_SESSIONS_ROOT
CLAUDE_PROJECTS_ROOT
HERMES_HOME
```

Paths are read locally; their contents are never uploaded by this package.

## Development

```bash
python -m pip install -e .
python -m unittest discover -s tests
python -m py_compile src/agent_context_mcp/*.py src/agent_context_mcp/adapters/*.py
```

## License

MIT. See [LICENSE](LICENSE).