MCP Tool Arguments Data Types and Schemas in the Xiaohongshu MCP Server

The xpzouying/xiaohongshu-mcp server defines strict Go structs with jsonschema tags for all MCP tool arguments, enabling automatic JSON validation and type conversion from LLM clients to the underlying Xiaohongshu API handlers.

The Model Context Protocol (MCP) implementation in xpzouying/xiaohongshu-mcp exposes Xiaohongshu (Little Red Book) functionality through typed tool interfaces. Each MCP tool accepts a specific argument struct defined in mcp_server.go, where Go field types and jsonschema struct tags enforce validation rules and provide semantic descriptions for LLM agents.

Overview of MCP Tool Argument Architecture

The server registers 10 active tools in mcp_server.go, each binding to a strongly-typed argument struct. When an LLM client invokes a tool, the server unmarshals the JSON payload into these structs, validates against schema constraints, and converts the data to map[string]interface{} for the internal handlers.

The argument structs utilize Go struct tags for dual purpose:

• json:"fieldname" handles JSON marshaling
• jsonschema:"description" provides validation metadata and human-readable field documentation

Complete Schema Reference for All MCP Tools

Content Publishing Tools

PublishContentArgs

Defined at lines 18‑28 of mcp_server.go【https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go#L18-L28】

Field	Go Type	JSON Schema Tag
Title	string	内容标题（小红书限制：最多20个中文字或英文单词）
Content	string	内容正文（小红书限制：最多1000个中文字或英文单词）
Images	[]string	图片列表，支持URL或本地文件路径
Tags	[]string	标签列表
ScheduleAt	string	发布时间，格式为ISO 8601
IsOriginal	bool	是否原创
Visibility	string	可见性：公开可见、仅自己可见、粉丝可见
Products	[]string	关联商品列表

PublishVideoArgs

Defined at lines 30‑39 of mcp_server.go【https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go#L30-L39】

Similar to PublishContentArgs but replaces Images with a single Video field (string type) for video file paths or URLs.

Feed Discovery and Retrieval Tools

SearchFeedsArgs

Defined at lines 41‑45 of mcp_server.go【https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go#L41-L45】

• Keyword (string): Search query with jsonschema tag 搜索关键词
• Filters (FilterOption): Nested struct for advanced filtering

FilterOption (Nested)

Defined at lines 47‑54 of mcp_server.go【https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go#L47-L54】

Contains optional filter fields with omitempty tags:

• SortBy, NoteType, PublishTime, SearchScope, Location

FeedDetailArgs

Defined at lines 56‑65 of mcp_server.go【https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go#L56-L65】

Controls comment loading behavior with fields:

• FeedID (string): 小红书笔记ID，从Feed列表获取
• XsecToken (string): Security token for API access
• LoadAllComments (bool): Flag to load all comments
• Limit (int): Maximum notes to retrieve
• ClickMoreReplies (bool): Expand nested replies
• ReplyLimit (int): Maximum replies per comment
• ScrollSpeed (string): normal or fast for pagination timing

Note: These fields map to the CommentLoadConfig struct in types.go (lines 38‑46) that the internal crawler uses.

Social Interaction Tools

PostCommentArgs

Defined at lines 73‑77 of mcp_server.go【https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go#L73-L77】

• FeedID (string): Target note identifier
• XsecToken (string): Session security token
• Content (string): 评论内容

ReplyCommentArgs

Defined at lines 80‑86 of mcp_server.go【https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go#L80-L86】

Extends comment functionality with:

• CommentID (string): 目标评论ID，从评论列表获取 (omitempty)
• UserID (string): Target user identifier

LikeFeedArgs

Defined at lines 89‑93 of mcp_server.go【https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go#L89-L93】

• Unlike (bool): 是否取消点赞 (optional, omitempty)

FavoriteFeedArgs

Defined at lines 96‑100 of mcp_server.go【https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go#L96-L100】

• Unfavorite (bool): 是否取消收藏 (optional, omitempty)

User Profile Tools

UserProfileArgs

Defined at lines 67‑71 of mcp_server.go【https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go#L67-L71】

• UserID (string): 小红书用户ID，从Feed列表获取
• XsecToken (string): Security token

Zero-Argument Tools

Three authentication and utility tools accept no arguments:

• list_feeds - Retrieves default feed without parameters
• check_login_status - Validates session cookies
• get_login_qrcode - Initiates QR code authentication flow
• delete_cookies - Clears session storage

