使用说明
MCP服务器示例
一个简单的模型上下文协议（MCP）服务器实现，使用Node.js和TypeScript，与Claude Desktop一起使用。
什么是MCP？
这 模型上下文协议（MCP） 是一种开放协议，使像Claude这样的人工智能模型能够与外部工具和数据源进行交互。它允许Claude Desktop调用本地或远程工具，检索信息，并通过标准化的JSON-RPC消息执行操作。
此服务器公开了Claude可以通过stdio（标准输入/输出）传输发现和调用的工具，使其非常适合本地集成。
项目结构
.
├── src/
│ ├── mcp/
│ │ └── server.ts # Main MCP server implementation
│ ├── tools/
│ │ ├── ping.ts # Ping tool example
│ │ ├── system-info.ts # System info tool example
│ │ └── registry.ts # Tool registry & dispatcher
│ └── types/
│ └── index.ts # TypeScript type definitions
├── dist/ # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── mcp.json # Claude Desktop manifest
└── README.md
特性
- ✅ 符合MCP标准的JSON-RPC 2.0服务器
- ✅ Stdio传输（与Claude Desktop本地工具配合使用）
- ✅ 两个示例工具：
ping和system_info - ✅ 可扩展的工具注册表系统
- ✅ 正确的错误处理和验证
- ✅ TypeScript用于类型安全
先决条件
- Node.js 16+（或兼容版本）
- npm 或 纱线
入门指南
1.安装依赖项
npm install
2.将TypeScript构建为JavaScript
npm run build
这将从以下位置编译TypeScript src/ JavaScript在 dist/.
3.运行MCP服务器
npm start
服务器将启动并监听stdin上的JSON-RPC请求。
可用工具
拼
一个简单的测试工具，返回 "pong".
请求：
{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "ping"}}
答复：
{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "pong"}]}}
系统信息
返回详细的系统信息，包括操作系统、体系结构、CPU计数、内存使用情况和正常运行时间。
请求：
{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "system_info"}}
答复：
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [{
"type": "text",
"text": "{\n \"platform\": \"win32\",\n \"arch\": \"x64\",\n \"osType\": \"Windows_NT\",\n ...\n}"
}]
}
}
MCP协议方法
工具/列表
列出所有可用工具。
请求：
{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
答复：
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{
"name": "ping",
"description": "A simple ping tool...",
"inputSchema": { "type": "object", "properties": {} }
},
...
]
}
}
工具/调用
使用可选参数调用特定工具。
请求：
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "tool_name",
"arguments": { "arg1": "value1" }
}
}
答复：
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{ "type": "text", "text": "Result here" }
]
}
}
在Claude Desktop注册
要将此MCP服务器与Claude Desktop一起使用：
-
构建项目：
npm run build -
找到您的Claude Desktop配置文件：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
- macOS:
-
将服务器添加到您的
claude_desktop_config.json:{ "mcpServers": { "example-mcp-server": { "command": "node", "args": ["/absolute/path/to/dist/mcp/server.js"], "env": {} } } }替换
/absolute/path/to包含项目文件夹的完整路径。 -
重新启动Claude Desktop以加载新的MCP服务器。
-
Claude现在将能够发现并调用此服务器提供的工具。
添加新工具
要添加新工具，请执行以下操作：
-
在中创建新的工具文件
src/tools/（例如。，src/tools/my-tool.ts):import { Tool, ToolResult, ToolHandler } from "../types/index.js"; export const myTool: Tool = { name: "my_tool", description: "Description of what the tool does", inputSchema: { type: "object", properties: { param1: { type: "string" }, }, required: ["param1"], }, }; export const myToolHandler: ToolHandler = async (args) => { // Implementation return { content: [{ type: "text", text: "Result" }], }; }; -
在中注册
src/tools/registry.ts:import { myTool, myToolHandler } from "./my-tool.js"; const toolRegistry: Map<string, ToolEntry> = new Map([ // ... existing tools ["my_tool", { definition: myTool, handler: myToolHandler }], ]); -
重建并重新启动服务器：
npm run build npm start
发展
对于自动重新加载的开发，您可以使用 ts-node:
npm run dev
这将直接运行TypeScript而无需编译（需要 ts-node 待安装）。
错误处理
服务器实现了正确的JSON-RPC 2.0错误处理：
- -32700：分析错误
- -32600：无效请求
- -32601：未找到方法
- -32603：内部错误
所有错误都会返回描述性消息，以帮助调试。
建筑
MCP服务器(src/mcp/server.ts)
- 从stdin读取JSON-RPC 2.0消息
- 将请求路由到适当的处理程序
- 验证传入请求
- 将响应写入stdout
- 优雅地处理错误
工具注册表(src/tools/registry.ts)
- 可用工具的中央注册表
- 提供用于发现的工具列表
- 将工具调用分派给适当的处理程序
工具操作员
每个工具都有：
- A.
Tool定义（名称、描述、输入模式） - A.
ToolHandler函数（异步执行逻辑）
故障排除
服务器未启动
- 确保已安装Node.js：
node --version - 检查是否安装了依赖项：
npm install - 构建项目：
npm run build
工具在Claude中不可见
- 验证中的完整路径
claude_desktop_config.json是正确的 - 配置更改后重新启动Claude Desktop
- 检查服务器日志是否有错误
连接问题
- 确保服务器进程保持运行
- 检查编译文件的文件权限
- 验证stdin/stdout是否未被拦截
许可证
麻省理工学院
