@voltro/mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to the `@voltro/*` packages are recorded here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## Stability contract — read this before you pin a version
+
+Voltro is **`0.x` — pre-1.0, and deliberately so.** Under SemVer, `0.y.z` means
+"anything MAY change." We hold to exactly that, stated out loud:
+
+- **Pin exact versions.** Depend on `@voltro/runtime@0.4.2`, never `^0.4.2` or
+  `~0.4.2`. There is no compatible-range promise below 1.0.
+- **Every MINOR may break.** Breaking changes land on a minor bump (`0.4.x →
+  0.5.0`); patches (`0.4.1 → 0.4.2`) are additive or fixes only. This is the
+  standard `0.x` reading of SemVer — the minor slot carries breaking under `0.x`.
+- **Read this changelog before upgrading.** The `⚠ BREAKING` section of each
+  release lists every incompatible change with its migration. It is the only
+  migration path we provide — there is no deprecation cycle, no compat shim.
+- **All packages release together (lockstep).** One coordinated version across
+  the whole framework; the git tag is the source of truth.
+
+This is not a placeholder disclaimer — it is the contract. The framework is
+refactored aggressively while it has no external stability obligations, and that
+velocity is the point. A stable-core tier and per-package `1.0` graduation are
+planned, but not yet; until then, treat the whole surface as movable and pin
+exact.
+
+The **public API** of each package is its `publishConfig.exports` entry points,
+minus anything marked `@internal` (those are cross-package internals and are
+stripped from the published `.d.ts`). Importing a deep path that isn't an
+exported entry point is unsupported.
+
+---
+
+## [Unreleased]
+
+_Changes staged for the next release accumulate here (rolled up from
+`.changes/*.md` at tag time — see `.changes/README.md`)._
+
+---
+
+## [0.1.0]
+
+Initial pre-release baseline. This is the starting point the changelog tracks
+from; it is not an exhaustive history of prior development. The framework ships
+as `@voltro/*` packages spanning the runtime, database/query layer, web client
+and router, durable workflows, the CLI, and the plugin ecosystem
+(auth, storage, mail, billing, observability, and more). Not published to a
+public registry yet.
+
+Subsequent releases record their deltas from here under dated headings, with
+`⚠ BREAKING` first.

package/LICENSE

@@ -0,0 +1,57 @@
+Voltro — Proprietary Software License
+
+Copyright (c) 2026 Voltro UG. All rights reserved.
+
+This software and all associated source code, documentation, and other
+materials (the "Software") are the proprietary property of Voltro UG
+("Voltro"). This is NOT open-source software.
+
+Your access to and use of the Software is governed exclusively by the Voltro
+Terms of Service at:
+
+    https://voltro.cloud/legal/terms
+
+By downloading, installing, or using the Software you agree to those Terms.
+Subject to and conditioned on your continued compliance with them, Voltro
+grants you a limited, non-exclusive, non-transferable, non-sublicensable,
+revocable license to use the Software. All rights not expressly granted in the
+Terms are reserved by Voltro. If you do not agree to the Terms, you have no
+license and may not use the Software.
+
+The Terms of Service — including the scope of permitted use, plan
+entitlements, fees, and pricing — may change from time to time. The version in
+force is the one published at the URL above. Commercial terms and pricing are
+NOT part of this notice and are not fixed by, or granted in perpetuity by, the
+version of the Software in which this file appears.
+
+Permitted use — your own software. Voltro is a development framework. You may
+use the Software to build, run, and commercially distribute your own
+applications and services, and to charge your own customers for them, without
+owing Voltro any share of that revenue or any further permission beyond the
+Terms. Applications you build with the Software are yours.
+
+Prohibited use — reselling Voltro. You may NOT redistribute, resell,
+sublicense, publish, or otherwise provide the Software itself — in whole or in
+part, in source or compiled form — to third parties as a library, framework,
+SDK, template, starter, or development tool for them to build upon, whether
+standalone or repackaged. Shipping the Software as a non-separable, bundled
+dependency inside an application you deliver (for example, compiled into your
+deployed app) is permitted; extracting or re-exposing it as a reusable
+component for others is not.
+
+Except as expressly permitted above or by the Terms, you may not copy, modify,
+merge, publish, sublicense, sell, distribute, or create derivative works of the
+Software, in whole or in part.
+
+Third-party open-source components distributed alongside the Software are the
+property of their respective owners and are licensed under their own terms; see
+THIRD-PARTY-NOTICES.md where provided. Nothing in this notice limits your
+rights, or extends Voltro's, in those components.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+VOLTRO BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM,
+OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+For licensing inquiries, contact Voltro UG.

package/README.md

