Agentic MCP

Agentic MCP — 面向 ChatGPT Developer Mode 的本地编码工具

项目网站 · GitHub 仓库 · npm 软件包 · MCP Registry

通过 MCP Developer Mode 将兼容的 ChatGPT Web 账户连接到本地编码工具。

Agentic MCP 通过安全的模型上下文协议（MCP）服务，将 ChatGPT Web Developer Mode 连接到本地代码仓库。它支持结构化文件编辑、Shell 执行、Git 工作树、语义导航和检查点。

ChatGPT Web → Developer Mode → HTTPS Tunnel → Agentic MCP → Local Repository

警告

安全提示：此工具在本地计算机上运行，可以执行 Shell 命令。受管理的 Git 工作树会提供隔离的 Git 检出，以防污染主代码仓库，但它不是操作系统沙箱，也不会限制网络访问或子进程。请始终检查大模型准备执行的操作。

说明

免责声明：Agentic MCP 是一个独立的开源项目，与 OpenAI 无关，也未获其赞助或认可。ChatGPT 和 OpenAI 是 OpenAI 的商标。维护者已使用 ChatGPT Plus 的 Developer Mode 和 HTTPS 隧道进行了测试。MCP 功能是否可用取决于用户的 ChatGPT 套餐、工作区配置以及 OpenAI 当前的推出情况。

🌐 官方 MCP Registry

Agentic MCP 已发布至官方 MCP Registry，名称为： io.github.hugolsramos01-bit/mcp-agentic-server

可在本地安装并运行，以供 Claude Desktop、Cursor 或其他本地 MCP 客户端使用：

npx -y mcp-agentic-server@latest stdio

---

⚡ 快速入门：3 分钟完成 ChatGPT Plus 设置

使用现有的 Web 套餐，将 ChatGPT Web 变为你的主要本地编码 Agent：

1. 初始化并启动服务：

   npx -y mcp-agentic-server@latest init
   npx -y mcp-agentic-server@latest serve
   

2. 通过 HTTPS 隧道公开本地端口（7676）：

   ngrok http 7676
   

3. 在 ChatGPT Web 中启用 Developer Mode：

   • 前往 chatgpt.com > 设置 > 应用 / Developer Mode（或 插件 / 应用）。
   • 启用 Developer Mode。

4. 连接自定义 MCP 应用：

   • 添加新的自定义 MCP 应用。
   • 输入以 /mcp 结尾的公开 ngrok HTTPS URL：

     https://YOUR-SUBDOMAIN.ngrok.app/mcp
     

5. 完成 OAuth 身份验证：

   • 出现本地浏览器 OAuth 授权提示时，完成授权。

6. 开始编码：

   • 在新的 ChatGPT Web 聊天中启用自定义 MCP 应用，并输入提示词：

     "使用 open_workspace 打开工作区 C:/path/to/project，并总结其架构。"

---

🙋 常见问题（FAQ）

这适用于 ChatGPT Plus 吗？

维护者已通过 Developer Mode 和公开 HTTPS 隧道（ngrok、Cloudflare Tunnel 等）使用 ChatGPT Plus 进行了测试。可用性可能因账户、地区、套餐和推出情况而异。

这会如何影响我的用量限制和账单？

通过 ChatGPT Developer Mode 直接连接时，模型用量由用户的 ChatGPT 账户处理，而非 OpenAI Platform API 密钥。适用的限制取决于用户的套餐和 OpenAI 政策。

是否需要 OpenAI API 密钥？

不需要 OpenAI 模型 API 密钥。MCP 服务和隧道的身份验证与模型 API 计费相互独立。

这是 Codex 或 Claude Code 的替代方案吗？

是的。它为 ChatGPT Web 提供完整的本地编码能力：文件检查、精确到行的结构化编辑、Shell 执行、Git 工作树、AST 导航和检查点。

---

🔐 Release 1.8.1 安全与隔离

1.8.1 版将工作区子进程与 Agentic MCP 控制平面隔离。Shell 命令、包脚本、进程会话、依赖项安装和锦标赛验证不再继承 AGENTIC_* 服务凭据/配置。使用 AGENTIC_HOST 和 AGENTIC_PORT 绑定 MCP 服务；仍接受旧版 HOST / PORT，但如果它们用于配置 Agentic，就不会传递到工作区命令中。

