项目简介

这是一个使用 TypeScript 实现的示例 Model Context Protocol (MCP) 服务器，用于演示如何构建一个具有动态工具和资源管理能力的 MCP 应用后端。该服务器承载一个简单的猜数字游戏。它展示了如何利用 MCP 协议为大型语言模型 (LLM) 客户端提供结构化的上下文和功能。

主要功能点

状态感知会话： 每个通过 HTTP 连接的客户端都会维护独立的游戏状态。
动态 MCP 工具： 服务器根据游戏当前状态启用或禁用工具（如“开始游戏”、“猜数字”、“放弃”），并动态更新“猜数字”工具的输入参数范围提示。
动态 MCP 资源： 游戏开始时会出现表示当前游戏状态的资源，游戏结束时消失；高分榜资源会随游戏结果更新。
结构清晰的设计： 采用状态模式、命令模式和事件模式，使游戏逻辑与 MCP 协议实现解耦。
MCP SDK 使用示例： 演示了如何实际应用 '@modelcontextprotocol/sdk' 构建服务器。
JSON 资源处理： 展示了如何将结构化数据（JSON）正确编码为 Base64 字符串并通过资源接口提供给客户端。

安装步骤

克隆代码库：

git clone https://github.com/portal-labs-infrastructure/number-guessing-game-mcp-server
cd number-guessing-game-mcp-server

安装依赖：

npm install
# 或使用 yarn
yarn install

服务器配置

这是一个 HTTP 服务器，需要先在您的环境中运行起来，然后 MCP 客户端通过网络地址连接。默认运行在 8080 端口，MCP 请求路径为 '/mcp'。

MCP 客户端连接此服务器时，需要配置连接信息。具体的配置方式取决于您使用的 MCP 客户端软件，但通常会包含服务器的网络地址。如果您的客户端支持通过指定命令自动启动本地 MCP 服务器进程，它可能需要以下信息：

{
  // 这是提供给MCP客户端用于配置与此服务器连接的信息

  // 服务器名称：客户端用于识别此服务器的名称
  "server name": "猜数字游戏示例服务器",

  // 启动命令：如果客户端需要自动启动服务器进程，这是执行文件的路径
  // 请确保 Node.js 已安装且在系统的 PATH 中
  "command": "node",

  // 启动参数：传递给启动命令的参数列表
  // 这是构建后服务器主文件的路径。运行前需要先执行 'npm run build'
  "args": ["build/index.js"]

  // 注意：此服务器使用HTTP传输协议，启动后客户端通常通过指定的网络地址连接（默认为 http://localhost:8080/mcp ）
  // 上述 command/args 主要用于客户端支持自动启动本地HTTP服务器进程的场景
}

基本使用方法

启动服务器：
- 开发模式 (带热重载)：
```
npm run dev
```
- 生产模式 (先构建后运行)：
```
npm run build
npm start
```
服务器启动后，您将看到类似 "MCP Game Server (HTTP Stateful) listening on port 8080" 的输出。
客户端连接： 使用支持动态 MCP 工具和资源发现的 MCP 客户端。将客户端连接到服务器的 HTTP 地址。如果服务器运行在本地，默认地址是 'http://localhost:8080/mcp'。如果客户端和服务器不在同一机器，您可能需要使用 ngrok 等工具将本地端口暴露到公网。
与游戏交互：
- 客户端发现并看到可用的 MCP 工具和资源。
- 最初，只有“开始游戏”工具 ('start_game') 可用。
- 调用 'start_game' 工具（需要提供玩家名）。
- 游戏开始后，“开始游戏”工具将变为不可用，“猜数字” ('guess_number') 和“放弃” ('give_up') 工具变为可用。同时，'game_state' 资源将出现，提供当前游戏信息。
- 调用 'guess_number' 工具，提供猜测的数字。工具的参数提示会根据当前允许猜测的数字范围动态更新。
- 观察客户端接收到的响应和通过 SSE 推送的资源更新通知，了解游戏进展和状态变化。
- 游戏结束（猜中或尝试次数用尽）或调用 'give_up' 工具后，游戏将返回初始状态，“猜数字”和“放弃”工具将再次变为不可用，'game_state' 资源消失。高分榜 ('highscores') 资源会在游戏结束后更新。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息