# meiweQueueMcp

**Repository Path**: sunlinfeng/meiwe-queue-mcp

## Basic Information

- **Project Name**: meiweQueueMcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-01
- **Last Updated**: 2026-03-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 美味排队系统 - SSE MCP Server

这是一个集成了Server-Sent Events (SSE) 和 Model Context Protocol (MCP) 工具的完整排队系统服务器实现。主要提供美位排队系统的API集成和服务。

## 项目结构

```
MeiweiQueue/
├── sse_mcp_server/          # SSE服务器组件
│   ├── __init__.py
│   ├── server.py           # 主SSE服务器实现
│   ├── models.py           # 数据模型定义
│   ├── utils.py            # 工具函数
│   ├── middleware.py       # 中间件实现
│   └── handlers.py         # 事件处理器
├── mcp_tools/              # MCP工具组件
│   ├── __init__.py
│   ├── queue_api.py        # 美位排队API封装
│   ├── queue_tool.py       # 排队工具实现
│   └── server.py           # MCP工具服务器
├── main.py                 # 主应用入口
├── mcp_example_usage.py    # MCP工具使用示例
├── HOW_TO_ADD_MCP_TOOL.md  # 添加MCP工具指南
├── requirements.txt        # 项目依赖
└── README.md               # 本说明文档
```

## 功能特性

### SSE服务器 (Server-Sent Events)
- 实时事件流传输
- 客户端连接管理
- 通道订阅系统
- 心跳保持连接
- 消息发布/订阅模式

### MCP工具 (Model Context Protocol)
- 可扩展的工具注册表
- 标准化的工具接口
- 参数验证和错误处理
- REST API接口

### 美位排队系统集成
- 附近门店搜索
- 线上取号服务
- 排队状态查询
- 排队号码取消
- 加密API通信

## 安装依赖

```bash
pip install -r requirements.txt
```

### 依赖说明
- `fastapi==0.104.1`: 现代高性能Web框架
- `uvicorn[standard]==0.24.0`: ASGI应用服务器
- `pydantic==1.10.13`: 数据验证和设置管理
- `python-multipart==0.0.6`: 多部分表单支持
- `requests`: HTTP客户端库
- `cryptography`: 加密库用于API安全通信

## 运行服务器

### 主服务器 (SSE + MCP)
```bash
python main.py
```
服务器将在 `http://localhost:8000` 上运行

### 独立的MCP工具服务器
```bash
uvicorn mcp_tools.server:mcp_app --host 0.0.0.0 --port 8001
```
MCP工具服务器将在 `http://localhost:8001` 上运行

### 注意事项
- 需要在 `mcp_tools/queue_tool.py` 中配置美位API的 `queue_api_key` 和 `queue_api_secret`
- 确保网络可以访问美位排队API服务

## API端点

### SSE服务器端点
- `GET /` - 服务器根路径，显示统计信息
- `GET /health` - 健康检查
- `GET /test-sse` - SSE连接测试页面
- `GET /events/{client_id}` - SSE事件流连接
- `POST /publish` - 发布消息到频道
- `GET /channels/{channel}/clients` - 获取频道客户端列表
- `DELETE /clients/{client_id}` - 断开客户端连接
- `POST /broadcast-test/{channel}` - 广播测试消息
- `GET /demo-mcp-tools` - MCP工具演示

### MCP工具服务器端点
- `GET /tools` - 列出所有可用工具
- `POST /tools/call` - 调用指定工具
- `GET /tools/{tool_name}/schema` - 获取工具参数模式

### 工具调用示例
```bash
# 列出所有工具
curl http://localhost:8000/mcp/tools

# 调用附近门店搜索工具
curl -X POST http://localhost:8000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "queue_near_shop_tool", "arguments": {"lat": 30.1111, "lng": 121.1111}}'

# 调用取号工具
curl -X POST http://localhost:8000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "queue_get_tool", "arguments": {"shop_id": 123, "number": 2, "mobile": "13800138000"}}'
```

## 使用示例

### 连接到SSE流
```javascript
const eventSource = new EventSource('http://localhost:8000/events/my-client-id');

eventSource.onmessage = function(event) {
    console.log('Received:', event.data);
};

eventSource.onerror = function(event) {
    console.error('SSE Error:', event);
};
```

### 调用MCP工具
```bash
# 列出所有工具
curl http://localhost:8000/mcp/tools

# 调用计算器工具
curl -X POST http://localhost:8000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "calculator_tool", "arguments": {"operation": "add", "a": 10, "b": 5}}'

# 调用天气工具
curl -X POST http://localhost:8000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "weather_tool", "arguments": {"city": "Beijing", "unit": "celsius"}}'
```

## MCP工具列表

