头条号 MCP & HTTP 自动化运营服务端 (Toutiao MCP Server)

基于 Model Context Protocol (MCP) 与 Go 语言实现的头条号创作者后台自动化运营工具包。支持作为标准 MCP 服务端直接接入 AI 客户端（如 Cursor、DeepSeek、Claude Desktop、Claude Code），同时也暴露了标准的 RESTful HTTP 接口，实现自媒体发文、数据分析与内容管理的自动化。

---

🚀 核心特性

• 双通道服务架构：同一端口（默认 8080）下，同时提供符合标准 MCP 协议的 JSON-RPC 路由（/mcp）与面向传统 Webhooks 的 RESTful HTTP API。同时支持标准 Stdio 管道启动方式无缝集成 Cursor/Claude Desktop。
• 微头条全量历史抓取：支持获取真实的微头条历史列表。底层自动对接前端实际使用的 Feed 流接口 /api/feed/mp_provider/v1/，传入 category=mp_wtt、offset_mode=2 并按响应 offset 翻页；再合并 /mp/agw/statistic/v2/item/list?type=3 返回的统计指标，规避作品管理接口游标卡死和统计接口数量不全的问题。
• 极速 HTTP 运营分析与降级兜底：
  • 数据概览和统计报告优先采用纯 HTTP 极速提取模式（耗时从 10s 降低到 200ms）。通过 /home/merge_v2 瞬间获取粉丝量、总阅读和累计收益；通过 Feed 流接口拉取前 100 篇内容并在内存中累加计算点赞和转发总数。
  • 趋势拉取固定使用全局过滤器 type=0，保障粉丝变化及各指标趋势与官方后台完美对应。
  • 自动保留了高容错的无头浏览器 DOM 抓取作为优雅降级兜底防线。
• 文章在线二次修改与安全测试沙盒：支持对已发布或草稿状态的文章进行无残留二次修改。新支持 SaveAsDraft 选项（仅保存草稿不发布），支持纯草稿箱安全测试，测试数据不污染真实主页，且测试完毕后能通过浏览器物理清除。智能跳过非必要封面重传以防超时；引入 React onChange 底层强力驱动与 3s 延迟平息期以彻底防止 React 异步重绘回滚；在最终发布前执行“一致性二次固化校验与强行覆盖”，保证提交数据 100% 固化；物理兼容“发布”确认弹窗。
• 文章全量历史混合抓取与去重：解除头条原接口对已发布文章仅展示最近 3 篇的封锁。对于 all / published 状态的文章采用双通道混合拉取：先调用列表 API 拿草稿，再通过 Feed 接口拉取历史文章，并在内存中根据 ID 与非空标题进行双重去重合并，防止重复项冗余堆叠。
• 字段命名别名规范化统一：彻底翻译并屏蔽了头条原始接口中晦涩难懂的字段名（如 go_detail_count_v2、digg_count），对外统一暴露标准的 read_count、view_count、like_count、impression_count、ctr 等规范字段别名。
• 真实评论读取与可验证回复：评论列表优先读取头条评论管理页实际使用的接口，稳定返回真实 comment_id、文章 ID、用户名、正文、时间和 reply_count；回复操作通过浏览器物理完成，并在提交后以真实接口中的回复数增长作为成功条件，避免“按钮点过但实际未发布”的假成功。
• 登录态自愈机制：支持本地 cookies.json 的自动装载与生命周期管理。若会话过期，程序会在有头模式下自动弹窗等待扫码登录，登录成功后自动更新并捕获凭证回写。
• Markdown 智能排版引擎：
  • 自动将正文解析分割为文本块与图片块，由浏览器控制完成图文交替混排。
  • 支持运行时相对图片路径（如 ./testdata/test.png）的自动解析与 Chrome 绝对路径转换上传。
  • 正文插图与封面图统一通过 Chrome 原生文件选择器上传，规避隐藏 file input 直写导致的“无效图片数据”问题。
  • 具备排版格式符强力清洗，自动滤除正文残留的 Markdown 标记符号。
• 合规合规合规：支持在发文设置中，自动物理点击并勾选“取材网络，虚构演绎”的作品声明，降低封禁风险。

---

🛠️ 技术栈与依赖前置

---

⚙️ 快速开始

1. 项目编译

go build -o toutiaohao-server .

2. 启动服务

# 启动混合服务（默认监听 8080 端口，包含 MCP 路由及 HTTP 接口）
./toutiaohao-server

# 以标准 Stdio 管道传输模式运行 (专供 AI 本地集成)
./toutiaohao-server -stdio

# 指定自定义端口启动混合服务
./toutiaohao-server -port 9000

3. 初始化登录态 (Cookie)

1. 首次启动服务并调用发文或查询功能时，若本地 cookies.json 不存在，程序会自动弹出一个 Chrome 浏览器窗口。
2. 请在弹出的浏览器中手动进行扫码登录或短信登录。
3. 登录成功后，终端将输出 检测到登录成功！，程序会在后台自动捕获最新的 Session Cookie 并保存为项目根目录下的 cookies.json。
4. 后续调用将全部转为无头（Headless）静默运行，无需人工干预。

