@womp/openai-plugin 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @womp/openai-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Womp in ChatGPT: the MCP tools, the model's workflow and the cards ChatGPT
+shows. It is a library. swan-backend serves it over HTTP and implements its
+backend; this package has no server, database or credentials of its own.
+
+```ts
+import { createServer, BackendRefusal, type WompBackend } from "@womp/openai-plugin"
+
+const server = createServer({ backend, subject, onError, instructions }) // one per request
+```
+
+## Architecture
+
+```
+ChatGPT ──MCP──► swan-backend ── createServer({ backend, subject }) ──► this package
+                      ▲                                                    │
+                      └──────────────── WompBackend ◄──────────────────────┘
+```
+
+```
+src/
+  index.ts         public API
+  server.ts        createServer → registerResources (every card) + registerTools (every tool group)
+  backend.ts       WompBackend: the contract the host implements
+  tools/           one file per tool group (scene.ts); tool.ts: shared helpers
+  cards/           one folder per card (design/); bridge.ts: shared host connection
+  text.ts          what tools and cards say to the model
+  prompts/         the workflow the model follows
+```
+
+### Dependency rules
+
+- `server` → `tools` → `backend`, `text`, `prompts`, `cards/<card>/data.ts`.
+- `cards/<card>` → its own `data.ts` and `cards/bridge.ts`. A card never imports `tools`, `server` or `backend`.
+- Nothing imports `server` except `index`. Nothing outside this package sees more than the public API.
+
+### Public API
+
+| Export | Purpose |
+|---|---|
+| `createServer({ backend, subject?, onError?, instructions? })` | the MCP server for one request |
+| `WompBackend` | the contract the host implements |
+| `BackendRefusal` | an error whose message reaches the model as worded |
+
+`subject` is the caller as the host established it. `onError` receives every
+error that is not a `BackendRefusal`. `instructions` is appended to the
+server instructions, for tools the host registers itself.
+
+## Contract
+
+### Host → plugin: `WompBackend`
+
+| Method | Does |
+|---|---|
+| `openScene(subject, { designId?, title? })` | finds the caller's design, or makes one, and opens a **build** of it; returns `{ designId, buildId, title }` |
+| `getSceneApi()` | the scene skill, script limits, view names, and `notes` about these designs |
+| `runScript(subject, { designId, code, purpose })` | runs one script on the design; `purpose` becomes the current build's activity, its last screenshot or a fresh render its picture; a failed script returns `ok: false` |
+| `renderScene(subject, { designId, view?, targetId? })` | renders the design; the image also becomes the current build's picture |
+| `finishScene(subject, { designId, title })` | marks the current build done, with this version's title |
+| `getBuild(subject, { designId, buildId })` | a build's status, activity, title and picture; a build that isn't the caller's reads as empty |
+
+A build is one round of changes and has one card. Opening a new build never
+changes an earlier one.
+
+### Plugin → model and cards
+
+- **Identity.** Every tool acts as `subject`. Tool arguments and client `_meta` are never read for identity. Without a subject every tool call fails.
+- **Errors.** A `BackendRefusal` message reaches the model as is. Any other error is one generic failure, reported to `onError`.
+- **Tool metadata states facts.** Descriptions, input schemas and server instructions say what a tool does, never how the model should behave. Behaviour lives in `prompts/` and reaches the model in `load_scene_skill`'s result.
+- **Every tool** declares `ui.visibility`, explicit annotation hints, and `securitySchemes: noauth`. Tools only a card calls are `ui.visibility: ["app"]`.
+- **Card data** is the tool result's `structuredContent`, typed by the card's `data.ts`. Tools map backend types to it; a card never receives backend types.
+- **Cards** are MCP Apps resources (`text/html;profile=mcp-app`): one self-contained HTML file each, loading nothing from outside, with a `ui://` URI that changes with its content.
+
+### Tools
+
+| Tool | Called by | Card |
+|---|---|---|
+| `open_scene` | model | shows `design` |
+| `load_scene_skill` | model | |
+| `run_scene_script` | model | |
+| `render_scene` | model | |
+| `finish_scene` | model | |
+| `get_scene_progress` | `design` card | |
+
+## Extending
+
+**A card.** A folder in `src/cards/<name>/` with `index.html`, `main.ts` and
+`data.ts`, and a description in `text.ts` (`CARD_DESCRIPTIONS`). The build
+picks it up as `CARDS.<name>`; the tool that shows it sets `ui.resourceUri:
+CARDS.<name>.uri` and returns its `data.ts` shape as `structuredContent`.
+
+**A tool group.** `src/tools/<group>.ts` exporting `register<Group>Tools(server,
+backend, run)`, called from `registerTools` in `server.ts`. Its text goes in
+`text.ts`; new backend methods in `backend.ts`.
+
+**A contract change** (anything in `backend.ts`) ships with the host's
+implementation in the same release.
+
+## Development
+
+```bash
+npm run dev     # card preview at http://127.0.0.1:5188/preview/, live from source
+npm test        # build the cards, run the tests
+npm run check   # format, build, typecheck, tests (CI)
+```
+
+Release: bump the version and tag `vX.Y.Z`; CI publishes to npm. Then bump the
+dependency in swan-backend.

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+interface SceneApi {
+    skill: {
+        name: string;
+        version: string;
+        instructions: string;
+        declarations: string;
+        examples: string[];
+    };
+    limits: {
+        timeoutMs: number;
+        maxCodeLength: number;
+        maxImages: number;
+    };
+    views: string[];
+    notes: string[];
+}
+interface Image {
+    data: string;
+    mimeType: string;
+}
+interface ScriptResult {
+    ok: boolean;
+    value?: unknown;
+    logs: string[];
+    receipts: {
+        operation: string;
+        status: string;
+    }[];
+    images: Image[];
+    error?: string;
+}
+interface Picture extends Image {
+    at: string;
+}
+interface Build {
+    status: "building" | "done";
+    activity?: string;
+    title?: string;
+    picture: Picture | null;
+}
+interface WompBackend {
+    openScene(subject: string, input: {
+        designId?: string;
+        title?: string;
+    }): Promise<{
+        designId: string;
+        buildId: string;
+        title: string;
+    }>;
+    getSceneApi(): Promise<SceneApi>;
+    runScript(subject: string, input: {
+        designId: string;
+        code: string;
+        purpose: string;
+    }): Promise<ScriptResult>;
+    renderScene(subject: string, input: {
+        designId: string;
+        view?: string;
+        targetId?: number;
+    }): Promise<Image>;
+    finishScene(subject: string, input: {
+        designId: string;
+        title: string;
+    }): Promise<void>;
+    getBuild(subject: string, input: {
+        designId: string;
+        buildId: string;
+    }): Promise<Build>;
+}
+declare class BackendRefusal extends Error {
+}
+
+interface ServerOptions {
+    backend: WompBackend;
+    subject?: string;
+    onError?: (tool: string, error: unknown) => void;
+    instructions?: string;
+}
+declare function createServer({ backend, subject, onError, instructions }: ServerOptions): McpServer;
+
+export { BackendRefusal, type WompBackend, createServer };