# Thread Contract MCP Server

Thread-scoped runtime contracts for AI coding agents.

[![CI](https://github.com/ch998244353/Thread-Contract-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ch998244353/Thread-Contract-mcp/actions/workflows/ci.yml)

[English](README.md) | [中文](docs/README.zh-CN.md) | [日本語](docs/README.ja.md)

## What Is Thread Contract?

Thread Contract is a local runtime contract layer for AI coding-agent threads.
It lets users pin explicit, thread-scoped rules such as "do not commit unless I
ask" or "read PLAN.md before editing" without turning those rules into project
policy or long-term memory.

It stores rules in local SQLite, exposes management tools through MCP, provides
a small local Web UI, and can inject active rules before every Codex or Claude
Code user turn through a `UserPromptSubmit` hook.

Use it when an instruction should survive a long coding-agent conversation, but
should not become a permanent repository rule or hidden memory.

## How It Differs From Rules, Memory, And Skills

Thread Contract is not another memory system or prompt template. It is a
runtime contract for the current thread: explicit temporary rules that stay
visible and enforceable without becoming repository policy or global memory.

| Approach | Best For | Not For |
| --- | --- | --- |
| `AGENTS.md` / `CLAUDE.md` | Long-term project norms and fixed development rules | Temporary task requirements; frequent edits pollute the repository |
| Long-term memory | User preferences and cross-conversation information | Short-term constraints inside the current task |
| Skill / prompt templates | Reusable capabilities and fixed workflows | Manual triggering; not suited for stable every-turn enforcement |
| Thread Contract | Temporary rule contracts for the current thread | Global long-term memory or project-wide policy changes |

## Usage Screenshots

These images show the core workflow: adding thread-scoped rules from an agent
thread and editing the same list in the local Web UI.

Thread Contract rules can be added and confirmed from a coding-agent thread:

![Thread Contract in Codex](docs/assets/codex-threadcontract-flow.png)

The same list can be edited in the local Web UI:

![Thread Contract Web UI](docs/assets/web-ui-threadcontract-list.png)

## Install

Version `0.1.0` is source-install first. PyPI publishing, MCP Registry
publishing, Docker images, and hosted sync are intentionally out of scope for
this release.

Requirements:

- Python 3.10 or newer.
- Codex or Claude Code for host integration.
- Optional: `mcp` Python package only if you want the alternate SDK-backed MCP
  server entrypoint.

Clone and install:

```powershell
git clone https://github.com/ch998244353/Thread-Contract-mcp.git threadcontract-mcp
cd threadcontract-mcp
python -m pip install -e .
```

Run the handwritten stdio MCP server:

```powershell
threadcontract-mcp
```

Run the local Web UI:

```powershell
threadcontract-web --port 8765
```

Open:

```text
http://127.0.0.1:8765/
```

By default, Thread Contract stores SQLite data at:

```text
~/.codex/threadcontract.sqlite3
```

Override it with `THREADCONTRACT_DB`:

```powershell
$env:THREADCONTRACT_DB = "$HOME\.codex\threadcontract-dev.sqlite3"
```

## Use With Codex

For source/plugin development, this repository includes:

```text
.codex-plugin/plugin.json
.codex-mcp.json
hooks/codex_hooks.json
hooks/user_prompt_submit.py
```

Use the helper script to add this checkout as a local Codex plugin marketplace:

```powershell
.\scripts\install-codex-plugin.ps1
```

Then restart Codex, install or enable the `Thread Contract` plugin from the
local marketplace, open `/hooks`, review the bundled hook, and trust it. Codex
does not run non-managed plugin hooks until the current hook definition is
trusted.

For MCP-only setup, add this to `~/.codex/config.toml` after installing the
package:

```toml
[mcp_servers.threadcontract]
command = "threadcontract-mcp"
enabled = true
startup_timeout_sec = 10
tool_timeout_sec = 30
enabled_tools = [
  "threadcontract_open_turn",
  "threadcontract_commit_turn_list",
  "threadcontract_list_turn",
  "show_threadcontract_list",
  "threadcontract_add_turn_item",
  "threadcontract_update_turn_item",
  "threadcontract_copy_list_text",
  "threadcontract_get_list_web_url",
  "threadcontract_delete_thread_list",
]
```

See [docs/codex-adapter.md](docs/codex-adapter.md) and
[docs/mcp-config.md](docs/mcp-config.md).

## Use With Claude Code

The Claude Code plugin files live at the repository root:

```text
.claude-plugin/plugin.json
.mcp.json
hooks/claude_hooks.json
hooks/claude_user_prompt_submit.py
```

Validate locally:

```powershell
claude plugin validate . --strict
```

Run a development session:

```powershell
claude --plugin-dir .
```

## Use As Python SDK

The importable SDK is for local agent runtimes that want Thread Contract without
MCP:

```python
from threadcontract_sdk import ThreadContractClient

client = ThreadContractClient(db_path="threadcontract.sqlite3")
thread = client.open_thread(
    thread_id="thread-a",
    workspace="/path/to/repo",
    user_message="start",
)
client.add_item(thread=thread, content="Answer with the conclusion first.")
client.commit_items(thread=thread)

context = client.build_context(thread=thread, user_message="next request")
print(context)
```

The stable public SDK exports only:

- `ThreadContractClient`
- `ThreadContractThread`

## What It Provides

- Stdio MCP server with Thread Contract management tools.
- Codex plugin manifest, bundled MCP config, and `UserPromptSubmit` hook.
- Claude Code plugin manifest, bundled MCP config, and hook adapter.
- Local Web UI for viewing and editing a Thread Contract list.
- Importable Python SDK for custom local agent runtimes.
- SQLite storage with cleanup for stale lists and capped local data size.

The server exposes these MCP tools:

- `threadcontract_open_turn`
- `threadcontract_commit_turn_list`
- `threadcontract_list_turn`
- `show_threadcontract_list`
- `threadcontract_add_turn_item`
- `threadcontract_update_turn_item`
- `threadcontract_copy_list_text`
- `threadcontract_get_list_web_url`
- `threadcontract_delete_thread_list`

## Alternate MCP SDK Server

The default plugin config uses `src/server.py`, a small handwritten stdio MCP
server with no runtime dependency outside the standard library.

An alternate server using the MCP Python SDK is available:

```powershell
python -m pip install -e ".[sdk-server]"
threadcontract-mcp-sdk-server
```

## Repository Layout

```text
threadcontract-mcp/
  .codex-plugin/plugin.json      # Codex plugin manifest
  .claude-plugin/plugin.json     # Claude Code plugin manifest
  .codex-mcp.json                # Codex bundled MCP server config
  .mcp.json                      # Claude Code bundled MCP server config
  hooks/                         # Codex and Claude Code hook adapters
  src/                           # MCP server, service layer, Web API, SDK
  web/                           # Source Web UI assets for plugin/source runs
  docs/                          # Installation, architecture, security docs
  examples/                      # MCP, Codex, Claude Code, and SDK examples
  scripts/                       # Local install helpers
  tests/                         # Unit, hook, stdio, Web UI, and acceptance tests
```

## Tests

Run the unit suite and acceptance smoke:

```powershell
python -m unittest discover -s tests -v
python tests/acceptance.py
```

Build verification:

```powershell
python -m pip install -e ".[dev]"
python -m build
```

## Security And Privacy

Thread Contract is local-first. It stores explicit user-created rules and audit
events in SQLite. It does not capture conversation history automatically and it
does not create cross-thread long-term memory.

Hooks can inject extra context before a prompt is sent to the model. Review and
trust hook code before enabling it. See [SECURITY.md](SECURITY.md) and
[docs/security.md](docs/security.md).

## Documentation

- [docs/install.md](docs/install.md)
- [docs/quickstart.md](docs/quickstart.md)
- [docs/mcp-config.md](docs/mcp-config.md)
- [docs/codex-adapter.md](docs/codex-adapter.md)
- [docs/architecture.md](docs/architecture.md)
- [docs/security.md](docs/security.md)

## License

MIT. See [LICENSE](LICENSE).