结构化 grep 也针对本地代码仓库进行了强化：它会排除 .git / Agentic 检查点内部文件、类似密钥的 .env 和私钥文件，以及 Windows nul 路径，同时正确遵循公开的 include glob。

🚀 Release 1.8.0 亮点

1.8.0 版将 read_many 从单纯的多文件读取器升级为有界的复合检查工具：

1. 一次往返，执行多项相关检查 — 有序条目可以混合精确读取/范围读取、带上下文的限定范围词法匹配，以及限定范围的 glob。
2. 共享输出预算 — 近似序列化证据、返回行数和唯一文件数的限制适用于整个调用；较早的条目具有明确优先级，glob 结果会返回仍能放入预算的有用子集，响应还会单独报告估算的最终载荷开销。
3. 去重上下文 — 同一文件中重叠的匹配窗口会在发送给模型前合并。
4. 逐步缩小范围 — 仅在架构确实未知时才进行广泛探索；一旦目标区域明确，就会引导 Agent 执行有界的复合检查，而不是重新收集广泛上下文。
5. 跨平台有界发现 — Git 感知的文件列表即使在限定范围的结果为空时也会遵循忽略规则，并提供有界的非 Git 后备方案和明确的扫描截断元数据。匹配条目还可以使用 include glob 筛选文件。
6. 可选的有界正则表达式 — 默认仍使用字面搜索；显式启用正则表达式模式时，会拒绝若干高风险回溯结构，限制扫描字节数，并跳过异常长的行，避免单次搜索独占服务资源。
7. 故障时关闭的资源限制 — 不兼容的操作字段会被拒绝，而非忽略；仍支持旧版 paths 调用；复合读取会限制路径/文件/源字节加载量以及诊断字符串长度，避免范围狭窄的请求意外生成过大的文件系统或响应载荷。

🚀 Release 1.6.0 亮点

1.6.0 版着重缩短编码循环的延迟，同时不削弱 1.5.0 版引入的安全和验证边界：

1. 三种命令安全模式 — safe 仍为默认模式；trusted 支持实用的内联脚本编写和 Shell 文件写入，同时保留破坏性命令防护；full 可用于明确允许不受限制的本地执行。
2. 按需匹配的编码工作流 — QUICK、STANDARD 和 CRITICAL 级别的更改不再承担相同的 PVDL 和验证成本；对于要求严格执行 PVDL 的环境，仍可显式启用严格模式。
3. 停止探索原则 — 直接检查已知文件和符号，而不是仅为再次确认已经明确的目标就触发广泛的启动/上下文探索。
4. 有界的快速上下文 — read_many 默认上限为 12k tokens；快速任务上下文会将大型代码区域读取限制在 160 行的锚点窗口内；文件索引在模型正常推理间隔期间保持热状态。
5. 更快的 QUICK 审查 — 设置 AGENTIC_WIDGETS=changes 时，单文件 edit/write 修改会直接附带审查界面，不再需要多余的聚合式 show_changes 往返。

🔥 关键创新

1. 智能上下文防膨胀

避免耗尽大模型的上下文窗口，并保留 ChatGPT Web 的消息额度。

• workspace_summary：不再返回庞大的统一文件转储，而是提供工作区的精简高级概览（Git 状态、包管理器、关键脚本和架构）。
• 强化文件读取：read 工具强制使用偏移量/限制分页，并严格约束行范围。模型只会获取所需内容，精确到行，避免大型文件导致令牌量暴涨。

2. 真正的 Git Worktree 沙箱

在主目录中运行实验性代码或测试，或执行破坏性的 LLM 编辑，可能会破坏热模块替换（HMR）、触发 Next.js/Vite 无限循环，或扰乱 node_modules。

• open_workspace (mode="worktree")：自动在项目主目录之外创建隔离的分离式 git worktree（例如 ~/.agentic/worktrees/）。
• 大模型可以随意修改内容，通过 worktree_install_deps 安装新依赖（安全控制 allowLifecycleScripts），或通过 worktree_sync_changes 同步未提交的更改，所有操作都不会影响正在运行的开发环境。

