@disusered/okf-cli 1.4.0 → 2.1.0

package/dist/mcp/help.js

@@ -0,0 +1,36 @@
+import { OKF_V1_MCP_PATH } from "okf-contracts";
+import { DEFAULT_HTTP_PORT, LOOPBACK_HOST } from "./arguments.js";
+import { HEALTH_PATH } from "./http.js";
+export const HELP = `okf mcp — serve one filesystem OKF bundle over MCP
+
+Usage:
+  okf mcp <project-root> --bundle NAME [options]
+
+Options:
+  --bundle NAME           The manifest bundle to serve. Always required.
+  --profile-module PATH   Trusted validation profile module, resolved against the
+                          project root. It must export \`profile\`.
+  --today YYYY-MM-DD      Date staleness is judged against. Never defaulted.
+  --http                  Serve loopback HTTP instead of stdio.
+  --port N                HTTP port (default ${String(DEFAULT_HTTP_PORT)}). Requires --http.
+  --allowed-host HOST     Accept HOST as the Host a tunnel or reverse proxy
+                          forwards. Repeatable. Requires --http.
+  -h, --help              Print this help.
+
+Identity (what a client shows and a model reads first):
+  --name NAME             Server name (default okf-<bundle>).
+  --title TEXT            Human-readable title.
+  --description TEXT      One or two sentences on what the server holds.
+  --website URL           Where a person can learn more.
+  --icon URL              Icon a client may show beside the server.
+  --purpose TEXT          One sentence that opens the server instructions.
+
+In stdio mode standard output carries protocol traffic only; diagnostics go to
+standard error.
+
+With --http the server binds ${LOOPBACK_HOST} only and serves ${OKF_V1_MCP_PATH}, plus
+GET ${HEALTH_PATH}. It refuses any Host or Origin that is neither localhost nor an
+--allowed-host. Publishing a loopback server is the job of the tunnel or proxy in
+front of it, which also authenticates every caller.
+`;
+//# sourceMappingURL=help.js.map

package/dist/mcp/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/mcp/help.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,MAAM,CAAC,MAAM,IAAI,GAAG;;;;;;;;;;;+CAW2B,MAAM,CAAC,iBAAiB,CAAC;;;;;;;;;;;;;;;;+BAgBzC,aAAa,oBAAoB,eAAe;MACzE,WAAW;;;CAGhB,CAAC"}

package/dist/mcp/http.d.ts

@@ -0,0 +1,34 @@
+import { type Server } from "node:http";
+import { type McpServerFactory } from "@modelcontextprotocol/server";
+export interface ServeHttpOptions {
+    /** 0 asks the operating system for an ephemeral port; the handle reports what it got. */
+    readonly port: number;
+    /**
+     * Public hostnames a tunnel or reverse proxy forwards to this loopback listener. Each is
+     * accepted as the hostname of `Host` and of `Origin`. Authentication for those names
+     * belongs to the proxy in front; this listener stays on loopback either way.
+     */
+    readonly allowedHosts?: readonly string[];
+    /** Named in `/healthz`. */
+    readonly service?: string;
+    readonly version?: string;
+    readonly onerror?: (error: Error) => void;
+}
+/** The liveness route. It reads nothing from the Bundle and needs no MCP session. */
+export declare const HEALTH_PATH = "/healthz";
+export interface HttpServerHandle {
+    readonly server: Server;
+    readonly port: number;
+    /** The exact endpoint to configure a client with. */
+    readonly url: string;
+    close(): Promise<void>;
+}
+/**
+ * Serve the MCP surface over loopback HTTP.
+ *
+ * The listener binds {@link LOOPBACK_HOST} only, and every request is checked against the
+ * localhost `Host` and `Origin` allowlists before it reaches the handler: a local server that
+ * reads a private corpus must not become reachable from a page the browser happens to load.
+ */
+export declare function serveHttp(factory: McpServerFactory, options: ServeHttpOptions): Promise<HttpServerHandle>;
+//# sourceMappingURL=http.d.ts.map

package/dist/mcp/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/mcp/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAGjG,OAAO,EAML,KAAK,gBAAgB,EACtB,MAAM,8BAA8B,CAAC;AAKtC,MAAM,WAAW,gBAAgB;IAC/B,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC3C;AAED,qFAAqF;AACrF,eAAO,MAAM,WAAW,aAAa,CAAC;AAEtC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAoDD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAgE3B"}

