meiwe-queue-mcp 1.0.0

美味排队系统 MCP Server - 符合 Model Context Protocol 官方协议规范

美味排队系统 - MCP Server

这是一个符合 Model Context Protocol (MCP) 官方协议规范的排队系统服务器实现。主要提供美位排队系统的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规范 的标准实现
• 支持 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 (推荐)

# 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. 安装依赖

# 使用 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. 配置环境变量

# 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 (远程访问) - 推荐

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

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

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

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

方式二：stdio (Claude Desktop)

uv run mcp_server.py stdio

5. 配置 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.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中添加：

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

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

开发模式

使用 MCP CLI 开发工具：

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

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

旧版服务器 (保留兼容)

# 需要安装旧版依赖
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，通过以下方式访问：

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

使用MCP Inspector进行测试：

npx @modelcontextprotocol/inspector
# 连接到 http://localhost:8000/mcp

旧版REST API端点 (main.py)

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

# 旧版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测试

# 启动服务器
uv run mcp_server.py

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

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，其中包含：

1. 工具结构要求

• name: 工具唯一标识符
• description: 工具功能描述
• get_parameters_schema(): 参数JSON Schema定义
• call(): 异步执行方法

2. 完整示例

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. 测试工具

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

运行MCP工具示例

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 并实现相应的处理方法。

添加新的MCP工具

1. 创建新工具类，实现必要的方法
2. 注册工具到 tool_registry
3. 定义参数模式

自定义中间件

可以在 middleware.py 中添加自定义的认证或日志中间件。

事件处理扩展

通过 handlers.py 可以添加自定义的事件处理逻辑。

技术栈

• uv - 现代Python包管理器
• MCP Python SDK - MCP官方Python SDK
• Model Context Protocol - 模型上下文协议规范
• Pydantic - 数据验证和设置管理
• HTTPX - 异步HTTP客户端
• Cryptography - 加密库用于API安全通信
• FastAPI - Web框架 (旧版兼容)

配置说明

环境变量配置

# 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)

{
  "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

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