@voltro/mcp 0.32.0 → 0.34.0

package/dist/http-BGeW8WkP.js

@@ -0,0 +1,104 @@
+import { D as e, E as t, a as n } from "./mcp-CZJe2Frv.js";
+import { randomUUID as r } from "node:crypto";
+//#region src/http.ts
+var i = "mcp-session-id", a = "application/json", o = "text/event-stream", s = (e) => e.some((e) => e.method === "initialize"), c = async (e) => {
+	let t = e.newSessionId ?? r;
+	if (e.method === "DELETE") return {
+		kind: "empty",
+		status: 204
+	};
+	if (e.method === "GET") return e.acceptsSse ? {
+		kind: "sse",
+		events: [],
+		keepOpen: !0
+	} : {
+		kind: "json",
+		status: 405,
+		body: u(null, "GET requires Accept: text/event-stream")
+	};
+	if (e.method !== "POST") return {
+		kind: "json",
+		status: 405,
+		body: u(null, `method ${e.method} not allowed`)
+	};
+	if (e.body === void 0 || e.body === null) return {
+		kind: "json",
+		status: 400,
+		body: l("empty POST body")
+	};
+	let a = Array.isArray(e.body) ? e.body : [e.body], o = s(a), c = e.headers[i];
+	if (!o && c === void 0) return {
+		kind: "json",
+		status: 400,
+		body: l("missing Mcp-Session-Id header")
+	};
+	let d = o ? c ?? t() : c, f = (await Promise.all(a.map((t) => n(e.snapshot, t, e.serverInfo, e.live)))).filter((e) => e !== null);
+	return f.length === 0 ? {
+		kind: "empty",
+		status: 202
+	} : e.acceptsSse ? {
+		kind: "sse",
+		events: f,
+		keepOpen: !1,
+		...d === void 0 ? {} : { sessionId: d }
+	} : {
+		kind: "json",
+		status: 200,
+		body: f.length === 1 ? f[0] : f,
+		...d === void 0 ? {} : { sessionId: d }
+	};
+}, l = (e) => ({
+	jsonrpc: "2.0",
+	id: null,
+	error: {
+		code: -32700,
+		message: e
+	}
+}), u = (e, t) => ({
+	jsonrpc: "2.0",
+	id: e,
+	error: {
+		code: -32601,
+		message: t
+	}
+}), d = (e) => `event: message\ndata: ${JSON.stringify(e)}\n\n`, f = (e) => e !== void 0 && e.split(",").some((e) => e.trim().startsWith(o)), p = async (e) => {
+	let t = "";
+	for await (let n of e) t += String(n);
+	if (t.trim() !== "") try {
+		return JSON.parse(t);
+	} catch {
+		return;
+	}
+}, m = (n) => async (r, s) => {
+	let l = r.method ?? "GET", u = l === "POST" ? await p(r) : void 0, m = await n.source.get(), h = {};
+	for (let [e, t] of Object.entries(r.headers)) h[e.toLowerCase()] = Array.isArray(t) ? t[0] : t;
+	let g = await c({
+		method: l,
+		headers: h,
+		body: u,
+		snapshot: m,
+		serverInfo: n.serverInfo,
+		acceptsSse: f(h.accept),
+		live: n.live ?? e(t(process.env)),
+		...n.newSessionId === void 0 ? {} : { newSessionId: n.newSessionId }
+	});
+	if (g.kind === "empty") {
+		s.writeHead(g.status), s.end();
+		return;
+	}
+	if (g.kind === "json") {
+		let e = { "content-type": a };
+		g.sessionId !== void 0 && (e[i] = g.sessionId), s.writeHead(g.status, e), s.end(JSON.stringify(g.body));
+		return;
+	}
+	let _ = {
+		"content-type": o,
+		"cache-control": "no-cache",
+		connection: "keep-alive"
+	};
+	g.sessionId !== void 0 && (_[i] = g.sessionId), s.writeHead(200, _);
+	for (let e of g.events) s.write(d(e));
+	g.keepOpen || s.end();
+};
+//#endregion
+export { c as n, d as r, m as t };