@@ -0,0 +1,26 @@
+<div align="center">
+
+# @voltro/mcp
+
+**MCP server for coding agents over a running Voltro api — exposes the app's procedures, tables, workflows and their JSON Schemas as MCP tools, resources and prompts, over stdio (voltro-mcp) or Streamable HTTP (voltro-mcp-http). Zero dependencies.**
+
+[📖 Documentation](https://docs.voltro.dev/docs/cli/mcp) · [Changelog](./CHANGELOG.md) · [voltro.dev](https://voltro.dev) · [Voltro Cloud](https://voltro.cloud)
+
+</div>
+
+---
+
+```sh
+npm install @voltro/mcp
+```
+
+> ### [→ Read the documentation for @voltro/mcp](https://docs.voltro.dev/docs/cli/mcp)
+
+Installation, guides, the full API reference, and examples all live in the
+**[Voltro documentation](https://docs.voltro.dev/docs/intro/getting-started)** — the single source of truth. This README is
+deliberately short so there is nothing here to drift out of date.
+
+## License
+
+Proprietary. © 2026 Voltro UG. Your use is governed by the
+[Terms of Service](https://voltro.cloud/legal/terms). See the bundled `LICENSE`.

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+We take the security of Voltro and the applications built on it seriously. This
+document explains how to report a vulnerability and what to expect in return.
+
+## Reporting a vulnerability
+
+**Please do not open public issues or discuss suspected vulnerabilities in
+public channels.** Report them privately by email:
+
+**security contact: [support@voltro.dev](mailto:support@voltro.dev)**
+(subject line: `SECURITY`).
+
+Include, where you can:
+
+- the affected package(s) and version(s) (e.g. `@voltro/runtime@x.y.z`);
+- a description of the issue and its impact;
+- a minimal reproduction or proof of concept;
+- any suggested remediation.
+
+If you'd like to encrypt your report, ask in a first plain email and we'll
+arrange a key.
+
+## What to expect
+
+- **Acknowledgement** of your report within **3 business days**.
+- An initial assessment (severity, affected surface) and a remediation plan as
+  soon as we've reproduced the issue.
+- **Coordinated disclosure:** we'll agree a disclosure timeline with you and
+  credit you in the release notes if you wish. Please give us reasonable time to
+  ship a fix before any public disclosure.
+
+We do not currently run a paid bug-bounty program, but we genuinely appreciate
+responsible disclosure and will credit reporters.
+
+## Software Bill of Materials (SBOM)
+
+A CycloneDX SBOM of the third-party runtime dependency graph is generated for the
+published packages (`pnpm gen:sbom` → `sbom.cdx.json`). If your procurement or
+security team needs it, request it at
+[support@voltro.dev](mailto:support@voltro.dev).
+
+## Supported versions
+
+Voltro is pre-1.0 and ships in lockstep: **only the latest published minor of
+each `@voltro/*` package receives security fixes.** Please upgrade to the latest
+release before reporting, and pin exact versions in production.
+
+## Scope
+
+In scope: the published `@voltro/*` packages and the framework's own code.
+
+Out of scope: vulnerabilities in third-party dependencies that are already
+tracked upstream (we monitor these via a production-dependency audit gate in
+CI), and issues that require a non-default, explicitly-unsafe configuration. If
+you're unsure, report it anyway — we'd rather hear about it.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,11 @@
+# Third-Party Notices — @voltro/mcp
+
+This package depends on the open-source software listed below. Each is the
+property of its respective copyright holders and is used under the terms of
+its license. This file is provided for attribution; it grants no rights in
+@voltro/mcp itself, which is proprietary (see LICENSE).
+
+Generated from the resolved runtime dependency closure (0 packages).
+
+---
+

package/dist/http-DFJ4CBnH.js

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

package/dist/httpServer.d.ts

@@ -0,0 +1 @@
+export { }

package/dist/httpServer.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { v as e } from "./mcp-Br4DcrKz.js";
+import { t } from "./http-DFJ4CBnH.js";
+import { t as n } from "./serve-7hA87wAd.js";
+import { createServer as r } from "node:http";
+//#endregion
+//#region src/httpServer.ts
+(async (i) => {
+	let a = i.env.VOLTRO_INSPECT_URL ?? "http://localhost:4000", o = i.env.VOLTRO_INSPECT_TOKEN, s = i.env.VOLTRO_MCP_HTTP_PATH ?? "/mcp", c = Number(i.env.VOLTRO_MCP_HTTP_PORT ?? "4100"), l = t({
+		source: e({
+			baseUrl: a,
+			...o === void 0 ? {} : { token: o },
+			...i.manifestTtlMs === void 0 ? {} : { ttlMs: i.manifestTtlMs }
+		}),
+		serverInfo: n(),
+		...i.newSessionId === void 0 ? {} : { newSessionId: i.newSessionId }
+	}), u = r((e, t) => {
+		let n = (e.url ?? "/").split("?")[0];
+		if (n !== s) {
+			t.writeHead(404, { "content-type": "application/json" }), t.end(JSON.stringify({ error: `not found: ${n}` }));
+			return;
+		}
+		l(e, t);
+	});
+	await new Promise((e) => u.listen(c, e));
+	let d = u.address();
+	return {
+		server: u,
+		port: typeof d == "object" && d ? d.port : c,
+		path: s,
+		close: () => new Promise((e, t) => u.close((n) => n ? t(n) : e()))
+	};
+})({ env: process.env });
+//#endregion

package/dist/index.d.ts

@@ -0,0 +1,308 @@
+import { IncomingMessage } from 'node:http';
+import { ServerResponse } from 'node:http';
+
+/** 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;
+
+export declare interface CapabilityManifest {
+    readonly version: number;
+    readonly procedures: ReadonlyArray<ManifestProcedure>;
+    readonly workflows: ReadonlyArray<{
+        readonly name: string;
+    }>;
+    /** The schema-driven-UI widget kinds — present from manifest v2. */
+    readonly widgets?: ReadonlyArray<string>;
+    /** USER tables (manifest v2) — graph nodes for tooling/agents. */
+    readonly tables?: ReadonlyArray<ManifestTable>;
+}
+
+/**
+ * A TTL-cached manifest source. The manifest is NOT a boot-time constant —
+ * during `voltro dev` procedures appear and disappear as files are saved —
+ * so every `tools/*` request reads through this source and picks up changes
+ * within `ttlMs`, instead of serving one stale process-lifetime snapshot.
+ */
+export declare const createManifestSource: (options: ManifestSourceOptions) => ManifestSource;
+
+export declare const EMPTY_MANIFEST: CapabilityManifest;
+
+/** 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. */
+timeoutMs?: number) => Promise<CapabilityManifest>;
+
+/**
+ * Render a prompt against the live manifest. Throws `UnknownPromptError` for
+ * an unknown name and `MissingPromptArgumentError` for a missing required
+ * argument (the transport maps both to JSON-RPC errors).
+ */
+export declare const getPrompt: (snapshot: ManifestSnapshot, name: string, args?: Record<string, unknown>) => McpGetPromptResult;
+
+/**
+ * Handle one JSON-RPC request against the manifest snapshot. Returns the
+ * response, or `null` for a notification (a request with no `id`, e.g.
+ * `notifications/initialized`) which must NOT be answered.
+ */
+export declare const handleMcpRequest: (snapshot: ManifestSnapshot, request: JsonRpcRequest, serverInfo?: ServerInfo) => 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). */
+    {
+    readonly kind: 'json';
+    readonly status: number;
+    readonly body: unknown;
+    readonly sessionId?: string;
+}
+/** Open an SSE stream and emit these JSON-RPC responses as `message` events, then (optionally) close. */
+| {
+    readonly kind: 'sse';
+    readonly events: ReadonlyArray<JsonRpcResponse>;
+    readonly sessionId?: string;
+    readonly keepOpen: boolean;
+}
+/** No body (202 Accepted for notification-only POSTs; 204 for a DELETE). */
+| {
+    readonly kind: 'empty';
+    readonly status: number;
+};
+
+export declare interface JsonRpcRequest {
+    readonly jsonrpc: '2.0';
+    readonly id?: string | number | null;
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+
+export declare interface JsonRpcResponse {
+    readonly jsonrpc: '2.0';
+    readonly id: string | number | null;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: number;
+        readonly message: string;
+    };
+}
+
+export declare const listPrompts: () => ReadonlyArray<McpPrompt>;
+
+/**
+ * Every readable resource in the app: the whole manifest, one per rpc
+ * procedure, one per user table. Enumerated fresh from the snapshot so a
+ * procedure/table added mid-session appears on the next `resources/list`.
+ */
+export declare const listResources: (snapshot: ManifestSnapshot) => ReadonlyArray<McpResource>;
+
+/** The stable URI for the whole-manifest resource. */
+export declare const MANIFEST_URI = "voltro://manifest";
+
+export declare interface ManifestProcedure {
+    readonly tag: string;
+    readonly kind: string;
+    readonly input?: Record<string, unknown>;
+    readonly output?: Record<string, unknown>;
+    readonly source?: string | ReadonlyArray<string>;
+    readonly targets?: ReadonlyArray<{
+        readonly table: string;
+        readonly op: string;
+    }>;
+    /** Present when the descriptor is projected to a public REST endpoint. */
+    readonly publicApi?: Record<string, unknown>;
+    /** Present when the descriptor is exposed as an agent tool. */
+    readonly exposeAsTool?: Record<string, unknown>;
+}
+
+/**
+ * The manifest as the tools see it: the (possibly last-good) manifest data
+ * plus the reason the LAST fetch failed, when it did. Carrying the failure
+ * into the tool layer lets an agent see "api unreachable: …" instead of a
+ * bare `(no procedures)`.
+ */
+export declare interface ManifestSnapshot {
+    readonly manifest: CapabilityManifest;
+    /** Present when the last fetch failed — e.g. `manifest fetch failed: HTTP 401`. */
+    readonly error?: string;
+}
+
+export declare interface ManifestSource {
+    /** The current snapshot — re-fetched when older than `ttlMs`. Never
+     *  rejects: a failed fetch degrades to the last-good manifest (or the
+     *  empty one) with `error` set. */
+    readonly get: () => Promise<ManifestSnapshot>;
+}
+
+export declare interface ManifestSourceOptions {
+    readonly baseUrl: string;
+    readonly token?: string;
+    /** Re-fetch when the cached snapshot is older than this. Default 10s —
+     *  fresh enough that a procedure added mid-session shows up on the next
+     *  tool call, cheap enough for a local dev api. */
+    readonly ttlMs?: number;
+    /** Clock override for tests. */
+    readonly now?: () => number;
+}
+
+export declare interface ManifestTable {
+    readonly name: string;
+    readonly columns: ReadonlyArray<{
+        readonly name: string;
+        readonly type: string;
+        readonly nullable: boolean;
+        readonly refersTo?: string;
+        readonly enum?: ReadonlyArray<string>;
+    }>;
+    readonly reactive: boolean;
+    readonly framework: boolean;
+}
+
+/** A `prompts/get` result. */
+export declare interface McpGetPromptResult {
+    readonly description: string;
+    readonly messages: ReadonlyArray<McpPromptMessage>;
+}
+
+/** An entry in a `prompts/list` result. */
+export declare interface McpPrompt {
+    readonly name: string;
+    readonly description: string;
+    readonly arguments: ReadonlyArray<McpPromptArgument>;
+}
+
+/** A declared argument of a prompt template. */
+export declare interface McpPromptArgument {
+    readonly name: string;
+    readonly description: string;
+    readonly required: boolean;
+}
+
+/** One rendered message in a `prompts/get` result. */
+export declare interface McpPromptMessage {
+    readonly role: 'user' | 'assistant';
+    readonly content: {
+        readonly type: 'text';
+        readonly text: string;
+    };
+}
+
+/** An entry in a `resources/list` result. */
+export declare interface McpResource {
+    readonly uri: string;
+    readonly name: string;
+    readonly description: string;
+    readonly mimeType: string;
+}
+
+/** One item in a `resources/read` result's `contents` array (text form). */
+export declare interface McpResourceContents {
+    readonly uri: string;
+    readonly mimeType: string;
+    readonly text: string;
+}
+
+export declare interface McpTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+}
+
+/** Raised when a required prompt argument is missing. */
+export declare class MissingPromptArgumentError extends Error {
+    readonly promptName: string;
+    readonly argument: string;
+    readonly _tag = "MissingPromptArgumentError";
+    constructor(promptName: string, argument: string);
+}
+
+/**
+ * MCP version negotiation: echo the client's requested revision when we
+ * support it, otherwise answer with our latest (the client then decides
+ * whether it can talk to us) — exactly the spec's `initialize` contract.
+ */
+export declare const negotiateProtocolVersion: (requested: unknown) => string;
+
+/**
+ * A `node:http` request handler serving MCP over Streamable HTTP. Refreshes
+ * the manifest per request (same freshness contract as the stdio transport)
+ * and writes the outcome as JSON, SSE, or an empty status.
+ */
+export declare const nodeHttpHandler: (options: NodeHttpHandlerOptions) => (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+
+export declare interface NodeHttpHandlerOptions {
+    readonly source: ManifestSource;
+    readonly serverInfo: ServerInfo;
+    readonly newSessionId?: () => string;
+}
+
+export declare const PROMPTS: ReadonlyArray<McpPrompt>;
+
+/** The latest MCP protocol revision this server speaks. */
+export declare const PROTOCOL_VERSION = "2025-06-18";
+
+/**
+ * Read one resource by URI → its `contents`. Throws `UnknownResourceError`
+ * for an unmatched URI (the transport maps it to a JSON-RPC error), so the
+ * `voltro://…` scheme is the single source of truth for what is readable.
+ */
+export declare const readResource: (snapshot: ManifestSnapshot, uri: string) => ReadonlyArray<McpResourceContents>;
+
+/**
+ * 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.
+ */
+export declare const routeHttp: (options: RouteHttpOptions) => HttpOutcome;
+
+export declare interface RouteHttpOptions {
+    readonly method: string;
+    readonly headers: Readonly<Record<string, string | undefined>>;
+    /** The parsed JSON body for a POST (a single request or a batch array); `undefined` for GET/DELETE. */
+    readonly body: unknown;
+    /** The manifest snapshot to answer against (already refreshed by the caller). */
+    readonly snapshot: Parameters<typeof handleMcpRequest>[0];
+    readonly serverInfo: ServerInfo;
+    /** Whether the client's `Accept` allows an SSE response. */
+    readonly acceptsSse: boolean;
+    /** Mint a session id (override for deterministic tests). */
+    readonly newSessionId?: () => string;
+}
+
+/** Fallback identity. The bin overrides `version` with the value from its own
+ *  `package.json` at runtime (see `serve.ts`), so the published artifact
+ *  reports the lockstep-stamped release version, not this dev placeholder. */
+export declare const SERVER_INFO: ServerInfo;
+
+export declare interface ServerInfo {
+    readonly name: string;
+    readonly version: string;
+}
+
+/** Format one SSE `message` event carrying a JSON-RPC response. */
+export declare const sseEvent: (response: JsonRpcResponse) => string;
+
+/**
+ * Every revision this server can serve, newest first. The surface here is
+ * tools-only over stdio, which is identical across these revisions (the
+ * differences — streamable-http transport, batching, audio content,
+ * elicitation — don't touch a tools-only stdio server), so claiming all
+ * three is honest.
+ */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: ReadonlyArray<string>;
+
+export declare const TOOLS: ReadonlyArray<McpTool>;
+
+/** Raised when `prompts/get` names no known prompt. */
+export declare class UnknownPromptError extends Error {
+    readonly promptName: string;
+    readonly _tag = "UnknownPromptError";
+    constructor(promptName: string);
+}
+
+/** Raised by `readResource` when the URI names no known resource. */
+export declare class UnknownResourceError extends Error {
+    readonly uri: string;
+    readonly _tag = "UnknownResourceError";
+    constructor(uri: string);
+}
+
+export { }

package/dist/index.js

@@ -0,0 +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-Br4DcrKz.js";
+import { n as y, r as b, t as x } from "./http-DFJ4CBnH.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 };

package/dist/mcp-Br4DcrKz.js

@@ -0,0 +1,337 @@
+//#region src/manifest.ts
+var e = {
+	version: 2,
+	procedures: [],
+	workflows: [],
+	widgets: [],
+	tables: []
+}, t = async (e, t, n = 5e3) => {
+	let r = new URL("/_voltro/inspect/manifest", e), i = await fetch(r, {
+		headers: t === void 0 ? {} : { authorization: `Bearer ${t}` },
+		signal: AbortSignal.timeout(n)
+	});
+	if (!i.ok) throw Error(`manifest fetch failed: HTTP ${i.status}`);
+	return await i.json();
+}, n = (n) => {
+	let r = n.ttlMs ?? 1e4, i = n.now ?? Date.now, a, o = -Infinity;
+	return { get: async () => {
+		if (a !== void 0 && i() - o < r) return a;
+		try {
+			a = { manifest: await t(n.baseUrl, n.token) };
+		} catch (t) {
+			a = {
+				manifest: a?.manifest ?? e,
+				error: String(t)
+			};
+		}
+		return o = i(), a;
+	} };
+}, r = {
+	type: "object",
+	properties: {},
+	additionalProperties: !1
+}, i = [
+	{
+		name: "voltro_list_procedures",
+		description: "List every rpc procedure (queries, mutations, actions, streams) in the app with its kind. Markers: [public-rest] = also served as a public REST endpoint, [agent-tool] = exposed as an in-app agent tool. Use this to discover what the backend exposes before writing UI or agent code.",
+		inputSchema: r
+	},
+	{
+		name: "voltro_get_procedure",
+		description: "Get one procedure's full metadata by its tag (e.g. 'todos.create'): kind, input/output JSON Schema, source file(s), the tables it reads/writes (targets), and its public-REST / agent-tool projection when present. Use the input schema to drive a form / a tool call; the output schema to type the result.",
+		inputSchema: {
+			type: "object",
+			properties: { tag: {
+				type: "string",
+				description: "The rpc tag, e.g. \"todos.create\"."
+			} },
+			required: ["tag"],
+			additionalProperties: !1
+		}
+	},
+	{
+		name: "voltro_search_procedures",
+		description: "Find procedures whose tag contains the query substring (case-insensitive).",
+		inputSchema: {
+			type: "object",
+			properties: { query: { type: "string" } },
+			required: ["query"],
+			additionalProperties: !1
+		}
+	},
+	{
+		name: "voltro_list_tables",
+		description: "List the app's USER tables (framework-internal tables excluded) with column count and reactivity. Use voltro_get_table for the full column list of one table.",
+		inputSchema: r
+	},
+	{
+		name: "voltro_get_table",
+		description: "Get one table's full column list (name, type, nullability, foreign-key target, enum values) by table name.",
+		inputSchema: {
+			type: "object",
+			properties: { name: {
+				type: "string",
+				description: "The table name, e.g. \"todos\"."
+			} },
+			required: ["name"],
+			additionalProperties: !1
+		}
+	},
+	{
+		name: "voltro_list_workflows",
+		description: "List the durable workflows registered in the app.",
+		inputSchema: r
+	},
+	{
+		name: "voltro_list_widgets",
+		description: "List the schema-driven-UI widget kinds the app supports — the enumerable set a generated UI binds to.",
+		inputSchema: r
+	}
+], a = (e) => {
+	let t = [...e.publicApi === void 0 ? [] : [" [public-rest]"], ...e.exposeAsTool === void 0 ? [] : [" [agent-tool]"]].join("");
+	return `${e.tag} (${e.kind})${t}`;
+}, o = (e) => `${e.name} (${e.columns.length} column${e.columns.length === 1 ? "" : "s"}${e.reactive ? ", reactive" : ""})`, s = (e, t) => t.error === void 0 ? `(no ${e})` : `(no ${e} — manifest unavailable: ${t.error}. Is the api running at VOLTRO_INSPECT_URL, and is VOLTRO_INSPECT_TOKEN set if the inspect surface is gated?)`, c = (e, t, n) => {
+	let r = e.manifest;
+	switch (t) {
+		case "voltro_list_procedures": return r.procedures.length === 0 ? s("procedures", e) : r.procedures.map(a).join("\n");
+		case "voltro_get_procedure": {
+			let e = String(n.tag ?? ""), t = r.procedures.find((t) => t.tag === e);
+			return t === void 0 ? `No procedure with tag "${e}". Call voltro_list_procedures to see available tags.` : JSON.stringify({
+				tag: t.tag,
+				kind: t.kind,
+				input: t.input,
+				output: t.output,
+				...t.source === void 0 ? {} : { source: t.source },
+				...t.targets === void 0 ? {} : { targets: t.targets },
+				...t.publicApi === void 0 ? {} : { publicApi: t.publicApi },
+				...t.exposeAsTool === void 0 ? {} : { exposeAsTool: t.exposeAsTool }
+			}, null, 2);
+		}
+		case "voltro_search_procedures": {
+			let e = String(n.query ?? "").toLowerCase(), t = r.procedures.filter((t) => t.tag.toLowerCase().includes(e));
+			return t.length === 0 ? `(no procedures matching "${e}")` : t.map(a).join("\n");
+		}
+		case "voltro_list_tables": {
+			let t = r.tables ?? [];
+			return t.length === 0 ? s("tables", e) : t.map(o).join("\n");
+		}
+		case "voltro_get_table": {
+			let e = String(n.name ?? ""), t = (r.tables ?? []).find((t) => t.name === e);
+			return t === void 0 ? `No table named "${e}". Call voltro_list_tables to see available tables.` : JSON.stringify(t, null, 2);
+		}
+		case "voltro_list_workflows": return r.workflows.length === 0 ? s("workflows", e) : r.workflows.map((e) => e.name).join("\n");
+		case "voltro_list_widgets": {
+			let t = r.widgets ?? [];
+			return t.length === 0 ? s("widgets", e) : t.join("\n");
+		}
+		default: throw Error(`unknown tool: ${t}`);
+	}
+}, l = "application/json", u = "voltro://manifest", d = (e) => `voltro://procedure/${e}`, f = (e) => `voltro://table/${e}`, p = (e) => {
+	let t = e.manifest;
+	return [
+		{
+			uri: u,
+			name: "Capability manifest",
+			description: "The full app capability manifest: every procedure, table, workflow and widget kind as JSON.",
+			mimeType: l
+		},
+		...t.procedures.map((e) => ({
+			uri: d(e.tag),
+			name: e.tag,
+			description: `The ${e.kind} "${e.tag}" — its input/output JSON Schema, source, and table targets.`,
+			mimeType: l
+		})),
+		...(t.tables ?? []).map((e) => ({
+			uri: f(e.name),
+			name: e.name,
+			description: `The "${e.name}" table — its full column list (types, nullability, foreign keys, enums).`,
+			mimeType: l
+		}))
+	];
+}, m = class extends Error {
+	uri;
+	_tag = "UnknownResourceError";
+	constructor(e) {
+		super(`no resource at "${e}"`), this.uri = e, this.name = "UnknownResourceError";
+	}
+}, h = (e, t) => {
+	let n = e.manifest, r = (e) => [{
+		uri: t,
+		mimeType: l,
+		text: JSON.stringify(e, null, 2)
+	}];
+	if (t === "voltro://manifest") return r(n);
+	let i = t.startsWith("voltro://procedure/") ? t.slice(19) : void 0;
+	if (i !== void 0) {
+		let e = n.procedures.find((e) => e.tag === i);
+		if (e === void 0) throw new m(t);
+		return r(e);
+	}
+	let a = t.startsWith("voltro://table/") ? t.slice(15) : void 0;
+	if (a !== void 0) {
+		let e = (n.tables ?? []).find((e) => e.name === a);
+		if (e === void 0) throw new m(t);
+		return r(e);
+	}
+	throw new m(t);
+}, g = [
+	{
+		name: "scaffold_procedure",
+		description: "Draft a new Voltro rpc procedure (query/mutation/action) following the app's existing conventions, grounded in the current manifest so it references real tables and matches the shape of siblings.",
+		arguments: [{
+			name: "kind",
+			description: "query | mutation | action",
+			required: !0
+		}, {
+			name: "purpose",
+			description: "What the procedure should do, in one sentence.",
+			required: !0
+		}]
+	},
+	{
+		name: "explain_table",
+		description: "Explain one table's schema and how the app's procedures read/write it, from the live manifest.",
+		arguments: [{
+			name: "table",
+			description: "The table name, e.g. \"todos\".",
+			required: !0
+		}]
+	},
+	{
+		name: "wire_ui_for_procedure",
+		description: "Generate the client code to call one procedure and render its result, using the procedure's real input/output JSON Schema from the manifest.",
+		arguments: [{
+			name: "tag",
+			description: "The rpc tag, e.g. \"todos.list\".",
+			required: !0
+		}]
+	}
+], _ = class extends Error {
+	promptName;
+	_tag = "UnknownPromptError";
+	constructor(e) {
+		super(`no prompt named "${e}"`), this.promptName = e, this.name = "UnknownPromptError";
+	}
+}, v = class extends Error {
+	promptName;
+	argument;
+	_tag = "MissingPromptArgumentError";
+	constructor(e, t) {
+		super(`prompt "${e}" requires the "${t}" argument`), this.promptName = e, this.argument = t, this.name = "MissingPromptArgumentError";
+	}
+}, y = () => g, b = (e) => ({
+	role: "user",
+	content: {
+		type: "text",
+		text: e
+	}
+}), x = (e, t, n) => {
+	let r = t[n];
+	if (typeof r != "string" || r === "") throw new v(e, n);
+	return r;
+}, S = (e, t, n = {}) => {
+	let r = e.manifest;
+	switch (t) {
+		case "scaffold_procedure": {
+			let e = x(t, n, "kind"), i = x(t, n, "purpose"), a = (r.tables ?? []).map((e) => e.name).join(", ") || "(none discovered)", o = r.procedures.filter((t) => t.kind === e).map((e) => e.tag).slice(0, 10).join(", ") || "(none yet)";
+			return {
+				description: `Scaffold a ${e} procedure`,
+				messages: [b(`Write a new Voltro ${e} procedure that: ${i}.\n\nThe app's tables are: ${a}.\nExisting ${e} procedures (match their file-convention and shape): ${o}.\n\nFollow the Voltro file conventions for a ${e} descriptor + its server handler, define the input/output with the schema DSL, and only reference tables that exist above.`)]
+			};
+		}
+		case "explain_table": {
+			let e = x(t, n, "table"), i = (r.tables ?? []).find((t) => t.name === e), a = r.procedures.filter((t) => (t.targets ?? []).some((t) => t.table === e)).map((t) => `${t.tag} (${(t.targets ?? []).filter((t) => t.table === e).map((e) => e.op).join("/")})`).join(", ") || "(none)", o = i === void 0 ? `(no table named "${e}" in the manifest)` : JSON.stringify(i, null, 2);
+			return {
+				description: `Explain the ${e} table`,
+				messages: [b(`Explain the "${e}" table of this Voltro app: its columns and their meaning, and how the app uses it.\n\nSchema:\n${o}\n\nProcedures touching it: ${a}.`)]
+			};
+		}
+		case "wire_ui_for_procedure": {
+			let e = x(t, n, "tag"), i = r.procedures.find((t) => t.tag === e), a = i === void 0 ? `(no procedure with tag "${e}" in the manifest)` : JSON.stringify({
+				tag: i.tag,
+				kind: i.kind,
+				input: i.input,
+				output: i.output
+			}, null, 2);
+			return {
+				description: `Wire UI for ${e}`,
+				messages: [b(`Write the Voltro client code to call the "${e}" procedure and render its result.\n\nProcedure:\n${a}\n\nUse the correct Voltro hook for this procedure kind, type the call from the input/output schema above, and render a minimal but complete UI for the result.`)]
+			};
+		}
+		default: throw new _(t);
+	}
+}, C = "2025-06-18", w = [
+	C,
+	"2025-03-26",
+	"2024-11-05"
+], T = {
+	name: "voltro-mcp",
+	version: "0.1.0"
+}, E = (e) => typeof e == "string" && w.includes(e) ? e : C, D = (e, t, n = T) => {
+	if ((t.id === void 0 || t.id === null) && t.method.startsWith("notifications/")) return null;
+	let r = t.id ?? null, a = (e) => ({
+		jsonrpc: "2.0",
+		id: r,
+		result: e
+	}), o = (e, t) => ({
+		jsonrpc: "2.0",
+		id: r,
+		error: {
+			code: e,
+			message: t
+		}
+	});
+	switch (t.method) {
+		case "initialize": return a({
+			protocolVersion: E(t.params?.protocolVersion),
+			capabilities: {
+				tools: {},
+				resources: {},
+				prompts: {}
+			},
+			serverInfo: n
+		});
+		case "ping": return a({});
+		case "tools/list": return a({ tools: i });
+		case "tools/call": {
+			let n = t.params ?? {}, r = String(n.name ?? ""), i = n.arguments ?? {};
+			try {
+				return a({ content: [{
+					type: "text",
+					text: c(e, r, i)
+				}] });
+			} catch (e) {
+				return a({
+					content: [{
+						type: "text",
+						text: `Error: ${String(e)}`
+					}],
+					isError: !0
+				});
+			}
+		}
+		case "resources/list": return a({ resources: p(e) });
+		case "resources/read": {
+			let n = String(t.params?.uri ?? "");
+			try {
+				return a({ contents: h(e, n) });
+			} catch (e) {
+				if (e instanceof m) return o(-32602, e.message);
+				throw e;
+			}
+		}
+		case "prompts/list": return a({ prompts: y() });
+		case "prompts/get": {
+			let n = String(t.params?.name ?? ""), r = t.params?.arguments ?? {};
+			try {
+				return a(S(e, n, r));
+			} catch (e) {
+				if (e instanceof _ || e instanceof v) return o(-32602, e.message);
+				throw e;
+			}
+		}
+		default: return t.method.startsWith("notifications/") ? null : o(-32601, `method not found: ${t.method}`);
+	}
+};
+//#endregion
+export { e as _, E as a, _ as c, u as d, m as f, c as g, i as h, D as i, S as l, h as m, T as n, v as o, p, w as r, g as s, C as t, y as u, n as v, t as y };

package/dist/serve-7hA87wAd.js

@@ -0,0 +1,47 @@
+import { i as e, n as t, v as n } from "./mcp-Br4DcrKz.js";
+import { createRequire as r } from "node:module";
+//#region src/serve.ts
+var i = () => {
+	try {
+		let e = r(import.meta.url)("../package.json");
+		return {
+			name: t.name,
+			version: e.version ?? t.version
+		};
+	} catch {
+		return t;
+	}
+}, a = async (t) => {
+	let r = t.env.VOLTRO_INSPECT_URL ?? "http://localhost:4000", a = t.env.VOLTRO_INSPECT_TOKEN, o = t.serverInfo ?? i(), s = n({
+		baseUrl: r,
+		...a === void 0 ? {} : { token: a },
+		...t.manifestTtlMs === void 0 ? {} : { ttlMs: t.manifestTtlMs }
+	}), c = await s.get();
+	c.error === void 0 ? t.errput.write(`voltro-mcp: loaded ${c.manifest.procedures.length} procedures from ${r}\n`) : t.errput.write(`voltro-mcp: could not fetch manifest from ${r}: ${c.error} — serving empty manifest\n`);
+	let l = async (n) => {
+		if (n === "") return;
+		let r;
+		try {
+			r = JSON.parse(n);
+		} catch {
+			return;
+		}
+		let i = Array.isArray(r) ? r : [r];
+		for (let n of i) {
+			(n.method === "tools/call" || n.method === "tools/list") && (c = await s.get());
+			let r = e(c, n, o);
+			r !== null && t.output.write(`${JSON.stringify(r)}\n`);
+		}
+	}, u = "";
+	for await (let e of t.input) {
+		u += String(e);
+		let t = u.indexOf("\n");
+		for (; t !== -1;) {
+			let e = u.slice(0, t).trim();
+			u = u.slice(t + 1), await l(e), t = u.indexOf("\n");
+		}
+	}
+	await l(u.trim());
+};
+//#endregion
+export { a as n, i as t };

package/dist/server.d.ts

@@ -0,0 +1 @@
+export { }

package/dist/server.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { n as e } from "./serve-7hA87wAd.js";
+//#region src/server.ts
+e({
+	input: process.stdin,
+	output: process.stdout,
+	errput: process.stderr,
+	env: process.env
+});
+//#endregion

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@voltro/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for coding agents over a running Voltro api — exposes the app's procedures, tables, workflows and their JSON Schemas as MCP tools, resources and prompts, over stdio (voltro-mcp) or Streamable HTTP (voltro-mcp-http). Zero dependencies.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "bin": {
+    "voltro-mcp": "./dist/server.js",
+    "voltro-mcp-http": "./dist/httpServer.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}