Minimum Viable Project

这个项目是一个可直接跑通的 MCP 学习样例，包含完整链路：

1. 写 MCP Server（Tool / Resource / Prompt）
2. 本地用 MCP Client 调用并验证
3. 接入 Codex，让 Codex 直接调用你的 MCP 能力

1. 环境要求

• Node.js >= 22（用 --experimental-strip-types 直接运行 TS）
• npm >= 9

2. 项目结构

.
├── src
│   ├── server.ts         # MCP server (stdio)
│   └── smoke-client.ts   # 本地全流程验证客户端
├── tsconfig.json
├── package.json
└── README.md

3. 安装依赖

npm install

4. 运行方式

4.1 开发模式（直接跑 TS）

npm run dev

4.2 启动服务

npm run start

4.3 全流程 Smoke Test（推荐先跑）

npm run smoke

这个命令会：

1. 在同一个进程内创建 MCP server/client（InMemoryTransport）
2. 用 src/smoke-client.ts 依次调用：
   • listTools
   • callTool(sum_numbers)
   • readResource(note://quickstart)
   • getPrompt(review_snippet)

5. 这个 Server 暴露了什么

Tools

• ping: 健康检查
• sum_numbers: 两数求和，返回文本 + 结构化结果

Resource

• note://quickstart: 学习提示文本

Prompt

• review_snippet(language, snippet): 生成可复用的 code review prompt

6. 接入 Codex（重点）

推荐使用 Codex CLI 命令直接添加 MCP server。

6.1 添加到 Codex

codex mcp add learning-mcp -- node --experimental-strip-types /home/fezhang/mcp/src/server.ts

6.2 检查是否生效

codex mcp list
codex mcp get learning-mcp

6.3 在 Codex 会话里验证

你可以直接对 Codex 说：

• 列出 learning-mcp 的工具
• 调用 sum_numbers，a=12，b=30
• 读取资源 note://quickstart

6.4 删除配置（可选）

codex mcp remove learning-mcp

7. 常见问题

Q1: 为什么 server 日志写到 stderr，而不是 stdout？

MCP stdio 协议使用 stdin/stdout 传输 JSON-RPC。
如果把日志写到 stdout，会污染协议消息，导致调用失败。

Q2: 改了 src/server.ts 之后，Codex 什么时候生效？

这个样例是直接执行 src/server.ts。
下次启动新的 MCP server 进程就会生效，不需要构建。

8. 下一步建议

1. 给 sum_numbers 增加输入边界校验（如最大值）。
2. 增加一个会访问真实 API 的 Tool（例如天气查询）。
3. 再加一个 ResourceTemplate 学习动态资源模式。