package/dist/httpServer.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { v as e } from "./mcp-DrI72Mwz.js";
-import { t } from "./http-CtkNxu9A.js";
-import { t as n } from "./serve-CRW_Na4H.js";
+import { j as e } from "./mcp-CZJe2Frv.js";
+import { t } from "./http-BGeW8WkP.js";
+import { t as n } from "./serve-ZSmqUcRM.js";
 import { createServer as r } from "node:http";
 //#endregion
 //#region src/httpServer.ts

package/dist/index.d.ts

@@ -1,6 +1,56 @@
 import { IncomingMessage } from 'node:http';
 import { ServerResponse } from 'node:http';
 
+/** The MCP tool-name prefix for an app procedure. Reserved: a static
+ *  `voltro_*` tool can never collide with it. */
+export declare const APP_TOOL_PREFIX = "app_";
+
+export declare interface AppToolInventory {
+    readonly enabled: boolean;
+    readonly reason?: string;
+    readonly tools: ReadonlyArray<AppToolListing>;
+    readonly dropped: ReadonlyArray<{
+        readonly name: string;
+        readonly reason: string;
+    }>;
+}
+
+/** One admitted app tool, as `GET /_voltro/inspect/agent/tools` reports it. */
+export declare interface AppToolListing {
+    readonly name: string;
+    readonly tag: string;
+    readonly kind: string;
+    readonly description: string;
+    readonly write: boolean;
+    readonly confirm: boolean;
+    readonly maxPerRun?: number;
+    readonly input?: Record<string, unknown>;
+}
+
+/**
+ * `todos.create` → `app_todos_create`.
+ *
+ * MCP tool names are `[A-Za-z0-9_-]`; an rpc tag is dotted. The mapping is NOT
+ * reversed by string surgery at call time — a tag containing a `-` and one
+ * containing a `.` can produce the same name — so the call path looks the
+ * original up in the SAME listing it rendered from. A collision drops the later
+ * tag (sorted first, so the drop is deterministic) rather than silently
+ * shadowing one procedure with another.
+ */
+export declare const appToolName: (tag: string) => string;
+
+export declare const boundText: (raw: unknown, maxChars: number) => string;
+
+/**
+ * `POST /_voltro/inspect/agent/call`. Returns the text the model sees.
+ *
+ * A refusal — missing credential, policy denial, the app's own guard — comes
+ * back as `Error: …` text rather than a thrown failure, exactly as an app tool's
+ * rejection does in `@voltro/ai`: a refusal IS information the model should act
+ * on, and hiding it behind a transport error makes the agent retry blindly.
+ */
+export declare const callAppTool: (options: LiveAppOptions, tag: string, input: unknown) => Promise<string>;
+
 /** Pure tool dispatch → the text payload for an MCP `tools/call` result. */
 export declare const callTool: (snapshot: ManifestSnapshot, name: string, args: Record<string, unknown>) => string;
 
@@ -30,6 +80,14 @@ export declare const createManifestSource: (options: ManifestSourceOptions) => M
 
 export declare const EMPTY_MANIFEST: CapabilityManifest;
 
