@ziprack/sdk 0.1.2 → 0.2.0

package/dist/docs/ziprack-1-authoring.md

@@ -0,0 +1,182 @@
+# Building a zipRACK applet (ziprack/1)
+
+You are building an **applet**: a self-contained static web app that a Rack hosts inside a sandboxed
+iframe. The Rack owns login, persistence, AI access, real-time coordination and reporting. The applet
+owns everything the participant sees. It never talks to a database, never calls an API, never holds a
+credential. It asks the Rack over `postMessage` through `@ziprack/sdk`, and the Rack decides, enforces
+and persists.
+
+Follow this document exactly. The Rack rejects packages and messages that break it.
+
+## 1. Mental model
+
+| Object | What it is |
+|---|---|
+| Applet | One experience or app, identified by an immutable `slug`. Has many versions. |
+| Version | One uploaded zip. Immutable. Exactly one is current. |
+| Attempt | One participant's run (`attempt@1`). Pinned to the version it started on. Holds `status`, `state`, `segment`. |
+| Room | A shared session: an applet plus its participants (`broadcast@1`). Two roles: `participant`, `facilitator`. |
+| Statement | Append-only "actor did verb on activity with result" (`activity@1`). The audit trail and the uniform export. |
+| Record | A mutable row in a declared collection at a declared scope (`db@1`). Working state. |
+| Profile attribute | A Rack-owned fact about the participant, released only if declared and permitted (`auth@1`). |
+
+Rules that do not bend:
+
+1. **Declare every capability you call.** `requires.capabilities` is mandatory, not advisory. An undeclared call is refused at runtime with `undeclared_capability`.
+2. **Nothing persists inside the iframe.** No cookies, no `localStorage`, no `fetch` to the Rack. If it matters, send it through `Rack.*`.
+3. **Answers are statements, not state.** State is for resuming position. Every committed answer is `Rack.activity.answer()`.
+4. **Resume must work.** Read `Rack.attempt.state()` and `Rack.attempt.status` at launch and put the participant back where they were.
+5. **Degrade gracefully.** A requested profile attribute may be withheld. A room may have no facilitator yet. Design for absence.
+
+## 2. Package layout
+
+```
+{slug}-{version}.zip
+├── manifest.json        required, at the zip root
+├── sbom.json            required: CycloneDX (or package-lock.json)
+├── index.html           the entry (configurable via manifest.entry)
+└── assets/…             everything the entry references, by RELATIVE path
+```
+
+Installer rules: static files only (`html js mjs css map json wasm txt vtt svg png jpg jpeg gif webp ico woff woff2 ttf mp3 mp4 wav webm ogg pdf`); no `..`, absolute paths or symlinks; dotfiles and `__MACOSX/` skipped; 50 MB default cap; `entry` must exist and end in `.html`; every asset URL relative (`base: './'` in Vite); a `version` uploads once per applet.
+
+`npm run package` in the starter builds all of this, including the SBOM from your lockfile.
+
+## 3. manifest.json
+
+```json
+{
+    "schema": "ziprack/1",
+    "slug": "my-applet",
+    "name": "My Applet",
+    "version": "1.0.0",
+    "entry": "index.html",
+    "requires": {
+        "capabilities": ["auth@1", "attempt@1", "activity@1"],
+        "profile": ["display_name", "locale"]
+    },
+    "media": [{ "id": "intro", "provider": "youtube", "key": "dQw4w9WgXcQ" }],
+    "segments": [],
+    "activities": [],
+    "reporting": { "metrics": [] }
+}
+```
+
+| Field | Rules |
+|---|---|
+| `schema` | Required, `ziprack/1`. |
+| `slug` | Required. `^[a-z0-9]+(-[a-z0-9]+)*$`, max 100. Immutable. Launch URL `/a/{slug}`. |
+| `name`, `version` | Required. Semver with optional prerelease. |
+| `entry` | Optional, default `index.html`. Relative, ends in `.html`. |
+| `requires.capabilities` | Required (may be empty). Each `id@version`; the Rack must implement every one. |
+| `requires.profile` | Attribute keys, only with `auth@1`. Withheld keys are simply absent. |
+| `media[]` | `provider` in the Rack's allowlist (vimeo, youtube); `key` `^\d+$` (Vimeo) or `^[\w-]{11}$` (YouTube). The Rack builds the URL. |
+
+Every other top-level block belongs to a capability and is invalid unless that capability is declared:
+
+| Block | Capability | Shape |
+|---|---|---|
+| `segments[]` | `attempt@1` | `{key, label, values[{key,label}]}`; the first segment drives admin filtering |
+| `activities[]`, `reporting.metrics[]` | `activity@1` | as in cn-sim/1: `{id, type, label, scale?, segment?, sequence?}`; metrics pair a pre and post rating and need `attempt@1` |
+| `collections[]` | `db@1` | `{name, scope, schema, indexed?, quota?, permissions?}` |
+| `uploads[]` | `storage@1` | `{name, scope, mime[], max_bytes?, max_files?}` |
+| `prompts[]` | `ai@1` | `{id, mode, template, vars?, output_schema?, budget?}` |
+| `broadcast` | `broadcast@1` | `{channels?, facilitator_events?}` |
+
+Scopes (`db@1`, `storage@1`): `attempt` (frozen at completion; needs `attempt@1`), `user` (outlives attempts), `room` (shared; needs `broadcast@1`), `applet` (per version, read-mostly).
+
+## 4. The SDK
+
+```ts
+import { Rack } from '@ziprack/sdk';
+
+const launch = await Rack.init({ slug: 'my-applet' });   // mock mode when not inside a Rack
+```
+
+| Namespace | Calls | Notes |
+|---|---|---|
+| `Rack` | `init()`, `on('launch'|'event')`, `mode`, `eject()` | `eject()` needs no capability |
+| `Rack.auth` | `user()`, `attribute(key, fallback)` | Released profile from launch data |
+| `Rack.attempt` | `status`, `state()`, `segment()`, `setState()`, `setSegment()`, `complete()` | State max 64 KB; `complete()` idempotent; after it, state and segment are refused with `completed` |
+| `Rack.activity` | `answer(id, value)`, `progress(stepId)`, `statement({...})` | Verbs `^[a-z][a-z0-9_.:-]*$`; answers put the value in `result.response` |
+| `Rack.db.collection(name)` | `create`, `get`, `update`, `delete`, `list`, `count` | Filters and sorting only on `indexed` paths; 100 per page |
+| `Rack.storage` | `put(upload, file)`, `url(id)`, `list()`, `delete(id)` | Files are addressable only once scanned clean |
+| `Rack.ai` | `ask(promptId, vars)`, `chat(promptId).send(text, onDelta)`, `chat(promptId).reset()` | You supply variables, never instructions |
+| `Rack.broadcast` | `join(channel)` → `{listen, publish, leave}`, `presence()`, `state.get/set`, `claim()`, `transfer(id)`, `on('presence'|'state'|'role'|'status')` | Facilitator-only events are declared in the manifest and enforced by the Rack |
+| `Rack.media` | `embedUrl(id)` | Rack-built player URL |
+
+Every call resolves to `{ ok, data?, error?, message? }` and never throws. Error codes: `timeout`,
+`persist_failed`, `undeclared_capability`, `unknown_type`, `validation`, `forbidden`, `completed`,
+`quota_exceeded`, `budget_exceeded`, `not_found`, `conflict`. Do not block the participant on acks;
+`await` only what you must confirm (for example the final answer before `complete()`).
+
+### Mock mode
+
+Outside a Rack (`npm run dev`), or if the Rack does not answer within 3 s, the SDK runs a local mock
+that reads `./manifest.json` so declared capabilities, activities, collections and prompts behave as
+they will in production. State and records persist in `localStorage` under `ziprack-mock:{slug}:*`.
+Rooms use `BroadcastChannel`, so two tabs of your dev server form a room. `Rack.mock.ai(promptId, fn)`
+answers prompts yourself; `Rack.mock.resetAttempt()` replays a completed attempt.
+
+For tests, `import { FakeHost } from '@ziprack/sdk/testing'` and pass `host.transport()` to
+`Rack.init({ transport })`; then inspect `host.statements`, `host.answers()`, `host.records()`.
+
+## 5. Studio, and its MCP server
+
+If the project has an `applet.json` rather than hand-written source, it is a
+[zipRACK Studio](studio.md) applet. That document is the applet: `index.html` and `manifest.json` are
+compiled from it, and the manifest is **derived** from the blocks in the tree, so there is no
+`requires.capabilities` to maintain and nothing that can drift. Editing the compiled output is
+pointless — the next build overwrites it.
+
+Studio ships an MCP server, and it is the right way to change such a project:
+
+```sh
+npx ziprack-studio mcp        # stdio, run in the project directory
+```
+
+`ziprack_list_blocks` and `ziprack_get_block_schema` tell you what exists and what each block accepts;
+`ziprack_compose` builds structure from a skeleton plus separate content maps; `ziprack_patch` makes
+edits; `ziprack_validate` answers with per-key errors, each carrying the JSON Schema that would have
+been valid. Every mutating tool takes `dry_run`, and every refusal explains itself, so you can converge
+in one round trip instead of guessing.
+
+Prefer it to writing `applet.json` directly. The tools go through the same registry, command bus and
+validator as the editor, which is what keeps the result openable by the non-technical colleague who
+will maintain it. When no block fits, write a real module and point a `custom.code` block at it: your
+code runs, and the tree still has a node the editor can show and move.
+
+## 6. Runtime constraints
+
+The Rack renders you with `sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"`
+and no `allow-same-origin`: an opaque origin. Cookies, `localStorage`, `IndexedDB` and `fetch` to the
+Rack all fail. `window.open` works. The entry document's CSP is:
+
+| Directive | Allowed |
+|---|---|
+| `script-src` | `'self' 'unsafe-inline' 'unsafe-eval' blob:` — bundle every dependency |
+| `style-src`, `font-src` | `'self'` + Bunny/Google fonts |
+| `img-src`, `media-src` | `'self' data: blob:` + the deployment's allowlist. **Not `https:`.** |
+| `connect-src` | `'self'` — no external APIs, no analytics |
+| `frame-src` | Vimeo and YouTube players, via declared `media` only |
+
+Ship your images and media inside the zip. A persistent Rack bar sits above the frame and cannot be
+spoofed; never ask participants for credentials inside an applet.
+
+## 7. Publishing
+
+Uploads land unpublished. Promoting a version is a deliberate admin action. A new version that adds a
+capability or a profile attribute waits for explicit approval; adding or removing `attempt@1` changes
+the applet from rolling to pinned (or back) and is flagged prominently. Known vulnerabilities from your
+SBOM appear in the review queue. Changing an activity `id` between versions splits export columns;
+changing a `label` only changes headers.
+
+## 8. Pre-upload checklist
+
+- [ ] `schema: "ziprack/1"`, version bumped, `requires.capabilities` lists exactly what you call.
+- [ ] `sbom.json` present (`npm run package` does it).
+- [ ] Every question has an `activities[]` entry with a stable `id`, a `type`, a full-sentence `label`.
+- [ ] `setState()` after every transition; refreshing mid-way in mock mode resumes.
+- [ ] `complete()` exactly once; reloading a completed attempt shows the final screen.
+- [ ] All URLs relative, no external `<script>`, no external images or APIs.
+- [ ] Layout works at phone width and leaves the Rack bar alone.

