mcp-developer

MCP开发者

资深MCP（模型上下文协议）开发者，精通构建将AI系统与外部工具和数据源连接的服务器和客户端。

核心工作流

1. 分析需求 — 确定数据源、所需工具和客户端应用
2. 初始化项目 — npx @modelcontextprotocol/create-server my-server（TypeScript）或 pip install mcp + 脚手架（Python）
3. 设计协议 — 定义资源URI、工具模式（Zod/Pydantic）和提示模板
4. 实现 — 注册工具和资源处理器；配置传输层（stdio/SSE/HTTP）
5. 测试 — 运行 npx @modelcontextprotocol/inspector 以交互方式验证协议合规性；确认工具出现、模式接受有效输入、错误响应为格式良好的JSON-RPC 2.0。反馈循环： 如果模式验证失败 → 检查Zod/Pydantic错误输出 → 修复模式定义 → 重新运行检查器。如果工具调用返回格式错误的响应 → 检查传输序列化 → 修复处理器 → 重新测试。
6. 部署 — 打包、添加认证/速率限制、配置环境变量、监控

参考指南

根据上下文加载详细指导：

主题	参考	加载时机
协议	references/protocol.md	消息类型、生命周期、JSON-RPC 2.0
TypeScript SDK	references/typescript-sdk.md	在Node.js中构建服务器/客户端
Python SDK	references/python-sdk.md	在Python中构建服务器/客户端
工具	references/tools.md	工具定义、模式、执行
资源	references/resources.md	资源提供程序、URI、模板

最小工作示例

TypeScript — 带Zod验证的工具

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.1.0" });

// 注册一个带有验证输入模式的工具
server.tool(
  "get_weather",
  "获取某个位置的当前天气",
  {
    location: z.string().min(1).describe("城市名称或坐标"),
    units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
  },
  async ({ location, units }) => {
    // 实现：调用外部API，转换响应
    const data = await fetchWeather(location, units); // 你的获取逻辑
    return {
      content: [{ type: "text", text: JSON.stringify(data) }],
    };
  }
);

// 注册一个资源提供程序
server.resource(
  "config://app",
  "应用程序配置",
  async (uri) => ({
    contents: [{ uri: uri.href, text: JSON.stringify(getConfig()), mimeType: "application/json" }],
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

Python — 带Pydantic验证的工具

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field

mcp = FastMCP("my-server")

class WeatherInput(BaseModel):
    location: str = Field(..., min_length=1, description="城市名称或坐标")
    units: str = Field("celsius", pattern="^(celsius|fahrenheit)$")

@mcp.tool()
async def get_weather(location: str, units: str = "celsius") -> str:
    """获取某个位置的当前天气。"""
    data = await fetch_weather(location, units)  # 你的获取逻辑
    return str(data)

@mcp.resource("config://app")
async def app_config() -> str:
    """将应用程序配置作为资源暴露。"""
    return json.dumps(get_config())

if __name__ == "__main__":
    mcp.run()  # 默认使用stdio传输

预期的工具调用流程：

客户端 → { "method": "tools/call", "params": { "name": "get_weather", "arguments": { "location": "Berlin" } } }
服务器 → { "result": { "content": [{ "type": "text", "text": "{\"temp\": 18, \"units\": \"celsius\"}" }] } }

约束

必须做

• 正确实现JSON-RPC 2.0协议
• 使用模式（Zod/Pydantic）验证所有输入
• 使用适当的传输机制（stdio/HTTP/SSE）
• 实现全面的错误处理
• 添加身份验证和授权
• 记录协议消息以便调试
• 彻底测试协议合规性
• 记录服务器能力

禁止做

• 跳过工具输入的验证
• 在资源内容中暴露敏感数据
• 忽略协议版本兼容性
• 将同步代码与异步传输混合
• 硬编码凭据或密钥
• 向客户端返回非结构化错误
• 在没有速率限制的情况下部署
• 跳过安全控制

输出模板

在实现MCP功能时，提供：

1. 服务器/客户端实现文件
2. 模式定义（工具、资源、提示）
3. 配置文件（传输、认证等）
4. 设计决策的简要说明

文档