How ifuryst/rednote-mcp works
Project Type and Purpose
• This is a TypeScript‑based CLI application that implements an MCP (Model Context Protocol) server for fetching content from the Xiaohongshu (Red Note) platform.
• It exposes commands (e.g. init, search, fetch by URL) over STDIO and integrates with tools like Cursor via the MCP protocol.
• It automates login via Playwright, persists cookies, scrapes or queries notes, and returns results over STDIO.
File Structure
• Top‑level files: cli.ts (entry point for commands), index.ts (bootstrap MCP protocol server).
• src/auth/: handles authentication and cookie persistence (authManager.ts, cookieManager.ts).
• src/tools/: core “business logic” for interacting with RedNote:
• rednoteTools.ts (search by keyword, URL parsing)
• noteDetail.ts (fetch content/details)
• src/utils/logger.ts: centralized logging.
• Config & metadata: package.json, tsconfig.json, Jest config, GitHub workflows.
Readme Insights
• Requires Playwright for browser automation during init.
• Cookie storage at ~/.mcp/rednote/cookies.json.
• Supports MCP protocol over STDIO (for Cursor integration).
• Provides a CLI interface that wraps the MCP server logic.
Main Components
a. CLI Layer
• cli.ts: parses CLI arguments, dispatches commands (e.g. init, search, fetch).
• MCP Protocol Server (index.ts): listens on STDIO, handles incoming MCP requests (Cursor or direct invocation).
b. Core Services
• AuthManager: orchestrates OAuth/login flow using Playwright.
• CookieManager: reads/writes persistent cookie JSON.
• RedNoteTools: exposes functions to search notes, parse URLs, orchestrate fetching.
• NoteDetail: fetches and formats the raw note data.
• Logger: emits standardized logs.
c. External Dependencies
• Playwright-controlled Browser (Chromium, Firefox, WebKit).
• Xiaohongshu Web endpoints.
• File system (~/.mcp/rednote/cookies.json).
• STDIO (for MCP protocol traffic) or console.
Relationships & Data Flows
1. User runs rednote-mcp init (or npx rednote-mcp --stdio) →
2. CLI Layer calls AuthManager →
3. AuthManager launches Playwright browser → user logs in → cookies stored via CookieManager.
4. For search/fetch: CLI/MCP server receives request over STDIO → invokes RedNoteTools → may read cookies via CookieManager → issues HTTP/browser requests to Xiaohongshu → receives HTML/JSON → NoteDetail extracts content → results returned over STDIO.
5. Logger writes to console/file throughout.
Architectural Patterns & Principles
• Modularity: separation into auth, tools, utils.
• Single‐process, layered approach: CLI → Core Services → External.
• Use of IPC (STDIO) for MCP protocol compliance.
• Dependency inversion: high‑level CLI depends on abstracted service interfaces (authManager, tools).
Elements
• Clear, human‑readable labels.
• Services (auth, tools, utils): another
• External systems (browser, web, FS, STDIO): a third