使用说明

Python MCP服务器模板

用于构建模型上下文协议（MCP）服务器的生产就绪Python模板。该模板为使用Weather API的模式验证、全面测试和示例实现提供了完整的基础。

🎯 目的

此模板可作为构建自己的模板的起点 独特的 Python中的MCP服务器。它包括：

使用完成MCP服务器设置 uv 包管理器
基于JSON模式的工具定义，带有清晰的示例
全面的输入/输出验证
广泛的测试套件框架
错误处理和日志
2个显示不同模式的天气工具示例
模板说明 嵌入在每个文件中，便于定制

🏗️ 模板结构

python-mcp-server/
├── mcp_server/              # Main package directory (⚠️ RENAME THIS!)
│   ├── __init__.py         # Package initialization
│   ├── __main__.py         # Entry point for the MCP server
│   ├── server.py           # Core MCP server implementation  
│   ├── handlers.py         # Tool function implementations
│   └── tools.json          # Tool schemas and definitions
├── main.py                 # Compatibility wrapper for testing
├── test_server.py          # Comprehensive test framework
├── test_cases.json         # Test case definitions  
├── pyproject.toml          # Project dependencies and metadata
├── .env.example            # Environment variables template
├── uv.lock                 # Locked dependencies
└── README.md               # This file

⚠️ 重要提示： 重命名 mcp_server/ 您的唯一名称（例如。， weather_server/)并相应地更新导入。

🚀 快速开始

使用此模板

克隆或分叉此存储库：

git clone https://github.com/yourusername/python-mcp-server.git my-mcp-server
cd my-mcp-server

使您的服务器独一无二（关键！）：

# Rename the package folder to avoid conflicts
mv mcp_server my_server_name  # e.g., mv mcp_server weather_server

# Follow template instructions (🎯) in these files to update imports:
# - my_server_name/server.py (line 18)
# - main.py (line 11)  
# - pyproject.toml (lines 41, 65, 67, 71)

使用uv安装依赖项：
```
uv sync
```
根据您的用例进行自定义：
- 遵循模板说明(🎯) 嵌入在每个文件中
- 替换中的工具实现 my_server_name/handlers.py
- 更新中的工具架构 my_server_name/tools.json
- 修改中的测试用例 test_cases.json
- 更新中的项目元数据 pyproject.toml
运行测试以验证：
```
uv run python test_server.py
```

📋 核心组件

1.服务器实现(`mcp_server/server.py`)

⚠️ 注： 重命名文件夹后，这将成为 your_server_name/server.py

核心MCP服务器：

从以下位置加载工具模式 tools.json
处理MCP协议通信
将工具调用路由到处理程序函数
管理服务器生命周期

主要功能：

load_tool_schemas() -从JSON加载工具定义
handle_list_tools() -将可用工具返回给MCP客户端
handle_call_tool() -通过验证执行工具功能
run_server() -主服务器循环

2.工具操作员(`mcp_server/handlers.py`)

⚠️ 注： 重命名文件夹后，这将成为 your_server_name/handlers.py

在此处实现您的工具功能。该模板包括Weather API处理程序示例：

# Example tool function structure
async def your_tool_function(param1: str, param2: int = None) -> dict:
    """Your tool implementation."""
    # Validate inputs
    if not param1:
        raise ValueError("param1 is required")
    
    # Process request
    result = await process_data(param1, param2)
    
    # Return structured response
    return {"status": "success", "data": result}

# Register in TOOL_FUNCTIONS mapping
TOOL_FUNCTIONS = {
    "your_tool": your_tool_function,
    # Add more tools here
}

3.工具示意图(`mcp_server/tools.json`)

⚠️ 注： 重命名文件夹后，这将成为 your_server_name/tools.json

使用JSON模式定义您的工具：

{
  "name": "YourServer",
  "tools": [
    {
      "name": "your_tool",
      "description": "Tool description",
      "inputSchema": {
        "type": "object",
        "properties": {
          "param1": {
            "type": "string",
            "description": "Parameter description"
          }
        },
        "required": ["param1"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "status": {"type": "string"},
          "data": {"type": "object"}
        }
      }
    }
  ]
}

4.测试框架(`test_server.py`)

全面测试包括：

