cscec-login-mcp

一个零依赖、可分发的 MCP（Model Context Protocol）服务器，把 中建三局（CSCEC）门户的企业微信扫码登录流程封装成标准化工具，供任意 MCP 客户端（WorkBuddy、Claude Desktop 等）调用。

适用场景：你要在自己的 AI 工作流 / 客户端里，让最终用户通过企业微信扫码登录 CSCEC 门户（及「应用商城」），并拿到门户 / 应用市场的令牌。

---

特性

• 零第三方依赖：只用 Python 标准库，python3 mcp_server.py 即可运行。
• 9 个工具：覆盖「生成二维码 → 等待扫码 → 兑换门户令牌 → 列出/搜索应用 → 选择应用 → 兑换应用市场令牌 → 查询令牌状态 → 清理会话」。
• 内置登录页（产品级展示）：cscec_qr_create 返回 login_url —— 一个本地 Web 登录页（http://127.0.0.1:<port>/login?session=...），页面 自动显示二维码、110 秒倒计时、到期自动刷新二维码（session_id 不变）、 实时扫码状态反馈、成功页。AI 客户端只需把这一个 URL 交给用户，用户在 浏览器里完成全部交互。SSO 长轮询由后台线程承担，页面状态查询即时返回。
• 唯一展示通道：浏览器登录页（login_url）。二维码在页面内渲染， 不依赖任何系统图片预览或桌面 PNG 副本。
• 密钥不外露：一次性 code、令牌只落在用户私有目录 ~/.cscec_qr_login/mcp/<session>/，tool 结果一律脱敏。

---

前置条件

• Python 3.10+

安装 / 分发

无需 pip install。把整个目录发给对方（或 git clone）即可：

git clone <repo> cscec-login-mcp
# 或直接拷贝目录

接入 MCP 客户端

在客户端的 MCP 配置文件（如 ~/.workbuddy/mcp.json、 claude_desktop_config.json）里加：

{
  "mcpServers": {
    "cscec-wecom-qr-login": {
      "command": "python3",
      "args": ["/abs/path/to/cscec-login-mcp/mcp_server.py"]
    }
  }
}

若客户端无法解析 python3，把 command 换成绝对路径，例如 /usr/bin/python3 或 ~/.workbuddy/binaries/python/versions/3.13.12/bin/python3。

重启客户端后，9 个 cscec_* 工具即被加载。

---

工具一览

工具	作用
cscec_qr_create	向 SSO 申请二维码，返回 login_url（登录页）等
cscec_qr_wait	等待用户扫码（默认 100 秒；session_id 可传 "latest"）
cscec_portal_exchange	用一次性 code 兑换门户 access_token / iam_token
cscec_portal_list_apps	列出当前用户的门户应用（按「岗位场景」配置树）
cscec_portal_search_apps	按关键词搜索门户应用目录
cscec_select_app	按序号选中某个应用
cscec_exchange_market_code	用应用市场一次性 code 兑换 xindun_token
cscec_token_status	查询门户 / 应用市场令牌的非敏感状态
cscec_session_cleanup	删除本次会话的私有文件

典型流程

1. cscec_qr_create            → 拿到 login_url，立即 present 给用户（浏览器打开登录页）
2. cscec_qr_wait              → 用户在登录页扫码（页面自动刷新码，无需 AI 介入）
3. cscec_portal_exchange      → 拿到门户令牌
4. cscec_portal_list_apps     → 列出可访问的应用
5. （可选）cscec_exchange_market_code → 登录「应用商城」

所有工具共享一个 session_id（由 cscec_qr_create 返回）。登录页刷新 二维码不会改变 session_id——AI 侧无需感知。

---

二维码如何展示给用户

cscec_qr_create 首选返回 login_url（推荐）：server 首次调用时自动 在 127.0.0.1 起 HTTP 服务，返回 http://127.0.0.1:<port>/login?session=...。这是一个完整的登录页：

• 大图二维码 + 110 秒倒计时，到期自动刷新（也可手动点按钮刷新）
• 每 2 秒轮询扫码状态："请扫码" → "已扫码，请确认" → "✔ 扫码成功"
• 深色模式自适应，移动端可扫

AI 客户端（WorkBuddy / Claude Desktop 等）只需 present_files(login_url) 或把 URL 展示给用户即可，用户看码、扫码、确认全在页面内闭环， AI 不再承担"展示图片"这个不可靠职责。

兜底（极少数宿主不渲染页面时）：

