内容
# 智能代理上下文图
`智能代理上下文图` 是一个用于 AI 编程代理的本地 MCP 服务器。它帮助 Antigravity、Codex、Claude Code 和 Cursor 等工具在编辑项目之前了解项目。
它提供：
- 本地代码知识图
- 文件编辑前的范围检查
- 仅追加的推理日志
- 用于测试、安全、API、身份验证和架构的本地最佳实践笔记
所有操作都在您的机器上运行。没有 SaaS 后端、遥测、分析、GitHub API 调用或运行时网络调用。
```mermaid
flowchart LR
App["您的项目"] --> MCP["智能代理上下文图 MCP 服务器"]
Antigravity["Antigravity"] --> MCP
Codex["Codex"] --> MCP
Claude["Claude Code"] --> MCP
Cursor["Cursor"] --> MCP
MCP --> Graph["图 JSONL"]
MCP --> Logs["推理日志"]
MCP --> Scope["范围锁定"]
```
## 要求
- Node.js 20 或更新版本
- npm
- Git
- Windows、macOS 或 Linux
## 安装
克隆此工具到任意方便的位置，不需要放入每个应用程序项目中，而是放入用户配置文件中以实现全局访问
```bash
git clone https://github.com/Raviraj2024/Agent-Context-Graph.git
cd Agent-Context-Graph
npm install
npm run build
npm test
npm link
```
在 `npm link` 之后，从任何文件夹运行此命令：
```bash
智能代理上下文图 status
```
推荐的文件夹布局：
```text
Projects/
Agent-Context-Graph/ # 此工具
my-app/ # 您的实际项目
```
## 在项目中使用
进入您要让 AI 工具工作的项目：
```bash
cd /path/to/my-app
智能代理上下文图 init
智能代理上下文图 status
```
这会创建：
```text
my-app/
.agent-context-graph/
config.json
graph/
logs/
```
每个项目只需运行一次 `智能代理上下文图 init`。
## Antigravity 设置
使用 Antigravity 的 MCP 配置格式：
```json
{
"mcpServers": {
"智能代理上下文图": {
"command": "智能代理上下文图",
"args": ["serve"],
"env": {
"AGENT_CONTEXT_GRAPH_ROOT": "/绝对路径/to/my-app"
}
}
}
}
```
Windows 示例[推荐]：
```json
{
"mcpServers": {
"智能代理上下文图": {
"command": "智能代理上下文图",
"args": ["serve"],
"env": {
"AGENT_CONTEXT_GRAPH_ROOT": "C:/Users/<用户配置文件>/.../my-app"
}
}
}
}
```
如果您不使用 `npm link`，请直接使用 Node：
```json
{
"mcpServers": {
"智能代理上下文图": {
"command": "node",
"args": [
"C:/Users/<用户配置文件>/agent-context-graph/dist/bin/智能代理上下文图.js",
"serve"
],
"env": {
"AGENT_CONTEXT_GRAPH_ROOT": "C:/Users/<用户配置文件>/.../my-app"
}
}
}
}
```
保存 MCP 配置后重启 Antigravity。
## Codex、Claude Code、Cursor
在目标项目中，只需为使用的平台运行命令：
```bash
智能代理上下文图 connect codex
智能代理上下文图 connect claude-code
智能代理上下文图 connect cursor
```
这些命令会写入项目本地的 MCP 配置文件：
- Codex：`.codex/config.toml`
- Claude Code：`.claude/mcp.json`
- Cursor：`.cursor/mcp.json`
## 提示
在 Antigravity 或其他编码代理中使用此类提示：
```text
使用智能代理上下文图 MCP 服务器进行编辑。
首先检查项目图，刷新它，查询相关最佳实践，
声明任务范围，检查编辑前的范围，并记录每次更改。
在最终答案之前，请自己运行实际的应用程序/测试命令。
如果命令失败，因为缺少依赖项，请在范围内安全地修复它
或报告确切的阻止器。不要给我一个未经测试的运行命令。
现在实现：<您的任务>
```
## 代理的工作方式
MCP 服务器告诉代理：
1. 检查项目图
2. 刷新过时的图数据
3. 读取相关的最佳实践笔记
4. 声明计划更改的文件或节点
5. 在每次写入前检查范围
6. 在敏感或超出范围的编辑之前询问用户
7. 记录每次更改及其推理
8. 在最终响应之前运行实际的应用程序/测试命令
服务器无法强制每个 AI 平台遵守，但这些指令通过 MCP 公开，代理可以自动遵循它们。
## 有用的命令
```bash
智能代理上下文图 init
智能代理上下文图 status
智能代理上下文图 serve
智能代理上下文图 reset
智能代理上下文图 connect codex
智能代理上下文图 connect claude-code
智能代理上下文图 connect cursor
```
- `init`：为当前项目构建图
- `status`：显示图/缓存状态
- `serve`：启动 MCP 服务器
- `reset`：重建本地 SQLite 缓存
- `connect`：为支持的客户端添加 MCP 配置
## MCP 工具
服务器公开这些工具：
- `get_project_overview`
- `init_or_refresh_graph`
- `get_node_context`
- `get_blast_radius`
- `get_definitive_path`
- `query_best_practices`
- `declare_task_scope`
- `check_scope`
- `record_change`
- `get_node_history`
## 提交内容
从目标项目提交这些文件：
```text
.agent-context-graph/config.json
.agent-context-graph/graph/nodes.jsonl
.agent-context-graph/graph/edges.jsonl
.agent-context-graph/logs/*.jsonl
.agent-context-graph/change-index.json
```
忽略这些文件：
```gitignore
.agent-context-graph/cache.sqlite
.agent-context-graph/cache.sqlite-*
.agent-context-graph/.lock
```
## 支持的代码
当前索引支持：
- TypeScript 和 TSX
- JavaScript 和 JSX
- Python
图存储签名、文档字符串、行号、标签和哈希值。它不存储完整的源代码主体。
## 故障排除
### `智能代理上下文图` 命令未找到
从克隆的工具存储库运行此命令：
```bash
npm link
```
或使用 Antigravity 设置中显示的直接 Node 命令。
### Antigravity 连接但看到错误的项目
检查此值：
```json
"AGENT_CONTEXT_GRAPH_ROOT": "/绝对路径/to/my-app"
```
它必须指向您要让 Antigravity 编辑的项目。
### 图为空
在目标项目中运行：
```bash
智能代理上下文图 init
```
### 缓存损坏
运行：
```bash
智能代理上下文图 reset
```
这只删除可重建的 SQLite 缓存。它不会删除图快照或日志。
### `npm install` 在 `better-sqlite3` 上失败
使用 Node.js 20 或更新版本。如果 npm 尝试编译 `better-sqlite3`，请安装您所在平台的正常 C/C++ 构建工具并重新运行：
```bash
npm install
```
## 开发
```bash
npm install
npm run build
npm test
```
## 许可证
MIT