package/dist/mcp/bin.d.ts

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

package/dist/mcp/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { startDocsMcp } from './server.js';
+await startDocsMcp();

package/dist/mcp/docs.d.ts

@@ -0,0 +1,31 @@
+export interface DocSection {
+    /** The `<a name>` anchor docs link to, or `null` for the text above the first heading. */
+    anchor: string | null;
+    heading: string;
+    text: string;
+}
+export interface Doc {
+    /** File name without `.md`, e.g. `sdk`. */
+    name: string;
+    title: string;
+    text: string;
+    sections: DocSection[];
+}
+export declare const GUIDELINES = "ziprack-1-authoring";
+/**
+ * The docs are copied into `dist/docs/` when the SDK is built, so the set an
+ * applet project reads is the set published with the SDK version it installed.
+ */
+export declare function loadDocs(directory?: string): Doc[];
+export declare function parseDoc(name: string, text: string): Doc;
+export interface SearchHit {
+    doc: Doc;
+    section: DocSection;
+    score: number;
+}
+/**
+ * Plain term frequency, with heading and title hits weighted up and an exact
+ * phrase match weighted most. The corpus is a few hundred sections; anything
+ * cleverer would be harder to predict than it is worth.
+ */
+export declare function searchDocs(docs: Doc[], queries: string[], limit: number): SearchHit[];

