toy-mcp-server

一个从零构建的最小化 Model Context Protocol (MCP) 服务器，用来理解 MCP 实际的工作方式——不用脚手架生成器、不用模板，只需用到 SDK。

这是我的第一个动手实践 MCP 项目：包含两个工具和一个资源，通过 stdio 接入 Claude Desktop。

它能做什么

MCP 让 LLM 客户端（比如 Claude Desktop）调用在你本机上运行的函数，而不只是从训练数据中生成文本。本服务器提供：

工具（Claude 可以调用的函数）：

• roll_dice — 掷 N 个骰子，骰子面数可配置

• flip_coin — 掷 N 次硬币

资源（Claude 可以获取的只读数据）：

• server-info — 服务器的基础元数据（名称、用途、启动时间）

为什么存在

LLM 无法访问训练数据之外的任何内容，并且默认情况下无法 执行 任何操作——它们只会生成文本。MCP 是一种以标准方式为模型提供以下能力的途径：

• 能力 — 模型自身不具备的能力（例如真正的随机性——众所周知，LLM 在随机选数字方面表现非常糟糕）

• 访问权限 — 访问模型无法知道的实时或私有数据

在把 MCP 服务器指向真实目标（数据库、带认证的 API 等）之前，这个项目是验证这一想法的一个安全小型沙箱。

技术栈

• TypeScript

• @modelcontextprotocol/sdk — 官方 MCP SDK

• zod — 工具参数的运行时 schema 校验

• stdio 传输（与 Claude Desktop 的本地子进程通信）

项目结构

toy-mcp-server/
├── src/
│   └── index.ts       # server setup, tools, and resource
├── build/              # compiled output (git-ignored)
├── package.json
├── tsconfig.json
└── README.md

设置

1. 安装依赖

npm install

2. 构建

npm run build

3. 连接到 Claude Desktop

找到你的 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：通常位于 %LOCALAPPDATA%\Packages\<Claude package folder>\LocalCache\Roaming\Claude\claude_desktop_config.json —— 具体路径可能因安装方式不同（Microsoft Store 与直接安装）而异。可靠的查找方式是：打开 Claude Desktop → Settings → Developer → Local MCP servers → Edit Config，这会打开应用实际读取的确切文件。

在 mcpServers 下合并这个服务器（合并到已有文件中，而非覆盖整个文件）：

{
  "mcpServers": {
    "toy-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/toy-mcp-server/build/index.js"]
    }
  }
}

请把路径替换为你机器上 build/index.js 的实际绝对路径。在 Windows 上，需要在 JSON 字符串中对反斜杠进行转义（\\）。

4. 重启 Claude Desktop

完全退出（不是只关闭窗口）后重新打开。检查 Settings → Developer → Local MCP servers，确认 toy-mcp-server 显示为已连接。

5. 试一试

在聊天中试着输入：

• “把 3 个六面骰子掷一下”

• “把一枚硬币抛 10 次”

你应该会在回复上方看到一个小的工具调用指示器（例如 Roll Dice），从而确认 Claude 确实调用了工具，而不是猜测一个答案。

简单工作原理

• McpServer — 向任何连接过来的客户端声明服务器能力的对象

• registerTool(name, config, handler) — 注册一个可调用函数。config.inputSchema 在 handler 执行前使用 Zod 校验模型发送的任何参数

• registerResource(name, uri, config, handler) — 注册通过 URI 寻址的只读数据，无需参数即可获取

• StdioServerTransport — 即通信格式：Claude Desktop 将该文件作为子进程启动，并通过 stdin/stdout 使用 JSON-RPC 通信。由于 stdout 是实际的协议通道，console.log 在这里绝对不能用于日志输出——改用 console.error（stderr）

下一步

• 将 toy 工具替换为真正连接数据库的工具（通过 Prisma 连接 Postgres）

• 添加一个基于 GitHub 的工具（如 list_open_prs），练习基于 token 的认证

• 探索 Streamable HTTP 传输，将服务部署到远端而非本地运行

许可证

MIT