package/dist/mcp/http.js

@@ -0,0 +1,132 @@
+import { createServer } from "node:http";
+import { createMcpHandler, hostHeaderValidationResponse, localhostAllowedHostnames, localhostAllowedOrigins, originValidationResponse, } from "@modelcontextprotocol/server";
+import { OKF_V1_MCP_PATH } from "okf-contracts";
+import { LOOPBACK_HOST } from "./arguments.js";
+/** The liveness route. It reads nothing from the Bundle and needs no MCP session. */
+export const HEALTH_PATH = "/healthz";
+/** The exact bytes, so nothing here has to assume the request body is UTF-8 text. */
+async function readBody(message) {
+    const chunks = [];
+    for await (const chunk of message) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const merged = Buffer.concat(chunks);
+    return merged.buffer.slice(merged.byteOffset, merged.byteOffset + merged.byteLength);
+}
+function toRequest(message, body, port) {
+    const host = message.headers.host ?? `${LOOPBACK_HOST}:${String(port)}`;
+    const url = new URL(message.url ?? "/", `http://${host}`);
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(message.headers)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value))
+            for (const item of value)
+                headers.append(name, item);
+        else
+            headers.set(name, value);
+    }
+    const method = message.method ?? "GET";
+    const hasBody = method !== "GET" && method !== "HEAD";
+    return new Request(url, { method, headers, ...(hasBody ? { body } : {}) });
+}
+async function send(response, target) {
+    const headers = {};
+    for (const [name, value] of response.headers)
+        headers[name] = value;
+    target.writeHead(response.status, headers);
+    if (response.body === null) {
+        target.end();
+        return;
+    }
+    // Streamed so a `text/event-stream` exchange reaches the client as it is produced rather
+    // than at the end of the response. A client that hangs up mid-stream cancels the reader,
+    // so the handler stops producing instead of writing into a dead socket.
+    const reader = response.body.getReader();
+    const cancel = () => { void reader.cancel(); };
+    target.once("close", cancel);
+    try {
+        while (!target.writableEnded) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            target.write(value);
+        }
+    }
+    finally {
+        target.removeListener("close", cancel);
+    }
+    target.end();
+}
+/**
+ * Serve the MCP surface over loopback HTTP.
+ *
+ * The listener binds {@link LOOPBACK_HOST} only, and every request is checked against the
+ * localhost `Host` and `Origin` allowlists before it reaches the handler: a local server that
+ * reads a private corpus must not become reachable from a page the browser happens to load.
+ */
+export async function serveHttp(factory, options) {
+    const handler = createMcpHandler(factory, {
+        ...(options.onerror === undefined ? {} : { onerror: options.onerror }),
+    });
+    // Both allowlists hold hostnames: the SDK compares the hostname of `Host` and of `Origin`.
+    const forwarded = (options.allowedHosts ?? []).map((host) => host.replace(/:\d+$/, ""));
+    const allowedHosts = [...localhostAllowedHostnames(), ...forwarded];
+    const allowedOrigins = [...localhostAllowedOrigins(), ...forwarded];
+    const health = JSON.stringify({
+        status: "ok",
+        ...(options.service === undefined ? {} : { service: options.service }),
+        ...(options.version === undefined ? {} : { version: options.version }),
+    });
+    const server = createServer((message, target) => {
+        void (async () => {
+            try {
+                const body = await readBody(message);
+                const port = server.address()?.port ?? options.port;
+                const request = toRequest(message, body, port);
+                const refused = hostHeaderValidationResponse(request, allowedHosts)
+                    ?? originValidationResponse(request, allowedOrigins);
+                if (refused) {
+                    await send(refused, target);
+                    return;
+                }
+                const { pathname } = new URL(request.url);
+                if (pathname === HEALTH_PATH && request.method === "GET") {
+                    target.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" }).end(health);
+                    return;
+                }
+                if (pathname !== OKF_V1_MCP_PATH) {
+                    target.writeHead(404).end();
+                    return;
+                }
+                await send(await handler.fetch(request), target);
+            }
+            catch (error) {
+                options.onerror?.(error instanceof Error ? error : new Error(String(error)));
+                if (!target.headersSent)
+                    target.writeHead(500);
+                target.end();
+            }
+        })();
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, LOOPBACK_HOST, () => {
+            server.removeListener("error", reject);
+            resolve();
+        });
+    });
+    const port = server.address().port;
+    return {
+        server,
+        port,
+        url: `http://${LOOPBACK_HOST}:${String(port)}${OKF_V1_MCP_PATH}`,
+        async close() {
+            await handler.close();
+            await new Promise((resolve, reject) => {
+                server.close((error) => (error ? reject(error) : resolve()));
+            });
+        },
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/mcp/http.js.map

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

package/dist/mcp/index.d.ts

@@ -0,0 +1,8 @@
+export { DEFAULT_HTTP_PORT, LOOPBACK_HOST, parseServerArguments as parseMcpArguments, type ServerArguments as McpServerArguments, } from "./arguments.js";
+export { bundleSettings, type BundleAccess, type BundleSettings } from "./bundle.js";
+export { HELP as MCP_HELP } from "./help.js";
+export { HEALTH_PATH, serveHttp, type HttpServerHandle, type ServeHttpOptions } from "./http.js";
+export { runMcp } from "./serve.js";
+export { createFilesystemOkfV1Operations, ReadOnlyBundleError, type FilesystemOkfV1OperationsOptions, } from "./operations.js";
+export { createOkfLocalServer, SERVER_VERSION, type OkfLocalServer, type OkfLocalServerOptions, } from "./server.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,oBAAoB,IAAI,iBAAiB,EACzC,KAAK,eAAe,IAAI,kBAAkB,GAC3C,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACjG,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACpC,OAAO,EACL,+BAA+B,EAC/B,mBAAmB,EACnB,KAAK,gCAAgC,GACtC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,qBAAqB,GAC3B,MAAM,aAAa,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,8 @@
+export { DEFAULT_HTTP_PORT, LOOPBACK_HOST, parseServerArguments as parseMcpArguments, } from "./arguments.js";
+export { bundleSettings } from "./bundle.js";
+export { HELP as MCP_HELP } from "./help.js";
+export { HEALTH_PATH, serveHttp } from "./http.js";
+export { runMcp } from "./serve.js";
+export { createFilesystemOkfV1Operations, ReadOnlyBundleError, } from "./operations.js";
+export { createOkfLocalServer, SERVER_VERSION, } from "./server.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,oBAAoB,IAAI,iBAAiB,GAE1C,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,cAAc,EAA0C,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAgD,MAAM,WAAW,CAAC;AACjG,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACpC,OAAO,EACL,+BAA+B,EAC/B,mBAAmB,GAEpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,oBAAoB,EACpB,cAAc,GAGf,MAAM,aAAa,CAAC"}

