byerisk-mcp

把 ByeRisk 的内容合规检测接进任何支持 MCP 的 AI 助手 —— 腾讯 WorkBuddy、Claude Code、Cursor 等。

写完一条口播稿、剪完一支投放视频，直接在助手里说「查一下这段能不能发」，就能拿到分档的风险明细：必须修改（违法或违反平台硬性规则）与影响推流（能发但会降权），每条带命中片段、法条依据和修改建议。

底层是 ByeRisk 开放 API（/v1），与网页控制台同一套检测引擎、同一个积分池 —— 不是第二套系统，是同一套系统的另一个入口。

---

快速开始

1. 拿一把 API Key

登录 www.byerisk.com → 控制台 → 开放 API → 创建 API Key，形如 brsk_live_…。

2. 配置到你的 AI 助手

请使用 0.1.1 及以上版本。0.1.0 已弃用：它的 fix_text 会一直等到超时拿不到结果 （当时按 spec 描述以为修复是「按版本递增追加」，实测后端是原地替换，判据不成立）。

腾讯 WorkBuddy —— 侧边栏 → 插件 → MCP Server → 配置 MCP，粘贴：

{
  "mcpServers": {
    "byerisk": {
      "command": "npx",
      "args": ["-y", "byerisk-mcp"],
      "env": {
        "BYERISK_API_KEY": "brsk_live_你的key"
      }
    }
  }
}

也可以直接写进 ~/.workbuddy/mcp.json（用户级，所有项目共享）或 <项目>/.workbuddy/mcp.json（仅当前项目）。

Claude Code：

claude mcp add byerisk -e BYERISK_API_KEY=brsk_live_你的key -- npx -y byerisk-mcp

其他 MCP 客户端：任何支持 stdio 传输的客户端都一样 —— 命令 npx -y byerisk-mcp，环境变量里给 BYERISK_API_KEY。

3. 用起来

直接对助手说人话即可：

• 「帮我检查这段口播稿在抖音发有没有违规」
• 「这张主图能投信息流吗」
• 「桌面上那个 demo.mp4 检测一下，是短剧，发红果」
• 「刚才那段文案帮我改成合规的」

---

工具清单

工具	作用	是否扣积分
check_text	文案合规检测。提交后自动等结果，直接返回分档风险明细	是
fix_text	对一次检测结果做 AI 合规改写（整篇重写 / 精准替换）	是
check_image	图片检测：广告违规、违规文字（OCR）、涉政、暴力、色情、侵权 Logo	是
check_video	视频检测：画面 + 音频 + 口播话术，返回带时间点的明细	是（按秒）
get_check_result	按 id 取已提交检测的结果，用于等待超时或回看历史	否
get_account	查积分余额、订阅状态、本月用量	否

这里刻意没有把开放 API 的 20 个端点一一映射成工具。/v1 是「POST 提交 → 拿 id → GET 轮询」的异步契约，直接摊给模型，它要么提交完忘了轮询，要么重复提交（每次都扣积分）。所以 check_* 把提交和等待合并成一个动作，只有真等超时才把 id 交回去，再由 get_check_result 兜底。

本机文件可以直接传

check_image / check_video 的入参既接受公网直链，也接受本机文件绝对路径。传路径时会自动走 ByeRisk 签发的 OSS 直传凭证上传，文件不经过 ByeRisk 服务器。

桌面 agent 场景下用户的素材基本都在本机，没有这一步这两个工具约等于不可用。

视频时长（durationSeconds）是计费依据 —— 标准模式 1 积分/秒，且后端会用实际抽帧时间点对账，申报明显短于实际的差额会自动补扣。所以：

• mp4 / mov：自动从 moov → mvhd 解析，不需要装 ffmpeg。
• 其他容器：尝试 ffprobe（装了才有）。
• 都拿不到：直接报错要求显式传 durationSeconds，绝不猜一个值出来。

---

配置项

环境变量	必填	默认	说明
BYERISK_API_KEY	是	—	控制台创建的 API Key，brsk_live_…
BYERISK_BASE_URL	否	https://www.byerisk.com/api	自建或测试环境时改这里
BYERISK_END_TENANT	否	—	子租户号。见下

子租户

如果你在自己的产品里集成 ByeRisk、又要给自己的每个客户做数据隔离，给 BYERISK_END_TENANT 填上你系统里的租户号即可：该租户的自定义违禁词与检测历史会隔离在独立的域中，积分和订阅仍统一算在这把 Key 所属的账户上。取值限 1–64 位的字母、数字、_ . : -，首次出现自动创建。

---

几个要知道的前提

• 积分是共用的：网页控制台、小程序、开放 API、这个 MCP server 共用同一个积分池。余额不足会返回 402，用 get_account 能确认余额。
• 产品线不是都开放：图片检测只支持 creator（短视频）和 touliu（投放），短剧没有图片检测；视频检测只有标准模式。
• 平台要填对：各平台的尺度差异很大，platform 决定命中哪套规则集。短剧场景通常填 hongguo（红果）。
• 广告场景记得声明：投放素材把 sceneMode 设为 ad，场景类提示就不再计为违规，否则会多出一堆无关告警。
• 限流：提交类 60 次/分钟、读取类 600 次/分钟，按 API Key 计。正常使用碰不到。

---

开发

npm install
npm run build      # tsc → dist/
npm test           # 契约测试 + 二进制解析回归测试
npm run type-check

spec/openapi.json 是开放 API 的 spec 快照，契约测试拿它核对 src/types.ts 里的字段名和 src/tools.ts 里的枚举值。手写类型最容易出的错是字段名笔误 —— TypeScript 不报错，只会让某个功能静默失效。生产 spec 变了就刷新快照，测试会指出哪些字段对不上：

curl -s https://www.byerisk.com/api/v1/openapi.json -o spec/openapi.json

本地调试可以直接用编译产物：

{
  "mcpServers": {
    "byerisk": {
      "command": "node",
      "args": ["/绝对路径/byerisk-mcp/dist/index.js"],
      "env": { "BYERISK_API_KEY": "brsk_live_…" }
    }
  }
}

stdio 传输下 stdout 是 JSON-RPC 通道，改代码时注意所有日志必须走 stderr，否则会破坏协议。

相关

• 开放 API 文档：https://www.byerisk.com/developers
• 机器可读 spec：https://www.byerisk.com/api/v1/openapi.json

License

MIT