Douyin Engagement MCP

本地运行的标准 MCP Server，用于在用户明确批准评论池后，执行抖音关键词搜索与评论活动。所有评论发送都发生在用户本人登录的专用 Chrome 中，并受人工审批与验证流程约束。

核心特性

• 人工审批工作流：评论池必须由用户一次性确认（userConfirmed: true）后才能签发有时效的批准 ID，活动方可启动。
• 关键词搜索真实视频：基于抖音搜索结果筛选通过相关性检查的视频候选。
• 跨活动去重：每次评论成功后，视频会被记入本地去重清单；后续活动自动跳过这些视频，不会重复评论同一视频。可通过 douyin_list_commented_videos 查看已评论清单。
• 活动结束自动关闭浏览器：活动正常完成、被停止或因失败结束时，自动关闭 Chrome 释放进程；仅当进入「等待人工验证」状态时保留浏览器供用户操作。
• 验证暂停：检测到短信、滑块、扫码或登录验证时，活动变为 waiting_for_verification 并保留浏览器与原进度；用户完成验证后调用 douyin_resume_campaign 从原进度继续。
• 安全边界：仅使用用户本人在专用 Chrome 中建立的登录态，不读取或导出 Cookie / 密码 / 验证码，验证码只允许用户在浏览器中手动输入。

工作流

1. douyin_check_login 打开专用 Chrome 并检查登录状态。
2. douyin_prepare_comment_brief 获取真实搜索样本与评论生成简报。
3. 客户端中的 AI 根据用户给定的方向预制 3–5 条评论。
4. 用户查看并一次性确认完整评论池。
5. douyin_approve_comment_pool 携带 userConfirmed: true，签发有时效的批准 ID（默认 30 分钟过期）。
6. 用户确认本次评论数量与间隔后，调用 douyin_start_campaign。
7. douyin_get_campaign_status 查看逐条评论与发布验证结果。
8. 检测到验证需求时，活动变为 waiting_for_verification 并保持浏览器与进度；用户在 Chrome 中完成验证后告知 AI，由 AI 调用 douyin_resume_campaign 继续。
9. MCP 先核对当前评论是否已发布，再从原视频、原评论与去重进度继续。

评论从已批准池随机抽取，一轮用完前不重复；搜索异常、视频不相关或评论无法验证时会停止活动。

douyin_start_campaign 可传入 excludeVideoUrls 手动追加排除视频；跨活动去重在此基础上自动叠加，无需每次手动维护。

安装

需要 Node.js 20+ 与 Google Chrome。

npm install
npm run build

首次使用先初始化登录状态：

npm run login

程序会打开专用 Chrome 并等待登录；请自行扫码登录抖音，检测成功后登录状态保存在本地专用资料目录（不会上传任何凭证）。

客户端配置（stdio）

将路径替换为本机实际项目目录的绝对路径：

{
  "mcpServers": {
    "douyin-engagement": {
      "command": "node",
      "args": [
        "<PROJECT_DIR>/dist/src/index.js"
      ],
      "cwd": "<PROJECT_DIR>"
    }
  }
}

只要客户端支持本地 stdio MCP，均可使用同一结构。部分客户端使用 servers 而非 mcpServers 作为顶层字段，请以该客户端说明为准。

环境变量

• DOUYIN_MCP_CHROME_PATH：Chrome 可执行文件路径；常规安装通常无需设置。
• DOUYIN_MCP_RUNTIME_DIR：Chrome 资料、活动状态与审计日志目录，默认 <PROJECT_DIR>/.runtime。
• DOUYIN_MCP_ARTIFACT_DIR：评论前后截图目录，默认 <PROJECT_DIR>/artifacts。

安全边界

• 只使用用户本人在专用 Chrome 中建立的登录状态。
• 不读取或导出 Cookie、密码和短信验证码。
• 验证码只允许用户在 Chrome 中输入；MCP 工具不接受验证码参数。
• 不尝试破解验证码或绕过安全验证。
• 评论池批准默认 30 分钟过期；活动创建后保存已批准评论快照，以便验证完成后恢复原活动。
• 等待验证时保留候选列表、当前视频、评论顺序、成功记录与去重进度，且不会关闭浏览器。
• 提交后找不到完整评论文本时，不计成功并停止后续活动。
• 默认单次最多 20 条，评论间隔最少 30 秒。
• 活动正常结束（完成 / 停止 / 失败）后自动关闭浏览器释放资源；仅验证等待期间保持打开。

开发验证

npm run check
npm test
npm run build

单元测试覆盖 blocker 识别、评论池、相关性评分与活动恢复逻辑。真实评论属于外部副作用，不包含在自动测试中；首次真实测试建议只设置 1 条评论，并在页面中人工复核。