package/dist/mcp/operations.d.ts

@@ -0,0 +1,23 @@
+import { type AnalyzeBundleOptions } from "okf-core";
+import type { OkfV1Operations } from "okf-contracts";
+import { type ResolvedBundleTarget } from "okf-node";
+import type { BundleSettings } from "./bundle.js";
+/** A writing operation reached a bundle whose manifest declares `access: read`. */
+export declare class ReadOnlyBundleError extends Error {
+    readonly code = "OKF_BUNDLE_READ_ONLY";
+    constructor(bundle: string, operation: string);
+}
+export interface FilesystemOkfV1OperationsOptions {
+    readonly target: ResolvedBundleTarget;
+    readonly settings: BundleSettings;
+    readonly analysis?: AnalyzeBundleOptions;
+    /**
+     * Where `okf_v1_visualize` writes the generated page. A local client opens a file, not a
+     * URL served by this process, so the page has to land somewhere on disk. Defaults to a
+     * per-process temporary directory created on the first call.
+     */
+    readonly visualizationDirectory?: string;
+}
+/** Create all versioned MCP operations for one filesystem bundle. */
+export declare function createFilesystemOkfV1Operations(options: FilesystemOkfV1OperationsOptions): OkfV1Operations;
+//# sourceMappingURL=operations.d.ts.map

package/dist/mcp/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/mcp/operations.ts"],"names":[],"mappings":"AAMA,OAAO,EAA6E,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChI,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,UAAU,CAAC;AAGlB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,mFAAmF;AACnF,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,0BAA0B;IAEvC,YAAY,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAG5C;CACF;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AAMD,qEAAqE;AACrE,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,gCAAgC,GACxC,eAAe,CAgGjB"}

package/dist/mcp/operations.js

