# ifuryst/rednote-mcp architecture

> Architecture diagram of the GitHub repository ifuryst/rednote-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ifuryst/rednote-mcp
- Repository: https://github.com/ifuryst/rednote-mcp

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI & Protocol"
        CLI["CLI (cli.ts)"]:::cli
        MCP["MCP Server (index.ts)"]:::cli
    end

    subgraph "Core Services"
        Auth["AuthManager"]:::core
        Cookie["CookieManager"]:::core
        Tools["RedNoteTools"]:::core
        Detail["NoteDetail"]:::core
        Logger["Logger"]:::core
    end

    subgraph "External Systems"
        Browser["Playwright Browser"]:::external
        Web["Xiaohongshu Web"]:::external
        FS["File System (cookies.json)"]:::external
        STDIO["STDIO"]:::external
    end

    CLI -->|"dispatches"| MCP
    STDIO -->|"MCP request"| MCP
    MCP -->|"returns response"| STDIO

    CLI -->|"init command"| Auth
    Auth -->|"launch browser"| Browser
    Browser -->|"user login flow"| Auth
    Auth -->|"store cookies"| Cookie
    Cookie -->|"read/write cookies"| FS

    MCP -->|"fetch/search request"| Tools
    Tools -->|"read cookies"| Cookie
    Tools -->|"HTTP/Browser request"| Web
    Web -->|"HTML/JSON response"| Detail
    Detail -->|"extract & format"| Tools
    Tools -->|"return data"| MCP

    Auth -->|logs| Logger
    Cookie -->|logs| Logger
    Tools -->|logs| Logger
    Detail -->|logs| Logger
    MCP -->|logs| Logger
    CLI -->|logs| Logger

    click CLI "https://github.com/ifuryst/rednote-mcp/blob/main/src/cli.ts"
    click MCP "https://github.com/ifuryst/rednote-mcp/blob/main/src/index.ts"
    click Auth "https://github.com/ifuryst/rednote-mcp/blob/main/src/auth/authManager.ts"
    click Cookie "https://github.com/ifuryst/rednote-mcp/blob/main/src/auth/cookieManager.ts"
    click Tools "https://github.com/ifuryst/rednote-mcp/blob/main/src/tools/rednoteTools.ts"
    click Detail "https://github.com/ifuryst/rednote-mcp/blob/main/src/tools/noteDetail.ts"
    click Logger "https://github.com/ifuryst/rednote-mcp/blob/main/src/utils/logger.ts"

    classDef cli fill:#ACE7EF,stroke:#036,stroke-width:2px
    classDef core fill:#BCEBCB,stroke:#036,stroke-width:2px
    classDef external fill:#FFD699,stroke:#036,stroke-width:2px
```
