@snowluma/mcp 1.9.5

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// @snowluma/mcp — an MCP server for the SnowLuma OneBot action catalog.
+//
+// Two modes in one binary:
+//   • docs  (default, no endpoint): read-only catalog tools (list/get/search/
+//     categories) + a catalog resource. Zero contact with any live instance.
+//   • read / write (when SNOWLUMA_MCP_ENDPOINT is set): the catalog tools PLUS
+//     execution — query_action (read-only actions) and, in write mode,
+//     invoke_action (any known action) — proxied to a running OneBot instance
+//     over HTTP.
+//
+// Env:
+//   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 (Bearer) for the endpoint.
+//   SNOWLUMA_MCP_TIMEOUT_MS  per-request timeout (default SDK 30s).
+//   SNOWLUMA_MCP_MODE        docs | read | write. Default: read when an
+//                            endpoint is set, else docs.
+//
+// NOTE: stdout is the MCP protocol channel — all diagnostics go to stderr.
+import { readFileSync } from 'node:fs';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { ACTIONS, CATEGORIES } from './generated/catalog.js';
+import { makeHttpClient } from './client.js';
+import { callTool, computeTools } from './tools.js';
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const VERSION = pkg.version;
+const RESOURCE_URI = 'snowluma://onebot/actions';
+// ── resolve mode + client from the environment ────────────────────────────
+function resolveRuntime() {
+    const endpoint = process.env.SNOWLUMA_MCP_ENDPOINT?.trim();
+    const token = process.env.SNOWLUMA_MCP_TOKEN?.trim() || undefined;
+    const timeoutRaw = Number(process.env.SNOWLUMA_MCP_TIMEOUT_MS);
+    const timeoutMs = Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : undefined;
+    const requested = process.env.SNOWLUMA_MCP_MODE?.trim().toLowerCase();
+    const validRequest = requested === 'docs' || requested === 'read' || requested === 'write' ? requested : undefined;
+    if (!endpoint) {
+        if (validRequest && validRequest !== 'docs') {
+            console.error(`[snowluma-mcp] SNOWLUMA_MCP_MODE=${validRequest} ignored: no SNOWLUMA_MCP_ENDPOINT set — docs-only.`);
+        }
+        return { mode: 'docs' };
+    }
+    const mode = validRequest ?? 'read';
+    if (mode === 'docs') {
+        // Endpoint set but operator explicitly wants docs-only — honor it.
+        return { mode: 'docs' };
+    }
+    const client = makeHttpClient({ endpoint, accessToken: token, timeoutMs });
+    return { mode, client };
+}
+const { mode, client } = resolveRuntime();
+const server = new Server({ name: 'snowluma-mcp', version: VERSION }, { capabilities: { tools: {}, resources: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: computeTools(mode) }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const args = (req.params.arguments ?? {});
+    return callTool(req.params.name, args, { mode, client });
+});
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: [
+        {
+            uri: RESOURCE_URI,
+            name: 'SnowLuma OneBot action catalog',
+            mimeType: 'application/json',
+            description: `SnowLuma v${VERSION} 的 ${ACTIONS.length} 个 OneBot action 完整目录（文档 + JSON Schema）。`,
+        },
+    ],
+}));
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+    if (req.params.uri !== RESOURCE_URI)
+        throw new Error(`unknown resource: ${req.params.uri}`);
+    return {
+        contents: [
+            {
+                uri: RESOURCE_URI,
+                mimeType: 'application/json',
+                text: JSON.stringify({ version: VERSION, categories: CATEGORIES, actions: ACTIONS }, null, 2),
+            },
+        ],
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+const where = client ? ` → ${process.env.SNOWLUMA_MCP_ENDPOINT?.trim()}` : '';
+console.error(`[snowluma-mcp] v${VERSION} ready — ${ACTIONS.length} actions, ${CATEGORIES.length} categories, mode=${mode}${where}`);

package/dist/tools.d.ts

@@ -0,0 +1,11 @@
+import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { ActionClient } from './client.js';
+export type Mode = 'docs' | 'read' | 'write';
+/** Tools visible for a given mode: docs always; +query in read/write; +invoke in write. */
+export declare function computeTools(mode: Mode): Tool[];
+export type ToolResult = CallToolResult;
+export interface CallCtx {
+    mode: Mode;
+    client?: ActionClient;
+}
+export declare function callTool(name: string, args: Record<string, unknown>, ctx: CallCtx): Promise<ToolResult>;

package/dist/tools.js

@@ -0,0 +1,160 @@
+// Tool surface for the MCP — kept free of any stdio / transport / env concerns
+// so it is directly unit-testable. `server.ts` reads the environment, builds a
+// client, and wires `computeTools` / `callTool` into the MCP request handlers.
+//
+// Two execution tools partition the action space by side-effect:
+//   • query_action  — read-only actions only   (readOnlyHint)
+//   • invoke_action — any known action          (destructiveHint, write mode)
+// Visibility is gated by `mode`, and `callTool` RE-checks every permission
+// (defense in depth: a client may call a tool that was never listed).
+import { ACTIONS, CATEGORIES } from './generated/catalog.js';
+// name + every alias → action, so lookups accept aliases too.
+const byName = new Map();
+for (const a of ACTIONS) {
+    for (const n of [a.name, ...a.aliases])
+        byName.set(n, a);
+}
+/** Lightweight index entry (keeps list/search payloads small). */
+function lite(a) {
+    return { name: a.name, category: a.category, summary: a.summary, aliases: a.aliases, readOnly: a.readOnly };
+}
+const DOCS_TOOLS = [
+    {
+        name: 'list_actions',
+        description: '列出所有 OneBot action（可按 category 过滤）。返回轻量索引（名称/分类/摘要/别名/是否只读）。',
+        inputSchema: {
+            type: 'object',
+            properties: { category: { type: 'string', description: '按分类过滤，如 群管理 / 消息 / 好友' } },
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: 'get_action',
+        description: '获取某个 OneBot action 的完整文档：摘要、参数表、跨字段约束、返回、是否只读，以及可直接用于构造调用的参数 JSON Schema（inputSchema）。',
+        inputSchema: {
+            type: 'object',
+            properties: { name: { type: 'string', description: 'action 名（接受别名）' } },
+            required: ['name'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: 'search_actions',
+        description: '按关键字模糊搜索 action（匹配名称 / 摘要 / 别名）。返回轻量索引。',
+        inputSchema: {
+            type: 'object',
+            properties: { query: { type: 'string', description: '关键字' } },
+            required: ['query'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: 'list_categories',
+        description: '列出所有分类及其 action 数量。',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+];
+const EXEC_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        action: { type: 'string', description: 'action 名（接受别名）。先用 get_action 查它的参数 inputSchema。' },
+        params: { type: 'object', description: '该 action 的参数对象', additionalProperties: true },
+    },
+    required: ['action'],
+    additionalProperties: false,
+};
+function queryTool() {
+    return {
+        name: 'query_action',
+        description: '调用一个【只读】OneBot action（如 get_*/can_*）并返回完整响应。仅接受只读 action；写操作请用 invoke_action。',
+        inputSchema: EXEC_INPUT_SCHEMA,
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    };
+}
+function invokeTool() {
+    return {
+        name: 'invoke_action',
+        description: '调用一个 OneBot action（可产生副作用：发消息、改群、改资料等）并返回完整响应。仅在写模式可用。',
+        inputSchema: EXEC_INPUT_SCHEMA,
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    };
+}
+/** Tools visible for a given mode: docs always; +query in read/write; +invoke in write. */
+export function computeTools(mode) {
+    const tools = [...DOCS_TOOLS];
+    if (mode === 'read' || mode === 'write')
+        tools.push(queryTool());
+    if (mode === 'write')
+        tools.push(invokeTool());
+    return tools;
+}
+function asText(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+function asError(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+export async function callTool(name, args, ctx) {
+    switch (name) {
+        case 'list_actions': {
+            const category = typeof args.category === 'string' ? args.category : undefined;
+            const list = ACTIONS.filter((a) => !category || a.category === category).map(lite);
+            return asText({ count: list.length, actions: list });
+        }
+        case 'get_action': {
+            const q = typeof args.name === 'string' ? args.name : '';
+            const action = byName.get(q);
+            if (!action)
+                return asError(`未找到 action: ${JSON.stringify(q)}。用 list_actions / search_actions 查可用项。`);
+            return asText(action);
+        }
+        case 'search_actions': {
+            const q = (typeof args.query === 'string' ? args.query : '').toLowerCase();
+            const list = ACTIONS.filter((a) => a.name.toLowerCase().includes(q) ||
+                (a.summary ?? '').toLowerCase().includes(q) ||
+                a.aliases.some((al) => al.toLowerCase().includes(q))).map(lite);
+            return asText({ count: list.length, actions: list });
+        }
+        case 'list_categories':
+            return asText(CATEGORIES);
+        case 'query_action':
+            return execute(args, ctx, 'read');
+        case 'invoke_action':
+            return execute(args, ctx, 'write');
+        default:
+            return asError(`未知工具: ${name}`);
+    }
+}
+/** Shared execution path for query_action (read) / invoke_action (write).
+ *  Re-checks mode + readOnly routing regardless of which tools were listed. */
+async function execute(args, ctx, kind) {
+    if (kind === 'write' && ctx.mode !== 'write') {
+        return asError('写操作未启用：需设置 SNOWLUMA_MCP_MODE=write。');
+    }
+    if (kind === 'read' && ctx.mode !== 'read' && ctx.mode !== 'write') {
+        return asError('执行未启用：需配置 SNOWLUMA_MCP_ENDPOINT。');
+    }
+    if (!ctx.client)
+        return asError('未配置 OneBot 端点（SNOWLUMA_MCP_ENDPOINT），无法执行。');
+    const action = typeof args.action === 'string' ? args.action : '';
+    const cat = byName.get(action);
+    if (!cat)
+        return asError(`未知 action: ${JSON.stringify(action)}。用 list_actions / search_actions 查可用项。`);
+    if (kind === 'read' && !cat.readOnly) {
+        return asError(`${action} 是写操作，不能用 query_action；请用 invoke_action（需 SNOWLUMA_MCP_MODE=write）。`);
+    }
+    const params = args.params && typeof args.params === 'object' && !Array.isArray(args.params)
+        ? args.params
+        : {};
+    try {
+        const envelope = await ctx.client.call(action, params);
+        return asText(envelope);
+    }
+    catch (err) {
+        return asError(`调用失败: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+export interface CatalogParam {
+    name: string;
+    /** Display type ('uint' | 'int' | 'messageId' | 'string' | 'bool' | 'message' | 'enum' | 'X[]' | 'raw'). */
+    type: string;
+    required: boolean;
+    default?: unknown;
+    desc?: string;
+    values?: ReadonlyArray<string | number>;
+    /** JSON Schema fragment for this single field. */
+    schema?: Record<string, unknown>;
+}
+export interface CatalogAction {
+    name: string;
+    aliases: string[];
+    category?: string;
+    summary?: string;
+    returns?: string;
+    /** True only for pure data-fetch actions (no side effects). Drives the
+     *  read/write tool routing: read-only → query_action, else → invoke_action.
+     *  Classified at the source spec by what the action's `run` actually does. */
+    readOnly: boolean;
+    params: CatalogParam[];
+    /** Cross-field invariants, e.g. "exactly one of: message_id | (group_id+user_id)". */
+    invariants: string[];
+    /** Composed JSON Schema for the whole params object. */
+    inputSchema: Record<string, unknown>;
+}
+export interface CatalogCategory {
+    category: string;
+    count: number;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+// The MCP's own view of the OneBot action catalog. Mirrors @snowluma/onebot's
+// ActionDoc, but is defined HERE so the published package does not couple to
+// onebot's internals — the generated `catalog.ts` (a build-time snapshot) is the
+// only contract (ADR-0005: the wire/data shape is the seam, not a shared type).
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@snowluma/mcp",
+  "version": "1.9.5",
+  "description": "MCP server exposing the SnowLuma OneBot action catalog (docs + JSON Schemas) and optional execution to LLM clients.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SnowLuma/SnowLuma.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/SnowLuma/SnowLuma#readme",
+  "bugs": {
+    "url": "https://github.com/SnowLuma/SnowLuma/issues"
+  },
+  "type": "module",
+  "bin": {
+    "snowluma-mcp": "./dist/server.js"
+  },
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "node -e \"const fs=require('node:fs');fs.rmSync('dist',{recursive:true,force:true})\"",
+    "gen": "vitest run scripts/gen-catalog.test.ts",
+    "prebuild": "pnpm run clean && pnpm run gen",
+    "build": "tsc -p tsconfig.json",
+    "prepack": "pnpm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "start": "node dist/server.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "onebot",
+    "snowluma",
+    "qq"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@snowluma/onebot": "workspace:*",
+    "@snowluma/proton": "workspace:*",
+    "@types/node": "^24.12.2",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vitest": "^4.1.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}