room-stu-fault-mcp

教室故障排查 MCP 服务，面向阿里云百炼 uvx / PyPI 部署。

提供三个工具（业务逻辑在 src/room_stu_fault_mcp/tools/ 中自行填充）：

未接好真实接口时，工具会返回模拟数据，便于本地和百炼联调。

本地开发

需要 Python 3.10+（本机默认 python3 若是 3.9，不要用它建 venv）。推荐用 uv：

uv python install 3.12
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .
cp .env.example .env   # 按需填写

或指定解释器：

/path/to/python3.12 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

本地以 stdio 启动：

room-stu-fault-mcp
# 或
python -m room_stu_fault_mcp
# 或
fastmcp run src/room_stu_fault_mcp/server.py:mcp

怎么调用测试

stdio 服务本身不会打印结果，要用 Client 去调工具。

1. FastMCP 内存调用（推荐，最快）

source .venv/bin/activate
python examples/call_tools.py

等价手写：

import asyncio
from fastmcp import Client
from room_stu_fault_mcp.server import mcp

async def main():
    async with Client(mcp) as client:
        print(await client.list_tools())
        print(await client.call_tool("query_classroom_logs", {"serial": "R101"}))
        print(await client.call_tool("get_room_network_info", {
            "company_id": 10097,
            "serial": "1000292304",
            "room_unit_id": 575718,
            "userid": "379180147",
            "receive_userid": "1b3e2441-b89d-2ef9-fa97-431d101daa51",
        }))
        print(await client.call_tool("get_classroom_tickets", {
            "companyid": 120554,
            "serial": "1248513074",
            "userid": "379180147",
            "starttime": 1788364800,
            "endtime": 1788451200,
        }))

asyncio.run(main())

2. 只测业务方法（不经过 MCP）

python -c "from room_stu_fault_mcp.tools.classroom_logs import fetch_classroom_logs; print(fetch_classroom_logs('R101'))"
python -c "from room_stu_fault_mcp.tools.network_info import fetch_room_network_info; print(fetch_room_network_info(10097, '1000292304', 575718, '379180147', '1b3e2441-b89d-2ef9-fa97-431d101daa51'))"
python -c "from room_stu_fault_mcp.tools.tickets import fetch_classroom_tickets; print(fetch_classroom_tickets(120554, '1248513074', '379180147', 1788364800, 1788451200))"

3. MCP Inspector 可视化调试

fastmcp dev src/room_stu_fault_mcp/server.py:mcp

浏览器打开后，在 Tools 里点三个工具，填 serial=R101 即可。

Cursor / Claude Desktop 本地调试配置：

{
  "mcpServers": {
    "room-stu-fault": {
      "command": "uvx",
      "args": ["--from", ".", "room-stu-fault-mcp"],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": ""
      }
    }
  }
}

发布到 PyPI

包名必须全局唯一。发布前把 pyproject.toml 里的 name / version 改成你的。

不要用系统自带的 pip（本机默认常是 Python 3.9，会和 botocore / selenium 抢 urllib3）。用项目虚拟环境或 uv：

source .venv/bin/activate
uv pip install build twine
python -m build
python -m twine upload dist/*

更省事：

uv build
uv publish --token pypi-xxxxxxxx

部署到阿里云百炼

1. 控制台 → MCP 管理 → 创建 MCP 服务 → 使用脚本部署
2. 安装方式选 uvx
3. 配置粘贴如下（把包名换成你发布到 PyPI 的名字）：

{
  "mcpServers": {
    "room-stu-fault": {
      "type": "stdio",
      "timeout": 600,
      "command": "uvx",
      "args": ["room-stu-fault-mcp@0.1.1"],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "你的 AccessKey ID",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "你的 AccessKey Secret",
        "ALIYUN_SLS_ENDPOINT": "cn-hangzhou.log.aliyuncs.com",
        "ALIYUN_SLS_PROJECT": "你的 SLS Project",
        "ALIYUN_SLS_LOGSTORE": "你的 Logstore",
        "NETWORK_API_URL": "https://your-server.example.com",
        "NETWORK_API_PATH": "/room/{serial}/user/figure",
        "NETWORK_API_TOKEN": "",
        "TICKET_API_URL": "https://your-server.example.com",
        "TICKET_API_PATH": "/api/tickets",
        "TICKET_API_TOKEN": ""
      }
    }
  }
}

4. 部署方式选 极速模式（不要用按次计费的基础模式）。uvx 首次拉包很慢，基础模式实例很容易被回收，随后就会 503。
5. 部署成功后，在智能体 / 工作流里勾选该 MCP 即可调用三个工具。

若出现 503 No active SSE connection for session：先重试 2～3 次；仍失败则到函数计算 FC 打开日志服务看 uvx 是否启动失败，然后停掉服务、改成极速模式并加上 "timeout": 600 后重新部署。

环境变量