MCP 服务器模板

这是一个基于 TypeScript 和 Express 构建的 Model Context Protocol (MCP) 服务器实现模板。

目录

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

概述

该项目实现了遵循 Model Context Protocol (MCP) 的服务器，该协议允许应用程序以标准化方式为 LLMs 提供上下文。它包括：

• 完全配置的 MCP 服务器，支持 HTTP 和 stdio 传输选项
• 示例资源、工具和提示，用于演示关键功能
• TypeScript 支持，提供类型安全性和更好的开发体验
• 集成 Express 作为 HTTP 传输层

项目结构

mcp-server-boilerplate/
├── .env # 环境变量
├── .env.example # 示例环境变量
├── .gitignore # Git 忽略文件
├── package.json # 项目依赖项和脚本
├── tsconfig.json # TypeScript 配置
├── src/
│ ├── index.ts # 主 HTTP 服务器入口点
│ ├── stdio.ts # Stdio 服务器入口点
│ ├── resources/ # MCP 资源
│ │ ├── index.ts # 资源注册
│ │ ├── infoResource.ts # 静态信息资源
│ │ └── greetingResource.ts # 动态问候资源
│ ├── tools/ # MCP 工具
│ │ ├── index.ts # 工具注册
│ │ ├── calculatorTool.ts # 示例计算器工具
│ │ └── timestampTool.ts # 示例时间戳工具
│ └── prompts/ # MCP 提示
│ ├── index.ts # 提示注册
│ ├── greetingPrompt.ts # 示例问候提示
│ └── analyzeDataPrompt.ts # 示例数据分析提示
└── dist/ # 编译后的 JavaScript 输出

开始使用

前提条件

• Node.js (v18 或更高版本)
• npm 或 yarn

安装

克隆仓库并安装依赖项：

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

环境变量

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

bash
cp .env.example .env

可用的环境变量：

• PORT: HTTP 服务器的端口（默认：3000）
• NODE_ENV: 环境模式（development, production）
• OAuth 设置（如果需要）

运行服务器

HTTP 服务器

构建并启动 HTTP 服务器：

bash
npm run build
npm start

对于带有自动重启的开发模式：

bash
npm run dev

服务器将在 http://localhost:3000/mcp （或您在 .env 文件中指定的端口）上可用。

Stdio 模式

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

bash
npm run start:stdio

对于带有自动重启的开发模式：

bash
npm run dev:stdio

资源

该模板包含以下示例资源：

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

   • 提供关于服务器的基本信息

2. 动态问候资源: greeting://{name}- 生成带有提供的名字参数的个性化问候

要访问资源：

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

工具

模板包括以下示例工具：

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

   • 参数：
     • operation：要执行的操作（加、减、乘、除）
     • 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 中注册它

示例：

typescript
// 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',
},
],
}));
}

// 然后在 resources/index.ts 中添加
import { myResource } from './myResource.js';

export function registerResources(server: McpServer): void {
// ...现有资源
myResource(server);
}

添加工具

要添加新工具：

1. 在 src/tools/ 目录下创建一个新的文件（例如，myTool.ts）
2. 实现你的工具处理器
3. 在 src/tools/index.ts 中注册它

示例：

typescript
// 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},
},
],
}));
}

// 然后在 tools/index.ts 中添加
import { myTool } from './myTool.js';

export function registerTools(server: McpServer): void {
// ...现有工具
myTool(server);
}

添加提示

要添加新提示：

1. 在 src/prompts/ 目录下创建一个新的文件（例如，myPrompt.ts）
2. 实现你的提示处理器
3. 在 src/prompts/index.ts 中注册它

示例：

typescript
// 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: 请用简单的术语解释${topic}。,
},
},
],
}));
}

// 然后在 prompts/index.ts 中添加
import { myPrompt } from './myPrompt.js';

export function registerPrompts(server: McpServer): void {
// ...现有提示
myPrompt(server);
}

测试和调试

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

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

许可证

此项目根据MIT许可证发布 - 详情请参阅 LICENSE 文件。