package/dist/mcp/docs.js

@@ -0,0 +1,107 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export const GUIDELINES = 'ziprack-1-authoring';
+/**
+ * The docs are copied into `dist/docs/` when the SDK is built, so the set an
+ * applet project reads is the set published with the SDK version it installed.
+ */
+export function loadDocs(directory = fileURLToPath(new URL('../docs/', import.meta.url))) {
+    const files = readdirSync(directory).filter((file) => file.endsWith('.md'));
+    const read = (name) => readFileSync(`${directory}/${name}.md`, 'utf8');
+    // docs/README.md is the index: its link order is the reading order.
+    const ordered = [];
+    if (files.includes('README.md')) {
+        for (const match of read('README').matchAll(/\]\(([\w.-]+)\.md\)/g)) {
+            if (!ordered.includes(match[1])) {
+                ordered.push(match[1]);
+            }
+        }
+    }
+    for (const file of files.sort()) {
+        const name = file.slice(0, -3);
+        if (name !== 'README' && !ordered.includes(name)) {
+            ordered.push(name);
+        }
+    }
+    return ordered
+        .filter((name) => files.includes(`${name}.md`))
+        .map((name) => parseDoc(name, read(name)));
+}
+export function parseDoc(name, text) {
+    const lines = text.split('\n');
+    const title = lines.find((line) => line.startsWith('# '))?.slice(2).trim() ?? name;
+    const sections = [];
+    let current = { anchor: null, heading: title, text: '' };
+    let buffer = [];
+    let pendingAnchor = null;
+    let fenced = false;
+    const flush = () => {
+        current.text = buffer.join('\n').trim();
+        if (current.text !== '') {
+            sections.push(current);
+        }
+    };
+    for (const line of lines) {
+        if (line.startsWith('```')) {
+            fenced = !fenced;
+        }
+        const anchor = fenced ? null : /^<a name="([^"]+)"><\/a>\s*$/.exec(line);
+        if (anchor !== null) {
+            pendingAnchor = anchor[1];
+            continue;
+        }
+        if (!fenced && line.startsWith('## ')) {
+            flush();
+            const heading = line.slice(3).trim();
+            current = { anchor: pendingAnchor ?? slug(heading), heading, text: '' };
+            buffer = [line];
+            pendingAnchor = null;
+            continue;
+        }
+        buffer.push(line);
+    }
+    flush();
+    return { name, title, text, sections };
+}
+/**
+ * Plain term frequency, with heading and title hits weighted up and an exact
+ * phrase match weighted most. The corpus is a few hundred sections; anything
+ * cleverer would be harder to predict than it is worth.
+ */
+export function searchDocs(docs, queries, limit) {
+    const hits = [];
+    for (const doc of docs) {
+        const title = doc.title.toLowerCase();
+        for (const section of doc.sections) {
+            const heading = section.heading.toLowerCase();
+            const body = section.text.toLowerCase();
+            let score = 0;
+            for (const query of queries) {
+                const phrase = query.trim().toLowerCase();
+                const terms = phrase.match(/[a-z0-9_@$.-]+/g)?.map((term) => term.replace(/^[.-]+|[.-]+$/g, '')).filter((term) => term.length > 1) ?? [];
+                if (terms.length > 1 && body.includes(phrase)) {
+                    score += 10;
+                }
+                for (const term of terms) {
+                    score += occurrences(body, term) + 5 * occurrences(heading, term) + 3 * occurrences(title, term);
+                }
+            }
+            if (score > 0) {
+                hits.push({ doc, section, score });
+            }
+        }
+    }
+    return hits.sort((a, b) => b.score - a.score).slice(0, limit);
+}
+function occurrences(haystack, needle) {
+    let count = 0;
+    let at = haystack.indexOf(needle);
+    while (at !== -1) {
+        count++;
+        at = haystack.indexOf(needle, at + needle.length);
+    }
+    return count;
+}
+function slug(heading) {
+    return heading.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}

package/dist/mcp/index.d.ts

@@ -0,0 +1,4 @@
+export * from './rpc.js';
+export * from './server.js';
+export * from './tools.js';
+export { loadDocs, searchDocs, type Doc, type DocSection } from './docs.js';

package/dist/mcp/index.js

@@ -0,0 +1,4 @@
+export * from './rpc.js';
+export * from './server.js';
+export * from './tools.js';
+export { loadDocs, searchDocs } from './docs.js';

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[];