# qzone-mcp

Independent local MCP wrapper for `astrbot_plugin_qzone_ultra` + NapCat.

This is an independent community integration. It is not affiliated with,
endorsed by, or maintained by QZoneUltra, NapCatQQ, AstrBot, or Tencent.

Architecture:

`Codex -> MCP (stdio) -> adapter -> QzoneUltra daemon (127.0.0.1) -> QZone`

`NapCat (127.0.0.1) -> credentials -> adapter -> daemon /bind`

The Ultra source is treated as an external dependency and is not modified or copied into this project.

## Credits and licensing

- [astrbot_plugin_qzone_ultra](https://github.com/diaomin66/astrbot_plugin_qzone_ultra)
  is an external runtime dependency by 雪碧bir, licensed under MIT. Its source
  is not bundled in this repository.
- [NapCatQQ](https://github.com/NapNeko/NapCatQQ) supplies the external QQ
  login and OneBot runtime. Its source and binaries are not bundled in this
  repository. Users must install it separately and comply with its own
  Limited Redistribution License, including its non-commercial-use terms.
- This MCP wrapper is licensed under the MIT license in [LICENSE](LICENSE).

See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for the exact upstream
references used by this project.

## Safety boundary

- NapCat and Qzone daemon URLs are rejected unless they use `127.0.0.1` or `localhost`.
- Cookie/CSRF values are only used internally for daemon binding.
- MCP results are recursively sanitized to remove credential-like keys.
- Cookie values are not intentionally logged.

## Install

1. Keep/clone QzoneUltra somewhere on disk and install its own requirements there.
2. Install this MCP:

```powershell
cd D:\qzone-mcp
python -m pip install -e .
```

3. Set environment variables from `.env.example` in your Codex MCP configuration.

Example Codex MCP config:

```toml
[mcp_servers.qzone]
command = "python"
args = ["-m", "qzone_mcp"]

[mcp_servers.qzone.env]
NAPCAT_URL = "http://127.0.0.1:3000"
NAPCAT_TOKEN = "YOUR_NAPCAT_TOKEN"
QZONE_ULTRA_ROOT = "D:\\path\\to\\astrbot_plugin_qzone_ultra"
QZONE_DATA_DIR = "D:\\qzone-mcp-data"
QZONE_MEDIA_ROOT = "D:\\qzone-mcp-media"
QZONE_DAEMON_PORT = "18999"
QZONE_AUTO_START_DAEMON = "true"
QZONE_AUTO_BIND = "true"
```

If an Ultra daemon is already running, set `QZONE_DAEMON_SECRET` to the same secret and optionally set `QZONE_AUTO_START_DAEMON=false`.

## First test

Ask Codex to call `qzone_status` first. It should verify:

- local daemon reachable;
- NapCat returns the logged-in QQ number;
- QZone cookie exists;
- `p_skey` exists if NapCat exposes the required QZone cookie;
- daemon accepts the internal bind.

Only after that call `qzone_publish`.

## Tools in v0.3

- `qzone_status`
- `qzone_list_posts`
- `qzone_get_post`
- `qzone_publish` (direct publish; text + multiple local images)
- `qzone_prepare_publish` (preview only; returns one-time confirmation token)
- `qzone_confirm_publish` (publishes a prepared preview)
- `qzone_like`
- `qzone_unlike`
- `qzone_comment`
- `qzone_reply_comment`
- `qzone_delete`
- `qzone_visitors`

Video is intentionally left out of the first version.


## v0.2 notes

- Keeps the existing direct publish flow unchanged.
- Adds an optional two-step preview/confirm publish flow to reduce accidental posts.
- Retries once with a fresh NapCat QZone credential bind when the daemon reports an authentication/login failure.
- Tightens local-only URL validation using parsed loopback hostnames (including `::1`) instead of string prefixes.
- Multi-image input continues to use the existing `images: list[str]` path and is validated against `QZONE_MEDIA_ROOT`.
- `QZONE_PUBLISH_PREVIEW_TTL` controls preview-token lifetime in seconds (default `600`).


## v0.3 notes

- Keeps all v0.2 behavior and APIs unchanged.
- Confirms feed listing, post detail, comments, replies, delete, and like flows are exposed as MCP tools.
- Adds a dedicated `qzone_unlike` tool so agents do not need to remember `unlike=true`.