# @taotao7/bypass-mcp

bypass-saas 课程平台的 MCP Server，提供课程、文章、学员、订单等管理能力，供 Claude Desktop / Claude Code 等 MCP 客户端调用。

## 快速开始

### 1. 获取 API Token

在你部署的 bypass-saas **Admin 后台**中生成 Token：

1. 登录 Admin 后台
2. 进入 **设置 → API Token 管理**
3. 点击"生成 Token"，复制生成的 `bp_xxx` 格式 token

### 2. 配置 MCP 客户端

#### Claude Desktop

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "bypass": {
      "command": "npx",
      "args": ["-y", "@taotao7/bypass-mcp"],
      "env": {
        "BYPASS_API_URL": "https://admin.airbypass.com/api",
        "BYPASS_API_TOKEN": "bp_your-token-here"
      }
    }
  }
}
```

#### Claude Code

编辑 `.claude/settings.json` 或全局配置：

```json
{
  "mcpServers": {
    "bypass": {
      "command": "npx",
      "args": ["-y", "@taotao7/bypass-mcp"],
      "env": {
        "BYPASS_API_URL": "https://admin.airbypass.com/api",
        "BYPASS_API_TOKEN": "bp_your-token-here"
      }
    }
  }
}
```

### 环境变量

| 变量 | 必填 | 说明 |
|------|------|------|
| `BYPASS_API_URL` | 是 | Admin 后台 API 地址（如 `https://admin.airbypass.com/api`） |
| `BYPASS_API_TOKEN` | 是 | 在 Admin 后台 **设置 → API Token 管理** 中生成的 Token（`bp_xxx` 格式） |

## 可用工具

### 课程管理

| 工具 | 说明 |
|------|------|
| `bypass_list_courses` | 列出课程，支持 status/category_id/search 筛选 + 分页 |
| `bypass_get_course` | 按 ID 获取单个课程详情（含购买项列表） |
| `bypass_generate_course_qrcode` | 在调用 MCP 的本机为单个课程详情页生成带网站 logo 和课程代码的 PNG 二维码 |
| `bypass_generate_course_qrcodes` | 在调用 MCP 的本机批量生成课程详情页二维码，默认只生成已发布课程，并自动识别课程代码 |
| `bypass_create_course` | 创建课程（价格通过购买项管理，非课程级别） |
| `bypass_update_course` | 更新课程，仅更新传入的字段 |
| `bypass_delete_course` | 删除课程 |
| `content_preview_images` | `bypass_create_course` / `bypass_update_course` 的课程详情页「内容预览」图片数组，支持多张图，按数组顺序展示 |
| `bypass_get_common_course_intro_images` | 获取所有课程详情页共用的「课程介绍」图片列表 |
| `bypass_update_common_course_intro_images` | 替换所有课程详情页共用的「课程介绍」图片列表，按传入顺序展示 |
| `bypass_list_course_comments` | 查看课程评论，含外部导入评论和真实学员评论奖励金 |
| `bypass_import_course_comment` | 导入外部评论；不绑定本地用户，不产生评论奖励金 |
| `bypass_delete_course_comment` | 删除课程评论；若有奖励金记录会同步删除 |

二维码工具只读取课程 slug/title，然后在 MCP 进程所在机器本地生成 PNG 文件，不上传图片、不新增数据库记录，也不占用服务器图片处理资源。默认链接为 `https://airbypass.com/courses/{slug}`，可用 `BYPASS_WEB_BASE_URL` 环境变量或工具参数 `base_url` 覆盖；默认输出目录为 MCP 进程当前目录下的 `bypass-course-qrcodes/`。中心区域默认展示 Bypass logo 和课程代码；单个生成可传 `course_code` 强制指定，例如 `BUSS6002`，不传时会从课程 title/slug 自动提取类似 `BUSS6002` 的代码；如不想展示课程代码，可传 `show_course_code: false`。

### 课程购买项管理

| 工具 | 说明 |
|------|------|
| `bypass_list_course_items` | 列出课程下所有购买项 |
| `bypass_create_course_item` | 创建购买项（价格单位：澳分，content_url 为交付链接，用户购买后以醒目的外链入口打开） |
| `bypass_update_course_item` | 更新购买项，仅更新传入的字段 |
| `bypass_delete_course_item` | 删除购买项 |

### 作业评改要求管理

作业评改要求是 assignment spec / rubric / marking criteria，用于前台作业评改选择器和作业评改接口。它不进入课程 AI 知识库检索，也不控制 AI 聊天授权；普通课程资料请上传到知识库。

| 工具 | 说明 |
|------|------|
| `bypass_list_homework_requirements` | 列出课程下的作业评改要求，支持 active/inactive 筛选 |
| `bypass_get_homework_requirement` | 获取单个作业评改要求 |
| `bypass_create_homework_requirement` | 直接用作业要求/评分标准文本创建作业评改要求 |
| `bypass_update_homework_requirement` | 更新作业评改要求 |
| `bypass_delete_homework_requirement` | 删除作业评改要求 |
| `bypass_upload_homework_requirement` | 上传一个或多个本地 assignment spec/rubric 文件，由平台抽取文本后创建作业评改要求；多文件用 `file_paths`，会合并为同一条要求 |
| `bypass_replace_homework_requirement_file` | 用一个或多个新的本地文件替换已有作业要求，平台重新抽取文本并更新同一条记录；多文件用 `file_paths` |
| `bypass_append_homework_requirement_files` | 给已有作业要求追加一个或多个本地文件，保留原要求正文；适合给同一个 A2/A3 阶段后续补 spec/rubric/report/presentation 等文件 |

