underwritten-mcp 0.0.0

package/README.md

@@ -0,0 +1,212 @@
+# Underwritten MCP Bridge
+
+`underwritten-mcp` is the local MCP companion for `underwritten.app`.
+
+It is the MCP server. The browser app is not.
+
+## Why this package exists
+
+`underwritten.app` is a PWA and the editor state lives in the browser. External MCP clients need a local process that can:
+
+- speak MCP over `stdio`
+- bind a localhost API
+- coordinate with the live browser editor session
+
+This package provides that bridge while the PWA remains the source of truth for document and workspace state.
+
+## Monorepo layout
+
+- `apps/mcp`: publishable MCP server package and localhost bridge
+- `apps/mcp/src/contract.ts`: shared browser-safe protocol types and markdown edit helpers
+- `apps/website`: PWA integration, bridge discovery, session registration, polling, and settings UI
+
+## User setup
+
+The intended end-user MCP config is:
+
+```json
+{
+  "mcpServers": {
+    "underwritten": {
+      "command": "npx",
+      "args": ["-y", "underwritten-mcp"]
+    }
+  }
+}
+```
+
+After that:
+
+1. The MCP client starts `underwritten-mcp`.
+2. The bridge binds a localhost API on `127.0.0.1`.
+3. The PWA discovers the bridge automatically and pairs without a manual token-copy step.
+4. The active editor tab registers itself and starts polling for pending actions.
+
+## Running locally
+
+Install dependencies first:
+
+```bash
+vp install
+```
+
+Run the website in one terminal:
+
+```bash
+vp run website#dev
+```
+
+Run the MCP bridge from source in another terminal:
+
+```bash
+vp dlx tsx apps/mcp/src/cli.ts
+```
+
+If you want to run the built output instead:
+
+```bash
+vp exec tsc -p apps/mcp/tsconfig.build.json
+node apps/mcp/dist/cli.js
+```
+
+If you want to test the user-facing bootstrap shape locally, the equivalent MCP client entry is still:
+
+```json
+{
+  "mcpServers": {
+    "underwritten": {
+      "command": "npx",
+      "args": ["-y", "underwritten-mcp"]
+    }
+  }
+}
+```
+
+## Validation
+
+Repo-level validation:
+
+```bash
+vp check
+vp test
+vp run test:e2e
+```
+
+MCP package build only:
+
+```bash
+vp exec tsc -p apps/mcp/tsconfig.build.json
+```
+
+## Discovery and pairing
+
+By default the PWA scans a reserved localhost port range and probes `GET /discover`.
+
+- Reserved range: `45261-45271`
+- Bind address: `127.0.0.1`
+- Pairing: automatic `POST /pair` from an approved Underwritten origin
+- Session sync: `POST /session/sync`
+- Status: `GET /status`
+
+For test isolation and local debugging, the browser also honors a `localStorage` override at `underwritten.mcp.bridgePorts` with an explicit JSON array of ports to probe.
+
+## Browser session model
+
+Each tab registers as a distinct session with:
+
+- `sessionId`
+- `activeFilePath`
+- `title`
+- `markdown`
+- `dirty`
+- `storageMode`
+- `nativeFolderSelected`
+- `revision`
+- `lastHeartbeatAt`
+- `lastFocusAt`
+- `visibilityState`
+- `pageUrl`
+- `windowLabel`
+
+The browser polls the bridge, receives queued actions, applies them through the existing `EditorPage` editor/workspace code paths, and posts the result back in the next sync.
+
+## Tool surface
+
+Workspace tools:
+
+- `get_workspace_status`
+- `list_files`
+- `read_file`
+- `open_file`
+- `create_file`
+- `create_folder`
+- `move_path`
+- `delete_path`
+- `save_document`
+
+Markdown tools:
+
+- `get_current_document`
+- `replace_current_document`
+- `apply_markdown_edits`
+
+### Markdown edit semantics
+
+`apply_markdown_edits` operates on raw markdown text, not editor-internal node ids.
+
+- Target matching is literal text matching.
+- `occurrence` is 1-based when provided.
+- If `occurrence` is omitted, the target text must match exactly once.
+- Ambiguous or missing targets fail with a clear error.
+- Edits apply sequentially to the updated markdown buffer.
+
+## Deterministic routing
+
+Current-document and workspace tools route to one live session:
+
+1. Keep only live sessions. A live session has a fresh heartbeat within `15s` and has not disconnected.
+2. Sort by most recent `lastFocusAt`.
+3. Break ties with most recent `lastHeartbeatAt`.
+4. Break remaining ties lexically by `sessionId`.
+5. If no live session remains, return an explicit error instead of guessing.
+
+This keeps tool routing deterministic across multiple open tabs while leaving room for future explicit `sessionId` targeting.
+
+## Security model
+
+- The HTTP bridge binds only to `127.0.0.1`.
+- Requests are limited to Underwritten origins plus local dev origins (`localhost` and `127.0.0.1`).
+- The browser must pair first and then present a bridge-issued bearer token.
+- The bridge does not expose shell execution.
+- Workspace operations are restricted to Underwritten’s real browser workspace model.
+- Native folder access still depends on the browser-granted File System Access handle already chosen in the app.
+
+### Threat model limits
+
+- Pairing is automatic for approved origins, so trust is anchored in the origin allowlist and localhost-only binding.
+- A malicious script running on an approved Underwritten origin would inherit the same bridge access as the app.
+- Multiple simultaneous MCP bridge processes are supported, but the browser only probes the configured port list/range and pairs with bridges it can discover.
+
+## Settings UI
+
+The existing settings dialog now includes an `MCP Bridge` section with:
+
+- reachability / connection status
+- current session id
+- detected localhost port
+- known session count
+- copyable MCP config snippet
+- reconnect action
+
+## Current limitations
+
+- The public tool surface does not yet support explicit `sessionId` targeting.
+- `delete_path.force` only bypasses unsaved-current-document protection; it is not a separate recursive-delete flag because the browser file APIs already define directory deletion behavior.
+- The settings panel reports bridge/session status from the local browser’s perspective; it is not a multi-client admin console.
+
+## Future improvements
+
+- explicit `sessionId` tool targeting
+- richer bridge diagnostics and per-session inspection
+- optional Streamable HTTP exposure in addition to `stdio`
+- stronger persisted pairing state if the product needs cross-restart trust continuity

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { underwrittenBridgePortRange } from "./contract.js";
+import { startUnderwrittenBridge } from "./index.js";
+const startedBridge = await startUnderwrittenBridge({
+    connectStdio: true,
+    portRange: underwrittenBridgePortRange,
+});
+const shutdown = async () => {
+    await startedBridge.close();
+    process.exit(0);
+};
+process.on("SIGINT", () => {
+    void shutdown();
+});
+process.on("SIGTERM", () => {
+    void shutdown();
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAE5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,aAAa,GAAG,MAAM,uBAAuB,CAAC;IAClD,YAAY,EAAE,IAAI;IAClB,SAAS,EAAE,2BAA2B;CACvC,CAAC,CAAC;AAEH,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;IAC1B,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC;IAC5B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC;AAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;IACxB,KAAK,QAAQ,EAAE,CAAC;AAClB,CAAC,CAAC,CAAC;AACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;IACzB,KAAK,QAAQ,EAAE,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/contract.d.ts

@@ -0,0 +1,179 @@
+export declare const underwrittenBridgePortRange: {
+    readonly end: 45271;
+    readonly start: 45261;
+};
+export declare const underwrittenBridgeApiVersion = "2026-03-16";
+export declare const underwrittenBridgeSessionTtlMs = 15000;
+export declare const underwrittenBridgePollIntervalMs = 1000;
+export declare const underwrittenBridgeActionTimeoutMs = 20000;
+export type UnderwrittenStorageMode = "origin-private" | "native-folder";
+export type MarkdownEditTarget = {
+    occurrence?: number;
+    text: string;
+};
+export type MarkdownEdit = {
+    newText?: string;
+    target: MarkdownEditTarget;
+    type: "delete" | "insert_after" | "insert_before" | "replace";
+};
+export type WorkspaceStatus = {
+    activeFilePath: string | null;
+    hasNativeFolderSelected: boolean;
+    hasUnsavedChanges: boolean;
+    storageMode: UnderwrittenStorageMode;
+};
+export type MarkdownOutlineItem = {
+    depth: number;
+    line: number;
+    text: string;
+};
+export type CurrentDocument = {
+    dirty: boolean;
+    filePath: string | null;
+    markdown: string;
+    outline?: MarkdownOutlineItem[];
+    storageMode: UnderwrittenStorageMode;
+    title: string;
+};
+export type BridgeSessionCapabilities = {
+    supportsDirectoryAccess: boolean;
+};
+export type BridgeSessionState = {
+    activeFilePath: string | null;
+    appCapabilities: BridgeSessionCapabilities;
+    dirty: boolean;
+    lastFocusAt: number | null;
+    lastHeartbeatAt: number;
+    markdown: string;
+    nativeFolderSelected: boolean;
+    pageUrl: string | null;
+    revision: string | null;
+    sessionId: string;
+    storageMode: UnderwrittenStorageMode;
+    title: string;
+    visibilityState: "hidden" | "visible";
+    windowLabel: string | null;
+};
+export type GetWorkspaceStatusAction = {
+    id: string;
+    type: "get_workspace_status";
+};
+export type ListFilesAction = {
+    id: string;
+    includeDirectories?: boolean;
+    path?: string;
+    recursive?: boolean;
+    type: "list_files";
+};
+export type ReadFileAction = {
+    id: string;
+    path: string;
+    type: "read_file";
+};
+export type OpenFileAction = {
+    discardUnsavedChanges?: boolean;
+    id: string;
+    path: string;
+    type: "open_file";
+};
+export type CreateFileAction = {
+    content?: string;
+    id: string;
+    openAfterCreate?: boolean;
+    path: string;
+    type: "create_file";
+};
+export type CreateFolderAction = {
+    id: string;
+    path: string;
+    type: "create_folder";
+};
+export type MovePathAction = {
+    destinationPath: string;
+    id: string;
+    sourcePath: string;
+    type: "move_path";
+};
+export type DeletePathAction = {
+    force?: boolean;
+    id: string;
+    path: string;
+    type: "delete_path";
+};
+export type SaveDocumentAction = {
+    id: string;
+    path?: string;
+    type: "save_document";
+};
+export type GetCurrentDocumentAction = {
+    id: string;
+    includeOutline?: boolean;
+    type: "get_current_document";
+};
+export type ReplaceCurrentDocumentAction = {
+    id: string;
+    markdown: string;
+    type: "replace_current_document";
+};
+export type ApplyMarkdownEditsAction = {
+    edits: MarkdownEdit[];
+    id: string;
+    type: "apply_markdown_edits";
+};
+export type UnderwrittenBridgeAction = ApplyMarkdownEditsAction | CreateFileAction | CreateFolderAction | DeletePathAction | GetCurrentDocumentAction | GetWorkspaceStatusAction | ListFilesAction | MovePathAction | OpenFileAction | ReadFileAction | ReplaceCurrentDocumentAction | SaveDocumentAction;
+export type UnderwrittenBridgeActionResult = {
+    actionId: string;
+    error: {
+        code: string;
+        message: string;
+    };
+    ok: false;
+} | {
+    actionId: string;
+    ok: true;
+    result: unknown;
+};
+export type UnderwrittenBridgeDiscoveryResponse = {
+    apiVersion: string;
+    appName: "underwritten";
+    bridgeId: string;
+    port: number;
+};
+export type UnderwrittenBridgePairRequest = {
+    pageUrl?: string | null;
+    sessionId: string;
+};
+export type UnderwrittenBridgePairResponse = {
+    apiVersion: string;
+    browserToken: string;
+    bridgeId: string;
+    pollIntervalMs: number;
+    sessionTtlMs: number;
+};
+export type UnderwrittenBridgeSessionSyncRequest = {
+    completedActions?: UnderwrittenBridgeActionResult[];
+    session: BridgeSessionState;
+};
+export type UnderwrittenBridgeSessionSyncResponse = {
+    pendingActions: UnderwrittenBridgeAction[];
+    serverTime: number;
+};
+export type UnderwrittenBridgeDisconnectRequest = {
+    sessionId: string;
+};
+export type UnderwrittenBridgeStatusResponse = {
+    activeSessionId: string | null;
+    bridgeId: string;
+    pairings: number;
+    port: number;
+    resolvedBy: "lastFocusAt,lastHeartbeatAt,sessionId" | "none";
+    sessions: Array<BridgeSessionState & {
+        connectedAt: number;
+        disconnectedAt: number | null;
+        origin: string;
+    }>;
+};
+export declare function createSessionId(): string;
+export declare function applyMarkdownTextEdits(markdown: string, edits: MarkdownEdit[]): string;
+export declare function buildMarkdownOutline(markdown: string): MarkdownOutlineItem[];
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/contract.js

@@ -0,0 +1,97 @@
+export const underwrittenBridgePortRange = {
+    end: 45271,
+    start: 45261,
+};
+export const underwrittenBridgeApiVersion = "2026-03-16";
+export const underwrittenBridgeSessionTtlMs = 15_000;
+export const underwrittenBridgePollIntervalMs = 1_000;
+export const underwrittenBridgeActionTimeoutMs = 20_000;
+export function createSessionId() {
+    return `uw-session-${Math.random().toString(36).slice(2, 10)}-${Date.now().toString(36)}`;
+}
+function findAllOccurrences(haystack, needle) {
+    if (needle.length === 0) {
+        throw new Error("Markdown edit targets must not be empty.");
+    }
+    const positions = [];
+    let fromIndex = 0;
+    while (fromIndex <= haystack.length) {
+        const index = haystack.indexOf(needle, fromIndex);
+        if (index < 0)
+            break;
+        positions.push(index);
+        fromIndex = index + needle.length;
+    }
+    return positions;
+}
+function resolveOccurrence(markdown, target) {
+    const positions = findAllOccurrences(markdown, target.text);
+    if (positions.length === 0) {
+        throw new Error(`Target text not found: ${JSON.stringify(target.text)}`);
+    }
+    if (typeof target.occurrence === "number") {
+        if (!Number.isInteger(target.occurrence) || target.occurrence < 1) {
+            throw new Error("Target occurrence must be a positive integer.");
+        }
+        const position = positions[target.occurrence - 1];
+        if (typeof position !== "number") {
+            throw new Error(`Target occurrence ${target.occurrence} was not found for ${JSON.stringify(target.text)}.`);
+        }
+        return position;
+    }
+    if (positions.length > 1) {
+        throw new Error(`Target text is ambiguous without an occurrence: ${JSON.stringify(target.text)}.`);
+    }
+    return positions[0] ?? 0;
+}
+export function applyMarkdownTextEdits(markdown, edits) {
+    let nextMarkdown = markdown;
+    for (const edit of edits) {
+        const start = resolveOccurrence(nextMarkdown, edit.target);
+        const end = start + edit.target.text.length;
+        switch (edit.type) {
+            case "replace": {
+                if (typeof edit.newText !== "string") {
+                    throw new Error("Replace edits require newText.");
+                }
+                nextMarkdown = `${nextMarkdown.slice(0, start)}${edit.newText}${nextMarkdown.slice(end)}`;
+                break;
+            }
+            case "insert_before": {
+                if (typeof edit.newText !== "string") {
+                    throw new Error("insert_before edits require newText.");
+                }
+                nextMarkdown = `${nextMarkdown.slice(0, start)}${edit.newText}${nextMarkdown.slice(start)}`;
+                break;
+            }
+            case "insert_after": {
+                if (typeof edit.newText !== "string") {
+                    throw new Error("insert_after edits require newText.");
+                }
+                nextMarkdown = `${nextMarkdown.slice(0, end)}${edit.newText}${nextMarkdown.slice(end)}`;
+                break;
+            }
+            case "delete": {
+                nextMarkdown = `${nextMarkdown.slice(0, start)}${nextMarkdown.slice(end)}`;
+                break;
+            }
+        }
+    }
+    return nextMarkdown;
+}
+export function buildMarkdownOutline(markdown) {
+    return markdown.split("\n").flatMap((line, index) => {
+        const match = /^(#{1,6})\s+(.*\S)\s*$/.exec(line);
+        if (!match) {
+            return [];
+        }
+        return [
+            {
+                depth: match[1].length,
+                line: index + 1,
+                text: match[2],
+            },
+        ];
+    });
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/contract.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.test.d.ts.map

package/dist/contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.test.d.ts","sourceRoot":"","sources":["../src/contract.test.ts"],"names":[],"mappings":""}

package/dist/contract.test.js

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "vite-plus/test";
+import { applyMarkdownTextEdits, buildMarkdownOutline } from "./contract.js";
+describe("contract helpers", () => {
+    test("applies sequential markdown edits", () => {
+        const markdown = "# Title\n\nAlpha\nBeta\n";
+        expect(applyMarkdownTextEdits(markdown, [
+            {
+                newText: "Intro\n",
+                target: { text: "Alpha" },
+                type: "insert_before",
+            },
+            {
+                newText: "Gamma",
+                target: { text: "Beta" },
+                type: "replace",
+            },
+        ])).toBe("# Title\n\nIntro\nAlpha\nGamma\n");
+    });
+    test("requires occurrence when the target text is ambiguous", () => {
+        expect(() => applyMarkdownTextEdits("repeat\nrepeat\n", [
+            {
+                target: { text: "repeat" },
+                type: "delete",
+            },
+        ])).toThrow("ambiguous");
+    });
+    test("builds a markdown outline with heading depth and line numbers", () => {
+        expect(buildMarkdownOutline("# Title\n\n## First\nBody\n### Nested\n")).toEqual([
+            { depth: 1, line: 1, text: "Title" },
+            { depth: 2, line: 3, text: "First" },
+            { depth: 3, line: 5, text: "Nested" },
+        ]);
+    });
+});
+//# sourceMappingURL=contract.test.js.map

package/dist/contract.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.test.js","sourceRoot":"","sources":["../src/contract.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE7E,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,IAAI,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC7C,MAAM,QAAQ,GAAG,0BAA0B,CAAC;QAE5C,MAAM,CACJ,sBAAsB,CAAC,QAAQ,EAAE;YAC/B;gBACE,OAAO,EAAE,SAAS;gBAClB,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;gBACzB,IAAI,EAAE,eAAe;aACtB;YACD;gBACE,OAAO,EAAE,OAAO;gBAChB,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;gBACxB,IAAI,EAAE,SAAS;aAChB;SACF,CAAC,CACH,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,uDAAuD,EAAE,GAAG,EAAE;QACjE,MAAM,CAAC,GAAG,EAAE,CACV,sBAAsB,CAAC,kBAAkB,EAAE;YACzC;gBACE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC1B,IAAI,EAAE,QAAQ;aACf;SACF,CAAC,CACH,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,+DAA+D,EAAE,GAAG,EAAE;QACzE,MAAM,CAAC,oBAAoB,CAAC,yCAAyC,CAAC,CAAC,CAAC,OAAO,CAAC;YAC9E,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE;YACpC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE;YACpC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE;SACtC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/http-server.d.ts

@@ -0,0 +1,4 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { type UnderwrittenBridgeService } from "./service.js";
+export declare function createHttpServer(service: UnderwrittenBridgeService, port: number): Promise<import("http").Server<typeof IncomingMessage, typeof ServerResponse>>;
+//# sourceMappingURL=http-server.d.ts.map

package/dist/http-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAUpF,OAAO,EAEL,KAAK,yBAAyB,EAE/B,MAAM,cAAc,CAAC;AAqItB,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,yBAAyB,EAAE,IAAI,EAAE,MAAM,iFA4FtF"}