当前位置：首页 > news >正文

小红书MCP服务器 - 技术架构深度解析

news 2025/11/10 7:54:37

本文档详细解析项目的技术架构、核心模块实现、设计模式和关键技术点

一、项目概述

这是一个基于 Electron + MCP框架 开发的跨平台桌面应用，通过直接调用小红书Web API实现高性能的数据采集和互动功能。

核心特性

开箱即用：无需Node.js/Python等环境配置
API直连：秒级响应，获取完整数据（包括隐藏字段）
会话持久化：一次登录，长期有效
工具插件化：20+ MCP工具，易于扩展
跨平台支持：Windows/macOS/Linux

二、技术栈

2.1 前端技术

技术	版本	用途
React	19.1.0	UI框架
Ant Design	5.24.8	UI组件库
Vite	6.2.6	构建工具
TypeScript	5.8.3	类型系统

2.2 桌面端

技术	版本	用途
Electron	35.1.5	跨平台桌面框架
electron-vite	3.1.0	开发构建工具
electron-builder	25.1.8	应用打包工具

2.3 服务端

技术	版本	用途
@aicu/mcp-framework	0.5.9	MCP服务器框架
@modelcontextprotocol/sdk	1.10.2	MCP协议SDK
Zod	3.24.3	运行时类型验证

2.4 其他工具

javascript-obfuscator: 代码混淆保护核心逻辑

三、项目结构

xhs-mcp-server/
├── src/                          # Electron主应用
│   ├── main/                     # 主进程
│   │   └── index.js             # 应用生命周期、IPC通信、窗口管理
│   ├── preload/                  # 预加载脚本
│   │   └── index.js             # Context Bridge API暴露
│   └── renderer/                 # 渲染进程（React应用）
│       ├── src/
│       │   ├── App.jsx          # 应用主组件
│       │   ├── pages/           # 页面组件
│       │   │   ├── Www.jsx      # MCP服务主页
│       │   │   ├── Home.jsx     # 关于页
│       │   │   └── McpTools.jsx # 工具列表
│       │   └── components/      # 通用组件
│       └── index.html
│
├── src-mcpserver/               # MCP服务器核心
│   ├── src/
│   │   ├── index.ts            # MCP服务创建入口
│   │   ├── xhs-browser.ts      # 小红书浏览器核心模块
│   │   └── tools/              # MCP工具集（20+个工具）
│   │       ├── SearchnotesTool.ts
│   │       ├── GetuserpostsTool.ts
│   │       ├── PostNoteTool.ts
│   │       └── ...
│   ├── dist/                   # 编译输出（混淆后）
│   └── tsconfig.json
│
├── src-extension/              # 浏览器扩展
│   ├── manifest.json           # Chrome扩展配置
│   └── content.js              # 内容脚本（混淆）
│
├── resources/                  # 应用资源
├── package.json               # 项目依赖
├── electron.vite.config.mjs   # Vite配置
└── electron-builder.yml       # 打包配置

四、核心模块架构

4.1 主进程 (src/main/index.js)

职责：应用生命周期管理、进程间通信、资源协调

4.1.1 安全的模块加载机制

// 延迟访问electron.app，避免模块加载时崩溃
const getApp = () => electron.app
const isDev = () => !getApp().isPackaged

4.1.2 MCP服务器生命周期管理

import CreateMCPServer from '../../src-mcpserver/dist/index.js';
import { getBrowser, getUserInfo } from '../../src-mcpserver/dist/xhs-browser.js';// IPC处理器 - 启动MCP服务
electron.ipcMain.handle('start-mcpserver', async (event, arg) => {setSaveDataPath(arg['savePath']);mcpServer = CreateMCPServer(arg);mcpServer.start();getBrowser(); // 初始化小红书浏览器return { success: true };
});

4.1.3 优雅的退出机制