`bypass_upload_homework_requirement` 兼容旧的单文件参数 `file_path`。如果一份作业要求由 spec、rubric、截图等多个文件组成，应传 `file_paths: ["/abs/spec.pdf", "/abs/rubric.pdf"]`，不要循环调用多次；循环调用会创建多条作业要求。
如果后续要给已有的 A3 要求补文件，应先用 `bypass_list_homework_requirements` 找到对应的 `requirement_id`，再调用 `bypass_append_homework_requirement_files`。

### 文章管理

| 工具 | 说明 |
|------|------|
| `bypass_list_articles` | 列出文章，支持 status/category/search 筛选 + 分页 |
| `bypass_get_article` | 按 ID 获取单篇文章 |
| `bypass_create_article` | 创建文章 |
| `bypass_update_article` | 更新文章，仅更新传入的字段 |
| `bypass_delete_article` | 删除文章 |

### 用户与学员

| 工具 | 说明 |
|------|------|
| `bypass_list_users` | 列出注册用户，支持 search 筛选 + 分页 |
| `bypass_list_students` | 列出学员课程记录（含用户和课程详情），支持搜索 |

### 订单

| 工具 | 说明 |
|------|------|
| `bypass_list_orders` | 列出订单（含用户、课程/服务、支付渠道、实收金额、支付宝/微信/Stripe 交易号），支持 status/service/provider/search 筛选 |

### 余额与提现

| 工具 | 说明 |
|------|------|
| `bypass_list_commission_balances` | 列出统一余额（折扣码佣金、拉新佣金、余额 token 兑换额合并） |
| `bypass_list_withdrawals` | 列出提现/购课抵扣/AI 额度抵扣记录 |
| `bypass_process_withdrawal` | 审核提现申请 |
| `bypass_create_balance_token` | 生成一次性余额兑换 token，可指定金额（单位：分），返回用户兑换链接 |

### 统计与学院

| 工具 | 说明 |
|------|------|
| `bypass_get_stats` | 获取平台聚合统计（用户数、课程数、收入、文章数、学员数等） |
| `bypass_list_categories` | 列出所有课程学院 |

### 知识库与历史文档迁移

知识库是普通课程 AI 助手的检索资料库，用于 lecture notes、tutorial、readings、历史资料等课程问答材料。它会进入 Cloudflare Vectorize 并通过知识库授权控制学生 AI 聊天访问；不要把“作业评改要用的 assignment spec/rubric”只上传到这里，作业评改要求应使用 `bypass_upload_homework_requirement` / `bypass_create_homework_requirement`。

| 工具 | 说明 |
|------|------|
| `bypass_list_knowledge_bases` | 列出知识库，支持 status/search 筛选 |
| `bypass_get_knowledge_base` | 获取知识库详情和文档数量 |
| `bypass_create_knowledge_base` | 创建 Cloudflare-backed 知识库 |
| `bypass_update_knowledge_base` | 更新知识库名称、描述或状态 |
| `bypass_delete_knowledge_base` | 软删除知识库 |
| `bypass_list_kb_documents` | 列出知识库文档 |
| `bypass_upload_kb_document` | 上传单个普通课程资料文件到知识库，供 AI 聊天检索 |
| `bypass_upload_kb_documents` | 批量上传普通课程资料文件路径数组，适合历史资料分批迁移 |
| `bypass_upload_kb_directory` | 扫描本地目录并上传匹配的普通课程资料，支持 recursive/dry_run/max_files/batch_size |
| `bypass_upload_kb_document_from_url` | 从 HTTP(S) URL 拉取普通课程资料并上传到知识库 |
| `bypass_replace_kb_document` | 用本地文件替换已有知识库文档，删除旧 Vectorize chunks 后重建向量 |
| `bypass_delete_kb_document` | 删除知识库文档，并删除关联 Vectorize chunks |

知识库文档上传会调用 Admin API，再由 `ai-knowledge-service` 使用 Cloudflare Workers AI 抽取文本、`@cf/baai/bge-m3` 生成 embedding，并写入 Cloudflare Vectorize。支持格式：`md`、`txt`、`pdf`、`doc`、`docx`、`csv`、`xls`、`xlsx`、`ppt`、`pptx`，单文件最大 50MB。

目录迁移建议先 dry-run：

```json
{
  "kb_id": 1,
  "directory_path": "/absolute/path/to/legacy-docs",
  "recursive": true,
  "dry_run": true
}
```

确认文件列表后再执行上传：

```json
{
  "kb_id": 1,
  "directory_path": "/absolute/path/to/legacy-docs",
  "recursive": true,
  "batch_size": 10,
  "max_files": 200
}
```

## 技术细节

- 传输方式：stdio
- 数据访问：通过 Admin REST API (`/api/v1/*`)，使用 API Token 认证
- 所有列表接口支持 `limit` + `offset` 分页，返回 `total` / `has_more` 元数据

## License

MIT