@snowluma/mcp weekly downloads statistics

@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. Omitted params defaults to an empty object; a supplied non-object value is rejected before calling OneBot.

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.…