$ show jobsonlook/xhs-mcp
The repository is an MCP (Model Context Protocol) server designed to interact with Xiaohongshu (Little Red Book) social media platform. It exposes a set of tools via the MCP standard that enable AI assistants to perform actions like checking cookie validity, retrieving home feed, searching notes, fetching note content and comments, and posting comments. The server requires a valid Xiaohongshu cookie obtained from web login for authentication. Architecturally, the application follows a modular design separating the MCP transport layer (implemented using FastMCP in `xhs_mcp/__main__.py`) from the business logic handled by API clients. Two API implementations exist: the original (`xhs_mcp/api/xhs_api.py`) uses curl_cffi and execjs to reverse-engineer and execute JavaScript for generating required anti-bot signatures (X-S, X-T headers), while the v2 version (`xhs_mcp/api/xhs_api_v2.py`) employs Playwright for JavaScript execution in a browser context. The MCP server dynamically registers tools from these API modules, manages server lifecycle with proper resource cleanup, and handles authentication errors by prompting cookie validation. The project demonstrates solid engineering practices with clear separation of concerns, async/await patterns for non-blocking I/O, and environment-based configuration for sensitive data. However, it faces inherent technical drift due to reliance on Xiaohongshu's private undocumented APIs, which are subject to frequent changes that break signature generation mechanisms. The dual API implementations indicate ongoing efforts to adapt to such changes, though they introduce maintenance overhead. Dependency management is modern using uv and Python 3.12, but version constraints (e.g., curl-cffi<0.14.0) may pose future compatibility risks.
The LLM identified 2 files worth highlighting for reuse:
Implements a reusable client for Xiaohongshu's private web API, encapsulating the complexity of generating X-S and X-T signature headers via execjs-obfuscated JavaScript. Provides isolated functions for core operations (home feed, search, note content, comments, posting) that depend only on external libraries (curl-cffi, execjs) and the included JavaScript VM. Demonstrates non-obvious skill in reverse-engineering API signatures and cleanly separating signature generation from HTTP request logic, allowing extraction for use in other projects with minimal modification (primarily supplying a valid cookie and updating the JS blob if needed).
Sets up the Model Context Protocol server using FastMCP with an asynchronous lifespan context for safe resource initialization and cleanup. Registers MCP tools from the API modules, defines error handling for authentication failures, and configures server transport (stdio or HTTP). Exhibits a reusable pattern for MCP server construction that cleanly separates transport concerns from business logic, allowing the same structure to be adapted for different tool sets by replacing the imported API functions and tool registrations while preserving the server lifecycle management.