• qr_image_path：私有目录固定路径 ~/.cscec_qr_login/latest/qr.png（供 MCP image content 等标准通道使用）
• desktop_login_url_file：~/Desktop/cscec-login-url.txt 记录登录页 URL，方便找不到浏览器标签时手动打开

AI 客户端接入提示：调 cscec_qr_wait 前必须先把 login_url 真正 展示给用户，且只宣称用户已经能看到的内容。QR 有效期约 110 秒（登录页 自动续）；cscec_qr_wait 默认 100 秒超时，超时后重新 cscec_qr_create。

---

安全说明

• 令牌与一次性 code 均存于 ~/.cscec_qr_login/mcp/，权限 0700/0600。
• tool 返回值中任何 access_token / xindun_token 字段都会被自动脱敏为 [redacted]。
• cscec_exchange_market_code 的 endpoint 被白名单锁定为官方市场端点， 防止任意端点被滥用（如需替换，只能通过环境变量 CSCEC_MARKET_TOKEN_ENDPOINT）。
• 仅 cscec_qr_wait 涉及「人在环路」——需要最终用户用企业微信扫码确认， 这是 CSCEC 的强制安全校验，无法自动化绕过。

---

给非 AI 应用用的扩展

本仓库是能力层（MCP 接口）。若要把 CSCEC 登录集成进你自己的 Web / 小程序 前端（而非通过 AI 对话），直接用 cscec_login_core.py 这个零依赖库：

import cscec_login_core as core
# core.create(...) / core.wait_for_scan(...) / core.exchange(...) ...

再在其上包一层你自己的 HTTP API 即可，前端自行渲染 qr.png。核心登录逻辑 不依赖 LLM，确定性执行。

---

发布 / 分发给他人

本 MCP 零第三方依赖，所谓「发布」就是把项目交给对方、并在对方的 WorkBuddy ~/.workbuddy/mcp.json 里注册这个 server——无需上架任何应用商店。

✅ 已发布到官方 PyPI（2026-08-27，v1.0.1）： https://pypi.org/project/cscec-login-mcp/ 同事直接 pip install cscec-login-mcp 即可，无需拷贝目录。

方式零（最简单）：从 PyPI 安装

python3 -m pip install cscec-login-mcp
cscec-install              # 注册进 WorkBuddy（随包装好的命令，自动优先用 `cscec-mcp`）
# 或从仓库目录运行： python3 install.py

重启 WorkBuddy 后加载 9 个 cscec_* 工具，说「登录门户」即用。

方式一：内部分发（给公司同事用）

1. 打包目录：

   zip -r cscec-login-mcp.zip cscec-login-mcp
   

2. 把 zip 发给同事，他解压后运行自带的一键安装脚本：

   cd cscec-login-mcp
   python3 install.py
   

   脚本会自动把本项目注册进 ~/.workbuddy/mcp.json（并备份旧配置）， 之后重启 WorkBuddy 即可加载 9 个 cscec_* 工具。
3. 同事在 WorkBuddy 里说「登录门户」即可使用。

也可直接 git clone 你的内网仓库，同样跑 python3 install.py。

方式二：离线 / 内网源安装（无外网时用）

本项目已是标准 Python 包（含 pyproject.toml，控制台入口 cscec-mcp）。 已发布的 wheel 在 dist/ 目录，也可从官方 PyPI 直接拉取。

1. 安装（任选其一）：

   python3 -m pip install .                       # 源码本地装
   # 或
   python3 -m pip install dist/cscec_login_mcp-1.0.1-py3-none-any.whl   # 离线 wheel
   # 或（需外网）
   python3 -m pip install cscec-login-mcp
   

2. 注册到 WorkBuddy（cscec-install 自动优先用 cscec-mcp 命令）：

   cscec-install
   # 或从仓库目录： python3 install.py
   

3. 重启 WorkBuddy。此后 mcp.json 里该 server 的 command 即为 cscec-mcp， 换机器 / 换目录都无需改配置。

方式三：上架 WorkBuddy 连接器市场（面向更广用户）

若希望同事在 WorkBuddy UI 里「点一下就装」，需把本项目封装成 WorkBuddy 的 connector 包并走官方发布流程（连接器市场由官方维护，通常需审核）。 内部使用一般不必走这一步——方式一已足够。

License

仅供内部 / 授权使用。CSCEC 登录流程依赖官方 SSO 接口，接口变动需同步更新 cscec_login_core.py 中的默认 host / appid。