# UCC Question Bank MCP

面向 `ucc.sziscloud.com` 的本地 MCP 工具。浏览器扩展只负责把用户自己已登录的 UCC 会话安全地同步到本机；读取题库、创建练习和提交答案由支持 MCP 的 AI 客户端完成。

> 本项目仅适用于你本人拥有或明确获授权的学习账号。使用前请确认符合平台规则、课程要求和所在机构政策。不要用于绕过验证码、访问控制、速率限制或批量操控他人账号。

## 特点

- 纯 MCP 架构：浏览器中没有答题弹窗、悬浮条或 AI API Key 配置。
- 本机通信：桥接服务只监听 `127.0.0.1:33741`。
- 凭据不落盘：登录令牌仅保存在 MCP 进程内存中。
- 每次安装生成独立的 256-bit 桥接密钥，密钥文件不提交 Git。
- 写操作有显式保护：真实提交需要 `dryRun=false` 和 `confirm=true`。
- 提供 8 个工具、中文使用文档、通用提示词和 CI。

## 项目结构

```text
browser-extension/   无界面 Edge/Chrome 登录桥
mcp-server/          Node.js stdio MCP Server
docs/                安装、使用、安全、排错和提示词
scripts/setup.mjs    生成本机桥接密钥
```

## 快速开始

要求 Node.js 20+、Edge/Chrome，以及支持本地 stdio MCP 的 AI 客户端。

```bash
git clone https://github.com/Adrian-Maa/ucc-question-bank-mcp.git
cd ucc-question-bank-mcp
npm run setup
npm run install:mcp
```

然后：

1. Edge 打开 `edge://extensions/`，开启开发人员模式。
2. 选择“加载解压缩的扩展”，加载 `browser-extension` 文件夹。
3. 在 AI 客户端中配置 `mcp-server/server.mjs` 的绝对路径。
4. 打开并登录 UCC 页面，保持标签页打开。
5. 新建 AI 任务并调用 `ucc_status`，确认返回 `paired: true`。

通用 MCP 配置：

```json
{
  "mcpServers": {
    "ucc_question_bank": {
      "command": "node",
      "args": ["/absolute/path/to/ucc-question-bank-mcp/mcp-server/server.mjs"]
    }
  }
}
```

Codex CLI：

```bash
codex mcp add ucc_question_bank -- node "/absolute/path/to/ucc-question-bank-mcp/mcp-server/server.mjs"
```

完整步骤见 [使用说明](docs/USAGE.md)，可直接复制的 AI 指令见 [通用提示词](docs/PROMPT.md)。

## MCP 工具

| 工具 | 用途 | 写入 |
| --- | --- | --- |
| `ucc_status` | 检查浏览器配对状态 | 否 |
| `ucc_list_libraries` | 列出题库和题量 | 否 |
| `ucc_start_exercise` | 创建顺序练习 | 是，需确认 |
| `ucc_get_question` | 读取题目、选项、标准答案和解析 | 否 |
| `ucc_submit_question` | 试运行或提交答案 | 默认不写；真实提交需双重确认 |
| `ucc_finish_exercise` | 结束练习并释放会话 | 是，需确认 |
| `ucc_list_active_exercises` | 列出进行中的练习 | 否 |
| `ucc_current_exercise_info` | 读取当前练习统计 | 否 |

## 重要注意事项

- 首次安装或重新克隆后必须运行 `npm run setup`，否则扩展和 MCP 不会启动。
- `.ucc-bridge-secret`、`browser-extension/bridge-config.js`、`.pem`、令牌和 Cookie 都不能提交或分享。
- AI 客户端通常只在启动时读取 MCP 工具；更新后请重启客户端或新建任务。
- 令牌过期时重新登录 UCC，并复用原 exerciseId，不要盲目新建练习。
- 建议保持正常作答节奏；连续网络失败时停止，避免形成异常请求风暴。
- 公开仓库不包含站点下载源码、真实账号数据、练习 ID、浏览器配置或预签名 CRX。

## 文档

- [完整使用说明](docs/USAGE.md)
- [通用 AI 提示词](docs/PROMPT.md)
- [常见问题与排错](docs/TROUBLESHOOTING.md)
- [安全说明](SECURITY.md)
- [贡献指南](CONTRIBUTING.md)

## 免责声明

本项目与 UCC、SZIS Cloud 或相关机构无隶属、认可或合作关系。站点名称和接口仅用于兼容性描述。使用者应自行承担账号、课程记录和平台合规风险。

## License

[MIT](LICENSE)