@snowluma/mcp

An MCP server for the SnowLuma OneBot action catalog. It runs in two modes from one binary:

• docs (default) — read-only: every action's docs, parameters, cross-field constraints, and a ready-to-use JSON Schema, so an LLM can answer "what params does set_group_ban take?" without holding the whole catalog in context.
• execution (opt-in) — when pointed at a running OneBot HTTP endpoint, the LLM can also call actions: read-only ones freely, write ones behind a gate.

Docs only (default)

Add to your MCP client (Claude Desktop, Cline, …) — no endpoint, no execution:

{
  "mcpServers": {
    "snowluma": { "command": "npx", "args": ["-y", "@snowluma/mcp"] }
  }
}

Docs tools

• list_actions({ category? }) — lightweight index (name / category / summary / aliases / readOnly / stream).
• get_action({ name }) — full doc for one action incl. inputSchema and readOnly (accepts aliases).
• search_actions({ query }) — fuzzy match over name / summary / aliases.
• list_categories() — categories and their action counts.

Also exposes the whole catalog as a resource: snowluma://onebot/actions.

Execution (opt-in)

Point the server at a running SnowLuma instance's OneBot HTTP endpoint (the httpServer network adapter) and it gains two execution tools:

• query_action({ action, params? }) — calls a read-only action (e.g. get_*, can_*) and returns the full OneBot response. Annotated readOnlyHint. Refuses write actions (points you to invoke_action).
• invoke_action({ action, params?, execution? }) — calls any known action, including ones with side effects (send a message, change a group, …). Annotated destructiveHint
  • openWorldHint. Only available in write mode. For automatic local-file upload, pass execution: { input_file: "/path/on/the/mcp/host" } with action: "upload_file_stream"; this option is never forwarded as OneBot params.

Ordinary actions pass the OneBot envelope through verbatim — a logical failure (retcode≠0) comes back as data with its wording. Stream protocol failures are reported as MCP errors because they mean no complete stream result was committed.

Configuration (env)

| Variable | Meaning | | --- | --- | | SNOWLUMA_MCP_ENDPOINT | OneBot HTTP endpoint, e.g. http://127.0.0.1:3000/. Absent → docs-only (execution tools hidden). | | SNOWLUMA_MCP_TOKEN | Access token (sent as Authorization: Bearer …), if the endpoint requires one. | | SNOWLUMA_MCP_TIMEOUT_MS | Ordinary-action request timeout; for Stream Actions, connection timeout and per-read idle timeout (the idle deadline resets after every body read). Default 30000. Invalid values fail startup. | | SNOWLUMA_MCP_MODE | docs | read | write. Default: read when an endpoint is set, else docs. Invalid values fail startup. | | SNOWLUMA_MCP_STREAM_DIR | Directory on the MCP host for completed Stream Action downloads. Created and validated at startup. Default: os.tmpdir()/onebot-mcp-downloads. | | SNOWLUMA_MCP_UPLOAD_ROOT | Existing directory on the MCP host from which automatic uploads may read. Automatic upload is disabled when absent. | | SNOWLUMA_MCP_MAX_STREAM_BYTES | Per-file download/upload ceiling in bytes. Positive integer up to 4 GiB; default 4294967296. Invalid values fail server startup. |

Read mode — the LLM can query read-only actions, but cannot perform any write:

{
  "mcpServers": {
    "snowluma": {
      "command": "npx",
      "args": ["-y", "@snowluma/mcp"],
      "env": {
        "SNOWLUMA_MCP_ENDPOINT": "http://127.0.0.1:3000/",
        "SNOWLUMA_MCP_TOKEN": "your-access-token"
      }
    }
  }
}

Write mode — also enables invoke_action (the bot can send messages, manage groups, etc.). Enable deliberately:

{
  "mcpServers": {
    "snowluma": {
      "command": "npx",
      "args": ["-y", "@snowluma/mcp"],
      "env": {
        "SNOWLUMA_MCP_ENDPOINT": "http://127.0.0.1:3000/",
        "SNOWLUMA_MCP_TOKEN": "your-access-token",
        "SNOWLUMA_MCP_MODE": "write",
        "SNOWLUMA_MCP_STREAM_DIR": "/var/tmp/onebot-mcp-downloads",
        "SNOWLUMA_MCP_UPLOAD_ROOT": "/home/me/mcp-share"
      }
    }
  }
}

Stream Actions

The existing query_action / invoke_action tools automatically select the ordinary or Stream Action HTTP transport from the generated catalog. No separate MCP tool is needed.

• File downloads (download_file_stream, download_file_image_stream, and download_file_record_stream) are parsed frame-by-frame. Base64 chunks are decoded directly into a randomly named .part file under the controlled download directory, hashed incrementally, and atomically renamed only after a valid file_complete terminal frame. The MCP result contains only file_path, file_size, sha256, frame_count, and terminal; the file path is on the MCP host.
• A client admits at most four top-level active Stream Actions. Download files share a directory quota of 2 * SNOWLUMA_MCP_MAX_STREAM_BYTES; an unknown-size download reserves the full per-file limit while active. Successfully committed files are not automatically deleted by MCP and continue consuming quota; the operator must move or delete them when no longer needed.
• Non-file streams such as test_download_stream return a bounded frame summary. Frame count, summary text, individual wire-frame size, total file bytes, and file chunk count are capped. A malformed frame, disconnect, timeout, size violation, caller cancellation, idle timeout, or invalid terminal cancels the response and removes the partial file. file_chunk / file_complete frames are never admitted without a preceding file_info header.
• Automatic upload reads execution.input_file only after resolving it inside SNOWLUMA_MCP_UPLOAD_ROOT (symlink escapes are rejected), hashes and sends it in fixed-size chunks, and asks SnowLuma to verify the final SHA-256. Transfer fields such as stream_id, chunk_data, and chunk_index are MCP-owned and must not also be supplied in params. The returned file_path is on the SnowLuma/OneBot host and can be passed to a normal send-file action.
• Automatic upload reset is best-effort before commit. If SnowLuma commits the file but the file_complete response is lost, the upload state has already gone and reset cannot remove that committed file. Keep file_retention non-zero (the default is 300000 ms) so SnowLuma eventually reclaims it.
• Stream Actions remain classified as write operations by the current catalog, so they require SNOWLUMA_MCP_MODE=write and invoke_action.

Example automatic upload:

{
  "action": "upload_file_stream",
  "params": { "file_retention": 300000 },
  "execution": { "input_file": "/home/me/mcp-share/report.pdf" }
}

Safety model

• Read/write is classified per action in the source specs (by what the action actually does, not its name) and baked into the catalog. The default is write: an action is callable via query_action only if it is explicitly read-only.
• The mode gate is enforced on every call, not just by hiding tools — calling invoke_action outside write mode is refused even if a client sends it directly.
• Unknown actions are rejected by both tools (only catalog actions are callable), so typos and non-catalog internal actions can't be driven.
• Stream downloads never put file Base64 into the model result. Downloads use a .part + atomic-rename commit; automatic uploads require an explicit realpath- fenced root and attempt a pre-commit remote reset if transfer fails.
• A well-behaved client can auto-approve query_action (read-only) and prompt for invoke_action (destructive) using the MCP tool annotations.

How it stays in sync

The catalog — including each action's readOnly flag — is a build-time snapshot generated from @snowluma/onebot's live action specs (collectActionDocs()) on every build, so it auto-tracks action add/remove and read/write reclassification. The snapshot is pinned to the SnowLuma version it was built from; a new SnowLuma release republishes a fresh catalog.

This package is generated; do not hand-edit src/generated/catalog.ts.