XHS-MCP

# MCP 使用指南 本项目已实现完整的 MCP (Model Context Protocol) 服务器，可以通过 Claude Desktop、Cursor 或其他支持 MCP 的客户端使用。 ## 🚀 一键部署（推荐） 最简单的方式是使用自动配置脚本，**无需手动配置路径**： ```bash xhs setup-mcp ``` 脚本会自动多个MCP配置选项： ## 前置要求 # MCP 使用指南 本项目包含一个 MCP（Model Context Protocol）服务器，可与 Claude Desktop、Cursor 等支持 MCP 的客户端集成。 下面说明了项目内置的自动配置脚本如何工作，以及手动配置要点。 ## 🚀 自动配置（推荐） 项目提供了一个自动配置脚本，用来把本仓库构建输出注册到 Claude Desktop / Cursor 的本地配置中。 运行方式说明： - 对于已通过 npm 全局安装（或使用 npx）的最终用户：请直接使用 CLI 命令运行（这是推荐的用户用法）： ```bash # 在终端中运行（全局安装或 npx） xhs setup-mcp [--claude|--cursor|--all] ``` - 对于在源码树中开发或调试的贡献者，可以在仓库根目录运行（使用 tsx）： ```bash npm run setup ``` 脚本会： - 检查并在必要时自动运行 `npm run build`，确保 `dist/mcp/index.js`（或兼容的 `dist/index.js`）存在； - 将 `mcpServers.xhs-mcp` 条目写入目标客户端的配置文件，命令为 `node`，参数为构建输出的绝对路径（例如 `.../dist/mcp/index.js`）； - 会合并已有配置（不会覆盖其他条目），并在需要时创建父目录。 脚本支持命令行参数来跳过交互式选择： - `--claude`：只配置 Claude Desktop - `--cursor`：只配置 Cursor - `--all`：同时配置 Claude Desktop 和 Cursor 或者（示例）： - 供最终用户（全局安装或 npx）： ```bash xhs setup-mcp --claude ``` - 供在源码树中运行的开发者： ```bash npm run setup -- --claude ``` (注意：通过 `npm run setup` 传递参数时需在 `npm run` 后加 `--`） 或者： ```bash npm run setup -- --claude ``` （注意：通过 `npm run setup` 传递参数时需在 `npm run` 后加 `--`） ## 前置要求 1. Node.js >= 18 2. 项目已安装依赖（例如：`npm install`） 3. 如果尚未构建，脚本会尝试运行 `npm run build`，但你也可以手动先运行一次 `npm run build`。 建议先运行： ```bash npm install npm run build ``` ## 脚本会修改的配置文件位置 - Claude Desktop： - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Linux: `~/.config/Claude/claude_desktop_config.json` - Cursor： - 所有平台: `~/.cursor/mcp.json` 脚本会把如下条目写入 `mcpServers` 下： ```json { "xhs-mcp": { "command": "node", "args": ["/absolute/path/to/your/repo/dist/mcp/index.js"] } } ``` 脚本会尽量保留和合并已有配置，不会删除其他服务器定义。 ## 手动配置（可选） 如果自动脚本无法使用，你可以手动将上面的 `mcpServers.xhs-mcp` 条目加入到对应的配置文件中（确保 `args` 中使用构建产物 `dist/mcp/index.js` 的绝对路径）。 Windows 路径在 JSON 中可以使用双反斜杠 `\\` 或正斜杠 `/`。 ## 配置完成后的操作 - 配置完成后请重启对应的客户端使配置生效： - Claude Desktop：重启应用 - Cursor：重启应用，并在 Cursor 中打开 AI 面板（Cmd/Ctrl + L）以确认连接 - 如果 MCP 工具提示未登录，请先在终端运行： ```bash # 使用 CLI 登录（会打开浏览器让你完成登录） xhs login ``` ## 可用工具（示例） MCP 配置成功后，服务器会暴露一组工具（名称请以 `src/mcp/index.ts` 中注册的工具为准），常见的工具包括： - `xhs_login` — 登录小红书（会在浏览器中触发登录流程） - `xhs_check_login` — 检查登录状态 - `xhs_get_recent_notes` — 获取近期笔记列表 - `xhs_get_operation_data` — 获取运营数据 - `xhs_get_note_detail` — 按 ID 获取笔记详情 - `xhs_read_posting_guidelines` — 读取发帖指南 - `xhs_create_or_update_post` — 创建或更新发帖队列中的帖子 - `xhs_generate_cover` — 生成封面图片 （准确的工具名和参数请参照 `src/mcp/index.ts` 与 `src/mcp/handlers.ts`）