SkillAgentSearch skills...

XiaoHongShuMCP

No description available

GenerateConvertImprove

Install / Use

/learn @mook-wenyu/XiaoHongShuMCP
About this skill

Quality Score

0/100

Supported Platforms

Claude Code
Cursor

README

HushOps.Servers.XiaoHongShu — 自动化浏览/MCP 服务

Node TypeScript Playwright MCP License

面向“小红书（Little Red Book）”相关业务的人机浏览自动化与 MCP 服务。以 RoxyBrowser 提供的多账号隔离（持久化 Context）为基础，通过 Playwright CDP 接入实现稳定、最小的原子动作工具面；截图、快照与选择器健康数据统一沉淀到 artifacts/<dirId> 便于离线验证与审计。

快速开始（TL;DR）

  • 做什么：提供稳定的原子浏览动作（打开/导航/点击/输入/截图/快照）与小红书专用采集工具面，支持多账号隔离。
  • 为什么有用：最小依赖、MCP 标准工具、可离线验证的工件沉淀，便于在任意编排器中组合业务流程。
  • 如何使用：准备 Node 环境与 Roxy API Token，安装依赖并启动 stdio MCP，或直接运行示例脚本。
# 1) 安装依赖
npm install

# 2) 准备环境变量（至少设置 ROXY_API_TOKEN 与 Roxy 连接）
Copy-Item .env.example .env
# 编辑 .env，填写 ROXY_API_TOKEN，设置 ROXY_API_BASEURL 或 ROXY_API_HOST/PORT

# 3) 预检（环境/官方桥接/Playwright 模块）
npm run preflight

# 4) 启动 stdio MCP（供客户端连接）
npm run mcp

# 5) 运行示例（打开并截图）
npm run run:example -- --dir-ids=user --url=https://example.com --limit=2

更多命令、环境变量与工具清单见文档下方章节与 AGENTS.md。

目录

能力总览

  • 多账号隔离：dirId 表示账号窗口；1 个 dirId = 1 个持久化 BrowserContext；同 Context 可创建多 Page。
  • 原子化工具（前缀+下划线命名）：browser_*、page_*、xhs_*、resources_*。
  • Roxy 管理工具（仅用于管理）：roxy_*（工作区/窗口管理）默认注册，无需开关。
  • 选择器韧性与拟人化：语义优先选择器（role/name/label/testId/text）→ CSS 兜底；人类化鼠标与输入（可按参数关闭）。
  • 工件真源：截图、快照与选择器健康日志统一落盘 artifacts/<dirId>，支持 MCP 资源读取。

环境要求

  • Node.js >= 18（建议 22.x）
  • 可用的 RoxyBrowser 本地/远程 API 与有效 ROXY_API_TOKEN
  • 首次安装通过 postinstall 自动安装 Playwright Chromium

关键环境变量：

  • ROXY_API_TOKEN（必填）
  • ROXY_API_BASEURL 或 ROXY_API_HOST + ROXY_API_PORT
  • ROXY_DEFAULT_WORKSPACE_ID（可选，用于默认上下文）
  • SNAPSHOT_MAX_NODES（页面快照节点上限，默认 800）
  • HUMAN_PROFILE（default/cautious/rapid），决定鼠标/滚动/输入节律的默认值
  • HUMAN_TRACE_LOG（可选，设为 true 将拟人化事件落盘到 artifacts/<dirId>/human-trace.ndjson）

完整环境变量列表请参考 .env.example，包括：

  • 连接配置: ROXY_API_*, ROXY_DEFAULT_WORKSPACE_ID, ROXY_DIR_IDS
  • 并发与超时: MAX_CONCURRENCY, TIMEOUT_MS
  • 选择器韧性: SELECTOR_RETRY_*, SELECTOR_BREAKER_*
  • 小红书配置: XHS_SCROLL_*, XHS_SELECT_MAX_SCROLLS, DEFAULT_URL
  • 日志: LOG_LEVEL, LOG_PRETTY, MCP_LOG_STDERR
  • 拟人化: HUMAN_PROFILE, HUMAN_TRACE_LOG

说明：

  • ENABLE_ROXY_ADMIN_TOOLS（自 0.2.x 起 roxy_* 管理工具默认注册，无需开关）
  • 断路器相关参数以 SELECTOR_BREAKER_* 为主；POLICY_* 作为全局策略限流/熔断兼容项仍保留（见 .env.example 注释），两者用途不同。

安装与最小自检

  1. 安装依赖
npm install
  1. 配置环境变量
Copy-Item .env.example .env
# 编辑 .env，填写 ROXY_API_TOKEN，设置 ROXY_API_BASEURL 或 HOST/PORT
  1. 预检（可选）
npm run preflight
  1. 自检脚本（可选）
npm run check:env
  1. 工具面对照检查（可选）
npm run check:tools
  1. 编码巡检（可选，CI 推荐）
npm run check:encoding

启动与集成（stdio MCP）

  1. 构建（或直接 TS 运行）
npm run build
  1. 启动 MCP Server（stdio）
npm run mcp

MCP 工具清单（唯一标准）