### 1. 附近门店搜索工具 (`queue_near_shop_tool`)
- 描述: 获取附近排队门店信息
- 参数:
  - `lat` (float, required): 纬度
  - `lng` (float, required): 经度
  - `search` (string, optional): 门店名称

### 2. 线上取号工具 (`queue_get_tool`)
- 描述: 发起线上取号
- 参数:
  - `order_sn` (string, required): 订单编号
  - `shop_id` (int, required): 门店id
  - `number` (int, required): 人数
  - `mobile` (string, required): 用户手机号

### 3. 排队号码取消工具 (`queue_cancel_tool`)
- 描述: 取消排队号码
- 参数:
  - `serial_id` (int, required): 排队号单id

### 4. 排队号码查询工具 (`queue_query_tool`)
- 描述: 查询排队号码状态
- 参数:
  - `serial_id` (int, required): 排队号单id
  - `order_sn` (string, optional): 订单编号

## 如何添加新的MCP工具

要添加新的MCP工具，请参考详细的指南文档 [HOW_TO_ADD_MCP_TOOL.md](./HOW_TO_ADD_MCP_TOOL.md)，其中包含：

### 1. 工具结构要求
- `name`: 工具唯一标识符
- `description`: 工具功能描述
- `get_parameters_schema()`: 参数JSON Schema定义
- `call()`: 异步执行方法

### 2. 完整示例
```python
import asyncio
from typing import Dict, Any
class MyNewTool:
    name = "my_new_tool"
    description = "我的新工具描述"
    
    @staticmethod
    def get_parameters_schema():
        return {
            "type": "object",
            "properties": {
                "param1": {"type": "string", "description": "参数1"},
                "param2": {"type": "number", "description": "参数2"}
            },
            "required": ["param1"]
        }
    
    async def call(self, param1: str, param2: int = 10) -> Dict[str, Any]:
        await asyncio.sleep(0.1)
        return {"result": f"处理结果: {param1}, {param2}"}

# 注册工具
from mcp_tools.queue_tool import tool_registry
tool_registry.register_tool(MyNewTool())
```

### 3. 测试工具
```python
# 通过代码测试
result = await tool_registry.call_tool("my_new_tool", {
    "param1": "测试值",
    "param2": 42
})
print(result.result)
```

## 运行MCP工具示例

```bash
python mcp_example_usage.py
```

这将运行所有MCP工具的使用示例，包括：
- 附近门店搜索示例
- 工具注册表演示
- API使用示例说明

### 示例输出预览
```
开始运行MCP工具示例...

=== 排队门店列表 ===
门店信息: {'shops': [...], 'timestamp': '...'}

=== 工具注册表示例 ===
可用工具列表:
- queue_near_shop_tool: 获取附近排队门店信息
- queue_get_tool: 取号
- queue_cancel_tool: 排队号码取消
- queue_query_tool: 排队号码查询
```

## 扩展性

### 添加新的SSE处理器
创建新的处理器类继承自 [EventHandler](./sse_mcp_server/handlers.py) 并实现相应的处理方法。

### 添加新的MCP工具
1. 创建新工具类，实现必要的方法
2. 注册工具到 [tool_registry](./mcp_tools/queue_tool.py)
3. 定义参数模式

### 自定义中间件
可以在 [middleware.py](./sse_mcp_server/middleware.py) 中添加自定义的认证或日志中间件。

### 事件处理扩展
通过 [handlers.py](./sse_mcp_server/handlers.py) 可以添加自定义的事件处理逻辑。

## 技术栈

- [FastAPI](https://fastapi.tiangolo.com/) - 现代高性能Web框架
- [Uvicorn](https://www.uvicorn.org/) - ASGI应用服务器
- [Pydantic](https://pydantic-docs.helpmanual.io/) - 数据验证和设置管理
- [SSE (Server-Sent Events)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) - 服务器推送技术
- [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) - 模型上下文协议
- [Requests](https://docs.python-requests.org/) - HTTP客户端库
- [Cryptography](https://cryptography.io/) - 加密库用于API安全通信

## 配置说明

### API密钥配置
在使用美位排队服务前，需要在 `mcp_tools/queue_tool.py` 中配置：

```python
queue_api_key = "your_api_key_here"
queue_api_secret = "your_api_secret_here"
```

### 环境变量配置（推荐）
建议使用环境变量来管理敏感信息：

```python
import os
queue_api_key = os.getenv('QUEUE_API_KEY', '')
queue_api_secret = os.getenv('QUEUE_API_SECRET', '')
```

## 许可证

MIT License

## 开发者信息

- 项目名称: 美味排队系统
- 主要功能: 美位排队系统API集成
- 技术架构: FastAPI + SSE + MCP
- 支持平台: Python 3.8+

如有问题或建议，请联系开发团队。