SnowLuma v2.4.2 source snapshot

packages/mcp/AGENT_FEATURES.md

@@ -0,0 +1,391 @@
+# MCP agent features
+
+These additions preserve the existing tool names, action parameters, text results,
+and read/write gates. No endpoint is contacted by catalog tools or by a local
+runtime overview. The action catalog remains a bundled snapshot, not a claim
+about the connected server's capabilities.
+
+## Protocol compatibility and catalog caching
+
+The same `snowluma-mcp` stdio command accepts MCP `2026-07-28` clients and
+older clients using the `initialize` handshake. The official server SDK selects
+the protocol for the connection. Modern clients can use `server/discover` and
+per-request metadata without initialization; legacy clients keep their existing
+configuration. This does not add a publicly listening MCP HTTP endpoint.
+
+Modern replies carry the protocol's completion and server metadata. Cache hints
+depend on whether a response contains static catalog data or private live state:
+
+| Response                                              | Lifetime                                      | Scope                                                                          |
+| ----------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
+| `tools/list`                                          | Five minutes                                  | `private`; mode and client capabilities affect tool metadata and availability. |
+| `resources/list`                                      | Five minutes, or zero when events are enabled | `private`; UI capability and active event resources affect the list.           |
+| `resources/templates/list`                            | Five minutes                                  | `public`; the bundled template list is static.                                 |
+| `resources/read` for the action catalog or message UI | Five minutes                                  | `public`; these are bundled static assets.                                     |
+| `resources/read` for event resources                  | Zero                                          | `private`; these contain account events and connection state.                  |
+
+These are client cache hints, not a server-side result cache. Tool calls,
+including the runtime overview, never receive these hints. The SDK omits
+modern-only result fields for legacy clients. Unsupported protocol revisions
+are rejected before action execution; they do not trigger an action retry.
+
+## Call tracing
+
+Every tool invocation gets a W3C trace context. Clients can supply `traceparent`
+and optional `tracestate` in the tool request's `_meta`:
+
+```json
+{
+  "name": "query_action",
+  "arguments": { "action": "get_status" },
+  "_meta": {
+    "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
+  }
+}
+```
+
+MCP preserves a valid caller trace ID and creates a new span ID for each call.
+Without a valid parent it creates an independent trace. The returned
+`_meta.traceparent` identifies that call, including tool errors; the existing
+text and structured result envelopes remain unchanged. This works with both
+protocol generations.
+
+Ordinary requests, streams, automatic upload chunks, and upload cleanup forward
+the call context in HTTP headers, never in OneBot action parameters. Concurrent
+calls keep independent headers. To follow a call, match its traceparent in MCP
+stderr diagnostics with SnowLuma's `http_trace` entry, then follow that entry's
+existing `req#` through action lifecycle logs. SnowLuma correlation requires
+TRACE logging and a valid authenticated HTTP request; the remote trace ID does
+not replace its local request ID. No telemetry exporter is installed.
+
+MCP's call diagnostics contain the known tool name, traceparent, outcome, failure
+category and duration, not message contents, tokens, file paths or arbitrary metadata.
+`tracestate` is validated with a maximum of 512 characters and 32 members; it is
+forwarded but not logged. Invalid trace metadata produces a fixed diagnostic and
+does not reject an otherwise valid action. `baggage` is neither forwarded nor
+logged. Trace identifiers are correlation data, not authentication or permission.
+
+## Optional execution services
+
+Existing configurations keep working. Input completion and message previews are
+additive tools; event connections and durable tasks require explicit configuration.
+For example, set these variables in the MCP client's server environment, replacing
+addresses, credentials and paths with the intended SnowLuma instance:
+
+```json
+{
+  "SNOWLUMA_MCP_MODE": "write",
+  "SNOWLUMA_MCP_ENDPOINT": "http://127.0.0.1:3000/",
+  "SNOWLUMA_MCP_TOKEN": "<your access token>",
+  "SNOWLUMA_MCP_EVENTS_URL": "ws://127.0.0.1:3001/event",
+  "SNOWLUMA_MCP_TASK_DIR": "/absolute/private/mcp-tasks",
+  "SNOWLUMA_MCP_UPLOAD_ROOT": "/absolute/allowed/uploads"
+}
+```
+
+The HTTP and WebSocket addresses are independently configured server endpoints;
+the WebSocket address is never guessed from the HTTP address. Events reuse
+`SNOWLUMA_MCP_TOKEN` in an authorization header. Upload and task directories are
+on the MCP host. Omit services that are not needed. Docs mode remains offline.
+
+## Completing missing parameters
+
+`query_action_with_input` and `invoke_action_with_input` use the same arguments,
+action lookup and mode gates as `query_action` and `invoke_action`. The existing
+tools continue to behave exactly as before. The additional tools ask for input
+only when a field listed in the action catalog's top-level `required` array is
+absent; they do not infer conditional requirements or optional values.
+
+For example, `invoke_action_with_input` with
+`{"action":"send_group_msg","params":{"group_id":20001}}` asks for the
+missing message. The form contains one `params_json` string, whose contents are
+a JSON object such as `{"message":"Hello"}`. The answer is validated against
+the missing fields' catalog schemas before normal action execution. Already
+provided fields, the action name and execution options cannot be overwritten;
+extra answer fields are rejected. A declined, cancelled or invalid answer does
+not execute the action.
+
+Clients must advertise form elicitation support. Modern clients receive
+`resultType: "input_required"` and resume using the SDK's request-state and input
+response mechanism. Legacy clients with elicitation support use the SDK's
+`elicitation/create` flow. Clients without form support receive a tool error and
+can provide complete arguments to the original tools instead.
+
+Continuation state is signed, tied to the original tool and arguments, expires
+after ten minutes and is consumed once before execution. Concurrent or repeated
+answers cannot execute the same continuation twice. A runtime holds at most 256
+pending prompts; restart invalidates them rather than replaying work. Completed
+arguments bypass the input round entirely. This feature is not a general approval
+gate and does not add confirmation prompts to existing action calls.
+
+## Live event resources
+
+With `SNOWLUMA_MCP_EVENTS_URL` configured, read and write modes expose
+`subscribe_events` and `unsubscribe_events`. The URL must use `ws:` or `wss:`
+without embedded credentials, query parameters or fragments. Listing tools or
+resources does not connect; only `subscribe_events` opens the event connection.
+
+```json
+{
+  "self_id": 10001,
+  "types": ["message", "notice"],
+  "group_ids": [20001],
+  "user_ids": [30001]
+}
+```
+
+Use the expected logged-in account for required `self_id`; obtain it through
+`get_login_info` if necessary. Every incoming event must match this account.
+An account mismatch or malformed event stops the connection and is surfaced.
+The optional types are `message`, `notice` and `request`; omitted types mean all
+three. `message_sent` is included in the message category. Group and user filters
+are combined with AND, so a group filter excludes events without a matching
+`group_id`. Each ID filter accepts at most 100 distinct positive integers.
+
+The result contains a canonical `snowluma://onebot/events/<id>` resource URI.
+Read it with `resources/read`; use `?after=<next_cursor>` on subsequent reads to
+obtain newer buffered entries. Cursors belong to that one resource. The response
+includes `status`, `next_cursor`, `oldest_cursor`, `dropped_events`, `gap` and
+`notification_failed`. Reads do not consume events. Only events received after
+subscription creation are available; this is not message-history storage.
+
+Each resource retains at most 256 events and 1 MiB of event data. One runtime
+supports at most 16 resources, sharing one account connection. Incoming frames
+are limited to 256 KiB. Buffer eviction and disconnection remain visible through
+the cursor/gap and status fields; the service does not silently reconnect or
+claim missing events were recovered. Release existing resources before changing
+accounts or creating a new connection after disconnection.
+
+For updates, use the **canonical URI without `?after`**:
+
+- Modern clients use `subscriptions/listen` with `resourceSubscriptions: [uri]`
+  (the TypeScript SDK exposes `client.listen(...)`). Closing that notification
+  stream does not release the event buffer; call `unsubscribe_events` explicitly.
+- Legacy clients first call `resources/subscribe` with the canonical URI, then
+  receive `notifications/resources/updated`. `resources/unsubscribe` also releases
+  that event resource. The explicit unsubscribe tool works for both generations.
+
+An update notification indicates that the resource changed; fetch the resource
+to read its data. Releasing the last resource closes the WebSocket. Closing the
+MCP connection releases its event resources and buffers. No event operation
+executes a OneBot business action or sends a QQ message.
+
+## Persistent background transfers
+
+Set an absolute `SNOWLUMA_MCP_TASK_DIR` and use write mode to enable persistent
+tasks. Task tools additionally require MCP `2026-07-28` clients advertising
+`extensions: {"io.modelcontextprotocol/tasks": {}}`. Legacy clients keep the
+existing synchronous execution tools; this server does not expose the obsolete
+`tasks/list` or `tasks/result` protocol methods.
+
+`invoke_action_background` takes the same arguments as `invoke_action`, but only
+accepts catalog actions marked as streams. For example, it can run
+`upload_file_stream` with `execution.input_file` inside the configured upload root.
+It writes the task record before starting work and returns a `resultType: "task"`
+handle. Ordinary actions continue through the existing tools. The current
+background transfer entry does not automatically combine with `_with_input`;
+provide the required transfer parameters before starting it.
+
+- `tasks/get` with `{ "taskId": "..." }` returns current state and, when finished,
+  the saved result or error. A `completed` task can contain a failed business
+  response: inspect the nested result's diagnostics, `status` and `retcode`.
+- `tasks/cancel` requests cooperative cancellation. Cancellation does not undo
+  remote effects, and a successful completion already in flight may win the race.
+  Poll the task again for its final state.
+- `tasks/update` accepts input responses only for outstanding task input requests.
+  It is the protocol lifecycle endpoint, not an arbitrary task-editing API. The
+  current background transfer entry does not itself request interactive input.
+- `list_tasks` is an MCP tool returning task metadata without result bodies. It
+  accepts optional `cursor` and `limit` (1–100; default 50) and returns `nextCursor`
+  when another page is available.
+
+Task handles advertise `pollIntervalMs: 1000` and `ttlMs: null`. Results survive
+restart and are not automatically expired or deleted. Restart marks unfinished
+work failed with an explicit **unknown remote outcome** message; it never
+replays the operation. This persists transfer status/results, not resumable
+upload or download execution. There are at most four concurrent tasks and a
+16 MiB limit on each persisted task record.
+
+Storage uses an exclusive runtime lease, private directories/files (0700/0600 on
+POSIX) and validated records. Corruption, permission errors and write failures
+remain errors. The directory is bound to a digest of the effective mode, endpoint
+and token; changing that configuration rejects reuse of the directory. Choose a
+new private directory for the new configuration and retain the old history.
+Credentials are not stored in the scope record, but task results can contain
+private account data and should be protected accordingly.
+
+## Message preview panel
+
+`preview_message` is available in every mode and only constructs a draft:
+
+```json
+{
+  "message_type": "group",
+  "target_id": 20001,
+  "text": "Hello",
+  "reply_to": -123456
+}
+```
+
+Use `private` for a private conversation. `target_id` must be a positive safe
+integer; optional `reply_to` is a non-zero signed 32-bit message ID. The preview
+supports literal text and optional quoted replies, not media rendering. Text
+that resembles message control codes remains literal text.
+
+Every client receives the same readable text draft, `can_send` flag and
+corresponding `invoke_action` arguments. Only clients advertising the MCP Apps
+extension `io.modelcontextprotocol/ui` with MIME type
+`text/html;profile=mcp-app` receive the tool's UI metadata and listed UI resource.
+The panel is a bundled, self-contained HTML asset built with the official Apps
+client. It loads no external scripts, fonts or media, opens no network connection
+of its own and displays external text without interpreting it as HTML. A missing
+packaged asset is a visible packaging error.
+
+Loading the panel sends nothing. Its send button calls the existing
+`invoke_action` through the host only after the user clicks, and the server's
+write gate still applies. Read/docs mode or a host without server-tool support
+keeps sending disabled. The panel prevents duplicate clicks and does not retry
+failed or uncertain sends; create a new draft only after checking the outcome.
+Successful acknowledgement is not proof of delivery or rendering in QQ.
+
+## Action result schemas and examples
+
+`get_action` and `snowluma://onebot/actions` include `returnsSchema` and
+`examples` for every bundled action, including aliases. Both are authored beside
+the OneBot action definition and copied into the generated catalog. List/search
+responses remain compact; use `get_action` to retrieve the complete contract.
+
+`returnsSchema` describes successful OneBot **`data`**, not the full OneBot
+envelope or the MCP `structuredContent` wrapper. Check `status` and `retcode`
+before reading it. For stream actions, the schema describes each successful
+frame's `data`; MCP downloads instead return saved-file metadata and generic
+streams return a frame collection. Error frames and failed envelopes are not
+successful results. Unsupported actions use `{ "not": {} }` because they have no
+successful result. Compatibility placeholders explicitly document their limits.
+
+Each example has `summary`, `params`, and optional `notes` explaining prerequisites
+and identifier sources. These are illustrative calls, never run by catalog tools.
+Replace example account/group IDs, opaque handles and paths with values from the
+current account before execution. Notes identify operations with multiple steps,
+such as completing an upload after all chunks have been acknowledged.
+
+For example, `get_action({ "name": "get_msg" })` documents signed message IDs:
+
+```json
+{
+  "action": "get_msg",
+  "params": { "message_id": -123456 }
+}
+```
+
+Pass this object to `query_action` with a real message ID. Writes and streams use
+`invoke_action` in write mode. For automatic upload, pass
+`{ "action": "upload_file_stream", "execution": { "input_file": "/allowed/hello.txt" } }`
+to `invoke_action`, with a real file inside the configured upload root. Ordinary
+action paths refer to the SnowLuma server, whereas `execution.input_file` and MCP
+download paths refer to the MCP host.
+
+Do not substitute zero for a signed message ID. Resource-only forward uploads
+and flash shares have a documented `message_id: 0` sentinel; it cannot be used
+for message lookup or recall. Also preserve `null` versus `{}`, optional fields,
+and decimal strings such as media `file_size` exactly as documented.
+
+## Structured results
+
+Completed tool results use the advertised `outputSchema` and return
+`structuredContent` alongside the existing `content` text block. Modern
+`input_required` and background task handles are protocol continuations; inspect
+their `resultType` first and obtain the completed result through the relevant
+continuation or task lifecycle:
+
+```json
+{
+  "result": { "status": "ok", "retcode": 0, "data": { "message_id": -123 } },
+  "diagnostics": { "outcome": "success" }
+}
+```
+
+`result` is the original payload, including arrays such as the category list.
+It is `null` for an MCP tool error. `diagnostics.outcome` is `success`, `failed`,
+or `unknown`; failures can include `kind`, `message`, and `next_step`.
+
+Ordinary OneBot business failures still return their original envelope without
+setting `isError`. Their structured diagnostics indicate failure. An asynchronous
+acknowledgement or a response that does not confirm success has outcome `unknown`.
+Transport errors and existing tool/stream errors still set `isError: true`.
+Error categories describe known causes; unclassified execution errors are not
+guessed from message strings. Neither tool execution nor connection checks retry
+automatically. Negative message IDs remain valid and are preserved unchanged.
+
+## Search, filters, and pagination
+
+`search_actions` retains its original case-insensitive substring matching and
+catalog order unless `match: "keywords"` is requested. Keyword mode combines
+space-separated terms with AND, recognizes a small set of common Chinese/English
+synonyms, and ranks exact action names or aliases first.
+
+```json
+{
+  "query": "群 禁言",
+  "match": "keywords",
+  "read_only": false,
+  "stream": false,
+  "limit": 10,
+  "offset": 0
+}
+```
+
+Both `list_actions` and `search_actions` accept optional `category`, `read_only`,
+`stream`, `limit` (1–200), and `offset` (non-negative integer). Omitting pagination
+returns the complete matching list and preserves `{count, actions}`. With `limit`
+or `offset`, `count` is the returned page size, `total` is the matching count, and
+`next_offset` is the next page offset or `null`. Pagination applies to the bundled
+catalog; it does not issue server requests.
+
+## Runtime overview
+
+`get_runtime_info({})` returns:
+
+- The effective `mode`, `execution_enabled`, and `write_enabled`.
+- The bundled catalog version and action count. `server_support` remains
+  `unknown`; a matching version alone does not prove action support.
+- In execution mode, effective request timeout, file size and directory quota
+  limits, concurrent stream limit, download directory, upload root, and whether
+  automatic upload is enabled. In docs mode, `transport` is `null`.
+- `connection_checked: false`. Local configuration is not proof of a live login.
+
+The overview does not expose the endpoint, access token, or authorization headers.
+Configured file paths are paths on the MCP host. All stream actions still require
+write mode; `upload_enabled` describes the configured file root, not permission
+to bypass that gate.
+
+`get_runtime_info({"check_connection": true})` is available only in read/write
+mode with a client. It explicitly queries `get_login_info`, `get_status`, and
+`get_version_info`, using the ordinary read-only execution gate. Each entry under
+`checks` contains its original response and diagnostics. Partial failures remain
+visible. Check the returned status data for online state; a successful HTTP
+exchange alone does not establish that the account is online.
+
+## Cancellation and progress
+
+MCP cancellation now reaches ordinary HTTP calls as well as stream actions,
+including response-body reads. Ordinary calls retain their request timeout;
+streams retain separate connection and per-read idle timeouts. A cancelled call
+does not automatically retry. Cancellation or timeout can leave a remote write's
+outcome unknown: stopping the wait does not undo an operation already received
+by SnowLuma.
+
+When a caller includes `_meta.progressToken`, stream execution emits standard
+`notifications/progress` notifications with the same token. File downloads report
+decoded bytes written; automatic uploads report bytes acknowledged by the server.
+Generic streams report accepted frame counts. A total is included only when a
+positive file size is known. Empty files and unknown-size downloads omit it.
+
+Notifications are limited to one per 250 ms, plus the final pending update before
+a successful response. Values increase, notifications stop on cancellation or
+completion, and callers without a progress token receive none. Notification
+delivery failures are surfaced. Progress describes transferred data, not final
+commit: only a successful tool result confirms file validation and completion.
+
+The existing file containment, quotas, partial-file cleanup and upload-reset
+behavior are unchanged. File bytes never appear in progress messages.