meiwe-queue-mcp 1.0.1
美味排队系统 MCP Server - 符合 Model Context Protocol 官方协议规范
License: MIT
Requires Python: >=3.10
Keywords: mcp, meiwe, model-context-protocol, queue

# 美味排队系统 - MCP Server

这是一个符合 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 官方协议规范的排队系统服务器实现。主要提供美位排队系统的API集成和服务，可直接被 Claude Desktop、Cursor 等 MCP 客户端使用。

## MCP 协议支持

本项目已完成MCP协议改造，支持以下传输方式：

| 传输方式 | 适用场景 | 端点 |
|---------|---------|------|
| **Streamable HTTP** | 远程部署、Web集成 | `http://localhost:8000/mcp` |
| **stdio** | Claude Desktop、本地客户端 | 标准输入/输出 |

## 项目结构

```
meiwe-queue-mcp/
├── mcp_server.py           # 【主入口】标准MCP Server (符合官方协议)
├── pyproject.toml          # 项目配置和依赖 (uv/pip)
├── mcp_tools/              # MCP工具组件
│   ├── __init__.py
│   ├── queue_api.py        # 美位排队API封装 (加密通信)
│   ├── queue_tool.py       # 排队工具实现 (旧版)
│   └── server.py           # MCP工具服务器 (旧版REST API)
├── sse_mcp_server/         # SSE服务器组件 (旧版，保留兼容)
│   ├── __init__.py
│   ├── server.py           # 主SSE服务器实现
│   ├── models.py           # 数据模型定义
│   ├── utils.py            # 工具函数
│   ├── middleware.py       # 中间件实现
│   └── handlers.py         # 事件处理器
├── main.py                 # 旧版主应用入口
├── requirements.txt        # 旧版依赖文件 (兼容pip)
└── README.md               # 本说明文档
```

## 功能特性

### MCP Server (官方协议)
- 符合 [MCP规范](https://modelcontextprotocol.io/specification/2025-06-18) 的标准实现
- 支持 Streamable HTTP 和 stdio 传输
- 可被 Claude Desktop、Cursor 等客户端直接使用
- JSON-RPC 2.0 消息格式

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

### 旧版SSE服务器 (保留兼容)
- 实时事件流传输
- 客户端连接管理
- 自定义REST API

## 快速开始

### 1. 安装 uv (推荐)

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 2. 安装依赖

```bash
# 使用 uv (推荐)
uv sync

# 或使用 pip
pip install -r requirements.txt
```

### 依赖说明 (pyproject.toml)
- `mcp[cli]>=1.2.0`: **MCP官方Python SDK**
- `httpx>=0.25.0`: 异步HTTP客户端
- `pydantic>=2.0.0`: 数据验证
- `requests>=2.31.0`: HTTP客户端库
- `cryptography>=41.0.0`: 加密库用于API安全通信

### 3. 配置环境变量

```bash
# Linux/macOS
export QUEUE_API_KEY="your_api_key_here"
export QUEUE_API_SECRET="your_api_secret_here"

# Windows PowerShell
$env:QUEUE_API_KEY="your_api_key_here"
$env:QUEUE_API_SECRET="your_api_secret_here"
```

### 4. 运行MCP Server

#### 方式一：Streamable HTTP (远程访问) - 推荐

```bash
# 使用 uv 运行 (推荐)
uv run mcp_server.py

# 或指定传输方式
uv run mcp_server.py streamable-http
```

服务器将在 `http://localhost:8000/mcp` 上运行，可通过MCP Inspector测试：

```bash
npx @modelcontextprotocol/inspector
# 然后连接到 http://localhost:8000/mcp
```

#### 方式二：stdio (Claude Desktop)

```bash
uv run mcp_server.py stdio
```

### 5. 配置 Claude Desktop

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "meiwe-queue": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/xiexinfa/mcp/meiwe-queue-mcp",
        "run",
        "mcp_server.py",
        "stdio"
      ],
      "env": {
        "QUEUE_API_KEY": "your_api_key",
        "QUEUE_API_SECRET": "your_api_secret"
      }
    }
  }
}
```

### 6. 配置 Cursor

先启动HTTP服务器，然后在Cursor中添加：

```bash
# 1. 启动服务器
uv run mcp_server.py

# 2. 添加到Cursor (另一个终端)
claude mcp add --transport http meiwe-queue http://localhost:8000/mcp
```

## 开发模式

使用 MCP CLI 开发工具：

```bash
# 开发模式 (带Inspector)
uv run mcp dev mcp_server.py

# 安装到Claude Desktop
uv run mcp install mcp_server.py --name "美味排队"
```

## 旧版服务器 (保留兼容)

```bash
# 需要安装旧版依赖
uv sync --extra legacy

# 运行旧版服务器
uv run python main.py
```
服务器将在 `http://localhost:8000` 上运行（非标准MCP协议）

## MCP 工具列表

新版MCP Server提供以下标准MCP工具：