function cleanupAndQuit() {let hasQuit = false;const quit = () => {if (hasQuit) return;hasQuit = true;getApp().quit();setTimeout(() => process.exit(0), 2500);};// 异步清理但不阻塞退出if (mcpServer) {Promise.race([mcpServer.stop(),new Promise(resolve => setTimeout(resolve, 2000))]).finally(quit);} else {quit();}
}

4.1.4 窗口和托盘管理

主窗口：725x550固定大小，禁用最大化
托盘图标：显示运行状态，支持双击打开
关闭行为：隐藏而非退出（常驻后台）

4.2 预加载脚本 (src/preload/index.js)

职责：通过Context Bridge安全地暴露主进程API到渲染进程

const api = {startMcpServer: async (opts) => ipcRenderer.invoke('start-mcpserver', opts),stopMcpServer: async () => ipcRenderer.invoke('stop-mcpserver'),getMcpServerTools: async () => ipcRenderer.invoke('get-mcpserver-tools'),toggleXhsBrowser: async () => ipcRenderer.invoke('toggle-xhs-browser'),getXhsUserInfo: async () => ipcRenderer.invoke('get-xhs-userinfo'),// ...
};contextBridge.exposeInMainWorld('AppApi', api);

设计模式：Context Bridge模式，确保进程隔离和安全性

4.3 渲染进程 (src/renderer/src/App.jsx)

架构：React + Ant Design + 函数式组件 + Hooks

4.3.1 主要组件

App.jsx - 应用入口

<Tabs><TabPane key="about" tab="关于"><Home /></TabPane><TabPane key="www" tab="MCP服务"><Www /></TabPane>
</Tabs>

4.3.2 MCP服务主页 (src/renderer/src/pages/Www.jsx)

核心状态管理：

const [running, setRunning] = useState(false);  // 服务状态
const [port, setPort] = useState(9999);         // 端口配置
const [endpoint, setEndpoint] = useState('/mcp'); // 路由配置
const [xhsUser, setXhsUser] = useState(null);   // 登录用户
const [mcpTools, setMcpTools] = useState([]);   // 工具列表

登录状态轮询：

useEffect(() => {if (!running) return;const loginCheckInterval = setInterval(() => {getXhsUser();}, 3000);return () => clearInterval(loginCheckInterval);
}, [running]);

4.3.3 内嵌Webview登录方案

<webviewsrc="https://www.xiaohongshu.com"style={{ width: '100%', height: '100%' }}partition="persist:xiaohongshu"  // 共享session
/>

优势：

用户无需离开应用即可扫码登录
实时显示登录状态
使用持久化session，避免重复登录

五、MCP服务器实现

5.1 服务创建 (src-mcpserver/src/index.ts)