+/** `GET /_voltro/inspect/agent/tools`. Never throws — a failure becomes an
+ *  `enabled: false` inventory carrying the reason, because a model handed an
+ *  empty tool list with no explanation concludes the app has no tools. */
+export declare const fetchAppTools: (options: LiveAppOptions) => Promise<AppToolInventory>;
+
+/** `GET /_voltro/inspect/checks` — the framework's invariant checks. */
+export declare const fetchInvariantChecks: (options: LiveAppOptions) => Promise<string>;
+
 /** Fetch the live capability manifest from a running api. */
 export declare const fetchManifest: (baseUrl: string, token?: string, 
 /** Abort the request after this long — a hung api must not hang the agent. */
@@ -49,6 +107,27 @@ export declare const getPrompt: (snapshot: ManifestSnapshot, name: string, args?
  */
 export declare const handleMcpRequest: (snapshot: ManifestSnapshot, request: JsonRpcRequest, serverInfo?: ServerInfo) => JsonRpcResponse | null;
 
+/**
+ * The same protocol, for the methods that need a ROUND TRIP to the app.
+ *
+ * Two of them do: `tools/list` has to fold in the app's executable agent tools
+ * (a set the app's policy decides, not us), and `tools/call` has to reach the
+ * app for those tools and for `voltro_check_invariants`. Everything else is
+ * unchanged and delegates to the pure `handleMcpRequest` above.
+ *
+ * A SEPARATE async entry point rather than a widened return type on the pure
+ * one — the same split `@voltro/cli` made between `handleInspectRequest` and
+ * `handleInspectAsyncRequest`, for the same reason: most of the surface does no
+ * I/O and should not become awaitable, and the pure core stays testable without
+ * a transport.
+ *
+ * `live === undefined` degrades to exactly the previous behaviour: manifest
+ * introspection only, no app tools, and `voltro_check_invariants` says why it
+ * cannot answer rather than throwing an "unknown tool" a reader would misread as
+ * a version mismatch.
+ */
+export declare const handleMcpRequestAsync: (snapshot: ManifestSnapshot, request: JsonRpcRequest, serverInfo?: ServerInfo, live?: LiveSurface) => Promise<JsonRpcResponse | null>;
+
 /** What `routeHttp` decided the transport should do. */
 export declare type HttpOutcome = 
 /** Reply once with a JSON body + status (single JSON-RPC response, or an error). */
@@ -71,6 +150,8 @@ export declare type HttpOutcome =
     readonly status: number;
 };
 
+export declare const isAppToolName: (name: string) => boolean;
+
 export declare interface JsonRpcRequest {
     readonly jsonrpc: '2.0';
     readonly id?: string | number | null;
@@ -97,6 +178,73 @@ export declare const listPrompts: () => ReadonlyArray<McpPrompt>;
  */
 export declare const listResources: (snapshot: ManifestSnapshot) => ReadonlyArray<McpResource>;
 
+export declare const LIVE_BOUNDS_DEFAULTS: LiveBounds;
+
+/** Where the app is and what we may present to it. */
+export declare interface LiveAppOptions {
+    readonly baseUrl: string;
+    readonly inspectToken?: string;
+    /** `VOLTRO_INSPECT_WRITE_TOKEN` — required for any non-GET inspect call. */
+    readonly inspectWriteToken?: string;
+    /** `VOLTRO_AGENT_TOKEN` — the APP credential a tool call executes as. */
+    readonly agentToken?: string;
+    readonly bounds: LiveBounds;
+    /** Injectable for tests; defaults to the global `fetch`. */
+    readonly fetchImpl?: typeof fetch;
+}
+
+export declare const liveAppOptionsFromEnv: (env: Readonly<Record<string, string | undefined>>, overrides?: Partial<LiveBounds>) => LiveAppOptions;
+
+/** Ceilings on what the app may send back into a model's context. Every one an
+ *  env-overridable number rather than a literal buried in the code. */
+export declare interface LiveBounds {
+    /** How many app tools may mount. Env `VOLTRO_MCP_MAX_APP_TOOLS`. */
+    readonly maxTools: number;
+    /** Ceiling on one tool description. Env `VOLTRO_MCP_MAX_DESCRIPTION_CHARS`. */
+    readonly maxDescriptionChars: number;
+    /** Ceiling on one tool-call result, in bytes. Env `VOLTRO_MCP_MAX_RESULT_BYTES`. */
+    readonly maxResultBytes: number;
+    /** Per-request deadline. Env `VOLTRO_MCP_TIMEOUT_MS`. */
+    readonly requestTimeoutMs: number;
+}
+
+/** The MCP tool shape, mirrored from `tools.ts` to avoid an import cycle. */
+export declare interface LiveMcpTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+}
+
+/** What `handleMcpRequestAsync` needs. One interface so a test supplies a fake
+ *  and never opens a socket — the same seam `McpTransport` is on the client. */
+export declare interface LiveSurface {
+    /** The app tools mountable right now, plus everything that did not mount. */
+    readonly appTools: () => Promise<{
+        readonly mounted: ReadonlyArray<MountedAppTool>;
+        readonly dropped: ReadonlyArray<{
+            readonly name: string;
+            readonly reason: string;
+        }>;
+    }>;
+    /** Execute one, by its rpc TAG (never by the MCP name the model produced). */
+    readonly callAppTool: (tag: string, input: unknown) => Promise<string>;
+    /** The framework's invariant checks, as JSON text. */
+    readonly invariantChecks: () => Promise<string>;
+}
+
+/**
+ * A `LiveSurface` over a running app, with the tool list TTL-cached.
+ *
+ * Cached for the same reason `createManifestSource` caches: during `voltro dev`
+ * the set changes as files are saved, so a process-lifetime snapshot goes stale
+ * within a minute — and re-fetching on every `tools/call` would put a round trip
+ * in front of every action. The CALL is never cached.
+ */
+export declare const makeLiveSurface: (options: LiveAppOptions, cache?: {
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+}) => LiveSurface;
+
 /** The stable URI for the whole-manifest resource. */
 export declare const MANIFEST_URI = "voltro://manifest";
 
@@ -123,6 +271,13 @@ export declare interface ManifestProcedure {
         readonly kind: 'policy';
         readonly action: string;
         readonly resourceType: string;
+    } | {
+        /** The erased `openAccess: '<why>'` decision. A procedure is guarded,
+         *  open-on-purpose, or undecided; without this variant the middle state
+         *  is indistinguishable from the last, and an agent reading the manifest
+         *  cannot tell a deliberately public tool from an unreviewed one. */
+        readonly kind: 'open';
+        readonly reason: string;
     }>;
     /** Present when the descriptor is projected to a public REST endpoint. */
     readonly publicApi?: Record<string, unknown>;
@@ -168,9 +323,21 @@ export declare interface ManifestTable {
         readonly nullable: boolean;
         readonly refersTo?: string;
         readonly enum?: ReadonlyArray<string>;
+        /** `.serverOnly()` — never crosses any wire, and refused as mutation input.
+         *  The only one of the three exposure axes that is a claim ABOUT the wire,
+         *  so the only one a tool may act on by omitting a field. */
+        readonly serverOnly?: boolean;
+        /** `.encrypted()` — ciphertext at rest. NOT a wire-exposure signal. */
+        readonly encrypted?: boolean;
+        /** `.sensitive(class)` — the declared class. The export-masking axis. */
+        readonly sensitive?: string;
     }>;
     readonly reactive: boolean;
     readonly framework: boolean;
+    /** The primary-key column a row-keyed action targets, when there is one. */
+    readonly pkColumn?: string;
+    /** False when no single primary key exists — no row can be addressed. */
+    readonly editable?: boolean;
 }
 
 /** A `prompts/get` result. */
