MCP Quick Start Server

MCP 快速入门服务

本项目是一个简单的快速入门示例，展示如何使用 TypeScript 和 @modelcontextprotocol/sdk 构建 Model Context Protocol（MCP）服务。它演示了如何定义基本工具、资源和提示词。

功能

• 工具：add：将两个数字相加。
  • 参数：a（数字）、b（数字）
  • 返回：以字符串形式返回两数之和。
• 工具：fetch-chuck-jokes：获取一则随机的 Chuck Norris 笑话。
  • 参数：无
  • 返回：以字符串形式返回一则 Chuck Norris 笑话。
• 资源：greeting：提供个性化问候。
  • URI 方案：greeting://{name}
  • 示例：greeting://World 会提供一条对 “World” 的问候。
• 提示词：getGreetingAndJoke：指示 AI 客户端按姓名问候用户，然后讲一则 Chuck Norris 笑话。
  • 参数：name（字符串）
  • 示例：使用 name: "Narendra" 调用后，会为 AI 设置一段对话，让 AI 问候 Narendra 并讲一则笑话。

目录结构

quick-start/
├── build/              # Compiled JavaScript output
├── src/                # TypeScript source files
│   ├── index.ts        # Main server setup and entry point
│   ├── tools/
│   │   └── index.ts    # Tool definitions
│   ├── resources/
│   │   └── index.ts    # Resource definitions
│   └── prompts/
│       └── index.ts    # Prompt definitions
├── .gitignore
├── package-lock.json
├── package.json
├── tsconfig.json
└── README.md           # This file

先决条件

• Node.js（建议使用 v18.x 或更高版本）
• npm（随 Node.js 一同安装）

设置与安装

1. 克隆仓库（如果尚未克隆）：

   git clone https://github.com/scriptstar/mcp-starter-kit-node.git
   cd mcp-starter-kit-node
   

2. 安装依赖：

   npm install
   

构建服务

要将 TypeScript 代码编译为 JavaScript，请运行：

npm run build

此命令会根据 tsconfig.json 配置执行 tsc（TypeScript 编译器），并将输出放入 build/ 目录。它还会使主构建文件具有可执行权限。

运行服务

构建完成后，可以使用以下命令启动 MCP 服务：

node build/index.js

或者，在类似生产环境的场景中，可以使用启动脚本：

npm start

服务启动后会在标准输入（stdin）上监听消息，并将响应发送到标准输出（stdout），因为它使用了 StdioServerTransport。

开发工作流

为获得更高效的开发体验，可以使用 dev 脚本：

npm run dev

此命令使用 concurrently 运行两个进程：

1. tsc -w：监视 TypeScript 文件的更改，并自动重新编译。
2. nodemon build/index.js：监视 build 目录（tsc 将 JavaScript 输出到此目录）的更改，并自动重启 Node.js 服务。

这样可以在开发期间实现类似实时重载的体验。

代码检查

本项目使用支持 TypeScript 的 ESLint 来维护代码质量和一致性。

• 检查代码中的 lint 错误：

  npm run lint
  

• 自动修复可修复的 lint 错误：

  npm run lint:fix
  

建议在提交代码前运行代码检查工具。

工作原理

此服务实现了 Model Context Protocol。

• src/index.ts：初始化一个 McpServer 实例，从对应模块导入工具、资源和提示词注册函数，调用这些函数将其注册到服务中，然后连接 StdioServerTransport 来处理通信。
• src/tools/index.ts：导出 registerTools 函数。
  • add：接收两个数字 a 和 b，并返回它们的和。
  • fetch-chuck-jokes：向 https://api.chucknorris.io/jokes/random 发起 HTTP GET 请求，并返回笑话。
• src/resources/index.ts：导出 registerResources 函数。
  • greeting：定义资源模板 greeting://{name}。请求此 URI 时，会返回一条个性化问候消息。
• src/prompts/index.ts：导出 registerPrompts 函数。
  • getGreetingAndJoke：定义一个接收 name 参数的提示词。它会构造一组初始消息来引导 AI 客户端。第一条消息（角色：assistant）设置上下文，第二条消息（角色：user）则使用提供的 name 来构造请求。

与服务交互（概念说明）

此 MCP 服务旨在由 MCP 客户端（例如 AI 助手、开发工具）控制。客户端通过向服务的 stdin 发送 JSON-RPC 消息并从其 stdout 接收响应，与服务进行通信。

以下是客户端与所定义功能交互的示例：

1. 调用 add 工具： 客户端可以发送如下 JSON-RPC 请求：

   {
     "jsonrpc": "2.0",
     "method": "callTool",
     "params": { "name": "add", "args": { "a": 5, "b": 3 } },
     "id": "request1"
   }
   

   服务将返回结果：

   {
     "jsonrpc": "2.0",
     "result": { "content": [{ "type": "text", "text": "8" }] },
     "id": "request1"
   }
   

2. 访问 greeting 资源： 客户端可以请求读取资源 URI greeting://Alice：

   {
     "jsonrpc": "2.0",
     "method": "readResource",
     "params": { "uri": "greeting://Alice" },
     "id": "request2"
   }
   

   服务将返回：

   {
     "jsonrpc": "2.0",
     "result": {
       "contents": [{ "uri": "greeting://Alice", "text": "Hello, Alice!" }]
     },
     "id": "request2"
   }
   

3. 使用 getGreetingAndJoke 提示词： 想要为“Bob”启动此引导式任务的客户端会发送：

   {
     "jsonrpc": "2.0",
     "method": "getPrompt",
     "params": {
       "uri": "prompt://getGreetingAndJoke",
       "args": { "name": "Bob" }
     },
     "id": "request3"
   }
   

   服务将返回初始消息：

   {
     "jsonrpc": "2.0",
     "result": {
       "messages": [
         {
           "role": "assistant",
           "content": {
             "type": "text",
             "text": "You are a friendly assistant. Your task is to greet the user by their name and then tell them a Chuck Norris joke. You should use the available tools and resources to accomplish this. I will now wait for your instruction to proceed with greeting and joke telling for the specified user."
           }
         },
         {
           "role": "user",
           "content": {
             "type": "text",
             "text": "Please greet Bob and then tell a Chuck Norris joke."
           }
         }
       ]
     },
     "id": "request3"
   }
   

   随后，AI 客户端会处理这些消息，并决定调用 greeting 资源（针对“Bob”）和 fetch-chuck-jokes 工具，分别使用 readResource 和 callTool 请求。

后续开发

• 添加更多具有不同输入／输出类型的复杂工具。
• 实现可与本地文件或数据库交互的资源。
• 为多轮对话创建更复杂的提示词。
• 根据需要探索其他传输层（例如 HTTP）。
• 添加全面的错误处理和日志记录。

本 README 应能让你全面了解项目！