MCP Python Starter

MCP Python入门

Python中使用FastMCP的功能完整的模型上下文协议（MCP）服务器模板。这个初学者用干净的Python代码演示了MCP的所有主要功能。

📚 文档

• 模型上下文协议
• 开发包
• FastMCP指南

✨ 特性

🚀 快速开始

先决条件

• Python 3.11+
• 紫外线 （推荐）或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代码集成

该项目包括用于无缝开发的VS代码配置：

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

使用DevContainers

1. 安装 开发容器扩展
2. 打开命令面板：“开发容器：在容器中重新打开”
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

实时重新加载

使用运行时，Python脚本会自动重新加载 uv run为了增强调试， 使用 mcp dev 其提供MCP检查器UI。

🔍 MCP检查员

这 MCP检查员 是测试和调试MCP服务器的重要开发工具。

运行检查器

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

检查员提供什么

• 工具选项卡：列出并调用所有已注册的带有参数的工具
• 资源选项卡：浏览和阅读资源和模板
• 提示选项卡：查看和测试提示模板
• 日志选项卡：请参阅客户端和服务器之间的JSON-RPC消息
• 模式验证：验证工具输入/输出模式

调试提示

1. 在连接IDE/客户端之前启动检查器
2. 使用“日志”选项卡查看确切的请求/响应有效载荷
3. 测试工具注释（ToolAnnotations）正确显示
4. 验证是否显示进度通知 long_task
5. 检查上下文注入是否适用于采样工具

📖 功能示例

带注释的工具（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许可证-请参阅 许可证 了解详情。