@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：

{
  "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 或全局配置：

{
  "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：

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

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

{
  "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