MCP服务器和客户端示例 (TypeScript)

本项目演示了如何使用 TypeScript 和 @modelcontextprotocol/sdk 创建一个简单的模型上下文协议 (MCP) 服务器和一个独立的 MCP 客户端，并进行交互。

该设置包括：

1. my-mcp-greeter-server: 一个 MCP 服务器，提供与问候相关的工具、资源和提示。
2. my-mcp-client-script: 一个简单的命令行客户端脚本，用于启动服务器、连接到服务器，并以编程方式与其功能进行交互。

本示例中客户端和服务器之间的通信使用 stdio (标准输入/输出) 传输机制。

流程概述

本项目按照以下主要阶段构建：

1. 服务器开发: 创建 MCP 服务提供者。
2. 客户端开发: 创建一个脚本来使用服务器的服务。
3. 测试与交互: 运行客户端脚本，该脚本启动服务器并演示通信。
4. （可选）集成: 讨论如何将服务器与现有的 MCP 客户端（如 VS Code 扩展）集成。

前提条件

在开始之前，请确保已安装以下内容：

• Node.js (建议 v16 或更高版本)
• npm (通常包含在 Node.js 中)
• 文本编辑器或 IDE（如 VS Code）
• npx (通常包含在 npm 中) - 用于使用 MCP Inspector 进行测试。

阶段 1：构建 MCP 服务器 (my-mcp-greeter-server)

1. 项目设置:

   • 创建目录 my-mcp-greeter-server。
   • 初始化一个 npm 项目：npm init -y。
   • 安装必要的依赖项：npm install @modelcontextprotocol/sdk zod。
   • 安装开发依赖项：npm install -D typescript @types/node。
   • 初始化 TypeScript 配置：npx tsc --init。
   • 配置 tsconfig.json (设置 "module": "Node16", "target": "ES2022", "outDir": "./build", "rootDir": "./src" 等)。
   • 更新 package.json 以包含 "type": "module" 并添加 build/start 脚本。
   • 创建源文件 src/index.ts。

2. 服务器实现 (src/index.ts):

   • 导入所需的模块 (McpServer, StdioServerTransport, z)。
   • 定义服务器 name 和 version 的常量。
   • 实例化 McpServer，传递名称、版本并声明其功能（工具、资源、提示）。
   • 定义一个工具 (greet): 使用 server.tool() 创建一个可由客户端调用的函数。包括描述，使用 Zod 定义输入参数 (name, politeness)，并实现处理程序以返回个性化的问候字符串。
   • 定义一个资源 (server-info): 使用 server.resource() 公开静态数据。提供唯一的 URI (info://greeter/about) 并实现处理程序以返回服务器的名称和版本。
   • 定义一个提示 (suggest-greeting): 使用 server.prompt() 创建一个可重用的交互模板。包括描述并实现处理程序以返回一组预定义的用户/助手消息，以指导 LLM 交互。
   • 使用 Stdio 传输: 实例化 StdioServerTransport 作为通信方法。
   • 连接: 调用 await server.connect(transport) 使服务器准备就绪。
   • 日志记录: 添加 console.error 语句以在执行期间提供可见性，这对于 stdout 用于协议消息的 stdio 传输尤其重要。
   • 保持活动: 确保 Node.js 进程在连接后不会立即退出。

3. 构建与修复:

   • 运行 npm run build 将 TypeScript 编译为 build 目录中的 JavaScript。
   • 修复了与直接访问服务器版本相关的 TypeScript 错误，选择使用预定义的常量。

阶段 2：构建 MCP 客户端脚本 (my-mcp-client-script)

1. 项目设置:

   • 创建一个单独的目录 my-mcp-client-script。
   • 初始化一个 npm 项目：npm init -y。
   • 安装必要的依赖项：npm install @modelcontextprotocol/sdk。
   • 安装开发依赖项：npm install -D typescript @types/node。
   • 初始化并配置 tsconfig.json，类似于服务器项目。
   • 更新 package.json 以包含 "type": "module" 和 build/start 脚本。
   • 创建源文件 src/client-script.ts。

2. 客户端实现 (src/client-script.ts):

   • 导入所需的模块 (Client, StdioClientTransport, path, url)。
   • 确定服务器路径: 计算 服务器 编译后的 index.js 文件的路径（相对或绝对）。
   • 配置 Stdio 传输: 实例化 StdioClientTransport，提供 command (node) 和 args (服务器脚本的路径)。此配置至关重要，因为客户端传输会启动服务器进程。
   • 实例化客户端: 创建一个 Client 实例，为其提供身份并声明其使用工具和资源的意图。
   • 连接: 调用 await client.connect(transport)，它启动服务器进程并通过其 stdio 流建立 MCP 连接。
   • 与服务器交互:
     • 使用 await client.callTool() 调用 greet 工具。
     • 使用 await client.readResource() 读取 server-info 资源。
     • 使用 await client.getPrompt() 获取 suggest-greeting 提示。
   • 记录结果: 使用 console.log 显示从服务器收到的响应。
   • 关闭连接: 在 finally 块中使用 await client.close() 以干净地关闭连接并终止服务器进程。

阶段 3：构建和运行

1. 构建两个项目:

   • cd my-mcp-greeter-server && npm run build
   • cd ../my-mcp-client-script && npm run build

2. 运行客户端:

   • cd my-mcp-client-script
   • npm run start (或 node build/client-script.js)
   • 观察来自客户端 (console.log) 和服务器 (console.error) 的交错输出，确认工具/资源/提示的成功通信和执行。

角色说明

• 服务器 (GreeterServer):

  • 提供服务: 公开特定功能（问候工具、服务器信息、提示模板）。
  • 被动监听器 (在 stdio 中): 等待客户端通过其标准流连接。
  • 执行逻辑: 运行与客户端请求的工具/资源/提示相关的代码。
  • 发送结果: 根据 MCP 规范格式化结果并将其发送回客户端。

• 客户端 (client-script.ts):

  • 使用服务: 使用服务器提供的功能。
  • 发起者 (在 stdio 中): 启动服务器进程并建立连接。
  • 发送请求: 决定调用哪个工具、读取哪个资源或获取哪个提示，并发送相应的 MCP 请求。
  • 接收结果: 处理服务器发回的响应。
  • 控制流程: 管理交互序列并决定何时关闭连接。

交互式测试服务器

虽然客户端脚本测试了编程交互，但您可以使用 MCP Inspector 单独测试服务器的功能：

# 确保服务器尚未运行
# 将 /path/to/... 替换为实际的绝对路径
npx @modelcontextprotocol/inspector node /path/to/my-mcp-greeter-server/build/index.js