@@ -0,0 +1,117 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { generateBundleIndexes, selectBundleIndex, listBundleEntries, searchBundle } from "okf-core";
+import { applyChange, previewChange, readBundleContext, } from "okf-node";
+import { generateVisualization } from "../generate.js";
+/** A writing operation reached a bundle whose manifest declares `access: read`. */
+export class ReadOnlyBundleError extends Error {
+    code = "OKF_BUNDLE_READ_ONLY";
+    constructor(bundle, operation) {
+        super(`bundle ${bundle} declares access: read; ${operation} is not available`);
+        this.name = "ReadOnlyBundleError";
+    }
+}
+function isNotFound(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+/** Create all versioned MCP operations for one filesystem bundle. */
+export function createFilesystemOkfV1Operations(options) {
+    const bundle = options.settings.name;
+    // `FilesystemBundle.analyze` walks the root itself and threads what it finds that is not a
+    // document, so a contract path naming a query or an attester script still resolves.
+    const analyze = () => options.target.bundle.analyze(options.analysis ?? {});
+    let visualizationDirectory = options.visualizationDirectory;
+    const visualizationTarget = async () => {
+        visualizationDirectory ??= await mkdtemp(path.join(tmpdir(), "okf-mcp-viz-"));
+        return path.join(visualizationDirectory, `${bundle}.html`);
+    };
+    const writable = (operation) => {
+        if (options.settings.access === "read") {
+            throw new ReadOnlyBundleError(bundle, operation);
+        }
+    };
+    return {
+        async index({ path: requested }) {
+            return { bundle, ...selectBundleIndex(generateBundleIndexes(await analyze()), requested) };
+        },
+        async context() {
+            let index = null;
+            try {
+                index = await options.target.bundle.readDocument(options.settings.index);
+            }
+            catch (error) {
+                if (!isNotFound(error))
+                    throw error;
+            }
+            return {
+                adapter: options.settings.adapter,
+                bundle,
+                audience: options.settings.audience,
+                access: options.settings.access,
+                instructions: await readBundleContext(options.target),
+                index,
+                navigation: selectBundleIndex(generateBundleIndexes(await analyze())),
+            };
+        },
+        async list({ path: requested, depth }) {
+            const paths = await options.target.bundle.listPaths();
+            return { bundle, path: requested, entries: listBundleEntries(paths, requested, depth) };
+        },
+        async search({ query, limit }) {
+            return { bundle, query, ...searchBundle(await analyze(), query, limit) };
+        },
+        async read({ path: requested }) {
+            return { bundle, ...await options.target.bundle.readDocument(requested) };
+        },
+        async links({ path: requested }) {
+            const analysis = await analyze();
+            const document = analysis.documents.find((entry) => entry.path === requested);
+            if (!document)
+                throw new Error(`path does not exist in bundle ${bundle}: ${requested}`);
+            const backlinks = analysis.documents.flatMap((entry) => entry.links
+                .filter((link) => link.resolvedPath === requested && entry.path !== requested)
+                .map((link) => ({ path: entry.path, href: link.href })));
+            return { bundle, path: requested, outgoing: document.links, backlinks };
+        },
+        async validate() {
+            const analysis = await analyze();
+            const diagnostics = [
+                ...analysis.diagnostics.core,
+                ...analysis.diagnostics.guidance,
+                ...analysis.diagnostics.profile,
+            ];
+            return {
+                bundle,
+                passed: diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
+                diagnostics: analysis.diagnostics,
+                summary: analysis.summary,
+            };
+        },
+        async inspect() {
+            return { ...await analyze() };
+        },
+        async visualize() {
+            const analysis = await analyze();
+            const output = await visualizationTarget();
+            await writeFile(output, generateVisualization({
+                bundle,
+                analysis,
+                // The same explicit date the analysis used, or nothing. Never the system clock, or
+                // the page stops being reproducible from the bundle.
+                evaluatedAt: options.analysis?.today ?? null,
+            }), "utf8");
+            return { bundle, url: pathToFileURL(output).href, path: output };
+        },
+        async previewChange(change) {
+            writable("okf_v1_preview_change");
+            return previewChange(options.target.bundle, change, options.analysis ?? {});
+        },
+        async applyChange(request) {
+            writable("okf_v1_apply_change");
+            return applyChange(options.target.bundle, request, options.analysis ?? {});
+        },
+    };
+}
+//# sourceMappingURL=operations.js.map

package/dist/mcp/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../src/mcp/operations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,YAAY,EAA6B,MAAM,UAAU,CAAC;AAEhI,OAAO,EACL,WAAW,EACX,aAAa,EACb,iBAAiB,GAElB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAIvD,mFAAmF;AACnF,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,GAAG,sBAAsB,CAAC;IAEvC,YAAY,MAAc,EAAE,SAAiB;QAC3C,KAAK,CAAC,UAAU,MAAM,2BAA2B,SAAS,mBAAmB,CAAC,CAAC;QAC/E,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAcD,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;AACnG,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,+BAA+B,CAC7C,OAAyC;IAEzC,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;IACrC,2FAA2F;IAC3F,oFAAoF;IACpF,MAAM,OAAO,GAAG,GAA4B,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAErG,IAAI,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAC5D,MAAM,mBAAmB,GAAG,KAAK,IAAqB,EAAE;QACtD,sBAAsB,KAAK,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,GAAG,MAAM,OAAO,CAAC,CAAC;IAC7D,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,CAAC,SAAiB,EAAQ,EAAE;QAC3C,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YACvC,MAAM,IAAI,mBAAmB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACnD,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;YAC7B,OAAO,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAAC,qBAAqB,CAAC,MAAM,OAAO,EAAE,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC;QAC7F,CAAC;QACD,KAAK,CAAC,OAAO;YACX,IAAI,KAAK,GAAG,IAAI,CAAC;YACjB,IAAI,CAAC;gBACH,KAAK,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC3E,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;oBAAE,MAAM,KAAK,CAAC;YACtC,CAAC;YACD,OAAO;gBACL,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,OAAO;gBACjC,MAAM;gBACN,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBACnC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAC/B,YAAY,EAAE,MAAM,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC;gBACrD,KAAK;gBACL,UAAU,EAAE,iBAAiB,CAAC,qBAAqB,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC;aACtE,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE;YACnC,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YACtD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC;QAC1F,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE;YAC3B,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,YAAY,CAAC,MAAM,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;QAC3E,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;YAC5B,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5E,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;YAC7B,MAAM,QAAQ,GAAG,MAAM,OAAO,EAAE,CAAC;YACjC,MAAM,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;YAC9E,IAAI,CAAC,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,MAAM,KAAK,SAAS,EAAE,CAAC,CAAC;YACxF,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK;iBAChE,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;iBAC7E,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAC3D,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC;QAC1E,CAAC;QACD,KAAK,CAAC,QAAQ;YACZ,MAAM,QAAQ,GAAG,MAAM,OAAO,EAAE,CAAC;YACjC,MAAM,WAAW,GAAG;gBAClB,GAAG,QAAQ,CAAC,WAAW,CAAC,IAAI;gBAC5B,GAAG,QAAQ,CAAC,WAAW,CAAC,QAAQ;gBAChC,GAAG,QAAQ,CAAC,WAAW,CAAC,OAAO;aAChC,CAAC;YACF,OAAO;gBACL,MAAM;gBACN,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,KAAK,OAAO,CAAC;gBAC1E,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,OAAO,EAAE,QAAQ,CAAC,OAAO;aAC1B,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,OAAO;YACX,OAAO,EAAE,GAAG,MAAM,OAAO,EAAE,EAAE,CAAC;QAChC,CAAC;QACD,KAAK,CAAC,SAAS;YACb,MAAM,QAAQ,GAAG,MAAM,OAAO,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,MAAM,mBAAmB,EAAE,CAAC;YAC3C,MAAM,SAAS,CAAC,MAAM,EAAE,qBAAqB,CAAC;gBAC5C,MAAM;gBACN,QAAQ;gBACR,mFAAmF;gBACnF,qDAAqD;gBACrD,WAAW,EAAE,OAAO,CAAC,QAAQ,EAAE,KAAK,IAAI,IAAI;aAC7C,CAAC,EAAE,MAAM,CAAC,CAAC;YACZ,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QACnE,CAAC;QACD,KAAK,CAAC,aAAa,CAAC,MAAc;YAChC,QAAQ,CAAC,uBAAuB,CAAC,CAAC;YAClC,OAAO,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;QAC9E,CAAC;QACD,KAAK,CAAC,WAAW,CAAC,OAA2B;YAC3C,QAAQ,CAAC,qBAAqB,CAAC,CAAC;YAChC,OAAO,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;QAC7E,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/mcp/serve.d.ts

@@ -0,0 +1,3 @@
+/** `okf mcp`: serve one filesystem bundle over stdio, or loopback HTTP with `--http`. */
+export declare function runMcp(argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/mcp/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/mcp/serve.ts"],"names":[],"mappings":"AAeA,yFAAyF;AACzF,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkDrE"}

package/dist/mcp/serve.js

@@ -0,0 +1,66 @@
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { parseServerArguments } from "./arguments.js";
+import { HELP } from "./help.js";
+import { serveHttp } from "./http.js";
+import { createOkfLocalServer } from "./server.js";
+/**
+ * Diagnostics never touch standard output. In stdio mode that stream is the protocol, and
+ * one stray line of prose ends the session.
+ */
+function note(message) {
+    process.stderr.write(`okf mcp: ${message}\n`);
+}
+/** `okf mcp`: serve one filesystem bundle over stdio, or loopback HTTP with `--http`. */
+export async function runMcp(argv) {
+    let arguments_;
+    try {
+        arguments_ = parseServerArguments(argv);
+    }
+    catch (error) {
+        note(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+    if (arguments_.help) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    let local;
+    try {
+        local = await createOkfLocalServer({
+            projectRoot: arguments_.projectRoot,
+            bundle: arguments_.bundle,
+            ...(arguments_.profileModule === undefined ? {} : { profileModule: arguments_.profileModule }),
+            ...(arguments_.today === undefined ? {} : { today: arguments_.today }),
+            ...(arguments_.name === undefined ? {} : { name: arguments_.name }),
+            identity: {
+                ...(arguments_.title === undefined ? {} : { title: arguments_.title }),
+                ...(arguments_.description === undefined ? {} : { description: arguments_.description }),
+                ...(arguments_.website === undefined ? {} : { websiteUrl: arguments_.website }),
+                ...(arguments_.icon === undefined ? {} : { icons: [{ src: arguments_.icon }] }),
+                ...(arguments_.purpose === undefined ? {} : { purpose: arguments_.purpose }),
+            },
+            cwd: process.cwd(),
+        });
+    }
+    catch (error) {
+        note(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+    const factory = () => local.createServer();
+    const served = `bundle ${local.settings.name} (${local.settings.access}) from ${local.target.bundle.root}`;
+    if (arguments_.http) {
+        const handle = await serveHttp(factory, {
+            port: arguments_.port,
+            allowedHosts: arguments_.allowedHosts,
+            service: arguments_.name ?? `okf-${local.settings.name}`,
+            onerror: (error) => note(error.message),
+        });
+        note(`serving ${served} at ${handle.url}`);
+    }
+    else {
+        serveStdio(factory, { onerror: (error) => note(error.message) });
+        note(`serving ${served} over stdio`);
+    }
+    return 0;
+}
+//# sourceMappingURL=serve.js.map

package/dist/mcp/serve.js.map

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

package/dist/mcp/server.d.ts

@@ -0,0 +1,42 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { type OkfV1Operations, type OkfV1ServerIdentity } from "okf-contracts";
+import { type ResolvedBundleTarget } from "okf-node";
+import { type BundleSettings } from "./bundle.js";
+/**
+ * The version this server reports to a client. It is a constant rather than a read of
+ * `package.json`, which does not sit under `rootDir`; `test/version.test.ts` keeps the two
+ * from drifting.
+ */
+export declare const SERVER_VERSION = "2.1.0";
+export interface OkfLocalServerOptions {
+    /** Absolute or relative project root. Relative paths resolve against `cwd`. */
+    readonly projectRoot: string;
+    readonly bundle: string;
+    /** Trusted module specifier, resolved against the bundle's project root. */
+    readonly profileModule?: string;
+    readonly today?: string;
+    /** Only used to resolve a relative `projectRoot`. Defaults to the process cwd. */
+    readonly cwd?: string;
+    readonly visualizationDirectory?: string;
+    /** The server name a client sees. Defaults to `okf-<bundle>`. */
+    readonly name?: string;
+    /** The deployment's own version. Defaults to {@link SERVER_VERSION}. */
+    readonly version?: string;
+    /** Title, description, website, icons, and the one-sentence purpose that opens the instructions. */
+    readonly identity?: OkfV1ServerIdentity;
+}
+export interface OkfLocalServer {
+    readonly target: ResolvedBundleTarget;
+    readonly settings: BundleSettings;
+    readonly operations: OkfV1Operations;
+    /** One MCP server instance. The stdio and HTTP entries call this per connection. */
+    createServer(): McpServer;
+}
+/**
+ * Resolve one manifest bundle off the filesystem and build the MCP surface over it.
+ *
+ * Every failure a deployment can fix — an unknown bundle name, an unreadable profile, an
+ * `access` value nothing defines — happens here, at startup, rather than on a tool call.
+ */
+export declare function createOkfLocalServer(options: OkfLocalServerOptions): Promise<OkfLocalServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAwB,KAAK,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACrG,OAAO,EAA8C,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAEjG,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlE;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,oFAAoF;IACpF,YAAY,IAAI,SAAS,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAmClG"}

package/dist/mcp/server.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { createOkfV1McpServer } from "okf-contracts";
+import { loadValidationProfile, resolveBundleTarget } from "okf-node";
+import { bundleSettings } from "./bundle.js";
+import { createFilesystemOkfV1Operations } from "./operations.js";
+/**
+ * The version this server reports to a client. It is a constant rather than a read of
+ * `package.json`, which does not sit under `rootDir`; `test/version.test.ts` keeps the two
+ * from drifting.
+ */
+export const SERVER_VERSION = "2.1.0";
+/**
+ * Resolve one manifest bundle off the filesystem and build the MCP surface over it.
+ *
+ * Every failure a deployment can fix — an unknown bundle name, an unreadable profile, an
+ * `access` value nothing defines — happens here, at startup, rather than on a tool call.
+ */
+export async function createOkfLocalServer(options) {
+    const projectRoot = path.resolve(options.cwd ?? process.cwd(), options.projectRoot);
+    const target = await resolveBundleTarget(projectRoot, options.bundle);
+    const settings = bundleSettings(target);
+    const analysis = {
+        ...(options.today === undefined ? {} : { today: options.today }),
+        // Resolved against the bundle's own project root, so `.agents/okf-private-profile.mjs`
+        // means the same thing here as it does in the repository's npm scripts.
+        ...(options.profileModule === undefined
+            ? {}
+            : { profile: await loadValidationProfile(target.projectRoot, options.profileModule) }),
+    };
+    const operations = createFilesystemOkfV1Operations({
+        target,
+        settings,
+        analysis,
+        ...(options.visualizationDirectory === undefined
+            ? {}
+            : { visualizationDirectory: options.visualizationDirectory }),
+    });
+    return {
+        target,
+        settings,
+        operations,
+        createServer: () => createOkfV1McpServer({
+            ...options.identity,
+            name: options.name ?? `okf-${settings.name}`,
+            version: options.version ?? SERVER_VERSION,
+            bundle: settings.name,
+            operations,
+        }),
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAI7B,OAAO,EAAE,oBAAoB,EAAkD,MAAM,eAAe,CAAC;AACrG,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAA6B,MAAM,UAAU,CAAC;AAEjG,OAAO,EAAE,cAAc,EAAuB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AAElE;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AA4BtC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAA8B;IACvE,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACpF,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IAExC,MAAM,QAAQ,GAAyB;QACrC,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAChE,uFAAuF;QACvF,wEAAwE;QACxE,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS;YACrC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;KACzF,CAAC;IAEF,MAAM,UAAU,GAAG,+BAA+B,CAAC;QACjD,MAAM;QACN,QAAQ;QACR,QAAQ;QACR,GAAG,CAAC,OAAO,CAAC,sBAAsB,KAAK,SAAS;YAC9C,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,sBAAsB,EAAE,OAAO,CAAC,sBAAsB,EAAE,CAAC;KAChE,CAAC,CAAC;IAEH,OAAO;QACL,MAAM;QACN,QAAQ;QACR,UAAU;QACV,YAAY,EAAE,GAAG,EAAE,CAAC,oBAAoB,CAAC;YACvC,GAAG,OAAO,CAAC,QAAQ;YACnB,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,OAAO,QAAQ,CAAC,IAAI,EAAE;YAC5C,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,cAAc;YAC1C,MAAM,EAAE,QAAQ,CAAC,IAAI;YACrB,UAAU;SACX,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/page/script.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"script.d.ts","sourceRoot":"","sources":["../../src/page/script.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,QA04BvB,CAAC"}
+{"version":3,"file":"script.d.ts","sourceRoot":"","sources":["../../src/page/script.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,QA27BvB,CAAC"}