模拟MCP服务器
一个演示用的MCP（模型上下文协议）服务器，展示了工具实现、输入验证、响应格式化、分页以及错误处理的最佳实践。
概述
这是一个用Python和FastMCP构建的模拟MCP服务器，用于演示：
- 最佳实践工具设计遵循MCP（可能是指某种标准或规范，如“命名、注释和结构规范”的缩写，具体需根据上下文确定）关于命名、注释和结构的指南
- 输入验证使用带有全面字段约束的 Pydantic v2 模型
- 多种响应格式支持JSON（机器可读）和Markdown（人类可读）两种输出格式
- 分页实现基于偏移量的分页，并提供清晰的元数据
- 字符限制尊重字符限制，优雅地进行截断
- 错误处理提供清晰、可操作的错误信息
- 类型安全在整个代码库中使用完整的类型提示
可用工具
1. dummy_get_time
获取当前的日期和时间。
参数：
timezone（可选）：显示时区（默认：“UTC”）response_format（可选）：输出格式（“markdown”或“json”）
示例：
{
"timezone": "UTC",
"response_format": "json"
}注释： 只读，幂等
______________________________________________________________________
2. dummy_calculate
执行基本的数学运算（加、减、乘、除）。
参数：
operation数学运算（“加”、“减”、“乘”、“除”）a第一个数字b第二个数字response_format（可选）：输出格式（“markdown”或“json”）
示例：
{
"operation": "add",
"a": 5.0,
"b": 3.0,
"response_format": "json"
}注释： 只读，幂等
______________________________________________________________________
3. dummy_search_items
使用分页和过滤功能搜索虚拟项目。
参数：
query（可选）：搜索查询以过滤项目limit（可选）：要返回的最大结果数（1-100，默认：20）offset（可选）：分页时要跳过的结果数量（默认：0）response_format（可选）：输出格式（“markdown”或“json”）
示例：
{
"query": "development",
"limit": 10,
"offset": 0,
"response_format": "json"
}注释： 只读，幂等
______________________________________________________________________
4. dummy_create_item
创建一个新的虚拟项目。
参数：
name项目名称（1-100个字符，必填）description（可选）：项目描述（最多500个字符）tags（可选）：标签列表（最多10个标签）response_format（可选）：输出格式（“markdown”或“json”）
示例：
{
"name": "Project Alpha",
"description": "New Q1 project",
"tags": ["development", "priority-1"],
"response_format": "json"
}注释： 非破坏性写入操作
______________________________________________________________________
5. dummy_format_text
使用各种转换选项来格式化文本。
参数：
text要格式化的文本（1-10000个字符，必填）format_type应用格式设置（“大写”，“小写”，“标题大小写”，“反转”）
示例：
{
"text": "hello world",
"format_type": "uppercase"
}注释： 只读，幂等
______________________________________________________________________
安装
先决条件
- 安装 Python 3.10 或更高版本
- 安装 uv（快速的 Python 包安装工具）：
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Or with pip
pip install uv安装依赖项
# Install dependencies using uv
uv sync
# Or install manually
uv pip install -e .用法
运行服务器
服务器默认使用stdio传输方式，这适用于命令行工具和子进程集成：
# Run with uv (recommended - manages dependencies automatically)
uv run server.py
# Or run directly if dependencies are installed
python3 server.py使用MCP Inspector进行测试
您可以使用MCP Inspector工具来测试服务器：
# With uv (recommended)
npx @modelcontextprotocol/inspector uv run server.py
# Or without uv
npx @modelcontextprotocol/inspector python3 server.py与Claude桌面版的集成
将此配置添加到您的Claude Desktop配置文件中：
macOS（发音为 /ˈmækɒs/，中文常译为“麦奥斯”或直接使用原名）： ~/Library/Application Support/Claude/claude_desktop_config.json
使用紫外线（推荐）：
{
"mcpServers": {
"dummy": {
"command": "uv",
"args": [
"--directory",
"/path/to/dummy-mcp",
"run",
"server.py"
]
}
}
}或者不加紫外线：
{
"mcpServers": {
"dummy": {
"command": "python3",
"args": ["/path/to/dummy-mcp/server.py"]
}
}
}建筑学
服务器结构
dummy-mcp/
├── server.py # Main MCP server implementation
├── pyproject.toml # Project metadata and dependencies (uv)
├── requirements.txt # Python dependencies (legacy, optional)
└── README.md # This file关键组件
Pydantic 模型所有工具输入均使用 Pydantic v2 模型进行验证，具体包括：
- 字段约束（最小/最大长度，范围）
- 自定义验证器
- 类型安全
- 自动错误消息
共享公用设施将常用功能提取到可重用的函数中：
_generate_dummy_items()生成测试数据_filter_items()按查询过滤项目_format_items_markdown()格式化为Markdown_format_items_json()格式化为JSON_check_character_limit()强制字符限制
工具注释所有工具都包含适当的注释：
readOnlyHint指示工具是否修改状态destructiveHint指示修改是否具有破坏性idempotentHint指示重复调用是否具有相同效果openWorldHint指示工具是否与外部系统交互
展示的最佳实践
这台服务器遵循MCP最佳实践：
- 服务器命名：
dummy_mcp遵循Python的约定{service}_mcp - 工具命名带服务前缀的蛇形命名法（例如。，
dummy_get_time） - 响应格式支持JSON和Markdown格式
- 分页实现基于偏移量的分页功能，包含元数据
- 字符限制25,000个字符限制，优雅截断
- 输入验证全面的 Pydantic 模型
- 错误处理清晰、可操作的错误信息
- 文档带有示例的全面文档字符串
- 类型安全全文采用完整类型提示
- 代码可重用性用于常见操作的共享实用工具
发展
验证语法
检查Python语法：
python3 -m py_compile server.py运行测试
# Install dev dependencies
uv sync --all-extras
# Run tests (when available)
uv run pytest代码质量
实施内容包括：
- 全程使用类型提示
- 全面的文档字符串
- Pydantic 验证
- 错误处理
- 用于实现DRY（Don't Repeat Yourself，不重复自己）原则的共享工具
许可证
这是一个用于教育目的的演示项目。