@ziprack/sdk 0.1.2 → 0.2.0

package/dist/mcp/tools.js

@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs';
+import { GUIDELINES, loadDocs, searchDocs } from './docs.js';
+export const SDK_VERSION = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+/**
+ * Docs and guidelines for the SDK version this server was installed with.
+ * Every answer names that version, so an assistant never mistakes it for
+ * whatever it remembers of an older one.
+ */
+export function docsTools(docs = loadDocs()) {
+    const byName = new Map(docs.map((doc) => [doc.name, doc]));
+    const header = `zipRACK docs for @ziprack/sdk ${SDK_VERSION}`;
+    const unknownDoc = (name) => ({
+        isError: true,
+        error: `Unknown doc [${name}].`,
+        sdk_version: SDK_VERSION,
+        docs: docs.map((doc) => doc.name),
+    });
+    return [
+        {
+            name: 'ziprack_guidelines',
+            description: 'The rules every zipRACK applet must follow: mental model, package layout, manifest, SDK usage, runtime constraints and the pre-upload checklist. Read this before writing or changing applet code.',
+            inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+            run: () => {
+                const guidelines = byName.get(GUIDELINES);
+                return guidelines === undefined ? unknownDoc(GUIDELINES) : `${header}\n\n${guidelines.text}`;
+            },
+        },
+        {
+            name: 'ziprack_list_docs',
+            description: 'Every zipRACK doc in reading order, with its section anchors. Use the names with ziprack_read_doc.',
+            inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+            run: () => ({
+                sdk_version: SDK_VERSION,
+                docs: docs.map((doc) => ({
+                    name: doc.name,
+                    title: doc.title,
+                    sections: doc.sections
+                        .filter((section) => section.anchor !== null)
+                        .map((section) => ({ anchor: section.anchor, heading: section.heading })),
+                })),
+            }),
+        },
+        {
+            name: 'ziprack_search_docs',
+            description: 'Search the zipRACK docs for the installed SDK version and return the best-matching sections in full. Pass several phrasings at once, e.g. ["setState resume", "attempt state"]. Search before guessing at an SDK method, manifest field or error code.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    queries: { type: 'array', items: { type: 'string' }, minItems: 1, description: 'Search phrases; a section scores on any of them.' },
+                    limit: { type: 'integer', minimum: 1, maximum: 20, description: 'Sections to return. Defaults to 5.' },
+                },
+                required: ['queries'],
+                additionalProperties: false,
+            },
+            run: (args) => {
+                const queries = Array.isArray(args.queries) ? args.queries.filter((query) => typeof query === 'string') : [];
+                if (queries.length === 0) {
+                    return { isError: true, error: 'queries must be a non-empty array of strings.' };
+                }
+                const limit = typeof args.limit === 'number' ? Math.min(Math.max(Math.trunc(args.limit), 1), 20) : 5;
+                const hits = searchDocs(docs, queries, limit);
+                if (hits.length === 0) {
+                    return `${header}\n\nNo section matches ${JSON.stringify(queries)}. ziprack_list_docs shows what is covered.`;
+                }
+                return [header, ...hits.map(({ doc, section }) => {
+                        const where = section.anchor === null ? doc.name : `${doc.name}#${section.anchor}`;
+                        return `---\n[${where}] ${doc.title}\n\n${section.text}`;
+                    })].join('\n\n');
+            },
+        },
+        {
+            name: 'ziprack_read_doc',
+            description: 'One zipRACK doc in full, or one section of it by anchor.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    doc: { type: 'string', description: 'A doc name from ziprack_list_docs, e.g. manifest.' },
+                    section: { type: 'string', description: 'A section anchor, e.g. acks-and-errors.' },
+                },
+                required: ['doc'],
+                additionalProperties: false,
+            },
+            run: (args) => {
+                const name = String(args.doc ?? '').replace(/\.md$/, '');
+                const doc = byName.get(name);
+                if (doc === undefined) {
+                    return unknownDoc(name);
+                }
+                if (typeof args.section !== 'string' || args.section === '') {
+                    return `${header}\n\n${doc.text}`;
+                }
+                const anchor = args.section.replace(/^#/, '');
+                const section = doc.sections.find((candidate) => candidate.anchor === anchor);
+                if (section === undefined) {
+                    return {
+                        isError: true,
+                        error: `Doc [${name}] has no section [${anchor}].`,
+                        sdk_version: SDK_VERSION,
+                        sections: doc.sections.flatMap((candidate) => candidate.anchor === null ? [] : [candidate.anchor]),
+                    };
+                }
+                return `${header}\n\n${section.text}`;
+            },
+        },
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ziprack/sdk",
-    "version": "0.1.2",
+    "version": "0.2.0",
     "description": "JS SDK for zipRACK applets: talk to the Rack over postMessage, with a mock mode for standalone development.",
     "license": "MIT",
     "type": "module",
@@ -9,12 +9,17 @@
     "types": "./dist/index.d.ts",
     "exports": {
         ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
-        "./testing": { "types": "./dist/testing.d.ts", "import": "./dist/testing.js" }
+        "./testing": { "types": "./dist/testing.d.ts", "import": "./dist/testing.js" },
+        "./mcp": { "types": "./dist/mcp/index.d.ts", "import": "./dist/mcp/index.js" }
+    },
+    "bin": {
+        "ziprack-mcp": "./dist/mcp/bin.js"
     },
     "files": ["dist"],
     "scripts": {
-        "build": "vite build && vite build --config vite.iife.config.ts && tsc -p tsconfig.build.json",
-        "typecheck": "tsc -p tsconfig.json --noEmit",
+        "build": "vite build && vite build --config vite.iife.config.ts && tsc -p tsconfig.build.json && npm run build:mcp",
+        "build:mcp": "tsc -p tsconfig.mcp.json && rm -rf dist/docs && cp -R ../docs dist/docs",
+        "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.mcp.json --noEmit",
         "test": "vitest run"
     },
     "ziprack": {
@@ -22,6 +27,7 @@
         "capabilities": ["auth@1", "attempt@1", "activity@1", "db@1", "storage@1", "ai@1", "broadcast@1"]
     },
     "devDependencies": {
+        "@types/node": "^22.20.4",
         "jsdom": "^26.1.0",
         "typescript": "^5.9.2",
         "vite": "^7.1.5",