SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场mcp-ops

mcp-ops

智能体与模型

查看项目

更新于 10-13 16:52

技能介绍

用途

mcp-ops 是一份用于 Model Context Protocol（MCP）服务器开发的技能资料，目标是为使用 Python 和 TypeScript 构建、测试、部署 MCP 服务器提供成体系的模式参考。资料声明其生态事实核验日期为 2026-07-05（独立 FastMCP 处于 3.x 主版本）。

主要能力与覆盖内容

  1. MCP 架构速览：说明 MCP Host（如 Claude Desktop、Claude Code、自定义应用）下挂多个 Client，Client 通过传输层（stdio、SSE、HTTP）连接各自的 Server，Server 内可包含 Tools、Resources、Prompts。协议为 JSON-RPC 2.0，流程为 Client 发起请求、Server 返回响应。

  2. 传输选型决策树：

    • 本地 CLI 工具或单用户桌面集成 → stdio（无需网络，由宿主管理进程生命周期）；
    • Web 面板或浏览器客户端 → SSE（基于 HTTP，可穿透防火墙，支持服务器到客户端的持续事件）；
    • 生产 API / 多租户 / 云部署 → Streamable HTTP（POST 请求加 SSE 流式响应，支持无状态与有状态模式，完整认证，适合负载均衡）。

  3. Tool / Resource / Prompt 选型决策树：

    • 需要执行动作或计算 → Tool（有副作用，接受结构化输入并返回结果，示例 run_query、create_issue、send_email）；
    • 需要读取数据或上下文 → Resource（只读，以 URI 标识，如 config://app、schema://users、file://readme.md）；
    • 需要引导模型行为或工作流 → Prompt（带参数的模板化指令，示例 code_review、summarize）。

  4. Python SDK 快速上手：使用 from mcp.server.fastmcp import FastMCP，以 @mcp.tool()、@mcp.resource()、@mcp.prompt() 装饰器注册能力，mcp.run() 默认使用 stdio 传输。安装命令为 uv init my-mcp-server && cd my-mcp-server、uv add mcp[cli]，运行方式为 uv run python server.py 或 uv run mcp run server.py。

  5. 两个 Python FastMCP 的区分：官方 mcp SDK 内置的是冻结在 1.x 时代的 FastMCP（稳定、最小）；独立 fastmcp 包（gofastmcp.com）是活跃开发所在，处于 3.x 主版本，装饰器接口相同，另含认证、代理、OpenAPI 生成和测试客户端。使用独立包需 uv add fastmcp，导入路径为 from fastmcp import FastMCP。FastMCP 3 相对 2.x 的破坏性变更包括：移除 16 个已弃用构造参数（传输配置改为在 serve 时传入）、ui= 由 app= 替代、ctx.set_state()/ctx.get_state() 变为异步且会话级持久化、元数据命名空间从 _fastmcp 改为 fastmcp。

  6. TypeScript SDK 快速上手：从 @modelcontextprotocol/sdk/server/mcp.js 导入 McpServer，从 .../server/stdio.js 导入 StdioServerTransport，使用 zod 定义参数 schema，通过 server.tool()、server.resource()、server.prompt() 注册能力，最后 server.connect(new StdioServerTransport())。安装命令为 npm init -y、npm install @modelcontextprotocol/sdk zod，运行 npx tsx server.ts。

  7. 传输选择矩阵：从使用场景、协议、认证支持、部署方式、重连、多客户端、防火墙、状态、适用对象等维度对比 stdio、SSE、Streamable HTTP 三者。例如 stdio 认证仅靠环境变量、仅支持 1:1；SSE 支持 Bearer token 与多客户端；Streamable HTTP 支持完整 OAuth2/PKCE、可水平扩展、无状态弹性。

  8. 认证模式：示例一是从环境变量读取 API Key 并在调用外部 API 时放入 Authorization 头；示例二是 OAuth2 刷新令牌并用内存缓存管理有效期。同时给出 Claude Desktop 配置文件中通过 mcpServers、command、args、env 注入环境变量的写法。

  9. 常见问题表：列出工具未在客户端出现（inputSchema 无效）、工具返回原始对象（需返回 content 列表）、长操作超时、并发请求失败（共享可变状态）、大响应崩溃、错误被静默吞掉、SSE 连接断开、客户端忽略新工具、工具名冲突、资源 URI 过于笼统、异步处理缺失、本地可用但 Claude Desktop 失败（工作目录或 PATH 不同）等现象的原因与修复方式。

  10. 参考文件与校验脚本：references 目录下按主题划分五个文件（server-architecture.md 约 700 行、tool-handlers.md 约 650 行、resources-prompts.md 约 550 行、transport-auth.md 约 550 行、testing-debugging.md 约 550 行）。scripts/check-mcp-facts.py 支持 --offline（结构校验，退出码 0 一致、10 漂移）与 --live（联网新鲜度校验，退出码 10 漂移、7 注册表不可达），规范事实集存放于 assets/mcp-facts.json。

使用方式

资料以技能文档形式提供，包含可直接复制的 Python 与 TypeScript 代码片段、安装与运行命令、配置文件片段以及排查对照表。可按需查阅对应参考文件深入了解某一主题。

适用场景

适合需要构建、测试或部署 MCP 服务器的开发者，尤其是需要选择传输方式、设计 Tool/Resource/Prompt、接入认证或排查客户端集成问题（如 Claude Desktop）的场景。

限制

资料本身未说明许可证、价格或收费模式，未提供具体性能指标。其中标注的生态事实核验日期与版本号可能随生态变化而过时，资料提供了校验脚本用于检测漂移。