# xpzouying/xiaohongshu-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/xpzouying/xiaohongshu-mcp
- Repository: https://github.com/xpzouying/xiaohongshu-mcp

## Overview

##### Project type and purpose
- This is a Go-based MCP (Model Context Protocol) service that automates interactions with the Xiaohongshu website via a headless browser.
- It exposes a JSON-RPC/HTTP interface (“MCP server”) for AI clients (Claude, Cursor, VSCode, Gemini, etc.) to call tools like check_login_status, publish_content, list_feeds, search_feeds, get_feed_detail, post_comment_to_feed.

##### File structure
- Top-level Go binaries:
- main.go + app_server.go + routes.go + handlers_api.go + mcp_handlers.go + service.go + middleware.go + streamable_http.go → compose the HTTP/MCP server
- cmd/login/main.go → CLI tool to perform an initial manual login in a browser window
- Domain-specific package: xiaohongshu/ → browser automation for login, feeds, publish, comments
- Utilities:
- pkg/downloader → image download & processing
- cookies/cookies.go → persistence and retrieval of session cookies
- configs/*.go → runtime configuration (headless flag, image settings, username)
- Static assets + docs + examples illustrate usage and integration.

##### Extract key architectural insights from README
- The service starts a headless Chrome (or non-headless when ‑headless=false) and holds cookies in local storage.
- Exposes an HTTP endpoint at localhost:18060/mcp implementing the MCP JSON-RPC API.
- AI clients register the MCP server and invoke “tools” mapped to specific handlers in mcp_handlers.go.
- Each tool handler calls into service.go, which in turn drives the xiaohongshu package that executes browser tasks to perform actions on the real website.

a. Main components
1. Clients: Claude Code CLI, Cursor, VSCode, Gemini CLI, Inspector
2. HTTP/MCP Server (main.go + HTTP router + JSON-RPC layer)
3. API Handlers (handlers_api.go → generic HTTP; mcp_handlers.go → protocol mapping)
4. Service Layer (service.go)
5. Domain/Browser Adapter (xiaohongshu/*)
6. Infrastructure: Headless Chrome / Browser driver (browser/browser.go)
7. Utilities: Cookie Store, Image Downloader, Config loader
8. External System: Xiaohongshu.com website

b. Relationships & data flow
- Client sends JSON-RPC over HTTP → HTTP/MCP Server
- Router forwards to appropriate handler → Handler calls Service Layer
- Service invokes Domain Adapter → Domain Adapter issues browser commands → Chrome navigates to Xiaohongshu → returns HTML/JSON
- Service processes the result → Handler marshals it back to JSON-RPC response → back to Client
- Cookie Store is read/written by Domain Adapter to maintain session between calls

c. Architectural patterns & principles
- Layered architecture: Presentation (HTTP/MCP & routing) → Application (Handlers) → Business (Service) → Integration (xiaohongshu adapter) → Infrastructure (Browser)
- Adapter pattern for decoupling the Service logic from the browser automation details
- Dependency injection via configs package and middleware
- Clear separation of concerns: downloader, cookies, browser, handlers

d. Key technologies & frameworks
- Go standard library for HTTP, JSON-RPC handling
- Chromedp or a custom browser driver (browser/browser.go) for headless Chrome automation
- Model Context Protocol (MCP) over HTTP
- JSON-RPC 2.0
- Go modules (go.mod)
- File-based cookie persistence

##### Essential details to capture
- “cmd/login” as a separate sub-flow for initial authentication
- Headless vs. non-headless mode toggle
- The six MCP tools as sub-components of mcp_handlers.go
- The cookie persistence mechanism that underpins session continuity

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "AI Clients" 
        direction TB
        Claude["Claude CLI"]:::client
        Cursor["Cursor"]:::client
        VSCode["VSCode"]:::client
        Gemini["Gemini CLI"]:::client
        Inspector["Inspector"]:::client
    end

    %% CLI Login Tool
    CLI["CLI Login Tool\n(cmd/login/main.go)"]:::cli

    %% Server Layer
    subgraph "MCP/HTTP Server" 
        direction TB
        Main["main.go"]:::server
        AppSrv["app_server.go"]:::server
        Routes["routes.go"]:::server
        HTTPUtil["streamable_http.go"]:::server
        Middleware["middleware.go"]:::server
    end

    %% Handlers Layer
    subgraph "API Handlers" 
        direction TB
        HTTPHandler["handlers_api.go"]:::handler
        MCPHandler["mcp_handlers.go"]:::handler
    end

    %% Service Layer
    Service["service.go"]:::service

    %% Adapter Layer
    subgraph "Xiaohongshu Adapter" 
        direction TB
        LoginMod["login.go"]:::adapter
        FeedsMod["feeds.go"]:::adapter
        DetailMod["feed_detail.go"]:::adapter
        CommentMod["comment_feed.go"]:::adapter
        PublishMod["publish.go"]:::adapter
        SearchMod["search.go"]:::adapter
        NavigateMod["navigate.go"]:::adapter
        TypesMod["types.go"]:::adapter
    end

    %% Infrastructure
    subgraph "Infrastructure" 
        direction TB
        BrowserDrv["browser/browser.go"]:::infra
        CookieStore["cookies/cookies.go"]:::infra_cylinder
    end

    %% Utilities
    subgraph "Utilities & Configs"
        direction TB
        Images["pkg/downloader/images.go"]:::util
        Processor["pkg/downloader/processor.go"]:::util
        ConfigBrowser["configs/browser.go"]:::config
        ConfigImage["configs/image.go"]:::config
        ConfigUser["configs/username.go"]:::config
    end

    %% External
    Website["xiaohongshu.com"]:::external_cloud

    %% Flows
    Claude -->|JSON-RPC/HTTP| Main
    Cursor -->|JSON-RPC/HTTP| Main
    VSCode -->|JSON-RPC/HTTP| Main
    Gemini -->|JSON-RPC/HTTP| Main
    Inspector -->|JSON-RPC/HTTP| Main

    Main --> |"initialize routes"| Routes
    Main --> |"load configs"| ConfigBrowser
    Main --> |"load configs"| ConfigImage
    Main --> |"load configs"| ConfigUser
    Routes --> |"use middleware"| Middleware
    Routes -->|"route HTTP calls"| HTTPHandler
    Routes -->|"route MCP tools"| MCPHandler

    HTTPHandler -->|"calls"| Service
    MCPHandler -->|"invokes tools"| Service

    Service -->|"drive browser tasks"| NavigateMod

    NavigateMod -->|browser commands| BrowserDrv
    BrowserDrv -->|HTTP/HTML| Website
    Website -->|HTML/JSON| BrowserDrv
    BrowserDrv -->|results| NavigateMod

    subgraph "Adapter Session"
        NavigateMod -->|"read/write cookies"| CookieStore
        CookieStore -->|"persist session"| NavigateMod
    end

    Service -->|"download images"| Images
    Images -->|"process images"| Processor

    CLI -->|manual login| BrowserDrv
    CLI -->|manual login| LoginMod

    %% Click Events
    click Main "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main.go"
    click AppSrv "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/app_server.go"
    click Routes "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/routes.go"
    click HTTPUtil "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/streamable_http.go"
    click Middleware "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/middleware.go"
    click HTTPHandler "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/handlers_api.go"
    click MCPHandler "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_handlers.go"
    click Service "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/service.go"
    click LoginMod "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/login.go"
    click FeedsMod "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/feeds.go"
    click DetailMod "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/feed_detail.go"
    click CommentMod "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/comment_feed.go"
    click PublishMod "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go"
    click SearchMod "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/search.go"
    click NavigateMod "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/navigate.go"
    click TypesMod "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/types.go"
    click BrowserDrv "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/browser/browser.go"
    click CookieStore "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cookies/cookies.go"
    click Images "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/pkg/downloader/images.go"
    click Processor "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/pkg/downloader/processor.go"
    click ConfigBrowser "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/configs/browser.go"
    click ConfigImage "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/configs/image.go"
    click ConfigUser "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/configs/username.go"
    click CLI "https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cmd/login/main.go"

    %% Styles
    classDef client fill:#D5E8D4,stroke:#82B366,color:#274E13
    classDef cli fill:#FFF2CC,stroke:#D6A600,color:#663C00
    classDef server fill:#DAE8FC,stroke:#6C8EBF,color:#274E13
    classDef handler fill:#F8CECC,stroke:#B85450,color:#822727
    classDef service fill:#E1D5E7,stroke:#9673A6,color:#402F4A
    classDef adapter fill:#FFF2CC,stroke:#D6A600,color:#663C00
    classDef infra fill:#FFE6CC,stroke:#D27B00,color:#4D2700
    classDef infra_cylinder fill:#FFE6CC,stroke:#D27B00,color:#4D2700,shape:cylinder
    classDef util fill:#F5F5F5,stroke:#999999,color:#333333
    classDef config fill:#F5F5F5,stroke:#999999,color:#333333
    classDef external_cloud fill:#E0F7FA,stroke:#006064,color:#004D40,shape:cloud
```