### 1. 附近门店搜索 (`queue_near_shop`)
- 描述: 搜索附近排队门店
- 参数:
  - `lat` (float, 必填): 纬度坐标
  - `lng` (float, 必填): 经度坐标
  - `search` (string, 可选): 门店名称搜索关键词

### 2. 线上取号 (`queue_get`)
- 描述: 发起线上取号
- 参数:
  - `shop_id` (int, 必填): 门店ID
  - `number` (int, 必填): 就餐人数
  - `mobile` (string, 必填): 用户手机号
  - `order_sn` (string, 可选): 订单编号

### 3. 取消排队 (`queue_cancel`)
- 描述: 取消排队号码
- 参数:
  - `serial_id` (int, 必填): 排队号单ID

### 4. 查询排队状态 (`queue_query`)
- 描述: 查询排队号码状态
- 参数:
  - `serial_id` (int, 必填): 排队号单ID
  - `order_sn` (string, 可选): 订单编号

## API端点

### 标准MCP端点 (mcp_server.py)

MCP协议使用JSON-RPC 2.0，通过以下方式访问：

```bash
# Streamable HTTP 端点
POST http://localhost:8000/mcp  # 发送JSON-RPC请求
GET  http://localhost:8000/mcp  # SSE流 (服务器推送)
```

使用MCP Inspector进行测试：
```bash
npx @modelcontextprotocol/inspector
# 连接到 http://localhost:8000/mcp
```

### 旧版REST API端点 (main.py)

- `GET /mcp/tools` - 列出所有工具
- `POST /mcp/tools/call` - 调用工具
- `GET /mcp/tools/{tool_name}/schema` - 获取工具参数模式

```bash
# 旧版API调用示例 (非标准MCP)
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}}'
```

## 使用示例

### 在Claude中使用 (配置完成后)

```
用户: 帮我搜索上海市中心附近的排队门店

Claude: 我来帮您搜索上海市中心附近的门店...
[调用 queue_near_shop 工具]
找到以下门店：
1. XXX餐厅 - 可手机取号，当前等待3桌
2. YYY火锅 - 不用排队
...
```

### 使用MCP Inspector测试

```bash
# 启动服务器
uv run mcp_server.py

# 另一个终端，启动Inspector
npx @modelcontextprotocol/inspector
# 在浏览器中打开，连接到 http://localhost:8000/mcp
```

### Python客户端示例

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    async with streamable_http_client("http://localhost:8000/mcp") as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # 列出可用工具
            tools = await session.list_tools()
            print(f"可用工具: {[t.name for t in tools.tools]}")
            
            # 调用工具
            result = await session.call_tool(
                "queue_near_shop",
                {"lat": 31.2304, "lng": 121.4737}
            )
            print(result)

asyncio.run(main())
```

## 如何添加新的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) 可以添加自定义的事件处理逻辑。

## 技术栈

- [uv](https://docs.astral.sh/uv/) - **现代Python包管理器**
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - **MCP官方Python SDK**
- [Model Context Protocol](https://modelcontextprotocol.io/) - 模型上下文协议规范
- [Pydantic](https://pydantic-docs.helpmanual.io/) - 数据验证和设置管理
- [HTTPX](https://www.python-httpx.org/) - 异步HTTP客户端
- [Cryptography](https://cryptography.io/) - 加密库用于API安全通信
- [FastAPI](https://fastapi.tiangolo.com/) - Web框架 (旧版兼容)

## 配置说明

### 环境变量配置

```bash
# Linux/macOS
export QUEUE_API_KEY="your_api_key_here"
export QUEUE_API_SECRET="your_api_secret_here"

# Windows PowerShell
$env:QUEUE_API_KEY="your_api_key_here"
$env:QUEUE_API_SECRET="your_api_secret_here"
```

### Claude Desktop 配置 (使用 uv)

```json
{
  "mcpServers": {
    "meiwe-queue": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/xiexinfa/mcp/meiwe-queue-mcp",
        "run",
        "mcp_server.py",
        "stdio"
      ],
      "env": {
        "QUEUE_API_KEY": "your_api_key",
        "QUEUE_API_SECRET": "your_api_secret"
      }
    }
  }
}
```

## 协议对比

| 特性 | 新版 (mcp_server.py) | 旧版 (main.py) |
|-----|---------------------|----------------|
| 协议规范 | MCP官方协议 | 自定义REST |
| 消息格式 | JSON-RPC 2.0 | HTTP REST |
| 传输方式 | Streamable HTTP / stdio | SSE + REST |
| 客户端支持 | Claude Desktop, Cursor等 | 自定义客户端 |
| 工具发现 | 标准 `tools/list` | 自定义 `/mcp/tools` |

## 许可证

MIT License

## 开发者信息

- 项目名称: 美味排队系统 MCP Server
- 主要功能: 美位排队系统API集成
- 技术架构: MCP SDK + Streamable HTTP
- 支持平台: Python 3.10+
- 包管理器: uv (推荐) / pip

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