3. 语义 AST 导航

服务会动态解析 TypeScript 和 JavaScript（使用内存中的 LRU 缓存以节省 CPU），为模型提供架构的语义映射。

• next_route_map：动态映射 Next.js App Router 和 Pages Router，展示角色（api、page、layout）和动态片段。
• payload_schema_map：分析 Payload CMS 集合，返回字段、钩子和关系的清晰映射。
• file_dependencies：即时映射文件的外部依赖（该文件导入了什么）和内部依赖（哪些文件导入了该文件）。

4. 安全编辑与试运行

• edit_dry_run：模拟替换，以验证字符串是否精确匹配且唯一，并返回拟编辑内容的上下文，但不会保存到磁盘。
• changed_files_summary：使用 git status --porcelain 快速准确地汇总已修改和新暂存的文件。

5. 检查点系统

对于长时间的自主会话，Agent 可以保存工作区在某个时间点的快照（checkpoint_save）、列出快照（checkpoint_list），并在架构方向有误时回滚（checkpoint_restore）。

---

💻 本地与桌面 MCP 客户端（Claude Desktop、Cursor、Roo Code）

如果你更喜欢使用桌面 MCP 宿主，请将客户端配置文件设置为使用 stdio 传输：

{
  "mcpServers": {
    "agentic-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-agentic-server@latest", "stdio"],
      "env": {
        "AGENTIC_ALLOWED_ROOTS": "C:/path/to/projects"
      }
    }
  }
}

---

🛠 可用工具参考

可用工具取决于 AGENTIC_TOOL_MODE 设置。

模式	包含的工具	使用场景
assistant（默认）	标准编码工作流：工作区、上下文、读取/搜索、Git、检查点、编辑/试运行、包脚本、worktree、诊断和语义映射。	配备精选模型指令的完整编码 Agent 工作流。
full	基础工具 + grep、glob、ls	通过 shell 手动检查
minimal	open_workspace、read、write、edit、bash	受限工具集

注意： 建议使用 assistant 模式，以获得完整的智能编码体验。在 .env 或环境变量中设置 AGENTIC_TOOL_MODE=assistant。

命令安全模式

工具模式和命令安全彼此独立。AGENTIC_SECURITY_MODE 控制哪些 Shell 命令可以通过策略引擎：

安全模式	行为
safe（默认）	严格的命令策略。阻止内联脚本、Shell 文件写入结构和破坏性命令。
trusted	允许 python -c、node -e、重定向、heredoc 和 Shell 原地写入，同时继续保护系统免受破坏性操作影响。
full	绕过命令策略限制，包括破坏性命令规则。

使用 agentic config set securityMode safe|trusted|full 保存设置，然后重启服务。OAuth 仍为必需项。Shell 不是 OS 沙箱，可能访问本地用户帐户可访问的任何内容，因此只有在明确需要时才应启用 trusted，尤其是 full。

核心工具（始终可用）

工具	描述
open_workspace	打开项目。支持 mode="checkout" 或 mode="worktree"。
read	加固的文件读取工具，支持 startLine、endLine、offset、limit。
write	创建或覆盖文件。
edit	定向字符串替换。
bash	用于没有专用工具的 Shell 交互的备用工具；运行包脚本时优先使用 run_package_script，操作 Git 时优先使用 Git 工具。
visual_review	在响应式桌面、笔记本电脑、平板电脑和手机视口中截取本地 Web 应用，并将 PNG 截图直接返回给模型。支持自定义视口；仅限本地 URL。

助手工具（模式：assistant）

