wechat-mcp-manual · diff
v2.0.0 to v2.1.0
55 added, 77 removed. Audit A to A.
---
name: wechat-mcp-manual
description: |
- Progressive-disclosure usage manual for the WeChat MCP tool. Read this when you
- need detail beyond the resident action catalog: safe send/reply operations,
- inbound and outbound media, QR login, settings, account ownership, or poller
- recovery. Pulled on demand via action='manual'; it is not required before every
- send.
- version: 2.0.0
- last_changed_at: "2026-09-07T00:00:00Z"
+ Progressive-disclosure usage manual for WeChat/iLink: first safe read, exact
+ IDs, external send/reply, media partials, and standalone poller/setup hazards.
+ Use the schema for routine calls; load this manual for media details,
+ unfamiliar results, setup, or recovery.
+ version: 2.1.0
+ last_changed_at: "2026-09-09T03:15:00Z"
related_files:
- src/lingtai/mcp_servers/ANATOMY.md
- src/lingtai/mcp_servers/wechat/manager.py
- src/lingtai/mcp_servers/wechat/server.py
- src/lingtai/mcp_servers/wechat/_family.py
- src/lingtai/mcp_servers/wechat/plugin.py
- src/lingtai/mcp_servers/wechat/settings.py
- src/lingtai/mcp_servers/wechat/api.py
- src/lingtai/mcp_servers/wechat/media.py
- src/lingtai/mcp_servers/wechat/login.py
- src/lingtai/mcp_servers/wechat/lockfile.py
- src/lingtai/mcp_servers/wechat/reference/operations.md
- src/lingtai/mcp_servers/wechat/reference/media.md
- src/lingtai/mcp_servers/wechat/reference/setup.md
- tests/test_wechat_toolfamily_ltpv2.py
- tests/test_wechat_media_validation.py
- tests/test_wechat_login.py
- tests/test_wechat_settings.py
- tests/test_wechat_config_resolution.py
- ENVIRONMENT_VARIABLES.md
maintenance: |
Tracks the WeChat MCP action catalog and its progressive-disclosure safety,
media, and setup routes; update this router and the owning references when the
provider behavior, setup boundary, settings projection, or public actions change.
---
- # WeChat MCP — usage manual (progressive disclosure)
+ # WeChat MCP
- The `wechat` MCP exposes one strict LTP-v2 tool. The `manual` action returns this
- file on demand; the resident description and action catalog are intentionally
- short so ordinary tool calls do not load operational detail.
+ Use the schema for routine calls; this progressive disclosure guide adds media,
+ setup/recovery and unfamiliar result details, not a per-send reading ritual.
- ## Public family and first-call boundaries
+ ## First safe action
- The root envelope is closed `{action, input, reasoning, summarize?}`. `action`,
- `input`, and `reasoning` are required. `input` is a closed object owned by the
- selected action; host-only fields, aliases, and legacy flat arguments are not
- accepted. The exact public actions are listed below; `settings` is immediately
- before `manual`.
+ ```json
+ {"action":"check","input":{},"reasoning":"find WeChat conversations"}
+ ```
- - `send` and `reply` cause real external side effects. Verify the recipient and
- content first. A provider-accepted request is not proof of delivery and must
- not be automatically replayed.
- - Use a `user_id` returned by `check`, `read`, or `contacts`; do not invent a
- recipient. `reply` needs the `message_id` of an inbound message from `read`.
- - `media_path` is an outbound file operation. Keep the file in the agent's
- allowed working area; text and media can produce a partial outcome.
- - Login and configuration are owner/setup procedures, not messaging actions.
- Never print, paste, or share the admin login QR, bot token, or credentials.
- - iLink `getUpdates` has one consumer per bot account. The MCP holds a per-account
- poller lock and refuses a second poller; after a refresh or recovery, reconcile
- with `read` before replying so a replay cannot cause a duplicate response.
- - `settings` is SHOW-only and `manual` is the route to this guide. Read the
- focused reference only when its topic is needed.
+ Then `read` an exact `user_id` from `check`, `read`, or `contacts`. For `reply`, use
+ an inbound `message_id` from `read`; do not invent recipients. `search` matches
+ inbox bodies by regex; it cannot prove that an outgoing reply is absent.
+ Calls require
+ `action`, closed action-owned `input`, and `reasoning`; optional `summarize` is
+ boolean. The advertised schema owns the action catalog and validation.
- ## Settings anchors
+ ## External effects and recovery
- The settings provider's `comment` values point to these stable anchors. The
- setup reference owns the detail; SHOW remains read-only.
+ `send`/`reply` are real external side effects: obtain authority and verify recipient
+ and content. Success is provider acceptance, not delivery (`delivery_confirmed`
+ is false); never replay an accepted request. `reply` cannot fall back to a new
+ recipient if its inbound target or sender is missing.
- ## setting-config-path
+ `media_path` is a file inside the allowed working directory. Text precedes media;
+ partial results or uncertain errors require reconciliation, not whole-request
+ replay. A missing local sent record does not prove nothing was accepted. Read
+ [operations](reference/operations.md) for result/read-state limits and
+ [media](reference/media.md) for paths, validation and upload stages.
- See [`reference/setup.md#setting-config-path`](reference/setup.md#setting-config-path).
+ `getUpdates` has one consumer per bot account. The per-account lock refuses a
+ second poller; do not delete its lockfile or start another. After refresh, worker
+ failure or recovery, use `read` to reconcile merged inbox/sent history before
+ replying. Local history is context, not a delivery receipt.
- ## setting-base-url
+ Login, configuration and credential replacement require the owner's setup
+ authorization. Avatar sessions must not reconfigure this MCP. Never share the
+ admin login QR, token or credentials. See [setup/recovery](reference/setup.md);
+ host addon activation remains owned by `mcp-manual`.
- See [`reference/setup.md#setting-base-url`](reference/setup.md#setting-base-url).
+ ## Settings SHOW
- ## setting-poll-interval
+ `settings` takes `input={}` and returns the startup snapshot without writing or
+ rereading owner files. Five sensitive rows redact both `current` and `default`;
+ only `poll_interval` is displayed. An unavailable row fails the whole inventory.
+ SHOW grants no configuration authority. Each stable anchor routes directly:
- See [`reference/setup.md#setting-poll-interval`](reference/setup.md#setting-poll-interval).
+ ## setting-config-path
+ [Resolved config source](reference/setup.md#setting-config-path).
- ## setting-allowed-users
+ ## setting-base-url
+ [Endpoint precedence](reference/setup.md#setting-base-url).
- See [`reference/setup.md#setting-allowed-users`](reference/setup.md#setting-allowed-users).
+ ## setting-poll-interval
+ [Polling interval/default](reference/setup.md#setting-poll-interval).
- ## setting-bot-token
+ ## setting-allowed-users
+ [Inbound allow-list](reference/setup.md#setting-allowed-users).
- See [`reference/setup.md#setting-bot-token`](reference/setup.md#setting-bot-token).
+ ## setting-bot-token
+ [Login secret](reference/setup.md#setting-bot-token).
## setting-user-id
-
- See [`reference/setup.md#setting-user-id`](reference/setup.md#setting-user-id).
-
- ## Resident action catalog
-
- | Action | Input and purpose |
- |---|---|
- | `send` | `user_id` plus `text` and/or `media_path`; deliver a new message |
- | `check` | `{}`; list conversations and unread counts |
- | `read` | `user_id`, optional `limit`; read merged inbox/sent history |
- | `reply` | `message_id` plus `text`; respond to a specific inbound message |
- | `search` | `query`, optional `user_id`; regex-search inbox messages |
- | `contacts` | `{}`; list saved contacts |
- | `add_contact` | `user_id` plus `alias`; save a local contact alias |
- | `remove_contact` | `alias` or `user_id`; remove a saved contact |
- | `accounts` | `{}`; list configured account details |
- | `settings` | `{}`; show the read-only startup configuration inventory |
- | `manual` | `{}`; return this progressive-disclosure guide |
-
- All calls still require the root `reasoning` string. Exact schemas, required
- fields, nullability, and validation remain owned by the advertised tool schema.
-
- ## Focused references
-
- | Need | Read |
- |---|---|
- | Send/reply, reading, contacts, account results, errors, and replay-safe operations | [`reference/operations.md`](reference/operations.md) |
- | Outbound attachments, inbound files, magic-byte checks, and partial media delivery | [`reference/media.md`](reference/media.md) |
- | QR login, config/credentials, poller startup, settings SHOW, and recovery | [`reference/setup.md`](reference/setup.md) |
+ [Backend identity](reference/setup.md#setting-user-id).
- These sidecars ship with the package but are not embedded in the `manual` result.
- Use the relative links above; do not infer setup fields or provider behavior from
- memory. Human-facing addon registration and activation remain the host's
- `mcp-manual` procedure, not this provider manual.
+ Sidecars ship with the package but are not embedded in `manual`; follow the
+ relative links only when their detail is needed.