最新资讯

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

目录

• 一、项目概述
• 二、技术栈
• 三、项目结构
• 四、核心模块架构
• 五、MCP服务器实现
• 六、浏览器扩展
• 七、构建与打包
• 八、设计模式
• 九、性能优化
• 十、安全性

一、项目概述

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

核心特性

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

二、技术栈

2.1 前端技术

2.2 桌面端

2.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 - 应用入口

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登录方案

{ 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]
    };
  });

  // 生成CSV
  const csvHeaders = parsedFields.map(f => f.header).join(",");
  let csvContent = csvHeaders + "
";

  jsonData.forEach(item => {
    const row = parsedFields.map(field => {
      // 嵌套字段访问：'user.nickname' -> item.user.nickname
      let 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" && /[,"
]/.test(value)) {
        value = `"${value.replace(/"/g, '""')}"`;
      }
      return value || "";
    });
    csvContent += row.join(",") + "
";
  });

  return csvContent;
}

特性：

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

5.2.6 图片上传功能

const uploadImage = async (filePath: string) => {
  // 1. 读取文件并转base64
  const 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);  // 防止请求过快
    }

    // 转换为CSV
    const 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 `✅ 笔记发布成功！
📝 标题: ${title}
🖼️ 图片: ${image_paths.length} 张`;
    }
  }
}

5.3.3 工具列表总览

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

数据获取类：

1. 搜索笔记 (SearchnotesTool)
2. 搜索用户 (SearchuserTool)
3. 获取笔记详情 (GetfeeddataTool)
4. 批量获取笔记 (BatchGetNotesTool)
5. 获取用户笔记列表 (GetuserpostsTool)
6. 获取用户收藏列表 (GetcollectnotesTool)
7. 获取用户点赞列表 (GetlikenotesTool)
8. 获取笔记评论 (GetnotecommentsTool)
9. 获取推荐笔记 (GethomefeedsTool)
10. 获取当前用户信息 (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"
}

构建步骤：

1. 编译MCP服务器（TypeScript → JavaScript）
2. 混淆MCP服务器代码（保护核心逻辑）
3. 构建Electron应用（主进程+渲染进程）
4. 打包成安装程序（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 代码保护

1. 混淆关键模块

   • MCP服务器逻辑
   • 浏览器扩展代码
   • 防止逆向和滥用

2. 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

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

当前限制

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

潜在改进

1. 性能优化

   • 引入请求队列，避免并发限制
   • 缓存热数据（用户信息、笔记详情）

2. 功能扩展

   • 数据分析仪表板
   • 定时任务（自动点赞、评论）
   • 数据可视化

3. 用户体验

   • 更丰富的配置选项
   • 任务进度展示
   • 错误恢复机制

4. 架构优化

   • 抽取公共逻辑为基类
   • 统一的错误处理中间件
   • 更完善的日志系统

附录：关键文件路径索引

主要源码文件

MCP服务器核心

配置文件

总结

小红书MCP服务器通过以下技术优势，实现了高性能、易用性和扩展性的平衡：

✅ Electron跨平台架构 - 一次开发，多平台运行
✅ MCP工具插件化 - 易于扩展和维护
✅ 会话持久化创新 - 解决重复登录痛点
✅ API直连模式 - 秒级响应，完整数据
✅ 进程隔离安全 - 保障应用安全性

项目展示了如何将Electron、MCP框架和Web自动化技术结合，构建一个专业级的桌面应用。无论是用于学习Electron开发、MCP协议实践，还是理解Web自动化和API交互，这个项目都提供了丰富的参考价值。

文档说明

本文档基于项目代码 v0.5.20 版本分析生成。