内容
# 上下文守护者
基于MCP的AI智能体上下文管理服务 - 将智能体保持在 **10万token智能区**。
通用安装 - 与所有 **MCP兼容的智能体** 兼容：Cursor、Claude Desktop、Cline、Continue、Claude Code等。
> **注意**：中文用户请参考 [README.zh.md](README.zh.md)
## 目录
- [快速入门](#快速入门)
- [功能](#功能)
- [安装](#安装)
- [配置](#配置)
- [工具参考](#工具参考)
- [跨智能体兼容性测试](#跨智能体兼容性测试)
- [架构](#架构)
- [故障排除](#故障排除)
- [最佳实践](#最佳实践)
- [开发](#开发)
## 快速入门
### 1. 通过CLI安装
CLI自动检测机器上的所有支持的智能体，并为每个智能体写入正确的配置块，无需手动JSON。
```bash
# 安装到所有检测到的智能体（推荐）
npx -y context-gatekeeper-cli install --all
# 或选择特定的智能体
npx -y context-gatekeeper-cli install cursor claude-desktop claude-code
# 查看CLI将要操作的内容
npx -y context-gatekeeper-cli status
# 删除条目
npx -y context-gatekeeper-cli uninstall --all
```
支持的智能体：`cursor`、`claude-desktop`、`cline`、`continue`、`claude-code`。
传递 `--local` 以编写项目级配置（例如 `./.cursor/mcp.json`），而不是全局配置。`claude-desktop` 始终为全局。
### 2. 手动配置（高级）
如果您更喜欢自己编写JSON，每个支持的智能体都接受相同的启动命令（`npx -y context-gatekeeper`）。
**Cursor** （`.cursor/mcp.json`）：
```json
{
"mcpServers": {
"context-gatekeeper": {
"command": "npx",
"args": ["-y", "context-gatekeeper"]
}
}
}
```
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`)：
```json
{
"mcpServers": {
"context-gatekeeper": {
"command": "npx",
"args": ["-y", "context-gatekeeper"]
}
}
}
```
**Claude Code** (`.mcp.json`)：
```json
{
"mcpServers": {
"context-gatekeeper": {
"command": "npx",
"args": ["-y", "context-gatekeeper"]
}
}
}
```
在Windows上，GUI应用程序（Cursor，Claude Desktop）可能不会继承shell PATH。如果找不到 `npx`，可以将其包装在 `cmd /c` 中，或使用 `where npx` 返回的绝对路径。
### 3. 设置环境变量（可选）
```bash
# 身份验证（Watchdog Security）
export CG_READ_TOKEN="您的只读令牌"
export CG_WRITE_TOKEN="您的读写令牌"
export CG_WATCHDOG_TOKEN="您的Watchdog令牌"
# 用于语义搜索（可选 - 默认使用TF-IDF）
export OPENAI_API_KEY="您的OpenAI密钥"
# 或
export COHERE_API_KEY="您的Cohere密钥"
```
### 4. 使用它
```typescript
// 存储约束
memory_store({
content: "对所有新文件使用TypeScript严格模式",
priority: "constraint",
project_tags: ["typescript", "code-style"]
});
// 回忆相关记忆
memory_recall({
query: "TypeScript配置",
limit: 5,
search_mode: "hybrid"
});
```
## 功能
- **通用MCP**：与所有MCP兼容的智能体合作
- **14+工具**：存储、回忆、搜索、锚定、压缩、批量操作、智能回忆、双模式执行
- **智能搜索**：关键词 + 语义（TF-IDF/OpenAI/Cohere）+ 混合 + BM25搜索
- **优先级系统**：锚定 > 约束 > 决策 > 偏好 > 事实
- **自动去重**：基于SHA256哈希的重复检测
- **上下文压缩**：自动清理低优先级记忆
- **Watchdog安全**：基于令牌的工具权限控制
- **链后自动化**：在其他工具完成后自动触发工具
- **纯JavaScript**：无需本地编译（sql.js）
- **结构化日志记录**：JSON输出用于日志聚合
### 第一阶段：自动技能风格的约束提取
分析对话回合以提取持久的约束：
```typescript
memory_extract({
conversation_turns: [
{ role: "user", content: "我总是更喜欢使用TypeScript严格模式。" },
{ role: "assistant", content: "我将启用严格模式。" }
],
extract_mode: "all",
min_confidence: 0.5
});
```
### 第二阶段：MemGate风格的智能回忆
语义相似性 + 学习的相关性模式：
```typescript
intelligent_recall({
query: "API实现指南",
conversation_context: "构建新的REST服务",
relevance_threshold: 0.07,
enable_soft_guidance: true
});
```
### 第三阶段：MPR风格的双模式执行
软引导 + 硬可接受性检查：
```typescript
dual_mode_execute({
action: "使用此变量的var关键字",
context: "编写JavaScript代码",
mode: "dual",
soft_guidance_style: "简洁"
});
```
## 安装
### 一键安装CLI
软件包附带一个 `context-gatekeeper-cli` 二进制文件，可以检测机器上的所有支持的MCP智能体，并在每个智能体的配置文件中写入正确的条目。有关命令，请参见上面的[快速入门](#快速入门)。要卸载，请运行 `context-gatekeeper-cli uninstall`。
### 全局安装
```bash
npm install -g context-gatekeeper
npm run build
```
查找全局安装路径：
```bash
npm root -g
```
### 本地安装
```bash
npm install context-gatekeeper
npm run build
```
### 验证安装
```bash
node dist/mcp/server.js --help
```
### CLI参考
`context-gatekeeper-cli` 命令支持：
```
context-gatekeeper-cli install [agent ...] [--all] [--local] [--cwd <dir>]
context-gatekeeper-cli uninstall [agent ...] [--all] [--local] [--cwd <dir>]
context-gatekeeper-cli status [--local] [--cwd <dir>]
context-gatekeeper-cli help
```
支持的智能体：`cursor`、`claude-desktop`、`cline`、`continue`、`claude-code`。
- `--all` 针对所有智能体。没有位置参数且没有 `--all`，CLI打印错误。
- `--local` 编写项目级配置（例如 `./.cursor/mcp.json`），而不是全局配置。`claude-desktop` 始终为全局，不会在 `--local` 下跳过。
- `--cwd <dir>` 覆盖 `--local` 使用的项目根目录。对于CI或预提交钩子中的脚本设置很有用。
## 配置
### 环境变量
#### 身份验证（Watchdog Security）
| 变量 | 描述 | 是否必需 |
| --- | --- | --- |
| `CG_READ_TOKEN` | 只读操作的令牌 | 否 |
| `CG_WRITE_TOKEN` | 读写操作的令牌 | 否 |
| `CG_WATCHDOG_TOKEN` | 具有完全访问权限的令牌（绕过限制） | 否 |
如果未设置令牌，服务器将在宽容模式下运行（所有工具均可访问）。
#### 嵌入式提供程序
| 变量 | 描述 | 默认值 |
| --- | --- | --- |
| `OPENAI_API_KEY` | 用于嵌入的OpenAI API密钥 | - |
| `COHERE_API_KEY` | 用于嵌入的Cohere API密钥 | - |
| `OPENAI_EMBEDDING_BASE_URL` | 自定义OpenAI兼容端点 | https://api.openai.com/v1 |
| `CG_EMBEDDING_PROVIDER` | 嵌入式提供程序：`tfidf`、`openai`、`cohere` | `tfidf` |
#### 日志记录
| 变量 | 描述 | 默认值 |
| --- | --- | --- |
| `CG_LOG_LEVEL` | 最低日志级别：`trace`、`debug`、`info`、`warn`、`error` | `info` |
| `CG_LOG_PRETTY` | 美丽打印JSON输出（`true`或`1`） | - |
| `CG_LOG_TO_FILE` | 启用基于文件的日志记录（`true`或`1`） | - |
| `CG_LOG_FILE_PATH` | 自定义日志文件路径 | `context-gatekeeper.log` |
#### 数据库
| 变量 | 描述 | 默认值 |
| --- | --- | --- |
| `DATA_DIR` | 数据库文件位置 | 平台特定 |
| `CG_DB_FLUSH_INTERVAL_MS` | 多久刷新到磁盘（毫秒） | 30000 |
默认 `DATA_DIR` 位置：
- **Windows**： `%APPDATA%/context-gatekeeper`
- **macOS**： `~/Library/Application Support/context-gatekeeper`
- **Linux**： `~/.context-gatekeeper`
### 运行时配置
使用 `configure_llm` 工具在运行时设置LLM设置：
```typescript
// 配置OpenAI
configure_llm({
provider: "openai",
apiKey: "sk-...",
model: "gpt-4"
});
// 配置Ollama（本地）
configure_llm({
provider: "ollama",
model: "llama3.2",
baseUrl: "http://localhost:11434"
});
```
## 工具参考
### 内存操作
| 工具 | 描述 |
| --- | --- |
| `memory_store` | 存储具有优先级的内存 |
| `memory_recall` | 回忆内存（4种搜索模式） |
| `memory_search` | 全文搜索内存 |
| `memory_anchor` | 永久锚定内存 |
| `memory_stats` | 获取内存统计信息 |
### 批量操作
| 工具 | 描述 |
| --- | --- |
| `memory_store_batch` | 批量存储内存 |
| `memory_delete_batch` | 批量删除内存 |
### 上下文管理
| 工具 | 描述 |
| --- | --- |
| `memory_report_usage` | 报告令牌使用情况 |
| `context_compress` | 触发上下文压缩 |
### 智能回忆（第2阶段）
| 工具 | 描述 |
| --- | --- |
| `intelligent_recall` | MemGate风格的相关性回忆 |
### 约束提取（第1阶段）
| 工具 | 描述 |
| --- | --- |
| `memory_extract` | 从对话中提取约束 |
### 双模式执行（第3阶段）
| 工具 | 描述 |
| --- | --- |
| `dual_mode_execute` | 使用双模式验证操作 |
### 会话管理
| 工具 | 描述 |
| --- | --- |
| `session_store` | 存储会话数据 |
| `session_get` | 获取会话数据 |
| `session_list` | 列出会话密钥 |
| `session_delete` | 删除会话数据 |
### 配置和基础设施
| 工具 | 描述 |
| --- | --- |
| `configure_llm` | 配置LLM提供程序 |
| `after_chain_configure` | 配置链后编排 |
| `project_create` | 创建项目 |
| `db_flush` | 将内存数据库刷新到磁盘 |
| `watchdog_manage` | 管理看门狗令牌 |
### GDPR合规
| 工具 | 描述 |
| --- | --- |
| `gdpr_export` | 以JSON导出所有内存 |
| `gdpr_delete` | 删除内存 |
| `data_summary` | 获取数据摘要 |
### 搜索模式
`memory_recall` 工具支持四种搜索模式：
| 模式 | 描述 | 最适合 |
| --- | --- | --- |
| `keyword` | 简单的子字符串匹配 | 快速、精确匹配 |
| `semantic` | TF-IDF/OpenAI/Cohere嵌入 | 基于意义的回忆 |
| `hybrid` | 结合关键词 + 语义 | 平衡的准确性 |
| `bm25` | Okapi BM25排名 | 文本检索 |
### 链后配置
```typescript
// 列出所有链
after_chain_configure({ action: "list_chains" });
// 禁用链
after_chain_configure({
action: "toggle_chain",
chain_name: "store-then-extract",
enabled: false
});
// 注册自定义链
after_chain_configure({
action: "register_chain",
chain_config: {
name: "store-then-recall",
triggerTool: "memory_store",
followupTool: "memory_recall",
async: true
}
});
```
## 跨智能体兼容性测试
除了单元测试外，Context Gatekeeper还配备了端到端兼容性测试套件，验证MCP服务器在 **完全相同的JSON-RPC合约** 下的行为，该合约由每个支持的智能体运行时使用。
### 测试内容
对于每个支持的智能体，测试套件针对新启动的MCP服务器进程测试四类场景：
| 类别 | 覆盖范围 | 为什么重要 |
| --- | --- | --- |
| **握手** | `initialize` + `tools/list` + 示例读取工具调用 | 确认MCP服务器启动、宣传24种工具并正确回答JSON-RPC |
| **CRUD** | `memory_store` -> `memory_recall` 往返，所有4种搜索模式（`keyword`、`semantic`、`hybrid`、`auto`）、 `memory_delete_batch`、`memory_anchor` | 验证核心存储路径在智能体的stdio传输下工作 |
| **链后** | `after_chain_configure` 列表/切换 + `memory_store` 触发 `memory_extract` 跟进 | 确认进程内链执行器在智能体边界正确连接 |
| **看门狗** | 4x4权限矩阵：`no-token-strict`、`read-token`、`write-token`、`watchdog-token` 对读取和写入探测 | 确保令牌强制执行与安全模型匹配 |
### 支持的智能体
- **Cursor** - 使用 `.cursor/mcp.json` 形状
- **Claude Desktop** - 使用 `claude_desktop_config.json` 形状
- **Cline** - VSCode工作区MCP服务器配置
- **Continue.dev** - 使用 `experimental.modelContextProtocolServers` 形状
- **Claude Code** - 使用 `.mcp.json` 形状
### 运行测试
```bash
# 对所有5种智能体运行测试
npm run test:agents
# 对单个智能体运行测试
npm run test:agents -- cursor
# 对子集运行测试
npm run test:agents -- cursor cline claude-code
```
### 工作原理
每个适配器为代理编写代理的确切MCP配置JSON，然后使用与代理运行时相同的 `command` + `args` 启动MCP服务器。测试套件通过stdio发送真正的MCP JSON-RPC消息 - 与Cursor、Claude Desktop等内部使用的线协议相同。
关键设计选择：
- **每个场景一个进程**：每个测试用例启动一个全新的MCP服务器，因此失败指向特定的场景，而不是共享状态
- **隔离的 `DATA_DIR`**：每个智能体拥有自己的数据库目录，消除跨测试污染
- **通过env vars注入令牌**：`CG_READ_TOKEN`、`CG_WRITE_TOKEN`、`CG_WATCHDOG_TOKEN` 作为环境变量传递，匹配生产部署
- **两种报告格式**：JSON用于CI集成，Markdown用于人工审查
### 报告输出
运行后， `scripts/reports/` 下会出现两个文件：
```
scripts/reports/report-<timestamp>.json # 可机器读取
scripts/reports/report-<timestamp>.md # 人工可读
```
Markdown报告按智能体分组结果：
```
## cursor
状态：14/14通过
| 工具 | 成功 | 延迟（毫秒） | 错误 |
| --- | --- | --- | --- |
| initialize+memory_stats | OK | 528 | |
| memory_store | OK | 9 | |
...
```
### 示例运行
```
[cursor] handshake ... handshakeOk=true tools=24 sampleOk=true 528ms
[cursor] CRUD ... 8/8场景通过（2508ms）
[cursor] 链后 ... allOk=true 479ms
[cursor] 看门狗 ... 4/4单元格ok（9985ms）
[cross-agent-test] 总结：
总计： 70
通过： 70
失败： 0
```
### 添加新代理
1. 创建 `scripts/agents/my-agent.ts` 扩展 `BaseAgentAdapter`
2. 实现 `name` 和 `buildSpawnCommand()`（或重写 `spawnAgent()`）
3. 添加静态 `buildMcpConfig(mcpBin)` 返回代理的确切配置形状
4. 在 `scripts/cross-agent-test.ts` 中注册适配器
测试套件会自动拾取任何新的适配器自动检测任何新适配器并使用 `buildAdapters()` 进行构建。
## 架构
### 系统概述
```
┌─────────────────────────────────────────────────────────────────┐
│ MCP 代理（Cursor / Claude / Cline / Continue / Claude Code） │
└─────────────────────────┬───────────────────────────────────────┘
│ MCP 协议
▼
┌─────────────────────────────────────────────────────────────────┐
│ 上下文守护者MCP服务器 │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 监视狗安全 │ │
│ │ 令牌验证 → 权限检查 → 工具执行 │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ 链后执行 │ │ LLM │ │ 嵌入式提供程序 │ │
│ │ 执行器 │ │ 服务 │ │ （TF-IDF/OpenAI/Cohere） │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 内存服务 / 约束提取器 │ │
│ │ / 智能回忆 / 双模式 │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ SQLite 数据库（sql.js） │
│ WAL 模式 + 定期刷新 │
└─────────────────────────────────────────────────────────────────┘
```
### 监视狗架构
监视狗安全模型提供基于令牌的访问控制：
```
┌──────────────────────────────────────────────────────────────────┐
│ 令牌类型： │
├──────────────────────────────────────────────────────────────────┤
│ ┌────────────┬────────────┬──────────────────────┐ │
│ │ 读取 │ 写入 │ 监视狗 │ │
│ ├────────────┼────────────┼──────────────────────┤ │
│ │ 回忆 │ 存储 │ 所有操作 │ │
│ │ 搜索 │ 锚定 │ （绕过所有 │ │
│ │ 统计 │ 压缩 │ 限制） │ │
│ │ 智能回忆 │ 批量 │ │ │
│ │ （软模式）│ 删除 │ │ │
│ │ 创建 │ │ │
│ └────────────┴────────────┴──────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```
### 目录结构
```
src/
├── mcp/ # MCP服务器实现
│ ├── server.ts # 主要MCP服务器入口
│ └── tools/ # 工具实现
│ ├── memory-store.ts
│ ├── memory-recall.ts
│ ├── memory-extract.ts # 阶段1：AutoSkill
│ ├── intelligent-recall.ts # 阶段2：MemGate
│ ├── dual-mode-execute.ts # 阶段3：MPR
│ └── ...
├── schema/ # 数据库模式和操作
├── services/ # 业务逻辑
│ ├── embedding-provider.ts # 多提供商支持
│ ├── llm.ts # LLM摘要
│ └── compressor/ # 上下文压缩
├── utils/
│ ├── db.ts # 数据库包装器（sql.js）
│ ├── watchdog.ts # 基于令牌的安全
│ ├── after-chain.ts # 链后工具
│ └── logger.ts # 结构化JSON日志记录
└── models/ # 类型定义
```
### 内存去重功能失效
**原因**: 语义相同的记忆内容哈希值不同。
**解决方案**:
1. 使用相同的措辞描述重复的记忆内容
2. 哈希值为归一化内容的SHA256 - 轻微的变动会产生不同的哈希值
### 搜索结果不符合预期
**原因**: 错误的搜索模式或嵌入式提供程序。
**解决方案**:
```typescript
// 对于精确匹配，使用关键词模式
memory_recall({
query: "精确短语",
search_mode: "keyword"
});
// 对于语义含义，使用混合或语义模式
memory_recall({
query: "身份验证",
search_mode: "hybrid"
});
```
### 大型语言模型提取失败
**原因**: 大型语言模型提供程序未配置或API错误。
**解决方案**:
```typescript
// 首先配置大型语言模型
configure_llm({
provider: "openai",
apiKey: "您的密钥",
model: "gpt-3.5-turbo"
});
// 如果大型语言模型不可用，则退回到基于规则的提取
memory_extract({
conversation_turns: [...],
min_confidence: 0.3 // 更低的阈值
});
```
## 最佳实践
### 优先级分配
| 优先级 | 使用场景 |
|----------|-------------|
| `anchored` | 必须严格遵守的关键规则 |
| `constraint` | API约定、编码标准 |
| `decision` | 架构选择、已选方法 |
| `preference` | 编码风格、工作流偏好 |
| `fact` | 项目详情、历史背景 |
```typescript
// 良好：关键的项目范围内的约束
memory_store({
content: "绝不直接提交到主分支",
priority: "anchored",
project_tags: ["git-workflow"]
});
// 避免：常识
memory_store({
content: "JavaScript 使用 camelCase",
priority: "fact"
});
```
### 项目标签策略
使用一致的、分层结构的标签：
```typescript
memory_store({
content: "新功能使用 React 18",
project_tags: ["frontend:react", "version:18"]
});
```
### Token 预算管理
定期监控和压缩上下文：
```typescript
// 接近限制时报告token使用情况
memory_report_usage({
used_tokens: 85000,
max_tokens: 100000
});
// 需要时触发压缩
context_compress({
target_ratio: 0.6 // 目标60%的最大token数
});
```
### Watchdog Token 安全
使用最小权限原则：
```bash
# 主代理：只读token
CG_READ_TOKEN="agent-read-token"
# 管理员代理：写入token
CG_WRITE_TOKEN="admin-write-token"
# 紧急情况：watchdog token（仅限受信任的进程）
CG_WATCHDOG_TOKEN="emergency-token"
```
### 何时使用哪种搜索模式
| 场景 | 推荐模式 |
|----------|----------------|
| 精确的代码片段 | `keyword` |
| 已知的约束文本 | `keyword` |
| 通用概念召回 | `semantic` 或 `hybrid` |
| 多样化知识检索 | `bm25` |
| 基于意图的召回 | `hybrid` |
### 链后使用
启用自动工具链以减少手动工具调用：
```typescript
// 存储记忆后自动提取约束
after_chain_configure({
action: "toggle_chain",
chain_name: "store-then-extract",
enabled: true
});
```
## 开发
```bash
# 安装依赖
npm install
# 编译TypeScript
npm run build
# 运行单元测试
npm test
# 跨代理兼容性测试（在所有支持的代理上启动MCP服务器）
npm run test:agents
# 单个代理的跨代理测试
npm run test:agents -- cursor
# 监视模式（自动重新编译）
npm run dev
# 类型检查
npm run lint
```
参见 [跨代理兼容性测试](#跨代理兼容性测试) 以了解 `scripts/agents/` 和 `scripts/tests/` 下的测试框架的详细信息。
## 灵感来源
- **AutoSkill**：从对话中提取经验驱动的技能
- **MemGate**：推理时使用学习的相关性进行内存过滤
- **Meta-Policy Reflexion (MPR)**：软引导 + 硬可接受性检查
## License
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器