How to Specify Parameters for MCP Tools like `publish_content` in xiaohongshu-mcp

The publish_content tool accepts a JSON payload unmarshaled into the PublishRequest struct in service.go, requiring title, content, and images as mandatory fields while supporting optional scheduling, visibility, and tagging parameters validated before browser automation executes.

The xiaohongshu-mcp project exposes 小红书 (Xiaohongshu) publishing capabilities through the Model Context Protocol (MCP), allowing automated content posting via standardized tool interfaces. When invoking tools like publish_content, parameters are passed as JSON arguments that the server unmarshals into Go structs, validates against business rules, and transforms into Rod-based browser automation commands. Understanding the exact parameter schema ensures successful API calls without validation errors.

Required Parameters

The publish_content tool enforces three mandatory fields defined in the PublishRequest struct in service.go:

• title (string): The note title. Must be ≤ 20 Chinese characters, validated by xhsutil.CalcTitleLength.
• content (string): The main text body of the note.
• images ([]string): Array of image URLs or local file paths. Must contain at least one element. Remote URLs are automatically downloaded via the internal image processor in pkg/downloader.

Optional Parameters and Validation Rules

Beyond the required fields, the tool accepts several optional parameters with specific constraints and defaults:

• schedule_at (string): ISO-8601 timestamp in RFC3339 format. If provided, the time must be ≥ 1 hour and ≤ 14 days from the current moment. Omitting this field triggers immediate publication.
• tags ([]string): Up to 10 hashtags. The UI automatically truncates excess tags if more than 10 are provided.
• is_original (bool): Enables the "原创声明" (original declaration) switch when set to true. Defaults to false.
• visibility (string): Controls note visibility. Accepted values are "公开可见" (public, default), "仅自己可见" (private), or "仅互关好友可见" (mutual followers only).
• products ([]string): Keywords of goods to bind to the note for the "添加商品" (add product) flow.

Parameter Processing Pipeline

When the MCP endpoint receives a payload, the server processes parameters through a specific chain of validation and transformation steps:

1. Extraction: handlePublishContent in mcp_handlers.go extracts fields from the generic MCP args map and logs the values.
2. Validation: The PublishContent method in service.go validates the title length and checks the schedule_at time window constraints.
3. Image Processing: processImages downloads any remote image URLs using the downloader package.
4. Struct Mapping: The validated data builds a PublishImageContent struct defined in xiaohongshu/publish.go.
5. Execution: The struct forwards to xiaohongshu.NewPublishImageAction(...).Publish to execute the browser automation.

Code Examples

REST API Endpoint

Send a direct HTTP POST to /api/v1/publish defined in routes.go:

POST /api/v1/publish HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
  "title": "我的旅行日记",
  "content": "这是一段关于春季徒步的记录。",
  "images": [
    "https://example.com/pic1.jpg",
    "/home/user/pic2.png"
  ],
  "tags": ["#旅行", "#徒步"],
  "schedule_at": "2026-04-01T10:00:00Z",
  "is_original": true,
  "visibility": "仅自己可见",
  "products": ["防晒霜", "登山背包"]
}

MCP Tool Invocation

Call via the MCP SDK using JSON RPC:

{
  "tool": "publishcontent",
  "args": {
    "title": "美食探店",
    "content": "今天尝了新开的咖啡店，味道超棒！",
    "images": ["https://cdn.example.com/coffee.jpg"],
    "tags": ["#咖啡", "#探店"],
    "visibility": "公开可见",
    "is_original": false
  }
}

Minimal Required Payload

Only title, content, and at least one image are mandatory:

{
  "title": "短篇笔记",
  "content": "只要文字即可。",
  "images": ["./local.jpg"]
}

Summary

• Three mandatory fields: title (≤ 20 chars), content, and images (≥ 1 item).
• Scheduling constraints: schedule_at must be 1 hour to 14 days in the future, formatted as RFC3339.
• Visibility options: Public (default), private, or mutual followers only.
• Processing flow: mcp_handlers.go → service.go validation → xiaohongshu/publish.go automation.
• Image handling: Supports both remote URLs (auto-downloaded) and local file paths.

Frequently Asked Questions

What happens if I omit the schedule_at parameter?

If schedule_at is omitted or set to null, the note publishes immediately upon request processing. The system does not queue the content for later delivery.

How does the tool validate title length?

The server calls xhsutil.CalcTitleLength to count Chinese characters. If the title exceeds 20 characters, validation fails before browser automation begins, returning an error to the caller.

Can I mix local file paths and URLs in the images array?

Yes. The images parameter accepts a mix of HTTP/HTTPS URLs and absolute local file paths. The processImages function in service.go automatically detects remote URLs and downloads them via pkg/downloader, while local paths are processed directly.

What error occurs if I provide an invalid visibility value?

Providing a value outside the accepted set ("公开可见", "仅自己可见", "仅互关好友可见") causes the parameter to fall back to the default "公开可见" (public), or may result in a validation error depending on the specific handler implementation in mcp_handlers.go.

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