code_style

Python MCP SDK (FastMCP) Code Style

Context: 适用于使用 mcp 官方 SDK 的 FastMCP 高级接口开发服务器。 Focus: 使用装饰器、类型提示自动生成 Schema、简化生命周期管理。 Reference: https://pypi.org/project/mcp/

1. 核心原则 (Core Principles)

• FastMCP 优先: 始终使用 mcp.server.fastmcp.FastMCP 类，避免直接操作底层的 Server 类。
• 类型驱动: 利用 Python 类型提示 (str, int, bool, list, 等) 自动生成 MCP Schema；优先使用简单类型平铺传参，避免用单个字典/对象包住所有参数。
• 文档即描述: 函数的 Docstring 会自动转换为工具/资源的描述字段。
• 上下文感知: 使用 Context 对象处理日志、进度报告和二进制数据。

2. 基础架构 (Basic Structure)

标准的 FastMCP 服务器结构如下：

from mcp.server.fastmcp import FastMCP, Context, Image

# 1. 初始化服务器
mcp = FastMCP("My Server")

# 2. 定义工具 (Tools)
@mcp.tool()
async def calculate_metrics(data: list[float], threshold: float = 0.5) -> dict[str, float]:
    """
    计算数据指标。
    
    Args:
        data: 输入的数据列表
        threshold: 过滤阈值
    """
    filtered = [x for x in data if x > threshold]
    return {
        "count": len(filtered),
        "average": sum(filtered) / len(filtered) if filtered else 0
    }

# 3. 定义资源 (Resources)
@mcp.resource("file://{path}")
def read_custom_file(path: str) -> str:
    """读取自定义格式文件"""
    return f"Mock content for {path}"

# 4. 运行入口
if __name__ == "__main__":
    mcp.run()

3. 关键模式 (Key Patterns)

3.1 工具传参：简单类型平铺 (Simple Flat Parameters)

优先使用简单类型平铺传参，不要用单个 Pydantic 模型或字典包住所有参数。这样 MCP 客户端只需传 key: value，无需构造 params: { ... } 对象。校验在函数内部完成。

• 必填/常用参数：str、int、bool、list、tuple 等，用 Annotated[T, Field(description="...")] 写描述。
• 可选参数：带默认值即可，如 limit: int = 10。
• 仅在确有复杂嵌套、且多工具复用时，再考虑 Pydantic 模型。

from typing import Annotated
from pydantic import Field

@mcp.tool()
async def search_database(
    query: Annotated[str, Field(description="搜索关键词")],
    limit: Annotated[int, Field(description="最多返回条数")] = 10,
    tags: list[str] | None = None,
    ctx: Context,
) -> list[str]:
    """在数据库中搜索内容。"""
    if tags is None:
        tags = []
    # 校验在内部完成，如 limit 范围等
    return [f"Result for {query}"]