浏览器与页面管理

  • browser_open / browser_close - 打开/关闭浏览器窗口（dirId 映射持久化 Context）
  • page_create / page_list / page_close - 创建/列出/关闭页面
  • page_navigate - 导航到指定 URL

页面交互（支持拟人化）

  • page_click - 点击元素（支持语义定位：role/name/label/text/testId/selector）
  • page_hover - 悬停元素
  • page_scroll - 滚动页面（支持相对/绝对/元素滚动）
  • page_type - 输入文本（支持 WPM 逐字延时）
  • page_input_clear - 清空输入框

页面信息获取

  • page_screenshot - 截图（默认仅返回 path 文本；如需图片数据，传 returnImage=true 附带 image/png）
  • page_snapshot - 可访问性快照（a11y 树 + url/title + 统计信息）

小红书专用

  • xhs_session_check - 检查会话状态（基于 cookies 和首页加载）
  • xhs_navigate_home - 导航到小红书首页并验证
  • xhs_open_context - 确保浏览器上下文已打开，返回页面数量与首个页面 URL（若存在）
  • xhs_note_extract_content - 提取笔记完整内容（标题/正文/标签/互动数据）

提示：xhs_note_extract_content 采用“API→DOM 兜底”的两段式提取。

  • 优先拦截 \/api\/sns\/web\/v1\/feed 获取详情；
  • 当导出链接（如 ?xsec_token=...）未触发 API 时，自动从 DOM 解析 #detail-title、#detail-desc .note-text、a.tag#hash-tag 等；
  • 返回 JSON 会附带 extraction_method=api|dom，便于上游统计命中率（消费方可忽略额外字段）。

小红书快捷工具（语义化）

  • xhs_close_modal - 关闭当前笔记详情模态（Esc→关闭按钮→遮罩）
  • xhs_navigate_discover - 导航到“发现”推荐流（含 homefeed 接口软校验）
  • xhs_search_keyword - 站内搜索关键词（拟人化输入 + 接口软校验）
  • xhs_collect_search_results - 在站内搜索后收集前 N 条笔记结果（优先 API 回执，DOM 兜底）
  • xhs_keyword_browse - 关键词浏览（轻量滚动，提升可见文本覆盖）
  • xhs_select_note - 在当前页（首页/发现/搜索）按关键词匹配卡片并点击，优先点击封面，标题兜底；成功判定为“模态优先，其次 URL 进入详情”，返回 openedPath="modal"|"url"
  • xhs_note_like / xhs_note_unlike - 点赞 / 取消点赞当前笔记（需模态已打开）
  • xhs_note_collect / xhs_note_uncollect - 收藏 / 取消收藏当前笔记（需模态已打开）
  • xhs_user_follow / xhs_user_unfollow - 关注 / 取关当前笔记作者（需模态已打开）
  • xhs_comment_post - 发表评论（拟人化输入 + 接口软校验，需模态已打开）

示例（命令行脚本）：

# 导航到发现页（stdio MCP）
npm run mcp -- --tool xhs_navigate_discover --dirId user

# 站内搜索关键词
npm run mcp:call:search -- --dirId=user --keyword=美食

# 关闭笔记模态（若已打开）
npm run mcp -- --tool xhs_close_modal --dirId user

# 点赞/取关/评论（需笔记详情模态已打开）
npm run mcp -- --tool xhs_note_like --dirId user
npm run mcp -- --tool xhs_user_unfollow --dirId user
npm run mcp -- --tool xhs_comment_post --dirId user --text="写得不错！"

资源管理

  • resources_listArtifacts - 列出 artifacts/<dirId> 下的所有文件
  • resources_readArtifact - 读取 artifacts 文件（自动识别图片/文本）

高权限管理工具（默认已注册）

  • roxy_workspaces_list - 获取工作区列表
  • roxy_windows_list - 获取浏览器窗口列表
  • roxy_window_create - 创建新浏览器窗口

诊断与监控

  • server_capabilities - 查看适配器信息（adapter/roxyBridge/adminTools）
  • server_ping - 连通性检查与心跳

MCP 资源（Resources）

  • xhs://artifacts/{dirId}/index - 列出指定 dirId 的所有 artifacts 文件
  • xhs://snapshot/{dirId}/{page} - 获取指定页面的 a11y 快照

示例（默认开启拟人化；两种方式关闭：human=false 或 human.enabled=false，可按需细化参数）：

  • 打开窗口：browser_open，{"dirId":"user"}
  • 打开上下文：xhs_open_context，{"dirId":"user"} → 返回 {"ok":true,"data":{"opened":true,"pages":1,"url":"https://..."}}
  • 导航：page_navigate，{"dirId":"user","url":"https://example.com"}
  • 语义点击（拟人化）：
    • 快速关闭：{"dirId":"user","target":{"text":"登录"},"human":false}
    • 细化参数：{"dirId":"user","target":{"text":"登录"},"human":{"enabled":true,"steps":24,"randomness":0.2}}
  • 输入（拟人化）：page_type，{"dirId":"user","target":{"role":"textbox","name":"标题"},"text":"今天好开心","human":{"enabled":true,"wpm":180}}
  • 截图：page_screenshot（默认仅返回路径；如需图片数据，传 returnImage=true）
  • 快照：page_snapshot → 返回 url/title/a11y 摘要 + 统计

