内容
# Agentic MCP 服务器
**将 Claude、ChatGPT 和任何 LLM 转化为安全、无臃肿的自主编码代理。**
本项目是一个高级、高性能的 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，专为自主编码设计。它为 LLMs 提供安全的本地仓库访问，但与简单地将文件内容转储到上下文窗口并触发限制的幼稚实现不同，该服务器具有 **上下文防臃肿**、**AST 语义导航** 和 **真正的 Git 工作树沙盒**。
> [!WARNING]
> **安全通知**：此工具在您的本地机器上运行，可以执行 shell 命令。托管的 Git 工作树提供了一个隔离的 Git 签出，以防止污染您的主仓库，但它 **不是** 操作系统沙盒。它不限制网络访问或子进程。请始终检查 LLM 打算运行的内容。
---
## 🔥 关键创新
### 1. 智能上下文防臃肿
停止让您的 LLM 上下文窗口膨胀。
* **`workspace_summary`**：代替大规模的统一文件转储，返回工作区的紧凑、高级地图（git 状态、包管理器、关键脚本和模式）。
* **强化文件读取**：`read` 工具强制偏移/限制分页和严格的行范围约束。模型获取所需的内容，精确到行，防止大文件发生灾难性 token 膨胀。
### 2. 真正的 Git 工作树沙盒
在主目录中运行实验性代码、测试或破坏性 LLM 编辑可能会破坏您的热模块替换（HMR）、在 Next.js/Vite 中触发无限循环或破坏您的 `node_modules`。
* **`open_workspace (mode="worktree")`**：自动在项目主目录外部（例如 `~/.agentic/worktrees/`）启动一个隔离的、分离的 `git worktree`。
* LLM 可以破坏事物，通过 `worktree_install_deps` 安装新依赖（安全控制 `allowLifecycleScripts`），或通过 `worktree_sync_changes` 同步未提交的更改，而无需触及您的实时开发环境。
### 3. 语义 AST 导航
服务器动态解析 TypeScript 和 JavaScript（使用内存 LRU 缓存以节省 CPU），为模型提供架构的语义地图。
* **`next_route_map`**：动态映射 Next.js 应用路由器和页面路由器，显示角色（`api`、`page`、`layout`）和动态段。
* **`payload_schema_map`**：分析 Payload CMS 集合以返回字段、钩子和关系的干净地图。
* **`file_dependencies`**：立即映射输出（文件导入）和输入（谁导入文件）依赖。
### 4. 安全编辑和干燥运行
* **`edit_dry_run`**：模拟替换以验证确切的字符串匹配和唯一性，在不保存到磁盘的情况下返回将要编辑的周围上下文。
* **`changed_files_summary`**：使用 `git status --porcelain` 快速、准确地总结修改和新暂存的文件。
### 5. 检查点系统
对于长时间的自主会话，代理可以保存工作区的时间点快照（`checkpoint_save`），列出它们（`checkpoint_list`），如果它走错了架构路径，则回滚（`checkpoint_restore`）。
---
## 🚀 安装和设置
要求：Node `>=22.12.0 <27`
### 通过 NPX 快速启动
配置和运行服务器的最简单方法是使用 `npx`：
```bash
npx -y mcp-agentic-server@1.1.1 doctor
npx -y mcp-agentic-server serve
```
### 手动克隆和构建
如果您更喜欢从源代码运行：
```bash
git clone https://github.com/hugolsramos01-bit/mcp-agentic-server.git
cd mcp-agentic-server
npm ci
npm run build
npm run start
```
### 依赖项
- **必填**：Node.js 和标准操作系统实用程序（Git）。
- **可选（`node-pty`）**：用于在运行交互式 shell 命令时进行交互式伪终端。如果它无法安装，服务器将安全地回退到标准子进程执行。
---
### 设置服务器
**适用于本地客户端（Claude Desktop、Cursor、Roo Code）**：
配置您的 MCP 客户端以启动服务器。在您的 MCP 配置中添加以下内容：
```json
{
"mcpServers": {
"agentic-mcp": {
"command": "npx",
"args": ["-y", "mcp-agentic-server", "serve"],
"env": {
"AGENTIC_ALLOWED_ROOTS": "C:/path/to/projects"
}
}
}
}
```
<details>
<summary><strong>高级：适用于云托管客户端（ChatGPT Web、Claude Web）</strong></summary>
要将云托管代理连接到您的本地机器，请使用安全隧道（例如 Cloudflare Tunnel、ngrok、Pinggy）。
1. 启动您的隧道（例如指向端口 7676）。
2. 启动 MCP 服务器：`npx -y mcp-agentic-server serve`
3. 将您的 MCP 客户端连接到公共 `/mcp` URL。
</details>
---
## 🛠 可用工具
工具表面取决于 `AGENTIC_TOOL_MODE` 设置。
| 模式 | 包含的工具 | 用例 |
|------|---------------|----------|
| **`assistant`** （默认） | 规范的编码工作流：工作区、上下文、读取/搜索、Git、检查点、编辑/干燥运行、包脚本、工作树、诊断和语义地图。 | 带有精选模型指令的完整编码代理工作流。 |
| **`full`** | 基础工具 + `grep`、`glob`、`ls` | 通过 shell 进行手动检查 |
| **`minimal`** | `open_workspace`、`read`、`write`、`edit`、`bash` | 受限表面 |
> **注意：** `assistant` 模式适用于完整的自主编码体验。在您的 `.env` 或环境中设置 `AGENTIC_TOOL_MODE=assistant`。
### 核心工具（始终可用）
| 工具 | 描述 |
|------|-------------|
| `open_workspace` | 打开一个项目。支持 `mode="checkout"` 或 `mode="worktree"`。 |
| `read` | 具有 `startLine`、`endLine`、`offset`、`limit` 的强化文件读取器。 |
| `write` | 创建或覆盖文件。 |
| `edit` | 有针对的字符串替换。 |
| `bash` | 用于没有类型工具的 shell 交互的后备；优先使用 `run_package_script` 进行包脚本和 Git 工具进行 Git 操作。 |
### 助手工具（模式：`assistant`）
| 工具 | 描述 |
|------|-------------|
| `workspace_summary` | 工作区的紧凑架构总结。 |
| `project_bootstrap` | 扫描包管理器、单体仓库边界和基础依赖项。 |
| `read_many` | 一次读取多个文件。 |
| `tree` | 目录树可视化。 |
| `next_route_map` / `payload_schema_map` | Next.js / Payload CMS 模式提取。 |
| `file_dependencies` | 输入和输出依赖关系映射。 |
| `checkpoint_*` | 保存、恢复、列出或删除快照。 |
| `edit_dry_run` | 预览编辑而不写入。 |
| `worktree_*` | 管理隔离的 git 工作树（创建、列出、同步、拆除）。 |
| `worktree_install_deps` | 在托管的工作树中安装依赖项；使用 `verify: true` 加载原生绑定。 |
| `agentic_doctor` | 诊断 Node、包管理器、Git 和原生 SQLite 可用性。 |
| `semantic_pack` | 具有 token 预算的紧凑目标相关总结。 |
| `context_budget` | 估计文件 token 计数。 |
| `expand_compressed_block` | 展开从 `read_compressed` 中省略的块。 |
| `token_audit` | 分析读取的文件的 token 使用情况。 |
| `tournament_*` | 变更的自主评估和判断。 |
| `risk_assess_command` | 在 bash 之前预览策略评估。 |
| `changed_files_summary` | 快速 Git 状态和差异抽象。 |
已弃用的兼容别名默认隐藏，从未出现在模型的标准工作流中。现有客户端可以临时选择加入 `AGENTIC_LEGACY_ALIASES=1`；它们将在下一个主要版本中删除。新客户端必须使用上述规范名称：`edit_dry_run`、`next_route_map`、`payload_schema_map`、`changed_files_summary` 和 `project_bootstrap`。
## 🧠 代理的思维模型
该服务器旨在充当远程 AGI 的“手和眼”。
如果您正在构建自主代理或使用 Claude/ChatGPT 进行编码，请指示您的代理：
1. 始终首先调用 `semantic_pack`、`project_bootstrap` 或 `workspace_summary`。
2. 对大文件使用 `read_compressed` — 使用 `expand_compressed_block` 展开块。
3. 使用 `context_budget` 在读取多个文件之前估计 token 成本。
4. 如果任务涉及运行复杂的 shell 命令或破坏性测试，请使用 `mode="worktree"`。
5. 在执行多行正则表达式或精确字符串替换之前使用 `edit_dry_run`。
## 隔离边界
托管的工作树是一个 **隔离的 Git 签出**，不是操作系统沙盒。它将实验与主签出隔离，但不限制网络访问、子进程、凭证、CPU/内存使用或服务器允许的路径。像对待真实的本地命令一样对待脚本，并优先使用类型化的 Git/脚本工具。Git 工具仅在打开的工作区本身是仓库根目录时才起作用；拒绝祖先仓库以避免暴露 sibling 项目。
## 📝 License & Acknowledgements
在 **MIT License** 下许可。有关更多详细信息，请参见 [LICENSE](LICENSE)。
我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解如何开始。
该项目大量使用了受内部安全架构启发的组件，并感谢开源社区的标准最佳实践。