@@ -231,6 +398,27 @@ export declare class MissingPromptArgumentError extends Error {
     constructor(promptName: string, argument: string);
 }
 
+/**
+ * Project the app's inventory onto MCP tools, bounded and deduplicated.
+ *
+ * The description carries the WRITE marker explicitly. A model choosing between
+ * `app_todos_list` and `app_todos_delete` has no other signal that one of them
+ * destroys data — the kind is in our type system, not in its context.
+ */
+export declare const mountAppTools: (inventory: AppToolInventory, bounds: LiveBounds) => {
+    readonly mounted: ReadonlyArray<MountedAppTool>;
+    readonly dropped: ReadonlyArray<{
+        name: string;
+        reason: string;
+    }>;
+};
+
+/** An app tool as a mountable MCP tool, plus the tag to call it by. */
+export declare interface MountedAppTool {
+    readonly tool: LiveMcpTool;
+    readonly tag: string;
+}
+
 /**
  * MCP version negotiation: echo the client's requested revision when we
  * support it, otherwise answer with our latest (the client then decides
@@ -249,6 +437,9 @@ export declare interface NodeHttpHandlerOptions {
     readonly source: ManifestSource;
     readonly serverInfo: ServerInfo;
     readonly newSessionId?: () => string;
+    /** Defaults to a surface built from `process.env` — the same variables the
+     *  stdio bin reads, so the two transports expose the same tools. */
+    readonly live?: LiveSurface;
 }
 
 export declare const PROMPTS: ReadonlyArray<McpPrompt>;
@@ -263,13 +454,21 @@ export declare const PROTOCOL_VERSION = "2025-06-18";
  */
 export declare const readResource: (snapshot: ManifestSnapshot, uri: string) => ReadonlyArray<McpResourceContents>;
 
