# 搜索工具安装与维护

## 环境与安装范围

辅助脚本面向 Apple Silicon Mac，使用 Python 3.11+ 标准库、系统 curl、hdiutil、ditto 和 launchctl。Windows、Linux 和 Intel Mac 请查看 [上游说明](https://github.com/xpzouying/xiaohongshu-mcp)。

安装会在当前用户的 Codex 配置追加 `xiaohongshu_search`，并注册用户级登录启动服务。因此 MCP 配置对该用户的其他项目也可见；项目技能由 `.agents/skills/`（Codex）与 `.cursor/skills/`（Cursor）决定。脚本遇到已有同名配置会停止，不覆盖当前安装。

## 1. 下载固定版本依赖

在仓库目录运行：

```bash
mkdir -p 本地资料/安装包
curl -fL -C - --output 本地资料/安装包/xiaohongshu-mcp-darwin-arm64 https://github.com/xpzouying/xiaohongshu-mcp/releases/download/v2.5.5/xiaohongshu-mcp-darwin-arm64
curl -fL -C - --output 本地资料/安装包/macos-arm64.dmg https://cdn.one-world.ai/browsers/148.0.7778.215/macos-arm64.dmg
```

两条命令支持断点续传。安装脚本将校验固定版本的 SHA-256，文件缺失或校验失败时停止。

- MCP：`fad3633fda4a8060e66e2941bc8fc5460326c7cb4e58a32485a9e2c9408e95a8`
- 浏览器：`b72f091e2e1a7583eed389c4b8e3534ed355e568af8c8bbf8fc30a25e23ca679`

若 GitHub 发布下载连接不稳定，可从 [官方发布页](https://github.com/xpzouying/xiaohongshu-mcp/releases/tag/v2.5.5) 下载同名文件并放入上述目录。不要把新版文件与旧版校验值混用。

## 2. 安装与连接

```bash
python3 scripts/prepare_xhs_browser.py
python3 scripts/setup_xhs_search.py
python3 scripts/xhs_mcp_check.py list
```

浏览器准备脚本保留 macOS 安全属性；如果系统要求许可，请正常完成系统提示。不要移除安全属性或关闭系统检查来解决问题。

安装脚本生成本机随机令牌，服务只监听 `127.0.0.1:18060`，并在 Codex 中只启用下列工具：

- `check_login_status`
- `get_login_qrcode`
- `search_feeds`
- `get_feed_detail`

这是 Codex 客户端的允许列表；上游服务本身仍包含其他接口，不能因此把完整上游服务称为只读服务器。令牌和 cookies 仅保留在本机。

默认运行目录是 `~/.codex/tools/xiaohongshu-mcp/`，配置文件为 `~/.codex/config.toml`；设置了 `CODEX_HOME` 时使用该目录。配置修改前会备份。浏览器缓存位于 `~/Library/Caches/xiaohongshu-mcp/`。

`list` 能验证本地服务与工具 schema，但不代表当前 Codex 会话已加载新工具。若当前会话看不到服务，请重新打开项目会话后检查。

## 3. 扫码登录与验收

```bash
python3 scripts/xhs_mcp_check.py get_login_qrcode
python3 scripts/xhs_mcp_check.py check_login_status
python3 scripts/xhs_mcp_check.py search_feeds '{"keyword":"租房卧室改造","filters":{"sort_by":"最多收藏","note_type":"图文"}}'
```

二维码保存路径会显示在终端；打开该图片，用手机小红书扫码并确认。二维码过期时重新获取。

连接通过后仍需用实际主题取得 3 条达标笔记，核验赞藏和来源，才能完成创作调研。搜索结果的 `xsecToken` 是详情访问所需参数，不应把带参数的个人调研缓存上传为开源示例。

## 常见问题与维护

- 已安装：不要重复运行安装脚本，先运行 `check_login_status` 或 `list`。
- 连接拒绝：检查服务是否运行、18060 端口是否被其他应用占用，以及运行目录内的日志。
- 未登录、验证码或访问限制：由用户在正常平台流程中处理；每个失败请求最多重试一次，之后排查原因。
- 返回赞藏缩写：保留原文；不要把“1.2万”表述为精确的 12000。
- 更新版本：先检查上游版本、组件与校验值，备份本地配置后再升级；本脚本不会自动升级。

停止后台服务（不删除配置或会话）：

```bash
launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.codex.xiaohongshu-search.plist"
```

再次启动：

```bash
launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.codex.xiaohongshu-search.plist"
```

完整移除时，先停止服务，再从 Codex 配置中仅删除 `[mcp_servers.xiaohongshu_search]` 这一节，并删除同名 LaunchAgent 文件。运行目录含登录会话，是否删除由使用者决定。