mcp-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MCP Builder

MCP 构建器

Build a working MCP server from a description of the tools you need. Produces a deployable Python server using FastMCP.

根据你所需工具的描述构建可运行的MCP服务器。使用FastMCP生成可部署的Python服务器。

Workflow

工作流程

Step 1: Define What to Expose

步骤1：定义要暴露的内容

Ask what the server needs to provide:

Tools — Functions Claude can call (API wrappers, calculations, file operations)
Resources — Data Claude can read (database records, config, documents)
Prompts — Reusable prompt templates with parameters

A brief like "MCP server for querying our customer database" is enough.

明确服务器需要提供的内容：

工具 — Claude可调用的函数（API封装器、计算、文件操作）
资源 — Claude可读取的数据（数据库记录、配置、文档）
提示词 — 带参数的可复用提示词模板

类似“用于查询客户数据库的MCP服务器”这样的简短描述就足够了。

Step 2: Scaffold the Server

步骤2：搭建服务器框架

bash

pip install fastmcp

Copy and customise

assets/basic-server.py

python

from fastmcp import FastMCP

bash

pip install fastmcp

复制并自定义

assets/basic-server.py

：

python

from fastmcp import FastMCP

MUST be at module level for FastMCP Cloud

mcp = FastMCP("My Server")

@mcp.tool() async def search_customers(query: str) -> str: """Search customers by name or email.""" # Implementation here return f"Found customers matching: {query}"

@mcp.resource("customers://{customer_id}") async def get_customer(customer_id: str) -> str: """Get customer details by ID.""" return f"Customer {customer_id} details"

if name == "main": mcp.run()

undefined

mcp = FastMCP("My Server")

@mcp.tool() async def search_customers(query: str) -> str: """Search customers by name or email.""" # Implementation here return f"Found customers matching: {query}"

@mcp.resource("customers://{customer_id}") async def get_customer(customer_id: str) -> str: """Get customer details by ID.""" return f"Customer {customer_id} details"

if name == "main": mcp.run()

undefined

Step 3: Add Companion CLI Scripts (Optional)

步骤3：添加配套CLI脚本（可选）

For Claude Code terminal use, add scripts alongside the MCP server:

my-mcp-server/
├── src/index.ts          # MCP server (for Claude.ai)
├── scripts/
│   ├── search.ts         # CLI version of search tool
│   └── _shared.ts        # Shared auth/config
├── SCRIPTS.md            # Documents available scripts
└── package.json

CLI scripts provide file I/O, batch processing, and richer output that MCP can't. See

assets/SCRIPTS-TEMPLATE.md

and

assets/script-template.ts

for TypeScript templates.

对于Claude Code终端使用，在MCP服务器旁添加脚本：

my-mcp-server/
├── src/index.ts          # MCP server (for Claude.ai)
├── scripts/
│   ├── search.ts         # CLI version of search tool
│   └── _shared.ts        # Shared auth/config
├── SCRIPTS.md            # Documents available scripts
└── package.json

CLI脚本提供MCP不支持的文件I/O、批量处理和更丰富的输出。请查看

assets/SCRIPTS-TEMPLATE.md

和

assets/script-template.ts

获取TypeScript模板。

Step 4: Test Locally

步骤4：本地测试

bash

undefined

bash

undefined

Run server directly

python server.py

With FastMCP dev mode (auto-reload)

fastmcp dev server.py

HTTP mode for remote clients

python server.py --transport http --port 8000

Test with MCP Inspector

fastmcp dev server.py --with-editable .

undefined

fastmcp dev server.py --with-editable .

undefined

Step 5: Deploy

步骤5：部署

FastMCP Cloud (simplest):

bash

fastmcp deploy server.py --name my-server

Docker (self-hosted): See

references/cloud-deployment.md

for Dockerfile patterns.

Cloudflare Workers (edge): See the cloudflare-worker-builder skill for Workers-based MCP servers.

FastMCP Cloud（最简方式）：

bash

fastmcp deploy server.py --name my-server

Docker（自托管）：请查看

