内容
# 代理上下文 MCP 服务器
适用于代理式 AI 编码工具（OpenCode、Antigravity、Claude Code 等）的便携式、与工具无关的内存和代码结构图。
## 🧠 问题
代理式 AI 工具通常将其内存锁定在单个会话中。当您用完上下文令牌或切换到不同的 AI 工具时，您将丢失：
- 您当前正在处理的内容（任务、待处理步骤）。
- 过去技术决策的原因。
- 代码库的结构架构。
## 🚀 解决方案
**代理上下文服务器** 是一种 MCP（模型上下文协议）服务器，它在轻量级、本地 SQLite 数据库（`.agentctx/context.db`）中跟踪工作上下文和代码结构。它提供了一个单一的、便携的内存，该内存跟随 *项目* 而不是 *工具*。
您可以在一个 AI 工具中开始一个任务，达到上下文限制，打开一个完全不同的 AI 工具，并从您离开的地方继续。
## ✨ 功能
* **工作上下文引擎：** 跟踪活跃任务、决策、进度日志和会话中的开放问题。
* **代码结构图：** 使用 `tree-sitter` 解析和映射 `Python`、`JavaScript` 和 `TypeScript` 文件，提取类、函数和方法，而无需将您的代码发送到外部 API。
* **增量索引：** 智能内容哈希确保仅重新索引修改过的文件。
* **项目导出：** 内置工具可立即压缩和备份代理的内存状态。
* **完全本地和私有：** 服务器内部没有 LLM 调用；所有状态通过 SQLite 完全本地保存。
## 🛠️ 先决条件
* [Python 3.10+](https://www.python.org/)
* [uv](https://docs.astral.sh/uv/) （快速 Python 包和项目管理器）
## 📦 安装
1. 将此仓库克隆到您的机器上：
```bash
git clone （用您自己的仓库 URL 替换，一旦您将其推送到 GitHub）
cd agent-context-mcp-server
```
2. 项目使用 `uv` 进行依赖管理。当您运行服务器时，将自动管理所需的包（`mcp`、`tree-sitter`、`tree-sitter-python`、`tree-sitter-javascript`、`tree-sitter-typescript`）。
## ⚙️ MCP 配置
要将此服务器与您首选的代理式 AI 工具（例如 Google Antigravity、OpenCode 或 Claude Code）一起使用，请将以下内容添加到您的 MCP 配置设置中：
```json
{
"mcpServers": {
"agent-context-server": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/agent-context-mcp-server",
"run",
"server.py"
]
}
}
}
```
> **注意：** 将 `/absolute/path/to/agent-context-mcp-server` 替换为实际的克隆仓库路径。服务器将动态创建 `.agentctx/` 目录，在您的 AI 代理当前工作的项目文件夹中。
---
## 🧰 可用工具
连接后，您的 AI 代理将可以访问以下工具：
### 工作上下文
* **`start_task(title)`**：创建新的工作上下文任务。
* **`log_progress(task_id, entry, entry_type)`**：追加进度日志（`step_done`、`error_hit`、`next_step`、`note`）。
* **`log_decision(task_id, decision, reason, symbol_ref)`**：记录技术决策和背后的原因。
* **`add_question(question)` / `resolve_question(question_id)`**：管理开放问题。
* **`resume(task_id?)`**：检索活动任务的完整状态以无缝继续工作。
* **`list_tasks(status?)`**：列出活动、完成、阻塞或废弃的任务。
### 结构图
* **`graph.index(path, languages?)`**：解析文件（`.py`、`.js`、`.ts`、`.jsx`、`.tsx`）并提取结构符号。
* **`graph.get_symbol(name)`**：检索特定符号的文件路径和行号。
* **`graph.trace_calls(symbol_name, direction)`**：跟踪同一文件内的入站或出站函数调用。
* **`graph.get_architecture()`**：返回解析代码库的高级概述，包括文件、符号计数和根入口点。
### 生命周期
* **`project.export()`**：压缩整个 `.agentctx/` 目录以进行安全备份和共享。
---
## 📄 许可证
* **MIT License**
