MCP服务器一
通过示例和最佳实践创建模型上下文协议（MCP）服务器的综合指南。
什么是MCP？
模型上下文协议（MCP）是一种开放协议，可实现主机应用程序（如Claude Desktop、IDE或其他AI工具）和外部数据源之间的安全连接。MCP服务器充当中介，可以以标准化的方式向AI模型提供工具、资源和提示。
入门指南
先决条件
- Node.js 18+或Python 3.8+
- 对TypeScript、JavaScript或Python有基本的了解
- 熟悉JSON-RPC协议概念
核心概念
在构建MCP服务器之前，请了解以下关键概念：
- 工具：AI可以调用以执行操作的函数
- 资源：人工智能可以读取的数据（文件、API响应等）
- 鼓励：带有参数的预定义提示模板
- 运输：通信层（stdio、HTTP、WebSocket）
创建MCP服务器的分步指南
步骤1：选择您的实现语言
MCP服务器可以用多种语言构建。最常见的是：
- Types/JavaScript：使用官方MCP SDK
- python：使用官方Python SDK
- 其他语言：遵循JSON-RPC规范
第二步：设置开发环境
对于Types/JavaScript：
# Create a new project
mkdir my-mcp-server
cd my-mcp-server
# Initialize npm project
npm init -y
# Install MCP SDK
npm install @modelcontextprotocol/sdk
# Install development dependencies
npm install -D typescript @types/node tsx对于Python：
# Create a new project
mkdir my-mcp-server
cd my-mcp-server
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install MCP SDK
pip install mcp步骤3：实现基本服务器结构
TypeScript示例：
#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
const server = new Server(
{
name: "my-mcp-server",
version: "1.0.0",
},
{
capabilities: {
tools: {},
},
}
);
// List available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: "echo",
description: "Echo back the input",
inputSchema: {
type: "object",
properties: {
message: {
type: "string",
description: "Message to echo",
},
},
required: ["message"],
},
},
],
};
});
// Handle tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
if (name === "echo") {
return {
content: [
{
type: "text",
text: `Echo: ${args.message}`,
},
],
};
}
throw new Error(`Unknown tool: ${name}`);
});
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("MCP Server running on stdio");
}
main().catch(console.error);Python示例：
#!/usr/bin/env python3
import asyncio
import sys
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent
app = Server("my-mcp-server")
@app.list_tools()
async def list_tools() -> list[Tool]:
return [
Tool(
name="echo",
description="Echo back the input",
inputSchema={
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Message to echo"
}
},
"required": ["message"]
}
)
]
@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
if name == "echo":
message = arguments.get("message", "")
return [TextContent(type="text", text=f"Echo: {message}")]
raise ValueError(f"Unknown tool: {name}")
async def main():
async with stdio_server() as streams:
await app.run(*streams)
if __name__ == "__main__":
asyncio.run(main())步骤4：配置服务器
创建配置文件以向MCP客户端注册服务器：
mcp-config.json （适用于克劳德桌面）：
{
"mcpServers": {
"my-mcp-server": {
"command": "node",
"args": ["path/to/your/server.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}步骤5：测试您的服务器
创建测试脚本以验证功能：
# Test with MCP Inspector (recommended)
npx @modelcontextprotocol/inspector node server.js
# Or test manually with stdio
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node server.js高级功能
添加资源
资源允许您的服务器提供可读内容：
// TypeScript example
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: "file://example.txt",
name: "Example File",
description: "An example text file",
mimeType: "text/plain",
},
],
};
});
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
const { uri } = request.params;
if (uri === "file://example.txt") {
return {
contents: [
{
uri,
mimeType: "text/plain",
text: "Hello from MCP server!",
},
],
};
}
throw new Error(`Resource not found: ${uri}`);
});添加提示
提示提供可重用的提示模板：
server.setRequestHandler(ListPromptsRequestSchema, async () => {
return {
prompts: [
{
name: "summarize",
description: "Summarize the given text",
arguments: [
{
name: "text",
description: "Text to summarize",
required: true,
},
],
},
],
};
});
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
if (name === "summarize") {
return {
description: "Summarize the given text",
messages: [
{
role: "user",
content: {
type: "text",
text: `Please summarize the following text: ${args.text}`,
},
},
],
};
}
throw new Error(`Unknown prompt: ${name}`);
});最佳实践
安全
- 彻底验证所有输入
- 使用环境变量进行敏感配置
- 实施适当的错误处理
- 遵循最小特权原则
演出
- 对I/O操作使用async/await
- 在适当的情况下实施缓存
- 优雅地处理超时
- 优化资源使用
错误处理
server.setRequestHandler(CallToolRequestSchema, async (request) => {
try {
// Tool implementation
} catch (error) {
return {
content: [
{
type: "text",
text: `Error: ${error.message}`,
},
],
isError: true,
};
}
});官方示例和文件
MCP官方存储库
- GitHub: 模型上下文协议/服务器
- 包含许多示例服务器，包括：
- 文件系统操作 - 数据库连接 - API集成 - Git操作 - 网络抓取
官方文件
- MCP规范: MCP文件
- TypeScript SDK: SDK文档
- 开发包: Python SDK指南
要研究的服务器示例
- 文件系统服务器: 文件系统示例
- 文件操作、目录列表 - 资源和工具实施
- Git服务器: git示例
- Git存储库操作 - 复杂的工具链
- SQLite服务器: sqlite示例
- 数据库连接 - 查询执行
- Web搜索服务器: 搜索示例
- 外部API集成 - 结果格式化
社区示例
部署选项
地方发展
- 使用stdio传输进行开发
- 使用MCP检查员进行测试
- 在Claude桌面中配置
生产部署
- 考虑HTTP/WebSocket传输以实现可扩展性
- 实施适当的日志记录和监控
- 使用流程管理器（PM2，systemd）
- 考虑使用Docker进行容器化
常见模式
环境配置
const config = {
apiKey: process.env.API_KEY,
baseUrl: process.env.BASE_URL || 'https://api.example.com',
timeout: parseInt(process.env.TIMEOUT || '5000'),
};速率限制
import { RateLimiter } from 'limiter';
const limiter = new RateLimiter(10, 'second');
server.setRequestHandler(CallToolRequestSchema, async (request) => {
await limiter.removeTokens(1);
// Tool implementation
});缓存
const cache = new Map();
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
const { uri } = request.params;
if (cache.has(uri)) {
return cache.get(uri);
}
const result = await fetchResource(uri);
cache.set(uri, result);
return result;
});故障排除
常见问题
- 传输错误：确保正确处理stdio
- 架构验证：验证输入/输出模式是否符合规范
- 异步处理：使用适当的async/await模式
- 错误响应：返回正确的错误结构
调试提示
- 使用MCP检查器进行交互式测试
- 启用调试日志记录
- 单独测试单个组件
- 验证JSON-RPC消息
贡献
请随时向此存储库提供示例、改进或其他文档。请遵循MCP社区指南，并确保所有示例都经过充分记录和测试。
许可证
MIT许可证-您可以在自己的项目中自由使用本指南和示例。
______________________________________________________________________
有关更多信息，请访问 MCP官方文件 或者加入GitHub上的社区讨论。