SWLC MCP Server

# SWLC MCP服务器架构说明 ## 整体架构 ``` ┌─────────────────┐ MCP协议 ┌─────────────────┐ │ Claude Desktop │ ←────────→ │ Python MCP Server │ │ │ │ (数据采集+分析) │ └─────────────────┘ └─────────────────┘ │ │ HTTP API ▼ ┌─────────────────┐ │ 其他应用/服务 │ │ (Web/移动端) │ └─────────────────┘ ``` ## 核心组件 ### 1. MCP服务器 (`src/swlc_mcp/server.py`) - **功能**: 提供MCP协议接口，支持Claude Desktop直接调用 - **工具**: 包含8个MCP工具，涵盖所有彩票查询和分析功能 - **数据源**: 优先从本地SQLite数据库获取，网络作为备选 ### 2. 数据库模块 (`src/swlc_mcp/database.py`) - **功能**: SQLite数据库管理，本地数据存储 - **表结构**: 7个数据表，支持4种彩票类型 - **特性**: 自动统计、同步日志、数据持久化 ### 3. HTTP API服务器 (`api_server.py`) - **功能**: FastAPI框架，提供RESTful API接口 - **端点**: 8个API端点，支持所有MCP功能 - **特性**: CORS支持、参数验证、错误处理 ### 4. 启动脚本 (`start_server.py`) - **功能**: 统一启动入口，支持MCP和API两种模式 - **参数**: 可配置主机、端口等参数 ## 数据流 ### MCP模式数据流 ``` Claude Desktop → MCP协议 → Python MCP Server → SQLite数据库 ↓ 网络API (备选) ``` ### HTTP API模式数据流 ``` 其他应用 → HTTP请求 → FastAPI服务器 → Python服务 → SQLite数据库 ↓ 网络API (备选) ``` ## 技术栈 ### 后端技术 - **Python 3.10+**: 主要开发语言 - **MCP Python SDK**: MCP协议实现 - **FastAPI**: HTTP API框架 - **Uvicorn**: ASGI服务器 - **SQLite**: 本地数据存储 - **httpx**: 异步HTTP客户端 - **Pydantic**: 数据验证 ### 数据存储 - **SQLite数据库**: 本地文件数据库 - **JSON格式**: 号码数据序列化 - **时间戳**: 数据同步和更新记录 ## 部署架构 ### 开发环境 ``` 项目根目录/ ├── src/swlc_mcp/ # 核心代码 │ ├── server.py # MCP服务器 │ ├── api_server.py # HTTP API服务器 │ ├── database.py # 数据库模块 │ ├── sync_data.py # 数据同步脚本 │ └── __init__.py ├── test/ # 测试目录 │ ├── test_api.py # API测试脚本 │ └── __init__.py ├── start_server.py # 启动脚本 └── lottery_data.db # SQLite数据库文件 ``` ### 生产环境 ``` 服务器/ ├── Python MCP Server # MCP协议服务 ├── HTTP API Server # RESTful API服务 ├── SQLite数据库 # 本地数据存储 └── 反向代理 (可选) # Nginx/Apache ``` ## 安全考虑 ### 数据安全 - **本地存储**: 数据存储在本地SQLite文件 - **网络请求**: 使用官方API，避免数据篡改 - **参数验证**: Pydantic模型确保数据完整性 ### API安全 - **CORS配置**: 支持跨域请求 - **参数限制**: 查询参数范围限制 - **错误处理**: 统一的错误响应格式 ## 扩展性 ### 水平扩展 - **多实例部署**: 可部署多个API服务器实例 - **负载均衡**: 通过反向代理实现负载均衡 - **数据库分离**: 可将SQLite替换为PostgreSQL等 ### 功能扩展 - **新彩票类型**: 在数据库和API中添加新表 - **新分析功能**: 扩展分析算法 - **第三方集成**: 通过HTTP API集成其他服务 ## 监控和日志 ### 日志系统 - **结构化日志**: 使用Python logging模块 - **同步记录**: 数据库同步操作日志 - **错误追踪**: 详细的错误信息和堆栈 ### 健康检查 - **API健康检查**: `/api/health` 端点 - **数据库连接**: 自动检测数据库状态 - **服务状态**: 实时服务状态监控 ## 性能优化 ### 数据库优化 - **索引优化**: 关键字段建立索引 - **查询优化**: 使用高效的SQL查询 - **连接池**: 数据库连接复用 ### API优化 - **异步处理**: 使用FastAPI异步特性 - **缓存策略**: 可添加Redis缓存层 - **压缩传输**: 启用gzip压缩 ## 故障恢复 ### 数据恢复 - **自动备份**: 定期备份SQLite数据库 - **数据同步**: 网络故障时使用本地数据 - **错误重试**: 网络请求失败自动重试 ### 服务恢复 - **进程监控**: 自动重启崩溃的服务 - **健康检查**: 定期检查服务状态 - **降级策略**: 网络不可用时使用本地数据