MCP模板服务器
使用Node.js和TypeScript构建的模型上下文协议（MCP）服务器模板。
特性
- 工具:
- get_time：获取任何时区的当前时间 - echo：回显消息
- 资源：服务器信息资源
- 双重运输：支持stdio和流式HTTP（单
/mcp端点）
安装
npm install构建
npm run build用法
开发模式（含tsx）
标准模式 （适用于Claude Desktop等MCP客户）：
npm run dev:mcpHTTP模式 （对于基于HTTP的客户端，使用Streamable HTTP传输）：
npm run dev:mcp:http
# Server runs on http://localhost:3001
# Custom port:
npm run dev:mcp:http:port 3002生产模式
标准模式:
npm run start:mcpHTTP模式:
npm run start:mcp:http
# Or with custom port:
npm run start:mcp:http:port 3002Claude桌面配置
添加到您的Claude Desktop配置文件中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"mcp-template": {
"command": "node",
"args": ["/path/to/mcp-template/build/index.js"]
}
}
}或者使用tsx进行开发：
{
"mcpServers": {
"mcp-template": {
"command": "npx",
"args": ["-y", "tsx", "/path/to/mcp-template/src/index.ts"]
}
}
}使用HTTP模式（流式HTTP）进行测试
新的Streamable HTTP传输使用 单 /mcp 端点 用于所有通信（POST、GET、DELETE方法）。
与旧SSE运输的主要区别
旧（已弃用）苏格兰和南方能源公司运输：
- 两个端点：
/sse（GET用于流媒体）和/message（POST用于请求） - 会话ID作为查询参数传递
新的流式HTTP传输：
- 单端点：
/mcp - POST/mcp：客户端发送请求
- GET/mcp：客户端为服务器发起的通知建立SSE流
- DELETE/mcp：客户端终止会话
- 传入会话ID
Mcp-Session-Id头球
测试步骤
- 启动服务器：
npm run dev:mcp:http- 测试运行状况端点：
curl http://localhost:3001/health- 初始化会话（必须初始化第一个请求）：
选项A：使用 -i 标志（包括标头、更清晰的输出）：
curl -i -X POST http://localhost:3001/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {
"name": "test-client",
"version": "1.0.0"
}
}
}'选项B：使用 -v flag（详细，显示完整的请求和响应）：
curl -v -X POST http://localhost:3001/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {
"name": "test-client",
"version": "1.0.0"
}
}
}'重要提示：
- 这
-i标志仅显示响应标头（更清晰） - 这
-v标志显示请求和响应标头（详细，用于调试） - 这
Accept标题必须同时包含这两个application/json和text/event-stream正确支持Streamable HTTP协议 - 寻找
mcp-session-id响应中的报头（例如。，mcp-session-id: e75aa1e2-8327-47fe-b670-a49f6a694e64) - 复制此会话ID以在后续请求中使用
- 列出工具（替换 `` 使用步骤3中的值）：
curl -i -X POST http://localhost:3001/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Mcp-Session-Id: " \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list"
}'实际会话ID示例：
curl -i -X POST http://localhost:3001/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Mcp-Session-Id: e75aa1e2-8327-47fe-b670-a49f6a694e64" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list"
}'- 调用工具：
curl -X POST http://localhost:3001/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Mcp-Session-Id: " \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "echo",
"arguments": {
"message": "Hello from Streamable HTTP!"
}
}
}'- 建立SSE流（可选，用于服务器发起的通知）：
curl -X GET http://localhost:3001/mcp \
-H "Mcp-Session-Id: " \
-H "Accept: text/event-stream"- 终止会话：
curl -X DELETE http://localhost:3001/mcp \
-H "Mcp-Session-Id: "从SSE运输迁移
此模板已更新为使用新 可流式HTTP传输 而不是弃用 SSEServerTransport.
发生了什么变化？
之前（弃用的SSE运输）：
- 用过的
SSEServerTransport从@modelcontextprotocol/sdk/server/sse.js - 需要两个端点：
- GET /sse -用于服务器到客户端流式传输 - POST /message?sessionId= -用于客户端到服务器的消息
- 会话ID作为查询参数传递
之后（新的流式HTTP传输）：
- 用途
StreamableHTTPServerTransport从@modelcontextprotocol/sdk/server/streamableHttp.js - 单端点
/mcp有三种HTTP方法：
- POST /mcp -对于所有客户端到服务器的消息 - GET /mcp -用于服务器到客户端的SSE流（可选） - DELETE /mcp -用于会话终止
- 传入会话ID
Mcp-Session-Id头球 - 需要
Accept: application/json, text/event-stream头球
流式HTTP的好处
- 简化架构：单个端点而不是两个端点
- 更好的可扩展性：更易于负载平衡和管理
- 标准符合性：遵循HTTP最佳实践
- 面向未来：新的MCP规范标准（截至2025年3月26日）
项目结构
该项目遵循模块化架构，以实现更好的可维护性和可扩展性。
备注：原始单片版本（重构前）保留在 reference/index.ts 以供参考。mcp-template/
├── src/
│ ├── index.ts # Main entry point
│ ├── config/ # Configuration
│ │ └── index.ts # Server config and argument parsing
│ ├── types/ # TypeScript type definitions
│ │ └── index.ts # Shared types
│ ├── schemas/ # Zod validation schemas
│ │ └── tool-schemas.ts # Tool input validation
│ ├── tools/ # Tool implementations
│ │ ├── index.ts # Tool registry and exports
│ │ ├── get-time.ts # Get time tool
│ │ └── echo.ts # Echo tool
│ ├── resources/ # Resource implementations
│ │ ├── index.ts # Resource registry
│ │ └── info.ts # Server info resource
│ ├── server/ # MCP server setup
│ │ └── mcp-server.ts # Server creation and handlers
│ └── transports/ # Transport layer
│ ├── stdio.ts # Standard I/O transport
│ └── http.ts # HTTP/SSE transport
├── build/ # Compiled JavaScript (after build)
├── package.json
├── tsconfig.json
├── README.md
└── ARCHITECTURE.md # Detailed architecture documentation定制
添加新工具
- 创建架构 在
src/schemas/tool-schemas.ts:
export const MyToolSchema = z.object({
param: z.string().describe("Parameter description"),
});- 创建工具 在
src/tools/my-tool.ts:
import { Tool } from "./index.js";
import { MyToolSchema } from "../schemas/tool-schemas.js";
export const myTool: Tool = {
name: "my_tool",
description: "Tool description",
inputSchema: { /* ... */ },
handler: async (args: any) => {
const parsed = MyToolSchema.safeParse(args);
// ... implement logic
return { content: [{ type: "text", text: result }] };
},
};- 出口 在
src/tools/index.ts:
export { myTool } from "./my-tool.js";- 注册 在
src/index.ts:
const server = createMCPServer(
serverConfig,
[getTimeTool, echoTool, myTool], // Add here
[infoResource]
);添加新资源
遵循与工具相同的模式，但 src/resources/ 目录。
有关详细的体系结构信息和扩展模式，请参见 建筑.md.
许可证
国际学生中心