
关于
为 Claude Code 构建 MCP 服务器,涵盖工具定义、资源处理和传输层。
name: mcp-ops description: "Model Context Protocol 服务器开发、工具设计、资源处理和传输配置。适用于:mcp、model context protocol、mcp server、mcp tool、mcp resource、fastmcp、mcp transport、stdio、sse、streamable http、mcp inspector、tool handler、mcp prompt。" license: MIT allowed-tools: "Read Write Bash" metadata: author: claude-mods related-skills: claude-code-hooks, claude-code-debug, typescript-ops, python-fastapi-ops
MCP 操作
使用 Python 和 TypeScript 构建、测试和部署 Model Context Protocol 服务器的全面模式。
MCP 架构快速参考
┌─────────────────────────────────────────────────────────┐
│ MCP Host │
│ (Claude Desktop, Claude Code, Custom App) │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Client A │ │ Client B │ │ Client C │ │
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
└────────┼───────────────┼───────────────┼────────────────┘
│ │ │
┌────┴────┐ ┌────┴────┐ ┌────┴────┐
│Transport│ │Transport│ │Transport│
│ (stdio) │ │ (SSE) │ │ (HTTP) │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
┌────────┴──┐ ┌──────┴────┐ ┌──────┴────┐
│ Server A │ │ Server B │ │ Server C │
│ ┌────────┐ │ │ ┌────────┐ │ │ ┌────────┐ │
│ │ Tools │ │ │ │Resources│ │ │ │Prompts │ │
│ └────────┘ │ │ └────────┘ │ │ └────────┘ │
└────────────┘ └────────────┘ └────────────┘
协议:JSON-RPC 2.0 通过选定传输
流程:Client → request → Server → response → Client
服务器类型决策树
你的 MCP 服务器需要什么传输方式?
│
├─ 本地 CLI 工具 / 单用户桌面集成?
│ └─ stdio
│ - 最简单的设置,无需网络
│ - Claude Desktop、Claude Code 原生支持
│ - 进程生命周期由宿主管理
│
├─ Web 仪表盘 / 基于浏览器的客户端?
│ └─ SSE(Server-Sent Events)
│ - 基于 HTTP,可穿越防火墙
│ - 持久连接用于服务器→客户端事件
│ - 适合开发和内部工具
│
└─ 生产 API / 多租户 / 云部署?
└─ Streamable HTTP
- HTTP POST 用于请求,SSE 用于流式响应
- 支持无状态和有状态模式
- 完整认证支持,负载均衡器友好
- 推荐用于生产部署
Tool vs Resource vs Prompt 决策树
LLM 需要做什么?
│
├─ 执行操作或计算?
│ └─ TOOL
│ - 有副作用(API 调用、文件写入、数据库变更)
│ - LLM 决定何时调用
│ - 示例:create_issue、run_query、send_email
│
├─ 读取数据或上下文?
│ └─ RESOURCE
│ - 只读,无副作用
│ - 由应用程序控制(非 LLM 决定)
│ - 示例:file://、db://schema、config://settings
│
└─ 需要结构化的提示模板?
└─ PROMPT
- 预定义的消息模板
- 用户选择,带参数
- 示例:code_review、summarize、translate
Python 快速开始(FastMCP)
from fastmcp import FastMCP
mcp = FastMCP("my-server")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
@mcp.resource("config://app")
def get_config() -> str:
"""Return app configuration."""
return json.dumps({"version": "1.0"})
TypeScript 快速开始
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = new McpServer({ name: "my-server", version: "1.0.0" });
server.tool("add", { a: z.number(), b: z.number() }, async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }],
}));
const transport = new StdioServerTransport();
await server.connect(transport);
工具设计最佳实践
| 原则 | 说明 |
|------|------|
| 单一职责 | 每个工具做一件事 |
| 清晰命名 | 动词_名词格式:create_issue、search_docs |
| 详细描述 | 帮助 LLM 理解何时使用 |
| 输入验证 | 使用 Pydantic/Zod 验证参数 |
| 错误处理 | 返回有意义的错误消息 |
| 幂等性 | 尽可能使工具幂等 |
附加资源
./references/fastmcp-patterns.md- FastMCP 高级模式./references/transport-config.md- 传输配置详解./references/testing-mcp.md- MCP 服务器测试策略./references/deployment.md- 生产部署模式
兼容工具
Claude Code
标签
AI与机器学习
