Metadata-Version: 2.4
Name: cscec-login-mcp
Version: 1.0.0
Summary: Stdio MCP server for CSCEC (中建三局) enterprise WeCom QR login
Author: CSCEC Login Team
License: Proprietary — internal use only
Project-URL: Homepage, https://internal/cscec-login-mcp
Keywords: cscec,mcp,qr-login,wecom,portal
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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`）即可：

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

## 接入 MCP 客户端

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

```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` 这个零依赖库：

```python
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——**无需上架任何应用商店**。

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

1. 打包目录：
   ```bash
   zip -r cscec-login-mcp.zip cscec-login-mcp
   ```
2. 把 zip 发给同事，他解压后运行自带的一键安装脚本：
   ```bash
   cd cscec-login-mcp
   python3 install.py
   ```
   脚本会自动把本项目注册进 `~/.workbuddy/mcp.json`（并备份旧配置），
   之后**重启 WorkBuddy** 即可加载 9 个 `cscec_*` 工具。
3. 同事在 WorkBuddy 里说「登录门户」即可使用。

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

### 方式二：做成标准 pip 包（适合有内网 pip 源的技术团队）

本项目已是标准 Python 包（含 `pyproject.toml`，控制台入口 `cscec-mcp`）。

1. 安装：
   ```bash
   python3 -m pip install .          # 或发布到内网源后 pip install cscec-login-mcp
   ```
2. 注册到 WorkBuddy（install.py 自动优先用 `cscec-mcp` 命令）：
   ```bash
   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。
