@ziprack/sdk 0.1.2 → 0.2.1

package/dist/mcp/rpc.d.ts

@@ -0,0 +1,33 @@
+import type { Readable, Writable } from 'node:stream';
+/**
+ * MCP over stdio is line-delimited JSON-RPC 2.0. That is little enough protocol
+ * to own outright, which keeps the studio dependency-free the way the SDK is.
+ */
+export interface RpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface RpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export declare const PARSE_ERROR = -32700;
+export declare const INVALID_REQUEST = -32600;
+export declare const METHOD_NOT_FOUND = -32601;
+export declare const INVALID_PARAMS = -32602;
+export declare const INTERNAL_ERROR = -32603;
+export declare class RpcFailure extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined);
+}
+export type RpcHandler = (params: Record<string, unknown>, method: string) => Promise<unknown> | unknown;
+export interface RpcConnection {
+    /** Resolves when the input stream ends. */
+    done: Promise<void>;
+    notify(method: string, params?: Record<string, unknown>): void;
+}
+export declare function serve(input: Readable, output: Writable, handlers: Map<string, RpcHandler>): RpcConnection;

package/dist/mcp/rpc.js

@@ -0,0 +1,86 @@
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+export class RpcFailure extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+    }
+}
+export function serve(input, output, handlers) {
+    const write = (payload) => {
+        output.write(`${JSON.stringify(payload)}\n`);
+    };
+    // One request at a time. Tools read and write the document, so overlapping
+    // them would let a later call answer from the state before an earlier one's
+    // save — the kind of ordering bug an assistant cannot see or work around.
+    let queue = Promise.resolve();
+    const done = new Promise((resolve) => {
+        let buffer = '';
+        input.setEncoding('utf8');
+        input.on('data', (chunk) => {
+            buffer += chunk;
+            let newline = buffer.indexOf('\n');
+            while (newline !== -1) {
+                const line = buffer.slice(0, newline).trim();
+                buffer = buffer.slice(newline + 1);
+                if (line !== '') {
+                    queue = queue.then(() => handle(line, handlers, write));
+                }
+                newline = buffer.indexOf('\n');
+            }
+        });
+        // The queue is drained before the caller is told the connection is over,
+        // so a request on the last line still gets its answer.
+        input.on('end', () => void queue.then(resolve));
+        input.on('close', () => void queue.then(resolve));
+    });
+    return {
+        done,
+        notify: (method, params) => write({ jsonrpc: '2.0', method, params: params ?? {} }),
+    };
+}
+async function handle(line, handlers, write) {
+    let request;
+    try {
+        request = JSON.parse(line);
+    }
+    catch {
+        write({ jsonrpc: '2.0', id: null, error: { code: PARSE_ERROR, message: 'Invalid JSON.' } });
+        return;
+    }
+    if (typeof request.method !== 'string') {
+        write({ jsonrpc: '2.0', id: request.id ?? null, error: { code: INVALID_REQUEST, message: 'Missing method.' } });
+        return;
+    }
+    const handler = handlers.get(request.method);
+    // A notification has no id and, per JSON-RPC, gets no answer at all —
+    // including for `notifications/initialized`, which every client sends.
+    const isNotification = request.id === undefined || request.id === null;
+    if (handler === undefined) {
+        if (!isNotification) {
+            write({ jsonrpc: '2.0', id: request.id, error: { code: METHOD_NOT_FOUND, message: `Unknown method [${request.method}].` } });
+        }
+        return;
+    }
+    try {
+        const result = await handler(request.params ?? {}, request.method);
+        if (!isNotification) {
+            write({ jsonrpc: '2.0', id: request.id, result });
+        }
+    }
+    catch (error) {
+        if (isNotification) {
+            return;
+        }
+        const failure = error instanceof RpcFailure
+            ? { code: error.code, message: error.message, data: error.data }
+            : { code: INTERNAL_ERROR, message: error instanceof Error ? error.message : String(error) };
+        write({ jsonrpc: '2.0', id: request.id, error: failure });
+    }
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,23 @@
+import { type RpcHandler } from './rpc.js';
+import { type ToolDefinition } from './tools.js';
+export declare const PROTOCOL_VERSION = "2024-11-05";
+export interface ServerInfo {
+    name: string;
+    version: string;
+    instructions: string;
+}
+export declare const DOCS_INSTRUCTIONS = "zipRACK applet docs, matched to the installed @ziprack/sdk. Call ziprack_guidelines before writing or changing applet code, and ziprack_search_docs before guessing at an SDK method, manifest field or error code.";
+/** Wires a tool set onto the MCP method surface a client expects. */
+export declare function session(tools: ToolDefinition[], info: ServerInfo): Map<string, RpcHandler>;
+/**
+ * Tool results are text content blocks. Structured payloads go through as
+ * indented JSON, which is what an assistant can actually read back.
+ */
+export declare function content(payload: unknown): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+};
+export declare function startDocsMcp(): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,55 @@
+import { INVALID_PARAMS, RpcFailure, serve } from './rpc.js';
+import { SDK_VERSION, docsTools } from './tools.js';
+export const PROTOCOL_VERSION = '2024-11-05';
+export const DOCS_INSTRUCTIONS = 'zipRACK applet docs, matched to the installed @ziprack/sdk. Call ziprack_guidelines before writing or changing applet code, and ziprack_search_docs before guessing at an SDK method, manifest field or error code.';
+/** Wires a tool set onto the MCP method surface a client expects. */
+export function session(tools, info) {
+    const byName = new Map(tools.map((tool) => [tool.name, tool]));
+    const handlers = new Map();
+    handlers.set('initialize', () => ({
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: info.name, version: info.version },
+        instructions: info.instructions,
+    }));
+    handlers.set('notifications/initialized', () => null);
+    handlers.set('ping', () => ({}));
+    handlers.set('tools/list', () => ({
+        tools: tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        })),
+    }));
+    handlers.set('tools/call', async (params) => {
+        const name = params.name;
+        if (typeof name !== 'string') {
+            throw new RpcFailure(INVALID_PARAMS, 'tools/call needs a tool name.');
+        }
+        const tool = byName.get(name);
+        if (tool === undefined) {
+            throw new RpcFailure(INVALID_PARAMS, `Unknown tool [${name}].`);
+        }
+        const args = params.arguments;
+        return content(await tool.run(args === null || typeof args !== 'object' ? {} : args));
+    });
+    return handlers;
+}
+/**
+ * Tool results are text content blocks. Structured payloads go through as
+ * indented JSON, which is what an assistant can actually read back.
+ */
+export function content(payload) {
+    if (typeof payload === 'string') {
+        return { content: [{ type: 'text', text: payload }] };
+    }
+    if (payload !== null && typeof payload === 'object' && 'isError' in payload) {
+        const { isError, ...rest } = payload;
+        return { content: [{ type: 'text', text: JSON.stringify(rest, null, 2) }], isError };
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+export async function startDocsMcp() {
+    const handlers = session(docsTools(), { name: 'ziprack', version: SDK_VERSION, instructions: DOCS_INSTRUCTIONS });
+    await serve(process.stdin, process.stdout, handlers).done;
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,20 @@
+import { type Doc } from './docs.js';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties?: Record<string, object>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+    /** Returned as the tool result; objects are serialised as JSON text. */
+    run(args: Record<string, unknown>): Promise<unknown> | unknown;
+}
+export declare const SDK_VERSION: string;
+/**
+ * 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 declare function docsTools(docs?: Doc[]): ToolDefinition[];

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}`;
+            },
+        },
+    ];
+}