import { MCPServer, MCPServerConfig } from "@aicu/mcp-framework";const createServer = (opt: UserOptions) => {const opts: MCPServerConfig = {name: 'xhs-mcp',version: '0.5.20',basePath: getToolsPath(),  // 自动扫描tools目录transport: {type: opt.proto === 'sse' ? 'sse' : 'http-stream',options: {port: opt.port,endpoint: opt.endpoint,cors: { allowOrigin: '*' }}}};return new MCPServer(opts);
}

支持的传输协议：

SSE (Server-Sent Events)
HTTP Streaming

5.2 核心模块 - xhs-browser.ts

这是整个项目最核心的模块，实现了与小红书平台的交互。

5.2.1 浏览器窗口管理

const getBrowser = () => {// 使用持久化session分区const partitionName = 'persist:xiaohongshu';const sharedSession = session.fromPartition(partitionName);// 初始化会话配置（cookie持久化）initSession(sharedSession);// 创建隐藏的浏览器窗口browser = new BrowserWindow({width: 1024,height: 768,show: false,  // 默认隐藏webPreferences: {session: sharedSession,webSecurity: false,  // 允许跨域contextIsolation: true}});// 注入扩展代码browser.webContents.on('dom-ready', async () => {await browser.webContents.executeJavaScript(extensionCode);});browser.loadURL('https://www.xiaohongshu.com');return browser;
}

5.2.2 会话持久化机制 ⭐核心创新

解决问题：每次登录需要重新扫码的痛点

关键实现：

const initSession = (session: any) => {// 1. 设置存储路径const sessionPath = path.join(userDataPath, 'xiaohongshu-session');session.setStoragePath(sessionPath);// 2. 启用持久化cookies（核心）session.cookies.setPersistSessionCookies(true);// 3. 配置请求拦截器session.webRequest.onBeforeSendHeaders((details, callback) => {details.requestHeaders['Cookie'] = details.requestHeaders['Cookie'] || '';details.requestHeaders['credentials'] = 'include';// 小红书特殊请求头if (details.url.includes('xiaohongshu.com')) {details.requestHeaders['Origin'] = 'https://www.xiaohongshu.com';details.requestHeaders['Referer'] = 'https://www.xiaohongshu.com/';}callback({ requestHeaders: details.requestHeaders });});// 4. 响应头处理session.webRequest.onHeadersReceived((details, callback) => {details.responseHeaders['Access-Control-Allow-Credentials'] = ['true'];callback({ responseHeaders: details.responseHeaders });});// 5. Cookie变化监听session.cookies.on('changed', (event, cookie, cause, removed) => {if (!removed) {console.log(`Cookie updated: ${cookie.name}`);}});// 6. 立即刷新到磁盘session.cookies.flushStore();
}

技术要点：

setPersistSessionCookies(true)：关键配置，使会话cookie持久化
请求/响应头拦截：确保cookie正确传递
flushStore()：立即写入磁盘，防止数据丢失

5.2.3 扩展注入机制

const extensionCode = fs.readFileSync(path.join(getExtPath(), 'content.js'),'utf8'
);browser.webContents.on('dom-ready', async () => {const wrappedCode = `try {${extensionCode}console.log('[Extension] Code executed successfully');} catch (err) {console.error('[Extension] Execution error:', err);}`;await browser.webContents.executeJavaScript(wrappedCode);
});

扩展功能：

注入AicuXHSApi对象到页面
提供get(url)和post(url, data)方法
自动处理请求签名和token

5.2.4 API调用封装

// 执行JS代码并获取结果
const evalJs = async (code: string, tryCount: number = 0) => {// 1. 检查是否在验证码页面const web_href = await browser.webContents.executeJavaScript('location.href');if (web_href.includes('web-login/captcha')) {await sleep(3);return evalJs(code, tryCount);  // 递归等待}// 2. 执行代码const result = await browser.webContents.executeJavaScript(code);// 3. 检查访问频次异常if (JSON.stringify(result).includes('访问频次异常')) {await sleep(2 + tryCount);return evalJs(code, tryCount + 1);  // 指数退避重试}return result;
}// HTTP包装器
const httpGet = async (url: String) => {return await evalJs(`AicuXHSApi.get('${url}');`);
};const httpPost = async (url: String, data: Object) => {return await evalJs(`AicuXHSApi.post('${url}', ${JSON.stringify(data)});`);
};

错误处理策略：

验证码检测：自动等待用户完成验证
频次限制：指数退避重试
最大重试次数保护

5.2.5 数据处理工具

CSV导出：

const jsonToCsv = (jsonData: Array<any>,fields: Array<string>,arrayDelimiter = ";"
) => {// 字段格式：'note_id@id' -> header: 'note_id', path: 'id'const parsedFields = fields.map(field => {const parts = field.split("@");return {header: parts[0],path: parts.length === 2 ? parts[1] : parts[0]};});// 生成CSVconst csvHeaders = parsedFields.map(f => f.header).join(",");let csvContent = csvHeaders + "\n";jsonData.forEach(item => {const row = parsedFields.map(field => {// 嵌套字段访问：'user.nickname' -> item.user.nicknamelet value = item;for (const part of field.path.split(".")) {value = value?.[part];}// 数组处理if (Array.isArray(value)) {value = value.join(arrayDelimiter);}// CSV转义if (typeof value === "string" && /[,"\n]/.test(value)) {value = `"${value.replace(/"/g, '""')}"`;}return value || "";});csvContent += row.join(",") + "\n";});return csvContent;
}

特性：

支持嵌套字段访问（如user.nickname）
自动数组拼接
正确的CSV转义
灵活的字段映射

5.2.6 图片上传功能

const uploadImage = async (filePath: string) => {// 1. 读取文件并转base64const fileBuffer = fs.readFileSync(filePath);const base64Data = fileBuffer.toString('base64');// 2. 获取上传许可const permitRes = await httpGet('https://edith.xiaohongshu.com/api/media/v1/upload/web/permit?...');const { upload_id, file_ids } = permitRes;// 3. 上传图片（通过浏览器执行）const uploadCode = `(async () => {const blob = await (await fetch('data:image/jpeg;base64,${base64Data}')).blob();const formData = new FormData();formData.append('file', blob, '${fileName}');formData.append('upload_id', '${uploadId}');const response = await fetch('https://edith.xiaohongshu.com/api/media/v1/upload/web/file',{method: 'POST',body: formData,credentials: 'include'});return await response.json();})();`;const uploadRes = await evalJs(uploadCode);return { file_id: uploadRes.file_id, upload_id, url: uploadRes.url };
}

5.3 MCP工具集实现

5.3.1 工具基类结构

import { MCPTool } from "@aicu/mcp-framework";
import { z } from "zod";class ToolName extends MCPTool<InputType> {name = "工具名称";description = "工具描述";schema = {param1: {type: z.string(),description: "参数描述",default: "默认值"  // 可选}};async execute(input: InputType) {// 实现逻辑}
}module.exports = ToolName;

5.3.2 典型工具实现示例

1. 搜索笔记工具 (src-mcpserver/src/tools/SearchnotesTool.ts)

class SearchnotesTool extends MCPTool<SearchnotesInput> {async execute(input: SearchnotesInput) {const { keyword, count, sort, noteType, download } = input;// 生成搜索ID（模拟前端行为）const searchId = createSearchId();// 分页获取数据let loaded_count = 0;let current_page = 1;const results_all: any[] = [];while (loaded_count < count) {const res = await httpPost('/api/sns/web/v1/search/notes', {keyword, page: current_page, page_size: 20,search_id: searchId, sort, note_type: noteType});// 过滤和收集数据res['items'].forEach(item => {if (item['modelType'] === 'note' && loaded_count < count) {results_all.push(item);loaded_count++;}});current_page++;await sleep(2);  // 防止请求过快}// 转换为CSVconst result_csv = jsonToCsv(results_all, ['note_id@id','title@noteCard.displayTitle','liked_count@noteCard.interactInfo.likedCount','user_name@noteCard.user.nickname']);// 可选导出if (download) {return downloadCsvData(`search_notes_${keyword}_${count}`, result_csv);}return result_csv;}
}

2. 发布笔记工具 (src-mcpserver/src/tools/PostNoteTool.ts)

class PostNoteTool extends MCPTool<PostNoteInput> {async execute(input: PostNoteInput) {const { title, content, note_type, image_paths, topics } = input;// 参数验证if (note_type === "normal" && (!image_paths || image_paths.length === 0)) {return "错误：图文笔记必须提供至少一张图片";}if (image_paths && image_paths.length > 9) {return "错误：图片最多9张";}// 上传所有图片const fileIds: string[] = [];for (let i = 0; i < image_paths.length; i++) {const uploadResult = await uploadImage(image_paths[i]);fileIds.push(uploadResult.file_id);if (i < image_paths.length - 1) await sleep(1);}// 发布笔记const result = await publishNote({title,desc: content,type: "normal",file_ids: fileIds,topics});if (result.success || result.note_id) {return `✅ 笔记发布成功！\n📝 标题: ${title}\n🖼️ 图片: ${image_paths.length} 张`;}}
}

5.3.3 工具列表总览

项目包含 20+ 个MCP工具，涵盖以下类别：

数据获取类：

搜索笔记 (SearchnotesTool)
搜索用户 (SearchuserTool)
获取笔记详情 (GetfeeddataTool)
批量获取笔记 (BatchGetNotesTool)
获取用户笔记列表 (GetuserpostsTool)
获取用户收藏列表 (GetcollectnotesTool)
获取用户点赞列表 (GetlikenotesTool)
获取笔记评论 (GetnotecommentsTool)
获取推荐笔记 (GethomefeedsTool)
获取当前用户信息 (GetselfinfoTool)

互动操作类：
11. 点赞/取消点赞 (LikenoteacionTool)
12. 收藏/取消收藏 (CollectnoteactionTool)
13. 关注/取消关注 (FollowuserTool)
14. 发布评论 (PostnotecommentTool)

创作发布类：
15. 发布笔记 (PostNoteTool) - 支持图文，视频开发中

工具类：
16. 获取本地文件内容 (GetfilecontentsTool)

六、浏览器扩展

6.1 扩展配置 (src-extension/manifest.json)

{"manifest_version": 3,"name": "xhs-extension","version": "0.5.20","content_scripts": [{"matches": ["*://www.xiaohongshu.com/*"],"js": ["content.js"],"run_at": "document_start","world": "MAIN"}]
}

6.2 扩展功能 (src-extension/content.js)

content.js (混淆后)：

注入AicuXHSApi全局对象
拦截和处理小红书API请求
自动添加必要的签名和token
绕过某些前端限制

注入时机：

document_start：在DOM构建之前注入
world: "MAIN"：注入到页面的主世界（可访问页面全局变量）

七、构建与打包

7.1 构建流程

{"dev": "electron-vite dev","build": "electron-vite build","build:mcp": "cd src-mcpserver && npm run build && cd .. && npm run encrypt:mcp","encrypt:mcp": "javascript-obfuscator src-mcpserver/dist --output src-mcpserver/dist","build:win": "npm run build:mcp && npm run build && electron-builder --win"
}

构建步骤：

编译MCP服务器（TypeScript → JavaScript）
混淆MCP服务器代码（保护核心逻辑）
构建Electron应用（主进程+渲染进程）
打包成安装程序（electron-builder）

7.2 打包配置 (electron-builder.yml)

appId: xhs.aicu.icu
productName: 小红书MCP服务器# 排除的文件
files:- '!src-mcpserver/src/**'    # 排除源码- '!src-mcpserver/*.*'       # 排除配置文件- '!*.md'                    # 排除文档# 解压的文件（不打包进asar）
asarUnpack:- resources/**- src-extension/**

ASAR打包策略：

主应用打包进asar（提高加载速度，保护代码）
扩展和资源解压（需要动态加载）

7.3 代码混淆

使用javascript-obfuscator混淆：

目标：src-mcpserver/dist和src-extension/content.js
目的：保护核心API调用逻辑，防止滥用和平台封禁
副作用：增加调试难度

八、设计模式

8.1 工厂模式 - MCP服务器创建

const createServer = (opt: UserOptions) => {const opts: MCPServerConfig = { ... };return new MCPServer(opts);
}

8.2 单例模式 - 浏览器窗口管理

var browser: any = null;
const getBrowser = () => {if (browser && browser.isEnabled()) return browser;browser = new BrowserWindow({ ... });return browser;
}

8.3 策略模式 - 工具插件化

class XXXTool extends MCPTool<InputType> {name = "...";description = "...";schema = { ... };async execute(input: InputType) { ... }
}

8.4 观察者模式 - IPC通信

// 主进程注册处理器
electron.ipcMain.handle('event-name', async (event, arg) => { ... });// 渲染进程触发
ipcRenderer.invoke('event-name', data);

8.5 适配器模式 - API封装

const httpGet = async (url: String) => {return await evalJs(`AicuXHSApi.get('${url}');`);
};

九、性能优化

9.1 请求优化

请求限流：

await sleep(2);  // 每次请求间隔2秒

批量处理：

// BatchGetNotesTool: 批量获取多个笔记
for (let i = 0; i < notes.length; i++) {// 获取笔记if (i < notes.length - 1) await sleep(2);
}

游标分页：

let cursor = res['cursor'];
while (res['hasMore']) {const res = await httpGet(`...&cursor=${cursor}`);// ...
}

9.2 启动优化

延迟加载：

// 避免模块加载时访问electron.app
const getApp = () => electron.app

异步初始化：

setTimeout(() => {getApp().whenReady().then(async () => {createWindow();});
}, 0);

9.3 内存优化

缓存管理：

var browser: any = null;  // 缓存浏览器实例
var mcpServer = null;     // 缓存MCP服务器实例

及时清理：

function cleanupAndQuit() {// 停止MCP服务器// 销毁窗口和托盘// 确保进程退出
}

十、安全性

10.1 代码保护

混淆关键模块
- MCP服务器逻辑
- 浏览器扩展代码
- 防止逆向和滥用
ASAR打包
- 主应用打包进asar
- 提高破解难度

10.2 进程安全

Context Bridge：

contextBridge.exposeInMainWorld('AppApi', api);
// 只暴露必要的API，避免任意代码执行

上下文隔离：

webPreferences: {contextIsolation: true  // 隔离上下文
}

10.3 数据安全

本地存储：

配置文件：userData/config.json
Session数据：userData/xiaohongshu-session
导出数据：用户指定目录

API调用：

通过官方Web API，降低封号风险
自动限流，避免触发反爬

十一、架构亮点总结

1. 会话持久化方案 ⭐⭐⭐

创新点：解决每次重启需要重新登录的痛点

技术实现：

持久化session分区
Cookie拦截和刷新
请求/响应头处理

用户体验：一次登录，长期有效

2. 内嵌Webview登录 ⭐⭐

优势：

无需离开应用即可登录
实时状态展示
共享session，确保cookie同步

3. 模块化工具体系 ⭐⭐

特点：

基于MCP框架的插件化架构
自动工具发现（basePath扫描）
统一的参数验证（Zod）

4. 错误重试机制 ⭐

策略：

自动检测验证码页面
访问频次异常自动重试
指数退避算法

5. 数据导出灵活性 ⭐

能力：

支持CSV格式导出
灵活的字段映射（path语法）
嵌套对象和数组处理

十二、开发和维护

12.1 开发环境搭建

# 安装依赖
npm i# 构建MCP服务器
npm run build:mcp# 启动开发服务器
npm run dev

12.2 调试

主进程调试：

console.log('[main]', '...');

渲染进程调试：

开发模式自动开启DevTools

MCP服务器调试：

console.log('[xhs-browser]', '...');

12.3 版本发布

# Windows
npm run build:win# macOS
npm run build:mac# Linux
npm run build:linux

十三、技术债务和改进方向

当前限制

视频笔记发布：视频上传需要分片上传和转码，流程复杂，暂未实现
代码重构：存在一定的代码重复，可以进一步优化
错误处理：部分工具的错误处理较简单

潜在改进

性能优化
- 引入请求队列，避免并发限制
- 缓存热数据（用户信息、笔记详情）
功能扩展
- 数据分析仪表板
- 定时任务（自动点赞、评论）
- 数据可视化
用户体验
- 更丰富的配置选项
- 任务进度展示
- 错误恢复机制
架构优化
- 抽取公共逻辑为基类
- 统一的错误处理中间件
- 更完善的日志系统

附录：关键文件路径索引

主要源码文件

文件	路径	说明
主进程	src/main/index.js	应用生命周期、IPC
预加载	src/preload/index.js	Context Bridge
应用入口	src/renderer/src/App.jsx	React应用
MCP服务主页	src/renderer/src/pages/Www.jsx	主界面

MCP服务器核心

文件	路径	说明
服务创建	src-mcpserver/src/index.ts	MCP服务入口
浏览器模块	src-mcpserver/src/xhs-browser.ts	核心模块
工具目录	src-mcpserver/src/tools/	20+工具