@snowluma/mcp 1.9.5

package/README.md

@@ -0,0 +1,113 @@
+# @snowluma/mcp
+
+An [MCP](https://modelcontextprotocol.io) 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:
+
+```json
+{
+  "mcpServers": {
+    "snowluma": { "command": "npx", "args": ["-y", "@snowluma/mcp"] }
+  }
+}
+```
+
+### Docs tools
+
+- `list_actions({ category? })` — lightweight index (name / category / summary / aliases / `readOnly`).
+- `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? })` — calls **any known** action, including ones
+  with side effects (send a message, change a group, …). Annotated `destructiveHint`
+  + `openWorldHint`. **Only available in write mode.**
+
+Both pass the OneBot envelope through verbatim — a logical failure (`retcode≠0`)
+comes back as data with its `wording`; only a transport failure is an error.
+
+### 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` | Per-request timeout (default `30000`). |
+| `SNOWLUMA_MCP_MODE` | `docs` \| `read` \| `write`. Default: `read` when an endpoint is set, else `docs`. |
+
+**Read mode** — the LLM can query read-only actions, but cannot perform any write:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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"
+      }
+    }
+  }
+}
+```
+
+### 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.
+- 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`.

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+/** OneBot v11 response envelope, passed through to the LLM verbatim. */
+export interface OneBotEnvelope {
+    status: string;
+    retcode: number;
+    data?: unknown;
+    message?: string;
+    wording?: string;
+    echo?: unknown;
+    [k: string]: unknown;
+}
+export interface ActionClient {
+    /** Send one OneBot action; resolves the full envelope (even on retcode≠0),
+     *  rejects only on transport-level failure (timeout / connection / bad body). */
+    call(action: string, params: Record<string, unknown>): Promise<OneBotEnvelope>;
+}
+export interface HttpClientOptions {
+    /** OneBot HTTP endpoint, e.g. http://127.0.0.1:3000/. */
+    endpoint: string;
+    accessToken?: string;
+    timeoutMs?: number;
+    /** Injectable fetch for tests; defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+export declare function makeHttpClient(opts: HttpClientOptions): ActionClient;

package/dist/client.js

@@ -0,0 +1,42 @@
+// Thin HTTP bridge to a running OneBot instance.
+//
+// The OneBot v11 HTTP action protocol is trivial — POST `{ action, params }` to
+// the endpoint, read back the JSON envelope — so the MCP talks to it directly
+// with `fetch`. We deliberately do NOT depend on @snowluma/sdk here: its
+// published dist is bundler-targeted ESM (extensionless relative imports) that
+// native `node` cannot resolve without a bundler, and this package is a plain
+// `tsc`-built stdio bin. The wire shape — not a shared client type — is the seam
+// (ADR-0005); tests inject a fake `ActionClient` (or a fake `fetch`).
+const DEFAULT_TIMEOUT_MS = 30_000;
+export function makeHttpClient(opts) {
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    const timeoutMs = opts.timeoutMs && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+    const headers = {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+    };
+    if (opts.accessToken)
+        headers.Authorization = `Bearer ${opts.accessToken}`;
+    return {
+        async call(action, params) {
+            const res = await fetchImpl(opts.endpoint, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ action, params }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const text = await res.text();
+            let parsed;
+            try {
+                parsed = text ? JSON.parse(text) : null;
+            }
+            catch {
+                throw new Error(`OneBot returned non-JSON (HTTP ${res.status})`);
+            }
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                throw new Error(`OneBot returned an unexpected response (HTTP ${res.status})`);
+            }
+            return parsed;
+        },
+    };
+}

package/dist/generated/catalog.d.ts

@@ -0,0 +1,3 @@
+import type { CatalogAction, CatalogCategory } from '../types.js';
+export declare const ACTIONS: CatalogAction[];
+export declare const CATEGORIES: CatalogCategory[];