MCP Spacex Server

MCP SpaceX服务器——设计文件

版本：1.0

日期：2026年2月25日

目录

1. 概述
2. 建筑
3. 执行流程
4. 工具系统
5. 工具清单系统
6. 模块结构
7. 数据处理
8. 测试策略
9. 设置和运行
10. 未来改进
11. 应用的设计原则

1.工程概况

该项目实现了一个轻量级的RPC型MCP服务器，该服务器公开了用于从公共SpaceX API检索数据的结构化工具。\ 服务器遵循远程过程调用（RPC）模式，而不是传统的REST资源端点（例如/launch）。\ 客户端通过单个执行端点动态调用工具。

该项目展示了：

• 基于RPC的工具执行
• 干净的分层架构
• 依赖注入
• 基于Pydantic的验证
• 通过结构化清单发现工具
• 经过单元测试的业务逻辑

2.架构概述

该系统遵循具有严格向下依赖性的分层架构。\ Architecture Diagram

层职责 SpaceX Diagram

依赖关系严格向下流动。无圆形联轴器。

3.执行流程

1. 客户端向发送POST请求 /execute.
2. 请求包含：

- tool （字符串） - arguments （对象）

1. FastAPI使用验证请求 ExecuteToolRequest.
2. ToolRegistry按名称查找工具。
3. 所选工具执行业务逻辑。
4. SpaceXClient执行外部API请求。
5. 该工具返回经过验证的Pydantic模型。
6. 注册表将结果封装在 ExecuteToolResponse.
7. JSON响应返回给客户端。

这遵循RPC风格的执行模型。

4.工具系统

服务器当前公开了以下工具：

• list_launches
• get_launch_by_id
• get_latest_launch
• list_rockets
• get_socket_by_id

每个工具：

• 通过依赖注入接受SpaceXClient
• 公开一个异步执行（参数：dict）方法
• 如果需要，执行输入验证
• 返回Pydantic模型
• 已在ToolRegistry中注册
• 具有相应的结构化清单

5.工具清单系统

每个工具都通过一个结构化的清单进行描述，清单包含：

• name
• description
• parameter schema （JSON模式样式）

舱单允许：

• 工具发现（GET/tools）
• 结构化元数据访问（GET/工具/清单）
• 未来AI/LLM集成

清单结构示例：

清单结构示例

{
  "name": "get_launch_by_id",
  "description": "...",
  "parameters": {
    "type": "object",
    "properties": {
      "launch_id": {
        "type": "string",
        "description": "SpaceX launch ID"
      }
    },
    "required": ["launch_id"]
  }
}

6.模块结构

src/
├── main.py
├── registry.py
├── schemas.py
├── spacex_client.py
└── tools/
    ├── launch_tool.py
    ├── launch_by_id_tool.py
    ├── latest_launch_tool.py
    ├── rocket_tool.py
    └── rocket_list_tool.py
tests/
├── test_launch_by_id_tool.py
├── test_latest_launch_tool.py
└── test_registry.py

7.数据处理

• 无持久存储
• 从SpaceX公共API实时检索的所有数据
• 使用Pydantic模型验证数据
• 仅用于瞬态内存处理

8.测试策略

单元测试包括：

• 工具逻辑（成功和验证错误）
• 注册表调度行为
• 错误处理

测试使用以下方式编写：

• pytest
• pytest异步
• 嘲笑SpaceXClient

单元测试期间不执行外部API调用。

运行测试：

  uv run pytest

9.设置和运行

需求

• Python 3.12+
• uv包管理器

安装依赖项

  uv sync

运行服务器

  uv run uvicorn main:app --reload

访问权限：

• 根：http://127.0.0.1:8000/
• Swagger用户界面：http://127.0.0.1:8000/docs
• 工具列表：http://127.0.0.1:8000/tools
• 工具清单：http://127.0.0.1:8000/tools/manifests

执行示例：

curl -X POST http://127.0.0.1:8000/execute \
     -H "Content-Type: application/json" \
     -d '{
       "tool": "list_rockets",
       "arguments": {}
     }'

10.未来的改进

• 添加缓存（基于TTL的内存缓存）
• 添加指数回退重试
• 添加速率限制处理
• 引入结构化日志记录
• 添加CI管道
• 扩展工具集（有效载荷、任务、机组人员）

11.应用的设计原则

• 单一责任原则
• 依赖注入
• 干净的分层架构
• RPC样式工具执行
• 显式模式验证
• 可测试的隔离组件