AgentSkillsCN

building-mcp-servers

以正确的模式与独特的设计，打造Next.js 16应用。当您需要创建页面、布局、动态路由，或从Next.js 15升级至Next.js 16，亦或是实现proxy.ts时，本技能将助您一臂之力。它不仅涵盖了重大变更（如async params/searchParams、Turbopack、cacheComponents），还兼顾了前端美学的优化与提升。 但请注意：本技能不适用于非React应用，或仅用于后端开发的项目。

SKILL.md
--- frontmatter
name: building-mcp-servers
description: |
  Guides creation of high-quality MCP (Model Context Protocol) servers that enable LLMs
  to interact with external services through well-designed tools. Use when building MCP
  servers to integrate external APIs or services, whether in Python (FastMCP) or
  Node/TypeScript (MCP SDK). Covers tool design, authentication, Docker deployment,
  and evaluation creation. NOT when consuming existing MCP servers (use the server directly).

MCP Server Development Guide

Overview

Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.

High-Level Workflow

Creating a high-quality MCP server involves four main phases:

Phase 1: Deep Research and Planning

1.1 Understand Modern MCP Design

API Coverage vs. Workflow Tools: Balance comprehensive API endpoint coverage with specialized workflow tools. When uncertain, prioritize comprehensive API coverage.

Tool Naming and Discoverability: Use consistent prefixes (e.g., github_create_issue, github_list_repos) and action-oriented naming.

Context Management: Design tools that return focused, relevant data. Support filtering/pagination.

Actionable Error Messages: Error messages should guide agents toward solutions with specific suggestions.

1.2 Study MCP Protocol Documentation

Start with the sitemap: https://modelcontextprotocol.io/sitemap.xml

Fetch pages with .md suffix (e.g., https://modelcontextprotocol.io/specification/draft.md).

Key pages: Specification overview, transport mechanisms, tool/resource/prompt definitions.

1.3 Study Framework Documentation

Recommended stack:

  • •Language: TypeScript (high-quality SDK, good AI code generation)
  • •Transport: Streamable HTTP for remote servers, stdio for local servers

Load framework documentation:

SDK Documentation:

  • •TypeScript: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
  • •Python: https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

1.4 Plan Your Implementation

Review the service's API documentation. List endpoints to implement, starting with most common operations.

Phase 2: Implementation

2.1 Set Up Project Structure

See language-specific guides:

2.2 Implement Core Infrastructure

Create shared utilities:

  • •API client with authentication
  • •Error handling helpers
  • •Response formatting (JSON/Markdown)
  • •Pagination support

2.3 Implement Tools

For each tool:

Input Schema:

  • •Use Zod (TypeScript) or Pydantic (Python)
  • •Include constraints and clear descriptions

Output Schema:

  • •Define outputSchema where possible
  • •Use structuredContent in responses

Tool Description:

  • •Concise summary, parameter descriptions, return type

Annotations:

  • •readOnlyHint, destructiveHint, idempotentHint, openWorldHint

Phase 3: Review and Test

3.1 Code Quality

Review for: DRY principle, consistent error handling, full type coverage, clear descriptions.

3.2 Build and Test

TypeScript:

bash
npm run build
npx @modelcontextprotocol/inspector

Python:

bash
python -m py_compile your_server.py
# Test with MCP Inspector

Phase 4: Create Evaluations

Create 10 evaluation questions to test LLM effectiveness with your server.

Requirements for each question:

  • •Independent, read-only, complex, realistic, verifiable, stable

Output Format:

xml
<evaluation>
  <qa_pair>
    <question>Your question here</question>
    <answer>Expected answer</answer>
  </qa_pair>
</evaluation>

See Evaluation Guide for complete guidelines.

Docker/Containerization

Transport Security (allowed_hosts)

FastMCP validates Host headers. For Docker, configure:

python
from mcp.server.fastmcp import FastMCP
from mcp.server.transport_security import TransportSecuritySettings

transport_security = TransportSecuritySettings(
    allowed_hosts=[
        "127.0.0.1:*", "localhost:*", "[::1]:*",
        "mcp-server:*",  # Docker container name
        "0.0.0.0:*",
    ],
)
mcp = FastMCP("my_server", transport_security=transport_security)

Health Check Endpoint

Add /health endpoint via middleware (see references for full example).

Verification

Run: python3 scripts/verify.py

Expected: ✓ building-mcp-servers skill ready

If Verification Fails

  1. •Run diagnostic: Check references/ folder exists
  2. •Check: All reference files present
  3. •Stop and report if still failing

References