MCP Server Boilerplate

MCP 服务脚手架

一个使用 TypeScript 和 Express 构建的 Model Context Protocol（MCP）基础服务实现。

目录

• 概览
• 项目结构
• 开始使用
  • 前置条件
  • 安装
  • 环境变量
• 运行服务
  • HTTP 服务
  • Stdio 模式
• 资源
• 工具
• 提示词
• 扩展服务
  • 添加资源
  • 添加工具
  • 添加提示词
• 测试与调试
• 许可证

概览

此项目实现了一个遵循 Model Context Protocol（MCP）的服务，使应用能够以标准化的方式为大模型提供上下文。项目包含：

• 配置完整的 MCP 服务，支持 HTTP 和 stdio 传输方式
• 用于展示核心功能的示例资源、工具和提示词
• TypeScript 支持，确保类型安全并提升开发体验
• 集成 Express，为 HTTP 传输层提供支持

项目结构

mcp-server-boilerplate/
├── .env                  # Environment variables
├── .env.example          # Example environment variables
├── .gitignore            # Git ignore file
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── src/
│   ├── index.ts          # Main HTTP server entry point
│   ├── stdio.ts          # Stdio server entry point
│   ├── resources/        # MCP resources
│   │   ├── index.ts      # Resource registration
│   │   ├── infoResource.ts # Static info resource
│   │   └── greetingResource.ts # Dynamic greeting resource
│   ├── tools/            # MCP tools
│   │   ├── index.ts      # Tool registration
│   │   ├── calculatorTool.ts # Sample calculator tool
│   │   └── timestampTool.ts # Sample timestamp tool
│   └── prompts/          # MCP prompts
│       ├── index.ts      # Prompt registration
│       ├── greetingPrompt.ts # Sample greeting prompt
│       └── analyzeDataPrompt.ts # Sample data analysis prompt
└── dist/                 # Compiled JavaScript output

开始使用

前置条件

• Node.js（v18 或更高版本）
• npm 或 yarn

安装

克隆仓库并安装依赖：

git clone https://github.com/yourusername/mcp-server-boilerplate.git
cd mcp-server-boilerplate
npm install

环境变量

复制示例环境文件，并根据需要进行修改：

cp .env.example .env

可用的环境变量：

• PORT：HTTP 服务使用的端口（默认值：3000）
• NODE_ENV：环境模式（development、production）
• OAuth 设置（如有需要）

运行服务

HTTP 服务

构建并启动 HTTP 服务：

npm run build
npm start

如需在开发期间自动重启：

npm run dev

服务将在 http://localhost:3000/mcp 上提供访问（或使用 .env 文件中指定的端口）。

Stdio 模式

如需以 stdio 模式运行服务（用于命令行工具）：

npm run start:stdio

如需在开发期间自动重启：

npm run dev:stdio

资源

此脚手架包含以下示例资源：

1. 静态信息资源：info://server

   • 提供有关服务的基本信息

2. 动态问候资源：greeting://{name}

   • 使用提供的姓名参数生成个性化问候语

访问资源的方式：

• 通过 MCP 协议
• 使用 MCP 客户端库

工具

此脚手架包含以下示例工具：

1. 计算器：执行基本算术运算

   • 参数：
     • operation：要执行的运算（add、subtract、multiply、divide）
     • a：第一个数字
     • b：第二个数字

2. 时间戳：以多种格式提供当前时间

   • 参数：
     • format：输出格式（iso、unix、readable）

提示词

此脚手架包含以下示例提示词：

1. 问候：创建个性化问候提示词

   • 参数：
     • name：要问候的姓名
     • formal：是否使用正式的问候风格（可选）

2. 分析数据：创建用于数据分析的提示词

   • 参数：
     • data：要分析的数据
     • format：数据格式（json、csv、text）
     • instructions：其他分析说明（可选）

扩展服务

添加资源

添加新资源的方法：

1. 在 src/resources/ 中创建新文件（例如 myResource.ts）
2. 实现资源处理程序
3. 在 src/resources/index.ts 中注册

示例：

// myResource.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

export function myResource(server: McpServer): void {
  server.resource('my-resource', 'my-resource://path', async uri => ({
    contents: [
      {
        uri: uri.href,
        text: 'My resource content',
      },
    ],
  }));
}

// Then add to resources/index.ts
import { myResource } from './myResource.js';

export function registerResources(server: McpServer): void {
  // ...existing resources
  myResource(server);
}

添加工具

要添加新工具：

1. 在 src/tools/ 中创建一个新文件（例如 myTool.ts）
2. 实现工具处理程序
3. 在 src/tools/index.ts 中注册该工具

示例：

// myTool.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

export function myTool(server: McpServer): void {
  server.tool('my-tool', { param: z.string() }, async ({ param }) => ({
    content: [
      {
        type: 'text',
        text: `Processed: ${param}`,
      },
    ],
  }));
}

// Then add to tools/index.ts
import { myTool } from './myTool.js';

export function registerTools(server: McpServer): void {
  // ...existing tools
  myTool(server);
}

添加提示词

要添加新提示词：

1. 在 src/prompts/ 中创建一个新文件（例如 myPrompt.ts）
2. 实现提示词处理程序
3. 在 src/prompts/index.ts 中注册该提示词

示例：

// myPrompt.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

export function myPrompt(server: McpServer): void {
  server.prompt('my-prompt', { topic: z.string() }, ({ topic }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Please explain ${topic} in simple terms.`,
        },
      },
    ],
  }));
}

// Then add to prompts/index.ts
import { myPrompt } from './myPrompt.js';

export function registerPrompts(server: McpServer): void {
  // ...existing prompts
  myPrompt(server);
}

测试与调试

要测试 MCP 服务，可以使用：

• MCP Inspector 工具
• MCP 客户端库
• 直接发送 HTTP 请求（用于调试）

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。