---

🤖 AI 协同与 MCP 配置

为了使 AI 客户端（如 Cursor、Claude Desktop）更高效、稳定地集成，建议使用本地无端口占用的 Stdio 管道传输模式（添加 -stdio 参数）。这能避免本地端口占用与冲突，且比 HTTP/SSE 传输方式具有更高的响应速度。

1. Cursor 配置

在 Cursor 中打开 Settings -> Features -> MCP，添加一个新的 MCP 服务：

• Name: toutiao
• Type: command
• Command: /path/to/your/toutiaohao-server -stdio

2. Claude Desktop 配置

编辑您的 config.json（通常在 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "toutiao-mcp": {
      "command": "/path/to/your/toutiaohao-server",
      "args": ["-stdio"]
    }
  }
}

[!TIP] 本项目已针对 AI 工具进行全方位的 AI-Friendly 深度优化。项目根目录下的 AGENTS.md 包含 AI 进行开发时的详细设计心智和约束规范。

---

🔗 HTTP 接口列表 (REST API)

---

📂 项目结构

toutiaohao-mcp-server/
├── main.go                 # 服务主入口
├── app_server.go           # 混合服务器引擎（聚合路由、MCP 与 HTTP Server）
├── mcp_server.go           # MCP Protocol 服务端初始化与 Tools 映射注册
├── mcp_handlers.go         # MCP 工具的具体分发处理器（参数校验与业务调度）
├── handlers_api.go         # REST API 接口的具体处理器
├── routes.go               # Gin HTTP 路由注册表
├── middleware.go           # 跨域 (CORS) 过滤与全局 Panic 拦截中间件
├── service.go              # 核心业务服务层（抽象调用底层自动化组件）
├── types.go                # 全局通用业务数据结构定义
├── configs/                # 静态配置模块
│   ├── urls.go             # 头条号各种导航页面 URL 与 API 接口端点
│   ├── content.go          # 头条号文章字数、图片大小限制
│   └── browser.go          # 浏览器性能限流及 Chrome 路径配置
├── cookies/                # 凭证存储与读取模块
│   └── cookies.go          # Cookier 接口及本地文件 FileCookieStore 实现
├── browser/                # 浏览器控制封装模块
│   └── browser.go          # go-rod 浏览器实例初始化及 Cookie 注入
└── toutiaohao/                # 【核心业务组件】
    ├── login.go            # 扫码登录、状态轮询与 Cookie 自动保存
    ├── dom.go              # 高容错 DOM 寻址、页面平滑滚动与障碍物清除
    ├── selectors.go        # 头条号创作者平台各个按钮/输入框的 CSS 选择器
    ├── publish_article.go  # 发图文（Markdown 解析、图片自动上传排版、虚构声明勾选）
    ├── publish_micro.go    # 发布微头条
    ├── draft_micro.go      # 保存微头条草稿
    ├── comments.go         # 评论列表抓取与回复评论
    ├── article_list.go     # 内容列表拉取与管理
    └── analytics.go        # 创作者运营数据面板解析与抓取

---

🧪 自动化测试与验证

1. 静态编译自检

go build ./...

2. 自动化图文发文集成测试

测试需要本地存在有效的 cookies.json（需要先启动服务扫码登录一次生成）。

在测试时，程序会准备临时测试图片，验证封面上传、定时发布弹窗和草稿保存路径。图片净化后的中转文件统一写入项目根目录 .tmp/：

cd toutiaohao
go test -v -run TestPublishArticleManual

3. 正文插图上传专项测试

此测试专门覆盖 Markdown 正文中的 ![图片](path) 插图路径，确保浏览器通过 Chrome 原生文件选择器接收文件，并且图片上传确认弹窗能正常关闭：

cd toutiaohao
go test -v -run TestPublishArticleBodyImageManual

预期日志中应出现：

Chrome 文件选择器已接收文件
正文图片上传确认弹窗已成功关闭

4. 自动化修改文章集成测试 (安全沙盒闭环)

此测试自动开展“发布临时新文章 -> 从文章列表提取新文章 ID -> 物理修改新文章 -> 自动删除临时新文章”的闭环测试，确保高容错性且不损耗线上老文章的宝贵修改额度，无任何脏数据残留：

cd toutiaohao
go test -v -run TestUpdateArticleManual

5. 自动化微头条全量列表与统计合并测试

此测试专门覆盖微头条 Feed 全量抓取与统计指标合并逻辑，输出总数和相应的 CTR、展现量、阅读数、评论数、点赞量等：

cd toutiaohao
go test -v -run TestGetMicroPostsManual

6. 数据分析趋势与详情测试

此测试专门覆盖近 N 天账户变动趋势以及文章具体草稿/发布详情获取：

cd toutiaohao
go test -v -run "TestGetAccountTrendsManual|TestGetArticleDetailManual"

图片上传实现约定

