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", "userid": "414325797", "sdkversion": "5.1.0", "osversion": "ios"}))
        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", {
            "company_id": 120554,
            "serial": "1248513074",
            "userid": "379180147",
            "starttime": 1788364800,
            "endtime": 1788451200,
        }))
        print(await client.call_tool("diagnose_classroom_fault", {
            "company_id": 120554,
            "serial": "120554",
            "userid": "379180147",
            "room_unit_id": 575718,
            "receive_userid": "1b3e2441-b89d-2ef9-fa97-431d101daa51",
            "sdkversion": "5.1.0",
            "osversion": "ios",
            "starttime": 1788364800,
            "endtime": 1788451200,
            "description": "看不到老师画面",
        }))

asyncio.run(main())

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

python -c "from room_stu_fault_mcp.tools.classroom_logs import fetch_classroom_logs; print(fetch_classroom_logs('R101', '414325797', '5.1.0', 'ios'))"
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))"
python -c "from room_stu_fault_mcp.tools.diagnose import diagnose_classroom_fault; print(diagnose_classroom_fault(120554, '120554', '379180147', 575718, '1b3e2441-b89d-2ef9-fa97-431d101daa51', '5.1.0', 'ios', description='看不到老师画面'))"

3. MCP Inspector 可视化调试

fastmcp dev src/room_stu_fault_mcp/server.py:mcp

浏览器打开后，在 Tools 里点工具即可。综合诊断用 diagnose_classroom_fault，需配置 DASHSCOPE_API_KEY。

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": "",
        "ALIYUN_SLS_ENDPOINT": "cn-beijing.log.aliyuncs.com",
        "ALIYUN_SLS_PROJECT": "tk-client-log",
        "ALIYUN_SLS_TOPIC_ALL_CLIENTS": "log-all-clients",
        "ALIYUN_SLS_TOPIC_IOS": "log-ios",
        "ALIYUN_SLS_TOPIC_ANDROID": "log-androidstore",
        "ALIYUN_SLS_TOPIC_JS": "log-js",
        "NETWORK_API_URL": "https://testing-dash-api.talk-cloud.com",
        "NETWORK_API_PATH": "/room/{serial}/user/figure",
        "NETWORK_API_TOKEN": "",
        "TICKET_API_URL": "https://testing.talk-cloud.net",
        "TICKET_API_PATH": "/ClientAPI/workOrderListByAI",
        "TICKET_API_TOKEN": "",
        "DASHSCOPE_API_KEY": "",
        "QWEN_MODEL": "qwen3.8-max",
        "QWEN_API_BASE": "https://dashscope.aliyuncs.com/compatible-mode/v1"
      }
    }
  }
}

发布到 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": [
        "-q",
        "--python",
        "3.12",
        "--index-url",
        "https://mirrors.aliyun.com/pypi/simple",
        "--from",
        "room-stu-fault-mcp==0.1.5",
        "room-stu-fault-mcp"
      ],
      "env": {
        "UV_NO_PROGRESS": "1",
        "UV_PYTHON_INSTALL_MIRROR": "https://registry.npmmirror.com/-/binary/python-build-standalone",
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "你的 AccessKey ID",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "你的 AccessKey Secret",
        "ALIYUN_SLS_ENDPOINT": "cn-beijing.log.aliyuncs.com",
        "ALIYUN_SLS_PROJECT": "tk-client-log",
        "ALIYUN_SLS_TOPIC_ALL_CLIENTS": "log-all-clients",
        "ALIYUN_SLS_TOPIC_IOS": "log-ios",
        "ALIYUN_SLS_TOPIC_ANDROID": "log-androidstore",
        "ALIYUN_SLS_TOPIC_JS": "log-js",
        "NETWORK_API_URL": "https://testing-dash-api.talk-cloud.com",
        "NETWORK_API_PATH": "/room/{serial}/user/figure",
        "NETWORK_API_TOKEN": "",
        "TICKET_API_URL": "https://testing.talk-cloud.net",
        "TICKET_API_PATH": "/ClientAPI/workOrderListByAI",
        "TICKET_API_TOKEN": "",
        "DASHSCOPE_API_KEY": "你的百炼 API Key",
        "QWEN_MODEL": "qwen3.8-max",
        "QWEN_API_BASE": "https://dashscope.aliyuncs.com/compatible-mode/v1"
      }
    }
  }
}

4. 部署方式选 极速模式（不要用按次计费的基础模式）。uvx 首次拉 Python 和依赖经常超过 1 分钟，基础模式冷启动会直接触发初始化超时。
5. 部署成功后，在智能体 / 工作流里勾选该 MCP。日常排查可调 diagnose_classroom_fault（按 description 结合日志和上下行诊断；查工单用 get_classroom_tickets）。

若出现 11200057 / Initialization request timeout: no response within 1m：这是 MCP 握手超时，不是诊断工具本身失败。按下面处理：

1. 确认已开 极速模式，配置里有 "timeout": 600，args 带 -q 且 pin 了正确版本（不要再用 ==0.1.1）。
2. 环境变量加上 UV_NO_PROGRESS=1 和国内镜像（见上），避免 uvx 进度输出打到 stdout、或从 GitHub 拉 Python 超时。
3. 到函数计算 FC 看启动日志：若卡在 Downloading / Resolved，多点几次「测试」把缓存打热，第二次通常就能握手成功。
4. 不要设置 MCP_TRANSPORT=rest 或 sse，百炼脚本部署必须走默认 stdio。

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

环境变量