# platform-xhs-mcp

Standalone Xiaohongshu platform adapter service for OpenClaw and Hermes.

This project is intentionally isolated from LongClaw and Hermes main apps.
It exposes a small MCP tool surface and keeps the actual platform integration
behind a dedicated service layer.

## Scope of the first scaffold

- `xhs.health_check`
- `xhs.upload_media`
- `xhs.publish_post`
- `xhs.list_comments`
- `xhs.reply_comment`

The current scaffold is browser-first with reserved Open API extension points.
It does not pretend to be fully production-ready yet. Browser selectors,
official endpoint mappings, and account credentials still need to be filled in.

## Recommended architecture

- `src/platform_xhs_mcp/mcp_server.py`
  - MCP tool definitions
- `src/platform_xhs_mcp/service.py`
  - business actions and mode routing
- `src/platform_xhs_mcp/adapters/browser.py`
  - browser automation adapter
- `src/platform_xhs_mcp/adapters/open_api.py`
  - official API adapter
- `src/platform_xhs_mcp/config.py`
  - config loading and validation

## Setup

1. Create a Python virtual environment.
2. Install dependencies:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python -m playwright install chromium
```

3. Copy `config/xhs.config.example.json` to `config/xhs.config.json`.
4. Fill in your account id, browser profile/session settings, and optional Open API fields.
5. Start the MCP server:

```powershell
python run_server.py
```

## Important notes

- Default publish mode should remain `draft` until the browser selectors and
  risk-control policy are fully verified.
- Keep one dedicated test account for automation before using any production
  account.
- Do not expose raw cookies, tokens, or session files into LongClaw logs.

## Browser session modes

The scaffold supports two browser session strategies:

1. `storage_state`
   - Use a Playwright-exported storage state JSON file.
   - Safer and easier to version/control per test account.

2. `persistent_profile`
   - Reuse an existing logged-in browser profile.
   - Requires:
     - `channel`: `chrome`, `msedge`, or another Chromium-compatible channel
     - `user_data_dir`: browser user data root
     - `profile_directory`: usually `Default` or `Profile 1`

For a first real test with your current logged-in Xiaohongshu browser, `persistent_profile`
is the correct starting point.

Important:

- If you run automation against a live Edge/Chrome profile, close the browser first.
- Chromium profiles are commonly locked while the browser is open.
- For safer long-term automation, export a dedicated `storage_state.json` from a
  separate test profile instead of reusing your daily browser session forever.
