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

> Understand MCP tool arguments schemas and data types in the Xiaohongshu MCP server. Learn how Go structs and jsontags ensure automatic JSON validation and type conversion.

- Repository: [zy/xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)
- Tags: api-reference
- Published: 2026-03-09

---

**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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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)**【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)**【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)**【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)**【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)**【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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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)**【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)**【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)**【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)**【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)**【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

```json
{
  "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

```json
{
  "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

```json
{
  "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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/types.go) to control the crawler's scroll and pagination behavior.

### Interactive Social Actions

```json
{
  "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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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.