SWLC MCP Server

# SWLC MCP Server 这是一个专为上海地区设计的彩票信息查询MCP（Model Context Protocol）服务器，提供双色球、福彩3D、七乐彩等彩票的开奖查询和分析功能。 ``` ⚠️作为技术人员，我必须强调： 1、彩票本质是概率游戏，任何算法都无法保证中奖 2、历史数据只能提供参考，不能预测未来 3、建议理性购彩，将其视为娱乐而非投资 4、以上推荐纯属技术分析，请根据个人情况谨慎选择 祝您好运！ ``` ## 功能特性 - 🎯 **最新开奖查询**：获取双色球、福彩3D、七乐彩的最新开奖结果 - 📊 **历史数据查询**：获取指定期数的历史开奖数据 - 📈 **号码分析**：提供热号、冷号统计和频率分析 - 🎲 **随机推荐**：生成随机彩票号码推荐 - 🔍 **智能统计**：提供详细的开奖统计信息 - 💾 **本地数据存储**：使用SQLite数据库本地存储彩票数据，减少网络查询 - ⚡ **快速响应**：优先从本地数据库查询，提高查询速度 - 🔄 **数据同步**：支持手动同步最新数据到本地数据库 ## 支持的彩票类型 - **双色球**：6个红球（1-33）+ 1个蓝球（1-16） - **福彩3D**：3位数字（000-999） - **七乐彩**：7个基本号码（1-30）+ 1个特别号码 - **快乐8**：20个号码（1-80） ## 安装方法 ### 1. 克隆仓库 ```bash git clone <repository-url> cd swlc-mcp ``` ### 2. 安装依赖 ```bash pip install -e . ``` ### 3. 运行服务器 #### 启动MCP服务器（用于Claude Desktop） ```bash # 方式1: 使用启动脚本 python start_server.py --mode mcp # 方式2: 直接运行 swlc-mcp ``` #### 启动HTTP API服务器（用于其他应用） ```bash # 启动HTTP API服务器 python start_server.py --mode api --host 0.0.0.0 --port 8000 # 或者直接运行 python src/swlc_mcp/api_server.py ``` ### 4. 数据同步（可选） 首次使用或需要更新数据时，可以运行数据同步脚本： ```bash python src/swlc_mcp/sync_data.py ``` ## MCP工具列表 ### `get_latest_ssq` 获取双色球最新开奖结果 ### `get_latest_3d` 获取福彩3D最新开奖结果 ### `get_latest_qlc` 获取七乐彩最新开奖结果 ### `get_latest_kl8` 获取快乐8最新开奖结果 ### `get_historical_data` 获取历史开奖数据 - `lottery_type`: 彩票类型（双色球/福彩3D/七乐彩/快乐8） - `periods`: 获取期数（1-500，默认10） - 如果数据库中的数据不足，会返回实际可用的数据 - 建议首次使用先同步数据：`python src/swlc_mcp/sync_data.py` ### `analyze_numbers` 分析号码统计信息 - `lottery_type`: 彩票类型（双色球/福彩3D/七乐彩/快乐8） - `periods`: 分析期数（5-500，默认30） ### `generate_random_numbers` 生成随机号码推荐 - `lottery_type`: 彩票类型（双色球/福彩3D/七乐彩/快乐8） - `count`: 生成组数（1-10，默认1） ### `sync_lottery_data` 同步指定彩票类型的最新数据到本地数据库 - `lottery_type`: 彩票类型（双色球/福彩3D/七乐彩/快乐8） - `periods`: 同步期数（1-50，默认10） ### `get_database_info` 获取本地数据库统计信息 ## 使用示例 ### 在Claude Desktop中配置 在Claude Desktop的配置文件中添加： ```json { "mcpServers": { "swlc": { "command": "swlc-mcp", "cwd": "D:\\github\\swlc-mcp" } } } ``` ### 查询示例 - "请获取双色球最新开奖结果" - "分析双色球最近30期的号码统计" - "为我推荐5注七乐彩号码" - "查看福彩3D最近10期的历史数据" - "获取快乐8最新开奖信息" - "同步双色球最新数据到本地数据库" - "查看本地数据库统计信息" <img width="400" alt="image" src="https://github.com/user-attachments/assets/cdee6ff7-4791-4fe8-9e12-e4f7261d8527" /> ## 智能数据更新机制 项目实现了智能的数据更新机制，能够自动判断何时需要从网络获取最新数据： ### 数据新鲜度检查 系统会根据彩票类型的开奖频率自动检查数据的新鲜度： - **双色球**：每周二、四、日开奖，超过3天没有新数据时自动更新 - **福彩3D**：每天开奖，超过1天没有新数据时自动更新 - **七乐彩**：每周一、三、五开奖，超过3天没有新数据时自动更新 - **快乐8**：每天开奖，超过1天没有新数据时自动更新 ### 智能更新策略 1. **自动更新**：当检测到数据过期时，系统会自动从网络获取最新数据 2. **智能回退**：如果网络获取失败，系统会返回数据库中的可用数据作为备选 3. **手动强制更新**：用户可以通过API强制同步数据，忽略数据新鲜度检查 ### 更新触发时机 - 获取最新开奖结果时 - 获取历史开奖数据时 - 获取号码分析时 - 手动调用同步API时 ### 强制同步API 如果用户需要立即获取最新数据，可以使用强制同步API： ```bash # 强制同步双色球最新20期数据 curl -X POST "http://localhost:8000/api/force-sync/ssq?periods=20" # 强制同步福彩3D最新50期数据 curl -X POST "http://localhost:8000/api/force-sync/3d?periods=50" ``` ### 数据一致性保证 - 系统会优先使用数据库中的最新数据 - 只有在数据过期或不足时才会触发网络更新 - 网络更新失败时会优雅降级到数据库数据 - 所有数据更新都会同步更新号码统计信息 ## 技术栈 - **Python 3.10+** - **MCP Python SDK**：用于构建MCP服务器 - **FastAPI**：HTTP API框架 - **Uvicorn**：ASGI服务器 - **httpx**：异步HTTP客户端 - **Pydantic**：数据验证和序列化 - **python-dateutil**：日期处理 - **SQLite**：本地数据存储 ## 数据库结构 项目使用SQLite数据库存储彩票数据，包含以下表： - `lottery_types`: 彩票类型信息 - `ssq_results`: 双色球开奖结果 - `fucai3d_results`: 福彩3D开奖结果 - `qilecai_results`: 七乐彩开奖结果 - `kuaile8_results`: 快乐8开奖结果 - `number_statistics`: 号码统计信息 - `sync_logs`: 数据同步日志 数据库文件默认保存在项目根目录的 `lottery_data.db` 文件中。 ## HTTP API接口 项目提供了完整的HTTP API接口，支持其他应用通过HTTP请求访问彩票数据： ### API端点 - `GET /` - API根路径，显示所有可用端点 - `GET /api/latest/{lottery_type}` - 获取最新开奖结果 - `GET /api/historical/{lottery_type}` - 获取历史开奖数据 - `GET /api/analysis/{lottery_type}` - 获取号码分析 - `GET /api/random/{lottery_type}` - 生成随机号码 - `POST /api/sync/{lottery_type}` - 同步彩票数据 - `GET /api/database/info` - 获取数据库信息 - `GET /api/health` - 健康检查 ### 支持的彩票类型 - `ssq` - 双色球 - `3d` - 福彩3D - `qlc` - 七乐彩 - `kl8` - 快乐8 ### 使用示例 ```bash # 获取双色球最新开奖结果 curl http://localhost:8000/api/latest/ssq # 获取福彩3D最近10期历史数据 curl http://localhost:8000/api/historical/3d?periods=10 # 分析双色球最近30期号码 curl http://localhost:8000/api/analysis/ssq?periods=30 # 生成5注七乐彩随机号码 curl http://localhost:8000/api/random/qlc?count=5 # 同步双色球数据 curl -X POST http://localhost:8000/api/sync/ssq?periods=20 # 查看数据库信息 curl http://localhost:8000/api/database/info ## 测试 ### API测试 ```bash # 运行API测试 python test/test_api.py ``` ## 数据来源 已接入中国福利彩票官方API： - 双色球：https://www.cwl.gov.cn/cwl_admin/front/cwlkj/search/kjxx/findDrawNotice?name=ssq - 福彩3D：https://www.cwl.gov.cn/cwl_admin/front/cwlkj/search/kjxx/findDrawNotice?name=3d - 七乐彩：https://www.cwl.gov.cn/cwl_admin/front/cwlkj/search/kjxx/findDrawNotice?name=qlc - 快乐8：https://www.cwl.gov.cn/cwl_admin/front/cwlkj/search/kjxx/findDrawNotice?name=kl8 所有数据均来自官方权威渠道，确保准确性和实时性。 ## 注意事项 - 本工具仅供娱乐和学习用途 - 购彩需理性，请根据自身情况合理投注 - 历史数据不代表未来走势，请谨慎参考 ## 贡献 欢迎提交Issue和Pull Request来改进这个项目。 ## 致谢 本项目完全由 [Cursor](https://cursor.sh/) 完成。 ## 许可证 MIT License