+export declare const resolveLiveBounds: (env: Readonly<Record<string, string | undefined>>, overrides?: Partial<LiveBounds>) => LiveBounds;
+
 /**
- * The pure protocol core of the Streamable HTTP transport. Given the HTTP
- * method, headers and parsed body, decide the response shape. Reuses the same
- * pure `handleMcpRequest` the stdio transport uses — the two transports share
- * one protocol implementation.
+ * The protocol core of the Streamable HTTP transport. Given the HTTP method,
+ * headers and parsed body, decide the response shape. Reuses the SAME
+ * `handleMcpRequestAsync` the stdio transport uses — the two transports share one
+ * protocol implementation, and that is the property that stopped an executable
+ * tool surface from existing on one of them only.
+ *
+ * Async because two methods now reach the app (`tools/list` folds in its agent
+ * tools, `tools/call` executes one). Everything else still resolves without
+ * touching the network. The DECISION is still pure in the sense that matters —
+ * no socket is bound here, and a test supplies a `live` double.
  */
-export declare const routeHttp: (options: RouteHttpOptions) => HttpOutcome;
+export declare const routeHttp: (options: RouteHttpOptions) => Promise<HttpOutcome>;
 
 export declare interface RouteHttpOptions {
     readonly method: string;
@@ -283,6 +482,9 @@ export declare interface RouteHttpOptions {
     readonly acceptsSse: boolean;
     /** Mint a session id (override for deterministic tests). */
     readonly newSessionId?: () => string;
+    /** The live app surface — executable agent tools + invariant checks. Absent ⇒
+     *  manifest introspection only, which is what this transport did before. */
+    readonly live?: LiveSurface;
 }
 
 /** Fallback identity. The bin overrides `version` with the value from its own

package/dist/index.js

@@ -1,3 +1,3 @@
-import { _ as e, a as t, c as n, d as r, f as i, g as a, h as o, i as s, l as c, m as l, n as u, o as d, p as f, r as p, s as m, t as h, u as g, v as _, y as v } from "./mcp-DrI72Mwz.js";
-import { n as y, r as b, t as x } from "./http-CtkNxu9A.js";
-export { e as EMPTY_MANIFEST, r as MANIFEST_URI, d as MissingPromptArgumentError, m as PROMPTS, h as PROTOCOL_VERSION, u as SERVER_INFO, p as SUPPORTED_PROTOCOL_VERSIONS, o as TOOLS, n as UnknownPromptError, i as UnknownResourceError, a as callTool, _ as createManifestSource, v as fetchManifest, c as getPrompt, s as handleMcpRequest, g as listPrompts, f as listResources, t as negotiateProtocolVersion, x as nodeHttpHandler, l as readResource, y as routeHttp, b as sseEvent };
+import { A as e, C as t, D as n, E as r, M as i, O as a, S as o, T as s, _ as c, a as l, b as u, c as d, d as f, f as p, g as m, h, i as g, j as _, k as v, l as y, m as b, n as x, o as S, p as C, r as w, s as T, t as E, u as D, v as O, w as k, x as A, y as j } from "./mcp-CZJe2Frv.js";
+import { n as M, r as N, t as P } from "./http-BGeW8WkP.js";
+export { O as APP_TOOL_PREFIX, e as EMPTY_MANIFEST, j as LIVE_BOUNDS_DEFAULTS, p as MANIFEST_URI, T as MissingPromptArgumentError, d as PROMPTS, E as PROTOCOL_VERSION, x as SERVER_INFO, w as SUPPORTED_PROTOCOL_VERSIONS, m as TOOLS, y as UnknownPromptError, C as UnknownResourceError, u as appToolName, A as boundText, o as callAppTool, c as callTool, _ as createManifestSource, t as fetchAppTools, k as fetchInvariantChecks, i as fetchManifest, D as getPrompt, g as handleMcpRequest, l as handleMcpRequestAsync, s as isAppToolName, f as listPrompts, b as listResources, r as liveAppOptionsFromEnv, n as makeLiveSurface, a as mountAppTools, S as negotiateProtocolVersion, P as nodeHttpHandler, h as readResource, v as resolveLiveBounds, M as routeHttp, N as sseEvent };