模式结构验证
输入/输出验证
工具功能测试
错误案例处理
性能监控

5.测试用例(`test_cases.json`)

定义测试场景：

{
  "test_cases": [
    {
      "name": "test_name",
      "tool": "your_tool",
      "arguments": {
        "param1": "test_value"
      },
      "description": "Test description",
      "expected_fields": ["status", "data"],
      "should_succeed": true
    }
  ]
}

🔧 定制指南

第一步：定义你的工具

编辑 mcp_server/tools.json:

更新服务器名称
定义您的工具模式
指定输入/输出验证规则

步骤2：实现工具功能

编辑 mcp_server/handlers.py:

删除示例Weather API函数
添加您的工具实现
更新 TOOL_FUNCTIONS 映射

步骤3：配置依赖关系

编辑 pyproject.toml:

更新项目名称和描述
根据需要添加/删除依赖项
如果需要，更新控制台脚本名称

步骤4：更新测试

编辑 test_cases.json:

删除示例Weather API测试
为您的工具添加测试用例
包括成功和失败的场景

步骤5：环境变量

如果您的服务器需要配置：

创建一个 .env 本地开发文件
在中添加环境变量处理 handlers.py
在README中记录所需变量

📦 包装和分销

选项1：从Git安装

用户可以直接从您的存储库安装：

uvx --from git+https://github.com/yourusername/your-mcp-server your-server-name

选项2：发布到PyPI

更新 pyproject.toml 包含您的包裹详细信息
构建包： uv build
发布： uv publish

选项3：与MCP客户端一起使用

在Claude Desktop或其他MCP客户端中配置：

{
  "mcpServers": {
    "your-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/your-mcp-server",
        "your-server-name"
      ],
      "env": {
        "YOUR_ENV_VAR": "value"
      }
    }
  }
}

🌟 示例实现：Weather API

此模板包括一个完整的Weather API实现作为参考，显示：

多种工具类型 -各种与天气相关的查询
复杂的模式 -嵌套对象和数组
错误处理 -无效输入和API错误
异步操作 -HTTP客户端集成
环境配置 -API密钥管理
综合测试 -45+测试用例

可用示例工具

工具	说明
`get_weather`	天气预报（1-3天）
`get_weather_history`	历史天气数据
`get_weather_airquality`	空气质量信息
`get_astronomy_data`	日出、日落、月相
`search_locations`	位置搜索
`get_timezone`	时区信息
`get_sport_events`	体育赛事天气

要使用Weather API示例：

从获取免费的API密钥 WeatherAPI.com 网站
集 WEATHER_API_KEY 在你的 .env 文件
运行测试： uv run python test_server.py

🧪 测试您的服务器

该模板包括一个全面的测试框架：

# Run all tests
uv run python test_server.py

# Test output includes:
# - Schema validation
# - Tool function tests  
# - Error handling
# - Performance metrics
# - Success/failure summary

测试特性

架构验证 -验证所有工具模式
输入验证 -测试参数约束
输出验证 -验证响应结构
错误案例 -测试无效输入
演出 -测量响应时间

🛠️ 开发工作流程

定义架构 在……里面 tools.json
实现处理程序 在……里面 handlers.py
编写测试 在……里面 test_cases.json
运行测试 随着 test_server.py
使用MCP客户端进行测试 （克劳德桌面等）
包装和分发

📚 MCP协议基础

此模板实现了MCP协议：

沟通：JSON-RPC 2.0通过标准输入
工具发现：客户来电 list_tools 发现可用工具
工具执行：客户来电 call_tool 带有工具名称和参数
验证：根据JSON模式验证输入/输出
错误处理：结构化错误响应

🤝 贡献

欢迎为改进此模板做出贡献：

分叉存储库
创建要素分支
添加新功能的测试
确保所有测试通过
提交拉取请求

📄 许可证

此模板以开源形式提供，供您在MCP服务器项目中使用。

🔗 资源

🎯 后续步骤

定制 -用您自己的工具替换示例实现
测试 -确保全面的测试覆盖率
文件 -用您的具体细节更新此README
部署 -与社区共享您的MCP服务器

此模板为在Python中构建MCP服务器提供了坚实的基础。Weather API实现是如何构建工具、处理验证和实现测试的一个全面示例。