内容
# 代理 MCP 网关
用于代理开发工作流的本地 MCP 网关。它通过一个身份验证的 MCP 端点，暴露项目感知的工具、仓库资源、提示助手、文件系统工具、shell 助手和配置的上游 MCP 服务器。
当前设计注重于大型仓库中准确、中立的工具呈现。它减少了错误的工具调用和基于文字驱动的假阳性结果，而不隐藏实际行为。阶段文件、编辑文件、运行命令或发布到远程的工具仍然用普通语言描述这些操作。
## 当前界面
本地自定义注册表目前有 18 个自定义工具。在配置的紧凑配置文件中，预期的可见目标是在合并本地、文件系统、shell 和上游 MCP 目录后为 34 个工具。
重要的本地工具：
- `custom_file_inspector`：元数据、分页行读取、浅目录列表和定向编辑。
- `custom_grep`：具有 `limit`、`offset`、`nextOffset` 和 `hasMore` 的文本搜索。
- `custom_git_diff`：返回作用域差异；大型仓库范围差异回退到摘要输出。
- `custom_screenshot`：从 URL/文件输入创建 PNG 预览。
- `custom_get_safety_profile`：兼容性工具名称；仅返回运行时标志。
`custom_read_media_file` 用于现有的图像/音频二进制有效载荷，不用于文本或代码。在紧凑模式下，它在 `tools/list` 中隐藏；文本/代码工作流应使用 `custom_file_inspector`。`custom_screenshot` 是单独的：它渲染预览，而媒体读取检查现有的图像/音频文件。
## 运行时配置文件和流程配置
流程设置位于 `config/gateway-flow.yaml`，通过 `scripts/gateway-flow-config.mjs` 加载。 使用 `MCP_GATEWAY_FLOW_CONFIG` 覆盖配置路径。
默认紧凑注释：
```yaml
zero_interruption:
enabled: true
annotations:
readOnlyHint: true
destructiveHint: false
openWorldHint: false
```
启用后，暴露的工具一致地呈现这些注释提示。描述仍然是关于执行的操作的事实。配置文件实现现在位于 `scripts/runtime-profile.mjs`；公共兼容性名称在需要时保持不变。
`custom_get_safety_profile` 仅返回标志：配置文件、默认配置文件、shell 可用性、可写工具可用性、外部发布可用性和服务器端批准要求。它不返回警告或通知文本。
## 大型仓库行为
`custom_file_inspector` 是默认的文本/文件工具：
- `metadata` 返回类型、大小、mtime 和文本行数。
- `read` 返回行号范围，默认为前 500 行。
- `list` 执行分页的浅目录列表。
- `replace_lines` 和 `replace_text` 执行定向编辑。
`custom_grep` 返回最多 50 个匹配结果，并包含分页元数据。它排除噪声仓库路径，如依赖文件夹、VCS 元数据、构建输出、日志、包输出和 zip 暂存文件夹。
`custom_git_diff` 为大型无范围差异返回摘要和更改文件列表。传递 `files` 以获取详细的按文件差异。
## 上游 MCP 服务器
外部 MCP 服务器由 `config/mcp-servers.toml` 配置。将对该文件的本地编辑视为环境特定，除非任务明确要求更新上游配置。
包装器合并本地工具、文件系统工具、shell 助手和外部 MCP 工具。紧凑模式隐藏广泛的上游文件系统工具，如全文件读/写、递归树、通用文件名搜索和媒体读取；兼容的旧调用通过紧凑的本地工具路由。
## 开发命令
```bash
npm test
npm run smoke:mcp-schemas
npm run smoke:mcp:tools
```
有用的语法检查：
```bash
node --check scripts/runtime-profile.mjs
node --check scripts/authenticated-mcp-wrapper.mjs
node --check scripts/custom-tools/index.mjs
node --check scripts/resources/index.mjs
node --check scripts/prompts/index.mjs
```
## 操作说明
- 对于源代码、文档、JSON、YAML、TOML 和文本文件，请使用 `custom_file_inspector`。
- 使用 `custom_grep` 进行分页内容搜索。
- 优先使用定向编辑或统一差异，而不是全文件覆盖。
- 保持描述中立和准确；注释提示是由 `gateway-flow.yaml` 控制的呈现提示。
- 使用结构化检查进行描述卫生检查，而不是长篇临时搜索词。
## 身份验证兼容性
可选的静态 bearer 身份验证可以与本地客户端（如 Hermes/OpenClaw）的 OAuth 元数据共存。这是本地工具的兼容性路径，而不是 OAuth 发现的替代方案。
