Back to Details

mcp-tool-developer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MCP Tool Developer

MCP工具开发者

Overview

概述

Expert at building Model Context Protocol (MCP) servers that give AI agents new capabilities. Covers the full MCP development lifecycle: specification, implementation, testing, deployment, and registry publishing. Supports both TypeScript and Python with production-ready patterns.
This skill understands MCP specification primitives (tools, resources, prompts, sampling), transport options (stdio, SSE, Streamable HTTP), and the tool design patterns that make MCP servers reliable and composable.
擅长构建为AI Agent赋予新能力的Model Context Protocol (MCP)服务器。覆盖MCP开发全生命周期：规格制定、实现、测试、部署及注册表发布。支持TypeScript与Python，并提供生产就绪的模式。
本技能熟悉MCP规格原语（工具、资源、提示词、采样）、传输选项（stdio、SSE、Streamable HTTP），以及能让MCP服务器可靠且可组合的工具设计模式。

When to Use This Skill

适用场景

  • Use when building a new MCP server from scratch
  • Use when wrapping an existing API as an MCP tool
  • Use when debugging MCP server issues
  • Use when designing the tool schema for an MCP server
  • Use when publishing an MCP server to a registry
  • 从头构建新的MCP服务器时使用
  • 将现有API封装为MCP工具时使用
  • 调试MCP服务器问题时使用
  • 为MCP服务器设计工具架构时使用
  • 将MCP服务器发布到注册表时使用

How It Works

工作流程

Step 1: Define the MCP Server Scope

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

Identify what capabilities the server should expose:
  • Tools - Functions the LLM can call (primary use case)
  • Resources - Data the LLM can read (files, APIs, databases)
  • Prompts - Reusable prompt templates
Choose the transport:
  • stdio - For local CLI tools (Claude Code, Cursor)
  • SSE (Server-Sent Events) - For remote/hosted tools
  • Streamable HTTP - New in MCP spec for modern deployments
确定服务器应暴露的能力：
  • 工具 - 大语言模型（LLM）可调用的函数（主要使用场景）
  • 资源 - LLM可读取的数据（文件、API、数据库）
  • 提示词 - 可复用的提示词模板
选择传输方式：
  • stdio - 适用于本地CLI工具（Claude Code、Cursor）
  • SSE (Server-Sent Events) - 适用于远程/托管工具
  • Streamable HTTP - MCP规格新增的现代部署方式

Step 2: Design the Tool Schema

步骤2：设计工具架构

Define input/output schemas before writing implementation:
typescript
{
  name: "tool_name",
  description: "What this tool does (visible to the LLM)",
  inputSchema: {
    type: "object",
    properties: { ... },
    required: [ ... ]
  }
}
在编写实现代码前定义输入/输出架构：
typescript
{
  name: "tool_name",
  description: "What this tool does (visible to the LLM)",
  inputSchema: {
    type: "object",
    properties: { ... },
    required: [ ... ]
  }
}

Step 3: Implement the Server

步骤3：实现服务器

Create the server with proper error handling, validation, and logging. Use the official MCP SDK for TypeScript (@modelcontextprotocol/sdk) or Python (mcp).
创建具备完善错误处理、验证及日志功能的服务器。使用官方MCP SDK：TypeScript版本为@modelcontextprotocol/sdk，Python版本为mcp。

Step 4: Test and Deploy

步骤4：测试与部署

Test with the MCP Inspector, validate tool schemas, handle edge cases, then deploy locally or remotely.
使用MCP Inspector进行测试，验证工具架构，处理边缘情况，随后在本地或远程环境部署。

Examples

示例

Example 1: TypeScript MCP Server

示例1：TypeScript MCP服务器

typescript
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);
typescript
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);

Example 2: API Wrapper Pattern

示例2：API封装模式

Wrap an external API as an MCP tool with auth, rate limiting, and error handling:
  • Map API endpoints to tools
  • Handle auth via environment variables
  • Transform API responses to LLM-friendly format
  • Add retry logic with exponential backoff
将外部API封装为MCP工具，包含认证、限流及错误处理：
  • 将API端点映射为工具
  • 通过环境变量处理认证
  • 将API响应转换为LLM友好格式
  • 添加指数退避重试逻辑

Best Practices

最佳实践

  • Build small, focused tools that can be chained rather than monolithic tools
  • Return structured errors, not crashes - tools should fail gracefully
  • Define schemas before implementation
  • Include descriptions that help the LLM understand when and how to use each tool
  • Validate all inputs against the schema
  • Add rate limiting for external API calls
  • Use environment variables for secrets, never hardcode credentials
  • 构建小型、专注的可链式调用工具，而非单体工具
  • 返回结构化错误而非崩溃——工具应优雅失败
  • 在实现前定义架构
  • 包含能帮助LLM理解何时及如何使用各工具的描述
  • 根据架构验证所有输入
  • 为外部API调用添加限流
  • 使用环境变量存储密钥，绝不要硬编码凭证

Limitations

局限性

  • This skill provides guidance and code generation; actual runtime testing requires a development environment
  • MCP specification is evolving; always check the latest spec version
  • Security review is essential before deploying tools that handle sensitive data
  • 本技能提供指导与代码生成；实际运行时测试需要开发环境
  • MCP规格在不断演进；请始终查阅最新版本的规格
  • 部署处理敏感数据的工具前，安全审查至关重要

Security and Safety Notes

安全与注意事项

  • Never hardcode API keys or credentials in tool implementations
  • Use environment variables or secret managers for all authentication
  • Validate and sanitize all inputs to prevent injection attacks
  • Rate limit external API calls to prevent abuse
  • Review tool permissions carefully - tools can access files, networks, and execute code
  • 绝不要在工具实现中硬编码API密钥或凭证
  • 所有认证均使用环境变量或密钥管理器
  • 验证并清理所有输入以防止注入攻击
  • 为外部API调用添加限流以防止滥用
  • 仔细审查工具权限——工具可访问文件、网络并执行代码

Common Pitfalls

常见陷阱

  • Problem: LLM calls tools with wrong parameters Solution: Improve tool descriptions and add examples in the description field. The LLM reads descriptions to decide how to call tools.
  • Problem: Tool times out on large inputs Solution: Add input size validation and pagination. Stream large responses instead of buffering.
  • 问题： LLM使用错误参数调用工具 解决方案： 优化工具描述，并在描述字段中添加示例。LLM会通过描述来决定如何调用工具。
  • 问题： 工具在处理大输入时超时 解决方案： 添加输入大小验证与分页功能。采用流式传输大响应而非缓冲。

Related Skills

相关技能

  • api-integration-architect
    - For API design patterns used in MCP tools
  • security-audit-code-reviewer
    - For reviewing MCP server code security
  • api-integration-architect
    - 适用于MCP工具中使用的API设计模式
  • security-audit-code-reviewer
    - 适用于审查MCP服务器代码的安全性