示例参数（速查）

以下为常用工具的入参与返回片段示例（仅展示关键字段，实际返回含标准包裹结构）。

# 浏览器与页面
browser_open        {"dirId":"user"}
page_create         {"dirId":"user","url":"https://example.com"}
page_list           {"dirId":"user"}
page_close          {"dirId":"user","pageIndex":0}
page_navigate       {"dirId":"user","url":"https://example.com","pageIndex":0}

# 页面交互（语义定位 + 拟人化可选）
page_click          {"dirId":"user","target":{"role":"button","name":"登录"}}
page_click(关闭拟人) {"dirId":"user","target":{"text":"登录"},"human":false}
page_hover          {"dirId":"user","target":{"selector":".menu-item[data-id='settings']"}}
page_type           {"dirId":"user","target":{"role":"textbox","name":"标题"},"text":"今天好开心","human":{"wpm":180}}
page_input_clear    {"dirId":"user","target":{"role":"textbox","name":"搜索"}}
page_scroll         {"dirId":"user","deltaY":1200,"human":{"segments":6,"perSegmentMs":120}}

# 页面信息获取
page_screenshot     {"dirId":"user","fullPage":true,"returnImage":true}
page_snapshot       {"dirId":"user","pageIndex":0,"maxNodes":800}

page_snapshot 返回示例（节选）：

{
  "ok": true,
  "data": {
    "url": "https://example.com",
    "title": "Example",
    "a11y": { "role": "document", "name": "", "children": [/* ...裁剪... */] },
    "stats": { "nodeCount": 801, "roleCounts": {"button": 12}, "landmarks": ["navigation","main"], "clickableCount": 37 }
  }
}

# 小红书（XHS）
xhs_open_context            {"dirId":"user"}
xhs_navigate_home           {"dirId":"user"}
xhs_search_keyword          {"dirId":"user","keyword":"美食"}
xhs_collect_search_results  {"dirId":"user","keyword":"美食","limit":10}
xhs_keyword_browse          {"dirId":"user","keywords":["美食","穿搭"]}
xhs_select_note             {"dirId":"user","keywords":["咖啡","拉花"]}
xhs_comment_post            {"dirId":"user","text":"写得不错！"}
xhs_note_extract_content    {"dirId":"user","noteUrl":"https://www.xiaohongshu.com/explore/xxxxxxxx"}

xhs_note_extract_content 返回示例（节选，含兜底标记）：

{
  "ok": true,
  "data": {
    "note_id": "xxxxxxxx",
    "url": "https://www.xiaohongshu.com/explore/xxxxxxxx",
    "title": "……",
    "content": "……",
    "tags": ["…"],
    "author_nickname": "…",
    "interact_stats": {"likes": 0, "collects": 0, "comments": 0, "shares": 0},
    "extracted_at": "2025-11-10T10:00:00.000Z",
    "extraction_method": "api" | "dom"
  }
}

# 资源管理
resources_listArtifacts     {"dirId":"user"}
resources_readArtifact      {"dirId":"user","path":"test/page-1.png"}

# 管理工具（高权限）
roxy_workspaces_list        {"page_index":1,"page_size":20}
roxy_windows_list           {"workspaceId":"123","dirIds":"user"}
roxy_window_create          {"workspaceId":"123","windowName":"xhs-user","defaultOpenUrl":["https://www.xiaohongshu.com/explore"]}

RoxyBrowser 集成架构

  • 直接通过 RoxyBrowser REST API 获取 CDP WebSocket 端点
  • 使用 Playwright 官方的 chromium.connectOverCDP() 方法连接浏览器
  • 每个 dirId 对应一个持久化 BrowserContext（由 RoxyBrowser 管理）
  • RoxyBrowserManager 负责连接管理、Context 缓存和生命周期控制
  • 能力探针：调用 server_capabilities 可查看 { adapter:"roxyBrowser", version, integration, adminTools }

常用脚本

  • 检查环境：npm run check:env
  • 工具面对照检查：npm run check:tools
  • 选择器健康报告：npm run report:selectors
  • 本地演示：npm run demo:local
  • Roxy 创建窗口（管理工具）：npm run roxy:create-window

目录结构

.
├─ src/
│  ├─ cli.ts                 # CLI 入口（示例/调试）
│  ├─ mcp/server.ts

Related Skills

node-connect

333.7k

Diagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps

frontend-design

82.0k

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

openai-whisper-api

333.7k

Transcribe audio via OpenAI Audio Transcriptions API (Whisper).

commit-push-pr

82.0k

Commit, push, and open a PR

mook-wenyu

View profile

View on GitHub
GitHub Stars14
CategoryDevelopment
Updated29d ago
Forks5
mook-wenyu/XiaoHongShuMCP

Languages

TypeScript

Security Score

85/100

Audited on Feb 22, 2026

No findings