• 所有本地/下载/净化后的临时图片必须生成在项目根目录 .tmp/ 下。
• 正文插图和封面图上传必须使用 go-rod HandleFileDialog() 拦截 Chrome 原生文件选择器，再物理点击当前可见上传弹窗里的“本地上传”按钮。封面槽可能直接触发文件选择器，因此封面上传会先注册文件选择器拦截，再点击封面槽；若页面弹出上传面板，再继续点击面板里的“本地上传”。
• 图文文章封面来源优先级为：cover_image > 显式传入的 images > 正文 Markdown 内嵌图自适应。调用方传 1 张 images 时使用单图封面，传 3 张及以上时使用三图封面。
• 头条可能从正文插图自动同步封面。若点击封面槽后没有出现“本地上传”面板，服务会复核目标 .article-cover-img-wrap；槽位已经存在真实图片时直接采用平台同步结果，不再误报上传失败。预览按钮和空槽加号图标不会被当作有效封面。
• 不要直接对隐藏的 input[type=file] 调用 SetFiles。该方式可能产生本地 blob 预览，但服务端实际收到约 210 字节的损坏请求体，最终显示“无效图片数据”。
• /spice/image、upload_source= 和 multipart/form-data 图片上传请求必须绕过 HijackRequests 的 LoadResponse 代理，直接 ContinueRequest 原样放行。
• 如果图片确认弹窗没有关闭，应保存错误截图并返回错误，避免缺图内容继续发布。

标题校验与失败草稿保护

• 图文标题最多 30 个头条加权字符：ASCII 英文字母和数字按 0.5 计，空白不计，中文及标点等其他字符按 1 计。标题超限时服务会直接返回可读错误，要求调用方重新生成或缩短标题，不会自动截断破坏语义。
• 发布过程中若正文、插图、封面或最终提交失败，服务会保留头条后台可能已经自动保存的草稿，并在错误信息中提示前往草稿箱检查。
• 普通发布失败不会自动调用删除接口。只有用户显式调用删除功能，或集成测试清理其自身创建的临时数据时，才会删除草稿。
• 点击“预览并发布”进入预览页不代表发布完成；服务会继续点击预览页中的“发布/确认发布”，仅在跳转到明确管理页或出现成功提示后返回成功。

草稿删除实现约定

• 删除接口会先调用头条 HTTP 删除 API，但不信任仅返回 success 的结果；必须重新查询列表确认文章消失。
• 草稿删除失败时会回退到浏览器自动化：用 rodBrowser.MustPage("https://mp.toutiao.com/profile_v4/graphic/articles?status=draft") 一步到位打开草稿列表，注入 Cookie 后 Reload()，然后在当前页面定位标题/ID 匹配的草稿卡片。
• 不要创建空白页后再 page.Navigate() 到草稿箱；该两步式导航可能导致 SPA 数据请求未携带 Cookie，表现为 URL 正确但列表卡片为空。
• URL 中的 status=draft 或 status=1 只作为初始导航辅助，不能用来判断草稿箱 Tab 是否已选中。删除前必须读取页面 DOM 中“草稿箱”Tab 的 active / selected / aria-selected 状态；如果未选中，需要先点击草稿箱 Tab 并等待卡片重新渲染。
• 草稿删除不依赖“更多”菜单或编辑页删除按钮；应勾选目标草稿行的真实复选框，再点击批量操作栏中的“删除”，最后处理确认弹窗。
• 复选框、批量删除按钮和确认按钮都必须只点击真实可见的小按钮本体，不要点击 .pgc-content 等外层容器。点击前需滚入视口中心，并使用 rod 鼠标坐标物理点击。
• 若仍失败，会保存 screenshot_delete_draft_not_found.png、screenshot_delete_draft_checkbox_error.png、screenshot_delete_draft_batch_error.png 或 screenshot_delete_draft_confirm_error.png 以便分析。

评论回复实现约定

• MCP 工具 get_comments 用于读取评论列表，可传 article_id、keyword、page_size；reply_comment 用于回复评论。
• get_comments 优先调用评论管理页真实使用的 /comment/author_receive_comment/ 接口，并按游标继续翻页；DOM 抓取只作为接口失败时的兜底。每条结果均返回真实 comment_id、article_id、user_name、content、create_time 和 reply_count。
• reply_comment 必须提供 reply_content，并且 comment_id 与 comment_text 至少提供一个。推荐优先传 comment_id；服务会先从真实接口补齐评论正文，再通过浏览器定位目标卡片。
• 回复内容采用 go-rod 物理键入，并校验输入值和“发布”按钮状态。点击提交后会轮询真实接口，只有目标评论的 reply_count 增长后才返回 success: true，同时返回 reply_count_before 与 reply_count_after。
• 回复失败时会保存 screenshot_comment_page_error.png、screenshot_comment_reply_not_found.png、screenshot_comment_reply_fill_error.png、screenshot_comment_reply_submit_error.png 或 screenshot_comment_reply_verify_error.png 辅助分析。

评论列表响应中的核心字段示例：

{
  "comment_id": "7655725926924206911",
  "article_id": "7655556701420061184",
  "user_name": "示例用户",
  "content": "评论正文",
  "reply_count": 1
}

---

📄 开源许可证

本项目基于 MIT License 许可证开源。请在使用时注意凭证文件的安全性，严禁将包含敏感会话 Token 的 cookies.json 上传至任何公共代码仓库中。