---

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 - 生产部署模式