# byerisk-mcp

把 [ByeRisk](https://www.byerisk.com) 的内容合规检测接进任何支持 MCP 的 AI 助手 —— 腾讯 WorkBuddy、Claude Code、Cursor 等。

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

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

---

## 快速开始

### 1. 拿一把 API Key

登录 [www.byerisk.com](https://www.byerisk.com) → 控制台 → 开放 API → 创建 API Key，形如 `brsk_live_…`。

### 2. 配置到你的 AI 助手

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

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

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

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

**Claude Code**：

```bash
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 计。正常使用碰不到。

---

## 开发

```bash
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 变了就刷新快照，测试会指出哪些字段对不上：

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

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

```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