场景：AI Agent 面对 N 个后端 API 时——Harbor MCP 网关用 Code Mode 实现零代码集成

当你的 AI Agent（Claude Code、Cursor、GPT）需要调用公司内部的用户服务、订单系统和支付网关时，你会怎么做？最常见的方案是给每个端点写一个 MCP 工具定义——但一个有几百个端点的真实 API，光工具定义就能撑爆 Agent 的上下文窗口。

更现实的问题：你的后端 API 每天都在变（新接口、参数调整、认证方式升级），每次后端改动都要同步更新 MCP 工具定义，维护成本比写代码本身还高。

Harbor 提出了一个不同的思路：不做「每端点一工具」，而是给 Agent 五个通用工具，让它自己写 JavaScript 去调用你的 API。这是一个 MCP 网关（API Gateway for AI Agents），位于 AI 客户端和你的后端服务之间。

痛点对比表

快速上手

Harbor 是一个 Node.js 22+ 应用，通过 npm 或 git 安装：

git clone https://github.com/vdssinha/harbor
cd harbor
npm install

Harbor 内置了演示环境——3 个本地后端服务 + MCP 网关，一个命令即可启动：

bash examples/demo/start.sh

启动后，Harbor 会在 http://127.0.0.1:3333/mcp 上暴露 MCP 端点。配置 Cursor 使用：

{
  "mcpServers": {
    "harbor": {
      "url": "http://127.0.0.1:3333/mcp",
      "headers": { "Authorization": "Bearer $(ADMIN_TOKEN)" }
    }
  }
}

或配置 Claude Desktop：

{
  "mcpServers": {
    "harbor": {
      "url": "http://127.0.0.1:3333/mcp",
      "headers": { "Authorization": "Bearer $(ADMIN_TOKEN)" }
    }
  }
}

配置完成后，Agent 就能自动发现所有已注册服务并开始调用了。

核心能力

1. Code Mode：五个工具替代数百个工具定义

这是 Harbor 区别于传统 MCP 方案的核心。Agent 只拿到 5 个 MCP 工具：

• discover_services — 列出所有可用的后端服务
• discover_skills — 查看每个服务的技能清单
• get_skill_details — 获取特定技能的完整说明
• search_code — 搜索已有的示例代码
• api_execute — 提交一段 JavaScript 调用后端 API

Agent 的工作流程是：先用 discover_services 了解有什么后端服务可用，然后用 discover_skills 查看每个服务的使用指南，接着用 search_code 找到现成的调用模板，最后用 api_execute 提交一段 JavaScript 代码来执行实际的 API 调用。

这种模式的核心优势是上下文效率——无论后端有多少个端点，Agent 的上下文里始终只有 5 个工具定义。

2. V8 沙箱隔离

api_execute 提交的 JavaScript 代码在 isolated-vm 沙箱中运行。Agent 写的代码不能访问网络、文件系统或 Harbor 进程内部。它只能通过 Harbor 提供的 api.request() 函数发出 HTTP 请求，且请求必须经过认证和熔断检查。

// Agent 提交的代码示例——调用后端任务服务
const { data } = await api.request({
  method: "POST",
  path: "/api/v1/tasks",
  body: { title: "Review PR #42", assignee: "alice", priority: "high" }
});

这个设计解决了 AI Agent 工具调用的一个根本安全问题——Agent 编写的代码不能做任何超出你配置范围的事情。

3. 声明式服务注册

注册一个后端服务只需要在 services/ 目录下创建一个子目录，包含一个 OpenAPI 规范文件和一个 config.json：

{
  "auth": { "type": "oauth-2.1" },
  "circuitBreaker": {
    "threshold": 5,
    "resetMs": 30000
  }
}

每个服务也可以关联一组 Skills——用 Markdown 编写的 SOP 文件，告诉 Agent 如何正确地使用该服务。例如一个任务管理服务可以有一个 manage-tasks.md Skill，包含创建任务、分配负责人、设置优先级的具体步骤和参数格式。

横向对比

注意事项

• Node.js 22+ 是硬要求——Harbor 依赖 isolated-vm 原生模块，低版本 Node 无法编译
• macOS/Linux 原生支持——Windows 需 WSL 2，因为 isolated-vm 需要 Unix 原生构建工具
• 不是 API 网关替代品——Harbor 是网关层之上的 MCP 适配层，它不替代 Kong、APISIX 等传统 API 网关
• Skill 文件需要人工编写——虽然 Agent 能自动发现 Skill 文件，但编写高质量的 Skill Markdown 仍然需要人介入。每条 Skill 包含 YAML 前置元数据（ID、标题、描述）和具体的调用步骤
• 当前阶段——v0.1.0，312 个单元测试，适合开发/测试环境。作者在项目 ROADMAP 中列出了生产级功能计划

总结

Harbor 解决了一个被大多数人忽视的问题：当 AI Agent 需要调用真实的后端 API 时，传统的「每个端点一个 MCP 工具」模式在规模面前不可持续。通过 Code Mode——给 Agent 少量通用工具让它自己写调用代码——Harbor 实现了后端 API 的零代码集成，同时通过 V8 沙箱和声明式配置保证了安全性。

如果你的团队正在构建 AI Agent 与后端服务的集成层，或者你发现 MCP 工具定义的数量正在失控，Harbor 值得一看。

• GitHub：github.com/vdssinha/harbor
• 详细文档：项目 docs/ 目录（含架构、服务注册、Skill 编写、OAuth 2.1 配置指南）
• 许可证：Apache 2.0