references/cloud-deployment.md

获取Dockerfile示例。

Cloudflare Workers（边缘部署）：请查看cloudflare-worker-builder技能获取基于Workers的MCP服务器构建方法。

Critical Patterns

关键模式

Module-Level Server Instance

模块级服务器实例

FastMCP Cloud requires the server instance at module level:

python

undefined

FastMCP Cloud要求服务器实例位于模块级别：

python

undefined

CORRECT

mcp = FastMCP("My Server")

@mcp.tool() def my_tool(): ...

mcp = FastMCP("My Server")

@mcp.tool() def my_tool(): ...

WRONG — Cloud can't find the server

def create_server(): mcp = FastMCP("My Server") return mcp

undefined

def create_server(): mcp = FastMCP("My Server") return mcp

undefined

Type Annotations Required

必须使用类型注解

FastMCP uses type annotations to generate tool schemas:

python

@mcp.tool()
async def search(
    query: str,           # Required parameter
    limit: int = 10,      # Optional with default
    tags: list[str] = []  # Complex types supported
) -> str:
    """Docstring becomes the tool description."""
    ...

FastMCP使用类型注解生成工具 schema：

python

@mcp.tool()
async def search(
    query: str,           # Required parameter
    limit: int = 10,      # Optional with default
    tags: list[str] = []  # Complex types supported
) -> str:
    """Docstring becomes the tool description."""
    ...

Error Handling

错误处理

Return errors as strings, don't raise exceptions:

python

@mcp.tool()
async def get_data(id: str) -> str:
    try:
        result = await fetch_data(id)
        return json.dumps(result)
    except NotFoundError:
        return f"Error: No data found for ID {id}"

将错误以字符串形式返回，不要抛出异常：

python

@mcp.tool()
async def get_data(id: str) -> str:
    try:
        result = await fetch_data(id)
        return json.dumps(result)
    except NotFoundError:
        return f"Error: No data found for ID {id}"

Asset Files

资源文件

```
assets/basic-server.py
```
— Minimal FastMCP server template
```
assets/self-contained-server.py
```
— Server with storage and middleware
```
assets/tools-examples.py
```
— Tool patterns and type annotations
```
assets/resources-examples.py
```
— Resource URI patterns
```
assets/prompts-examples.py
```
— Prompt template patterns
```
assets/client-example.py
```
— MCP client usage
```
assets/SCRIPTS-TEMPLATE.md
```
— CLI companion docs template
```
assets/script-template.ts
```
— TypeScript CLI script template

```
assets/basic-server.py
```
— 最小化FastMCP服务器模板
```
assets/self-contained-server.py
```
— 包含存储和中间件的服务器模板
```
assets/tools-examples.py
```
— 工具模式与类型注解示例
```
assets/resources-examples.py
```
— 资源URI模式示例
```
assets/prompts-examples.py
```
— 提示词模板模式示例
```
assets/client-example.py
```
— MCP客户端使用示例
```
assets/SCRIPTS-TEMPLATE.md
```
— CLI配套文档模板
```
assets/script-template.ts
```
— TypeScript CLI脚本模板

Reference Files

参考文件

```
references/common-errors.md
```
— 30+ documented errors with fixes
```
references/cli-commands.md
```
— FastMCP CLI reference
```
references/cloud-deployment.md
```
— Deployment patterns (Cloud, Docker, Workers)
```
references/production-patterns.md
```
— Auth, middleware, storage backends
```
references/integration-patterns.md
```
— FastAPI mount, OpenAPI import
```
references/context-features.md
```
— Lifespan, dependency injection

```
references/common-errors.md
```
— 30+个带修复方案的已记录错误
```
references/cli-commands.md
```
— FastMCP CLI参考文档
```
references/cloud-deployment.md
```
— 部署模式（Cloud、Docker、Workers）
```
references/production-patterns.md
```
— 认证、中间件、存储后端
```
references/integration-patterns.md
```
— FastAPI挂载、OpenAPI导入
```
references/context-features.md
```
— 生命周期、依赖注入