mcp-builder

s-hiraoku 的头像作者 s-hiraoku

此技能指导构建高质量的MCP(模型上下文协议)服务器,使LLM能够与外部服务交互。当创建MCP服务器、设计工具接口或实现协议处理器时使用。

📖 中文导读:此技能指导构建高质量的MCP(模型上下文协议)服务器,使LLM能够与外部服务交互。当创建MCP服务器、设计工具接口或实现协议处理器时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: mcp-builder description: This skill guides building high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services. Use when creating MCP servers, designing tool interfaces, or implementing protocol handlers.

MCP Server Builder

Overview

Build MCP servers that enable LLMs to interact with external services through thoughtfully designed tools.

Key Principle: Don't simply wrap API endpoints—build thoughtful, high-impact workflow tools.

Four-Phase Development

Phase 1: Research & Planning

  • Study agent-centric design principles
  • Review MCP protocol documentation
  • Study target API documentation exhaustively
  • Create detailed implementation plan

Phase 2: Implementation

  • Set up project structure
  • Build core infrastructure (auth, request helpers, formatters)
  • Implement tools with JSON Schema validation
  • Follow language-specific best practices

Phase 3: Review & Refine

  • Code quality review (DRY, consistency, error handling)
  • Test safely using evaluation harness
  • Verify against quality checklist

Phase 4: Create Evaluations

  • Design 10 complex, realistic test questions
  • Create XML-formatted evaluation files
  • Verify answers independently

Server Types

Type Transport Use Case
stdio Process pipes Local custom servers
HTTP REST Cloud-hosted servers
SSE Server-Sent Events Real-time updates
WebSocket Bidirectional Real-time communication

Tool Design

// Good: Workflow-oriented
async function analyzeAndSummarize(url: string) {
  // Fetches, parses, and summarizes in one call
}

// Avoid: Simple API wrapper
async function fetchPage(url: string) {
  // Just wraps fetch()
}

Implementation Standards

TypeScript

import { Server } from "@modelcontextprotocol/sdk/server/index.js";

const server = new Server({
  name: "my-server",
  version: "1.0.0"
}, {
  capabilities: { tools: {} }
});

Python (FastMCP)

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def my_tool(param: str) -> str:
    """Tool description."""
    return result

Best Practices

  1. JSON Schema validation on all inputs/outputs
  2. Comprehensive error handling with meaningful messages
  3. Logging to stderr (stdout reserved for protocol)
  4. Security-first - validate inputs, manage sessions
  5. Configurable detail levels for context efficiency
  6. Tool annotations - mark read-only, destructive, idempotent