MCP Agent Homework

这是一个用 TypeScript 编写的 MCP（模型上下文协议）系统，专为 MCP_HOMEWORK_SKILL.md 中的作业而构建：一个代理主机，用于加载代理技能（SKILL.md），通过所有三种必需的传输方式连接到三个 MCP 服务器，发现/聚合它们的工具，并让 Gemini 选择并调用正确服务器上的正确工具。

架构

                          Agent Host (src/host)
                     skill-loader + connection-manager
                       + tool-bridge + gemini-client
                                 |
              +------------------+------------------+
              |                  |                   |
              v                  v                   v
        stdio server       local HTTP server    public HTTP server
     (src/servers/stdio-  (src/servers/http-   (same http-server.ts,
        server.ts)          server.ts, no auth)   API-key protected)
              |                  |                   |
              +------------------+-------------------+
                                 |
              shared tool logic (src/servers/shared/tools.ts)
       3 tools (calculator, text_stats, unit_convert) + 1 resource + 1 prompt

• src/servers/shared/tools.ts — 3 个工具、1 个资源和 1 个提示词的单一实现，在每个服务器上以相同方式注册，以便在任何地方复用相同的逻辑（不重复业务逻辑）。

• src/servers/stdio-server.ts — 通过 stdio 的 MCP（作为子进程生成）。

• src/servers/http-server.ts — 通过流式 HTTP 的 MCP。完全相同的文件/代码同时运行“本地”和“公共”服务器；唯一的区别是配置（PORT、PUBLIC_MCP_API_KEY）。

• src/host/connection-manager.ts — MCP 主机：连接到每个配置的服务器，发现工具/资源/提示词，将工具名称命名为 <namespace>__<tool> 以避免冲突，并将工具调用分派回所属服务器。

• src/host/tool-bridge.ts — 将发现的 MCP 工具转换为 Gemini 函数声明。

• src/host/gemini-client.ts — Gemini 工具调用循环（发送消息 → 读取函数调用 → 通过连接管理器分派 → 将函数响应发送回去 → 重复直到得到最终文本）。

• src/host/skill-loader.ts — 加载 SKILL.md 并将其作为模型的系统指令注入，以便技能积极影响工具使用。

• src/host/agent-host.ts — 根据 config/servers.json 将上述内容组合在一起。

• src/host/cli.ts — CLI 入口点（交互式或 --demo）。

Related MCP server: mcp-tools-server

设置

npm install

密钥位于 api.env 中（已加入 .gitignore）：

API_KEY=your-gemini-api-key
# Optional, only needed once you deploy the public server:
# PUBLIC_MCP_URL=https://your-app.onrender.com/mcp
# PUBLIC_MCP_API_KEY=some-strong-random-key

运行各个组件

stdio 服务器（20 分）

npm run server:stdio            # run directly
npm run inspector:stdio         # open MCP Inspector against it

Inspector 将发现 3 个工具（calculator、text_stats、unit_convert）、1 个资源（docs://unit-conversions）和 1 个提示词（explain-tool-result），并且可以执行/读取所有这些。

本地 HTTP 服务器

npm run server:http             # listens on http://127.0.0.1:8787/mcp, no auth
npm run inspector:http          # then connect Inspector to that URL

公共 HTTP 服务器（15 分）

一旦设置了 PUBLIC_MCP_API_KEY，相同的 http-server.ts 就变成“公共”服务器——每个请求都需要匹配的 x-api-key 头；缺失或无效的密钥将返回 401 Unauthorized。

$env:PORT=8788; $env:PUBLIC_MCP_API_KEY="a-strong-secret"; npm run server:http

公开部署它（Render.com，使用附带的 render.yaml）：

1. git init && git add -A && git commit -m "MCP homework" 然后推送到你拥有的 GitHub 仓库。

2. 在 Render 中：New + → Blueprint → 选择仓库（它会自动读取 render.yaml），或手动创建 Web Service，并设置：

   • 构建命令：npm install && npm run build

   • 启动命令：npm run start:http

   • 健康检查路径：/health

3. 在 Render 仪表板中，将 PUBLIC_MCP_API_KEY 环境变量设置为强密钥（切勿提交）。

4. 部署后，将生成的 URL 和密钥放入 api.env：PUBLIC_MCP_URL=https://<your-service>.onrender.com/mcp 和 PUBLIC_MCP_API_KEY=<same secret>。

5. 使用 Inspector 验证：

   • 无密钥 → 被拒绝：curl -X POST https://<url>/mcp -H "Content-Type: application/json" -d "{...}" 返回 401。

   • 有密钥 → 正常工作：将 --header "x-api-key: <secret>" 传递给 npx @modelcontextprotocol/inspector --cli <url> --method tools/list。

代理主机

npm run agent          # interactive CLI
npm run agent:demo      # runs a scripted set of demo queries

主机启动时：

1. 将 SKILL.md 作为系统指令加载。

2. 读取 config/servers.json 并连接到 stdio 服务器（自动生成）、本地 HTTP 服务器（必须已在运行）和公共 HTTP 服务器（如果未设置 PUBLIC_MCP_URL/PUBLIC_MCP_API_KEY，则自动跳过——它是可选的，因此演示在没有实时部署的情况下也能工作）。

3. 发现并命名每个工具，将它们交给 Gemini，并将 Gemini 发出的每个工具调用分派到正确的 MCP 服务器。

配置

服务器注册是通过 config/servers.json 数据驱动的——在那里添加/删除服务器，而不是编辑主机代码。url 中的 ${VAR} 在连接时从 process.env 解析；apiKeyEnv 指定环境变量的名称，其值将作为 x-api-key 发送。

代理技能

SKILL.md 指示代理优先调用工具，而不是猜测算术/转换/文本统计；为每个逻辑请求选择一个带命名空间的工具；在不确定支持的转换时查阅 docs://unit-conversions 资源；并用通俗的语言解释结果。它会在每次运行时逐字加载到 Gemini 系统指令中（参见 src/host/skill-loader.ts），因此其规则直接影响工具选择和响应风格——这可以在演示输出中观察到（例如，代理总是调用工具进行算术，而不是自己计算）。

安全说明

• 不提交任何密钥；api.env 已被 gitignore，公共服务器仅从环境变量中读取 PUBLIC_MCP_API_KEY。

• 公共 HTTP 服务器拒绝任何没有匹配 x-api-key 头的请求（401），并在提供有效密钥后接受请求。