---

name: mcp-tool-developer description: "从零构建模型上下文协议（MCP）服务器和工具。使用 TypeScript/Python 进行全栈 MCP 开发，包括测试、部署和注册表发布。" category: developer-tools risk: safe source: community source_repo: demo112/yunqu-ai-skills source_type: community date_added: "2026-05-13" author: yundu-ai tags: [mcp, ai-agent, tool-development, typescript, python, llm, model-context-protocol] tools: [claude, cursor, gemini]

MCP 工具开发者

概述

擅长构建模型上下文协议（MCP）服务器，为 AI 代理赋予新能力。涵盖完整的 MCP 开发生命周期：规范定义、实现、测试、部署和注册表发布。支持 TypeScript 和 Python，提供生产就绪的模式。

本技能理解 MCP 规范原语（工具、资源、提示、采样）、传输选项（stdio、SSE、Streamable HTTP），以及使 MCP 服务器可靠且可组合的工具设计模式。

何时使用本技能

• 从零开始构建新的 MCP 服务器时使用
• 将现有 API 封装为 MCP 工具时使用
• 调试 MCP 服务器问题时使用
• 为 MCP 服务器设计工具模式时使用
• 将 MCP 服务器发布到注册表时使用

工作原理

步骤 1：定义 MCP 服务器范围

确定服务器应暴露的能力：

• 工具 - LLM 可以调用的函数（主要用例）
• 资源 - LLM 可以读取的数据（文件、API、数据库）
• 提示 - 可复用的提示模板

选择传输方式：

• stdio - 用于本地 CLI 工具（Claude Code、Cursor）
• SSE（服务器发送事件） - 用于远程/托管工具
• Streamable HTTP - MCP 规范中用于现代部署的新方式

步骤 2：设计工具模式

在编写实现之前定义输入/输出模式：

{
  name: "tool_name",
  description: "What this tool does (visible to the LLM)",
  inputSchema: {
    type: "object",
    properties: { ... },
    required: [ ... ]
  }
}

步骤 3：实现服务器

创建具有适当错误处理、验证和日志记录的服务器。使用官方 MCP SDK：TypeScript（@modelcontextprotocol/sdk）或 Python（mcp）。

步骤 4：测试和部署

使用 MCP Inspector 进行测试，验证工具模式，处理边缘情况，然后进行本地或远程部署。

示例

示例 1：TypeScript MCP 服务器

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-tools", version: "1.0.0" });

server.tool("greet", "Greet someone by name",
  { name: z.string().describe("Person's name") },
  async ({ name }) => ({ content: [{ type: "text", text: `Hello, ${name}!` }] })
);

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

示例 2：API 封装模式

将外部 API 封装为 MCP 工具，包含认证、速率限制和错误处理：

• 将 API 端点映射到工具
• 通过环境变量处理认证
• 将 API 响应转换为 LLM 友好的格式
• 添加指数退避的重试逻辑

最佳实践

• 构建小型、专注的工具，可以链式调用，而非单体工具
• 返回结构化错误，而非崩溃 - 工具应优雅地失败
• 在实现之前定义模式
• 包含帮助 LLM 理解何时以及如何使用每个工具的描述
• 根据模式验证所有输入
• 为外部 API 调用添加速率限制
• 使用环境变量存储密钥，永远不要硬编码凭据

限制

• 本技能提供指导和代码生成；实际运行时测试需要开发环境
• MCP 规范正在演进；请始终检查最新的规范版本
• 部署处理敏感数据的工具之前，安全审查是必不可少的

安全和安全注意事项

• 永远不要在工具实现中硬编码 API 密钥或凭据
• 对所有认证使用环境变量或密钥管理器
• 验证和清理所有输入以防止注入攻击
• 对外部 API 调用进行速率限制以防止滥用
• 仔细审查工具权限 - 工具可以访问文件、网络和执行代码

常见陷阱

• 问题： LLM 使用错误参数调用工具 解决方案： 改进工具描述并在描述字段中添加示例。LLM 通过阅读描述来决定如何调用工具。

• 问题： 工具在大输入时超时 解决方案： 添加输入大小验证和分页。对大响应使用流式传输而非缓冲。

相关技能

• api-integration-architect - 用于 MCP 工具中的 API 设计模式
• security-audit-code-reviewer - 用于审查 MCP 服务器代码安全性