工具	描述
workspace_summary	工作区的精简架构摘要。
project_bootstrap	扫描包管理器、monorepo 边界和基础依赖。
read_many	有界组合式检查：在一次有序调用中执行精确读取/范围读取、限定范围的匹配+上下文（可选文件 include glob），以及限定范围的 glob，并共享序列化证据、行数和文件数预算，同时报告负载成本。
tree	目录树可视化。
next_route_map / payload_schema_map	提取 Next.js / Payload CMS 架构。
file_dependencies	内部和外部依赖关系图。
checkpoint_*	保存、恢复、列出或删除快照。
edit_dry_run	预览编辑而不写入。
worktree_*	管理隔离的 git worktree（创建、列出、同步、拆除）。
worktree_install_deps	在托管的 worktree 中安装依赖；使用 verify: true 加载原生绑定。
agentic_doctor	诊断 Node、包管理器、Git 和原生 SQLite 是否可用。
semantic_pack	在令牌预算内生成与目标相关的精简摘要。
context_budget	估算文件的令牌数量。
expand_compressed_block	展开 read_compressed 中省略的区块。
token_audit	分析已读取文件的令牌用量。
tournament_*	自主评估和判断变更。
risk_assess_command	在运行 bash 前预览策略评估结果。
changed_files_summary	快速概述 Git 状态和差异。
task_context	根据聚焦路径计算 RiskProfile（风险级别、评分、影响范围）。
suggest_checks	提供建议的规划器，返回确定性的 VerificationPlan。

验证与风险（在 1.5.0 中扩展）

风险与验证流程会强制执行严格、确定性的规划。

• task_context 现在会生成一个 RiskProfile，综合考虑敏感配置、扇出范围、与测试的接近程度以及分析置信度。
• suggest_checks 会返回一个 VerificationPlan，且仅供参考（不会执行命令）。会排除会产生修改的检查和不存在的脚本。置信度较低时可以提升 policyLevel，但不会改变内在的 riskLevel。当本地 Git 元数据不可用时，规划器会根据声明的目标和重点路径使用 goal_discovery，而不是继承上级仓库。

支持的输入：

{
  workspaceId: string;
  changedPaths?: string[]; // Actual paths changed
  goal?: string;           // Optional goal for discovery
  taskType?: "auto" | "bug_fix" | "feature" | "refactor" | "security_review" | "migration" | "frontend" | "release";
  focusPaths?: string[];   // Specific files to focus on

  // Legacy compatibility transition (deprecated)
  paths?: string[];
  scope?: "changed" | "workspace";
  level?: "minimal" | "recommended" | "full";
}

默认情况下，已弃用的兼容别名会被隐藏，且不会出现在模型的标准工作流中。现有客户端可以暂时通过 AGENTIC_LEGACY_ALIASES=1 启用这些别名；它们将在下一个主要版本中移除。新客户端必须使用上述规范名称：edit_dry_run、next_route_map、payload_schema_map、changed_files_summary 和 project_bootstrap。

🧠 Agent 的思维模型

此服务旨在充当远程 AGI 的“手和眼”。 如果你正在构建自主 Agent，或使用 Claude/ChatGPT 编码，请指示你的 Agent：

1. 逐步缩小范围。 如果尚不清楚哪些文件相关，请使用 task_context；如果已经有明确的目标，则跳过广泛发现。
2. 使用 read_many，在一次往返中批量读取相关的精确内容、检查匹配项及其上下文，并执行限定范围的 glob 搜索。将最重要的项目放在前面，因为项目顺序决定预算优先级。
3. 仅当确实不清楚更广泛的领域结构或文件间关系时，才使用 semantic_pack；当实现目标已足够明确时，停止广泛发现。
4. 使用 read_compressed 快速了解大型文件的整体内容——编辑前展开被省略的代码块。
5. 如果任务涉及运行复杂的 shell 命令或破坏性测试，请使用 mode="worktree"；对于含糊或有风险的替换，请先使用 edit_dry_run。

隔离边界

受管理的工作树是隔离的 Git 检出目录，不是操作系统沙箱。它能让实验与主检出目录隔离，但不会限制网络访问、子进程、凭据、CPU/内存使用，或服务本身允许访问的路径。请将脚本视为真实的本地命令，并优先使用类型化的 Git/脚本工具。只有当打开的工作区本身就是仓库根目录时，Git 工具才会运行；上级仓库会被拒绝，以避免暴露同级项目。

📝 许可证与致谢

本项目基于 MIT License 授权。详情请参阅 LICENSE。

本项目大量采用了受内部安全架构启发的组件，并感谢开源社区提供的标准最佳实践。

欢迎贡献！请参阅 CONTRIBUTING.md 了解如何开始。