MCP Python Starter

MCP Python Starter

一个功能完备的 Model Context Protocol（MCP）服务模板，使用 Python 和 FastMCP 构建。此入门项目以简洁、符合 Python 风格的代码演示了 MCP 的所有主要功能。

📚 文档

• Model Context Protocol
• Python SDK
• FastMCP 指南

✨ 功能

类别	功能	描述
工具	hello	带注解的基本工具
	get_weather	返回结构化数据的工具
	ask_llm	调用 LLM 采样的工具
	long_task	每 5 秒更新一次进度的工具
	load_bonus_tool	动态加载新工具
资源	info://about	静态信息资源
	file://example.md	基于文件的 Markdown 资源
模板	greeting://{name}	个性化问候语
	data://items/{id}	按 ID 查找数据
提示词	greet	多种风格的问候语
	code_review	侧重特定方面的代码审查

🚀 快速开始

前置条件

• Python 3.11+
• uv（推荐）或 pip

安装

# Clone the repository
git clone https://github.com/SamMorrowDrums/mcp-python-starter.git
cd mcp-python-starter

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

运行服务

stdio 传输（用于本地开发）：

uv run mcp-python-starter --stdio

HTTP 传输（用于远程或 Web 部署）：

uv run mcp-python-starter --http --port 3000

🔧 VS Code 集成

本项目包含 VS Code 配置，可实现流畅开发：

1. 在 VS Code 中打开项目
2. MCP 配置位于 .vscode/mcp.json
3. 使用 VS Code 的 MCP 工具测试服务

使用 DevContainers

1. 安装 Dev Containers 扩展
2. 打开命令面板，选择：“Dev Containers: Reopen in Container”
3. 所有内容均已预先配置，可直接使用！

📁 项目结构

.
├── mcp_starter/
│   ├── __init__.py
│   ├── tools.py       # Tool definitions (hello, get_weather, ask_llm, etc.)
│   ├── resources.py   # Resource and template definitions
│   ├── prompts.py     # Prompt definitions
│   └── server.py      # Server orchestration (imports and wires modules)
├── .vscode/
│   ├── mcp.json       # MCP server configuration
│   ├── settings.json  # Python settings
│   └── extensions.json
├── .devcontainer/
│   └── devcontainer.json
├── pyproject.toml     # Project configuration (uv/pip, Ruff config)
└── .python-version

🛠️ 开发

# Run the server (Python reloads automatically on changes)
uv run mcp-python-starter --stdio

# Use MCP Inspector for debugging
uv run mcp dev mcp_starter/server.py

# Format code
uv run ruff format .

# Lint
uv run ruff check .

# Lint with auto-fix
uv run ruff check --fix .

# Type check
uv run pyright

实时重载

使用 uv run 运行时，Python 脚本会自动重新加载。如需增强调试功能， 请使用 mcp dev，它提供 MCP Inspector 界面。

🔍 MCP Inspector

MCP Inspector 是用于测试和调试 MCP 服务的重要开发工具。

运行 Inspector

npx @modelcontextprotocol/inspector -- uv run mcp-python-starter

Inspector 提供的功能

• Tools 选项卡：列出并调用所有已注册的工具及其参数
• Resources 选项卡：浏览并读取资源和模板
• Prompts 选项卡：查看并测试提示词模板
• Logs 选项卡：查看客户端和服务之间的 JSON-RPC 消息
• 架构验证：验证工具输入和输出架构

调试提示

1. 在连接 IDE 或客户端之前启动 Inspector
2. 使用“Logs”选项卡查看确切的请求和响应载荷
3. 测试工具注解（ToolAnnotations）是否正确公开
4. 确认 long_task 会显示进度通知
5. 检查采样工具的 Context 注入是否正常工作

📖 功能示例

带注解的工具（FastMCP 装饰器）

@mcp.tool(
    title="Say Hello",
    description="A friendly greeting tool",
    annotations={"readOnlyHint": True},
)
def hello(name: str) -> str:
    """Say hello to someone.
    
    Args:
        name: The name to greet
    """
    return f"Hello, {name}!"

资源模板

@mcp.resource("greeting://{name}")
def greeting_template(name: str) -> str:
    """Generate a personalized greeting."""
    return f"Hello, {name}!"

带进度更新的工具

@mcp.tool(title="Long Task")
async def long_task(
    task_name: str,
    ctx: Context[ServerSession, None],
) -> str:
    for i in range(5):
        await ctx.report_progress(
            progress=i / 5,
            total=1.0,
            message=f"Step {i + 1}/5",
        )
        await asyncio.sleep(1.0)
    return "Done!"

带采样功能的工具

@mcp.tool(title="Ask LLM")
async def ask_llm(
    prompt: str,
    ctx: Context[ServerSession, None],
) -> str:
    result = await ctx.session.create_message(
        messages=[{"role": "user", "content": {"type": "text", "text": prompt}}],
        max_tokens=100,
    )
    return result.content.text

🔐 环境变量

将 .env.example 复制为 .env 并进行配置：

cp .env.example .env

🤝 参与贡献

欢迎贡献！请确保你的更改与其他语言入门项目保持功能一致。

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE。