项目简介

'mcp-boilerplate-node' 是一个 Node.js 端的 MCP (Model Context Protocol) 服务器脚手架，旨在帮助开发者快速构建符合 MCP 规范的应用后端。它提供了标准化的方式来托管资源、注册工具、定义 Prompt 模板，并通过 JSON-RPC 协议与 LLM 客户端通信，支持 Stdio 和 HTTP/SSE 等多种传输协议。

主要功能点

MCP 服务器框架: 提供构建 MCP 服务器的基础结构，支持资源、工具和 Prompt 模板的注册与管理。
工具与 Prompt 模板支持: 允许开发者定义和注册自定义的工具（API）和 Prompt 模板，供 LLM 客户端调用。
多种传输协议: 内置支持通过标准输入输出 (Stdio) 或 HTTP/SSE 协议进行通信，满足不同部署场景需求。
会话管理: HTTP 服务器支持有状态会话，通过 'mcp-session-id' 头部管理客户端会话生命周期。
可观测性: 集成 OpenTelemetry，支持分布式追踪和日志记录，便于故障排查和性能监控。
REST API 兼容: 除了 MCP 协议，还提供了将注册的工具暴露为传统 REST API 的功能，便于直接访问。
健壮性: 包含完善的错误处理、输入验证 (Zod) 和优雅退出机制。

安装步骤

克隆仓库:

git clone https://github.com/timescale/mcp-boilerplate-node.git
cd mcp-boilerplate-node

安装依赖:
```
npm install
```
构建项目:
```
npm run build
```
这会将 TypeScript 文件编译成 JavaScript 文件，生成到 'dist/' 目录中。

服务器配置

MCP 客户端需要配置服务器的启动命令和参数才能建立连接。以下是基于该脚手架启动的 MCP 服务器的配置示例（JSON 格式）：

STDIO 模式 (默认): 此模式下服务器通过标准输入输出与客户端通信。

{
  "serverName": "MCP Node.js 应用",
  "command": "node",
  "args": [
    "dist/cliEntrypoint.js",
    "stdio"
  ],
  "environment": {
    // 可选：设置环境变量，例如：
    "OTEL_SERVICE_NAME": "my-mcp-service"
    // 更多 OpenTelemetry 配置请参考项目文档或环境变量说明
  }
}

HTTP 模式: 此模式下服务器通过 HTTP 协议提供 MCP 端点和可选的 REST API。

{
  "serverName": "MCP Node.js 应用",
  "command": "node",
  "args": [
    "dist/cliEntrypoint.js",
    "http",
    "--instrument" // 启用 OpenTelemetry 追踪，可选
  ],
  "environment": {
    "PORT": "3001", // 服务器监听的端口，默认为 3001
    "OTEL_SERVICE_NAME": "my-mcp-service",
    "MCP_ENABLED_TOOLS": "tool1,tool2", // 可选：指定启用哪些工具，多个用逗号分隔
    "MCP_DISABLED_TOOLS": "tool3", // 可选：指定禁用哪些工具，多个用逗号分隔
    "INSTRUMENT": "true" // 可选：等同于 --instrument 参数，启用 OpenTelemetry
    // 更多 OpenTelemetry 配置，例如 Logfire 或 Jaeger 导出器：
    // "LOGFIRE_TRACES_ENDPOINT": "your_logfire_traces_endpoint",
    // "LOGFIRE_TOKEN": "your_logfire_token",
    // "JAEGER_TRACES_ENDPOINT": "your_jaeger_traces_endpoint"
  },
  "url": "http://localhost:3001/mcp" // MCP 客户端连接的 URL
}

请注意：在实际部署时，'url' 中的 'localhost' 应替换为服务器的实际 IP 地址或域名。

基本使用方法

这个仓库是一个脚手架，您需要在其基础上进行开发：

定义工具 (Tools): 在 'src/' 目录下创建新的文件，定义您的业务逻辑作为 MCP 工具。例如：

// src/tools/myTool.ts
import { z } from 'zod';
import { ApiFactory } from '../types.js';

export const myToolFactory: ApiFactory<Record<string, unknown>, any, any> = () => ({
  name: 'myTool',
  description: '一个简单的示例工具',
  config: {
    inputSchema: {
      name: z.string().describe('要打招呼的名字'),
    },
    outputSchema: {
      greeting: z.string().describe('打招呼的消息'),
    },
  },
  fn: async (args) => {
    return { greeting: '你好, ${args.name}!' };
  },
});

定义 Prompt 模板 (Prompts): 同样可以在 'src/' 目录下定义 Prompt 模板。例如：

// src/prompts/welcomePrompt.ts
import { z } from 'zod';
import { PromptFactory } from '../types.js';

export const welcomePromptFactory: PromptFactory<Record<string, unknown>, any> = () => ({
  name: 'welcomePrompt',
  config: {
    inputSchema: {
      userName: z.string().describe('用户的名称'),
    },
  },
  fn: async (args) => ({
    content: [
      {
        type: 'text',
        text: '欢迎您，${args.userName}！很高兴为您服务。',
      },
    ],
  }),
});

注册工具和 Prompt: 在您自定义的入口文件中 (例如，可以创建一个 'src/app.ts' 或修改现有的 'src/stdio.ts'/'src/httpServer.ts' 来传入您定义的 'apiFactories' 和 'promptFactories')，将这些工厂函数传递给 'stdioServerFactory' 或 'httpServerFactory'。例如，如果您有一个 'src/index.ts' 文件作为主要入口：

// src/index.ts
import { stdioServerFactory } from './stdio.js';
import { myToolFactory } from './tools/myTool.js';
import { welcomePromptFactory } from './prompts/welcomePrompt.js';

// 假设您的上下文是一个空对象，实际应用中可以包含数据库连接等
const context = {};

stdioServerFactory({
  name: 'my-mcp-server',
  context,
  apiFactories: [myToolFactory],
  promptFactories: [welcomePromptFactory],
});

运行服务器: 编译后，使用 'node dist/cliEntrypoint.js stdio' (或 'http') 启动您的 MCP 服务器。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息