内容
# 线程上下文MCP
用于AI编码代理的共享内存MCP服务器。与 **Claude Code** 和 **Cursor** 配合使用时效果相同 —— 使用相同的软件包和配置格式，无需为每个客户端进行集成。
## 模式
- **本地模式（默认，免费，无需注册）：** 内存存储为一个普通的JSON文件，位于 `~/.threadctx/local.json` —— **零原生依赖**，因此 `npx threadctx-mcp` 可以立即在任何具有Node 18+的机器上安装（无需编译器，无需node-gyp步骤）。除了与LLM提供商进行交互外，无需进行网络调用。匹配基于关键词，限定在当前仓库（通过 `git remote` 检测）。随时运行 `npx threadctx-mcp list` 以查看代理已存储的内容。
- **云模式（付费团队层级+）：** 内存由仓库中的所有人共享，具有真正的语义搜索。需要从 [threadctx.dev](https://threadctx.dev) （或您自己的自托管部署 —— 请参见 `../cloud/README.md`）获取API密钥。
## 快速开始
```bash
# 本地模式 —— 无需配置。同时会在首次启动时自动将“检查团队内存”的指令添加到CLAUDE.md / .cursor/rules/threadctx.mdc中。
npx threadctx-mcp
# 可选：编写一个可提交的.threadctx.json配置文件，或显式重新应用项目规则块。
npx threadctx-mcp init
# 云模式 —— 打印要粘贴的确切MCP配置块
npx threadctx-mcp init --mode=cloud --api-key=tctx_xxx
# 查看代理已写入此机器的内容
npx threadctx-mcp list # 此仓库
npx threadctx-mcp list --all # 所有仓库
```
`init` 会在当前目录中写入一个 `.threadctx.json` 文件（仅 `{ "mode": "cloud" }`）。它可以安全地提交 —— 它永远不会包含您的API密钥。密钥在运行时从 `THREADCTX_API_KEY` 环境变量中读取（在MCP客户端的 `env` 块中设置，如下所示），因此密钥通过构造保持在版本控制之外。
threadctx还会在您的项目规则中添加一个小的、明确标记的指令 —— 用于Claude Code的 `CLAUDE.md`，用于Cursor的 `.cursor/rules/threadctx.mdc` —— 告诉代理在任务前调用 `memory_query`，在任务后调用 `memory_write`。**此操作会在项目中首次启动服务器时自动发生 —— 您无需运行 `init` 即可完成此操作。** 运行 `init` 只会显式触发它并打印结果；无论哪种方式，它都是幂等的（可以安全地重新运行，永远不会重复）。如果您设置了 `THREADCTX_NO_AUTO_RULES=1`，或在每次 `init` 调用时使用 `--no-rules`，则可以完全退出。
相同的指令也会作为MCP `initialize` 握手的一部分发送（协议的 `instructions` 字段），因此它甚至在规则文件存在之前就到达了模型，并且适用于根本不读取项目规则文件的客户端。基于文件的规则在此基础上是对其的补充，因为并非所有MCP客户端都保证会突出显示 `instructions`。
## Claude Code 设置
在您的Claude Code MCP配置中添加（`claude mcp add` 或直接编辑 `~/.claude/mcp.json`）：
```json
{
"mcpServers": {
"threadctx": {
"command": "npx",
"args": ["-y", "threadctx-mcp"],
"env": {
"THREADCTX_MODE": "cloud",
"THREADCTX_API_KEY": "tctx_xxx"
}
}
}
}
```
## Cursor 设置
将相同的块添加到项目根目录中的 `.cursor/mcp.json` 中（或通过Cursor设置 → 工具和MCP）：
```json
{
"mcpServers": {
"threadctx": {
"command": "npx",
"args": ["-y", "threadctx-mcp"],
"env": {
"THREADCTX_MODE": "cloud",
"THREADCTX_API_KEY": "tctx_xxx"
}
}
}
}
```
就是这样 —— 相同的软件包和配置适用于两个客户端，因为MCP是一种可移植的开放协议。
## 环境变量
| 变量 | 是否必需 | 描述 |
|---|---|---|
| `THREADCTX_MODE` | 否 | `local`（默认）或 `cloud` |
| `THREADCTX_API_KEY` | 仅在云模式下需要 | 通过 `cloud/scripts/create-tenant.ts` 发行 |
| `THREADCTX_API_URL` | 否 | 默认值为 `https://threadctx.dev/api/v1`；为自托管而覆盖 |
| `THREADCTX_REPO` | 否 | 覆盖通过 `git remote` 自动检测的仓库 |
| `THREADCTX_DB_PATH` | 否 | 本地模式存储路径；默认值为 `~/.threadctx/local.json` |
| `THREADCTX_NO_AUTO_RULES` | 否 | 设置为 `1` 以禁用自动注入 `CLAUDE.md` / `.cursor/rules/threadctx.mdc` 在服务器启动时 |
## 本地开发
```bash
npm install
npm run dev # 通过tsx运行服务器，监视更改
npm run build # 编译到dist/以供发布
```
## 工具的工作原理
- `memory_write(content, tags?)` —— 代理在解决一个不明显的错误、做出架构决策或学习值得记住的东西后调用此函数。
- `memory_query(task_description, max_results?)` —— 代理在开始有风险或重复的工作之前调用此函数。结果返回时带有一致的署名脚注（`· via threadctx — 共享团队内存（N个命中）`），因此相同的字符串在Claude Code的终端输出或Cursor的代理面板中都是可识别的。
工具描述的编写是为了使模型倾向于主动调用 `memory_query`，并且截至0.3.0，服务器通过两种方式强化了这一点，无需任何设置：MCP `initialize` 响应将相同的指令发送给每个连接的客户端，并且 `CLAUDE.md` / `.cursor/rules/threadctx.mdc` 在首次启动时自动注入。MCP工具仍然从根本上是基于拉取的（没有机制可以强制工具调用），但这三个层面的结合是我们能够构建的最强保证。
## CLI 子命令
| 命令 | 执行的操作 |
|---|---|
| `npx threadctx-mcp` | 运行MCP服务器（Claude Code / Cursor启动时使用）。在项目中首次启动时自动注入项目规则。 |
| `npx threadctx-mcp init [--mode=cloud --api-key=…] [--no-rules]` | 编写 `.threadctx.json` 并显式（重新）应用项目规则块。 |
| `npx threadctx-mcp list [--all] [--full] [--json]` | 显示存储在本地磁盘内存中的内容。 |