JSON Schema Validation Implementation

The server uses the jsonschema struct tag convention to generate validation metadata. When MCP clients discover tools, they receive these schemas as part of the tool definition, allowing LLMs to construct valid payloads automatically.

For example, the Title field in PublishContentArgs includes the constraint description directly in the tag, informing the LLM that Xiaohongshu limits titles to 20 Chinese characters or English words.

Practical Usage Examples

Publishing Content with Full Metadata

{
  "tool_name": "publish_content",
  "arguments": {
    "title": "我的旅行日记",
    "content": "这次去到了云南，风景超赞！",
    "images": [
      "https://example.com/photo1.jpg",
      "/Users/alice/pictures/photo2.jpg"
    ],
    "tags": ["旅行", "云南"],
    "schedule_at": "2024-05-01T10:00:00+08:00",
    "is_original": true,
    "visibility": "公开可见",
    "products": ["防晒霜SPF50"]
  }
}

The server validates this against PublishContentArgs before forwarding to handlePublishContent in the internal API layer.

Advanced Feed Search with Filters

{
  "tool_name": "search_feeds",
  "arguments": {
    "keyword": "手帐",
    "filters": {
      "sort_by": "最新",
      "note_type": "图文",
      "publish_time": "一周内",
      "search_scope": "已关注",
      "location": "同城"
    }
  }
}

The nested FilterOption struct validates optional filter combinations, with all fields marked omitempty in the Go definition.

Deep Comment Loading Configuration

{
  "tool_name": "get_feed_detail",
  "arguments": {
    "feed_id": "6412a1b3c4d5e6f78g9h0i1j",
    "xsec_token": "eJzN1...",
    "load_all_comments": true,
    "limit": 50,
    "click_more_replies": true,
    "reply_limit": 15,
    "scroll_speed": "normal"
  }
}

This maps to FeedDetailArgs and subsequently converts to CommentLoadConfig in types.go to control the crawler's scroll and pagination behavior.

Interactive Social Actions

{
  "tool_name": "post_comment_to_feed",
  "arguments": {
    "feed_id": "6412a1b3c4d5e6f78g9h0i1j",
    "xsec_token": "eJzN1...",
    "content": "好棒的内容！👍"
  }
}

The PostCommentArgs schema requires exactly three string fields, rejecting payloads missing the xsec_token security parameter.

Summary

• All MCP tools in xpzouying/xiaohongshu-mcp use strongly-typed Go structs defined in mcp_server.go (lines 18‑100)
• Argument validation relies on jsonschema struct tags that describe field semantics and constraints
• Publishing tools (publish_content, publish_with_video) accept complex media arrays and scheduling parameters
• Feed operations support nested filter schemas and pagination controls via SearchFeedsArgs and FeedDetailArgs
• Social interactions require security tokens (XsecToken) alongside target identifiers for authentication
• Zero-argument tools handle authentication state (check_login_status, get_login_qrcode) without client payload

Frequently Asked Questions

How does the server validate incoming MCP tool arguments?

The server uses Go's jsonschema struct tags defined in mcp_server.go to validate JSON payloads against the expected schema. When a tool is invoked, the server unmarshals the JSON into the specific argument struct (e.g., PublishContentArgs), where field types enforce data correctness and tags provide semantic validation metadata that MCP clients use to construct valid requests.

What data type should I use for the Images field in publish_content?

The Images field accepts a slice of strings ([]string) where each element can be either a remote URL (https://...) or an absolute local file path (/Users/...). The schema tag indicates support for both formats, and the internal handler in handlers_api.go processes these paths to upload media to Xiaohongshu's servers.

Why do some tools like list_feeds not have argument structs?

Tools such as list_feeds, check_login_status, get_login_qrcode, and delete_cookies operate on session state or default parameters, requiring no client input. These are registered in mcp_server.go with nil argument handlers, indicating they accept empty JSON objects {} or null arguments in the MCP protocol.

Where is the XsecToken parameter obtained for feed-related operations?

According to the schema definitions in mcp_server.go, the XsecToken is a security token required for authenticated API calls. LLM clients must extract this token from previous feed list responses or user profile data, as indicated by the jsonschema descriptions: 小红书笔记ID，从Feed列表获取 and similar annotations across FeedDetailArgs, UserProfileArgs, and interaction structs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}