@voyant-travel/mcp 0.0.0

package/README.md

@@ -0,0 +1,54 @@
+# @voyant-travel/mcp
+
+The in-deployment MCP server for the Voyant framework (voyant#2792). It exposes
+the framework tool registry as a real [Model Context Protocol](https://modelcontextprotocol.io)
+server, mounted as a Hono route group inside the operator deployment at
+`/v1/admin/mcp` — **not** a separate app/worker, and **no Durable Object**.
+
+External MCP clients (Claude, ChatGPT, …) connect to that endpoint over the wire.
+
+## API
+
+`createMcpHonoApp({ registry, buildContext, serverInfo? })` → a Hono sub-app. Mount it
+at `/v1/admin/mcp` (the `"operator/mcp"` composition entry):
+
+- `POST /` — MCP JSON-RPC (`initialize` / `tools/list` / `tools/call`).
+- `GET /manifest` — the contract-versioned tool discovery manifest for remote agents.
+
+`buildContext(c)` maps the request's `c.var` (db lease / actor / audience / scope) into
+a `@voyant-travel/tools` `ToolContext`.
+
+## Authentication (external MCP clients)
+
+External MCP clients (Claude Desktop, ChatGPT, …) authenticate with a **Bearer
+scoped API key** — the operator's existing `voy_` key pipeline — sent as
+`Authorization: <key>`. No separate OAuth/runner is introduced (voyant#2801): the
+request auth middleware resolves the key into `scopes` + `audience` on `c.var`, and
+this server gates every tool by its `requiredScopes`.
+
+Because authorization is per-tool, the `/v1/admin/mcp` surface is exempt from the
+coarse method+path permission guard (`require-actor`, like `_meta`): any
+authenticated key reaches the endpoint, and a key with no relevant scopes simply
+sees an empty `tools/list`. Mint keys with a grant preset (e.g. `agent-customer`)
+to bundle a scope subset with an `audience`.
+
+The reserved `apps/agent-runner` / `apps/agent-control-plane` stubs are intentionally
+**not** built out — Voyant ships the tool primitives + this ready-to-use MCP, not an
+agent.
+
+## How it works
+
+- **Transport:** `@hono/mcp`'s `StreamableHTTPTransport` (web-standard `Request`/
+  `Response`) connected to `@modelcontextprotocol/sdk`'s `McpServer`. The SDK's own
+  Node-`http` transport is **not** used.
+- **Stateless, per request:** a fresh `McpServer` + transport per request with
+  `{ sessionIdGenerator: undefined, enableJsonResponse: true }`, then
+  `server.connect(transport)` → `transport.handleRequest(c)`. No session store, no
+  Durable Object — fits the operator's single-worker `nodejs_compat` runtime and
+  survives the lazy-route `c.var` re-hydration. Clients must send
+  `Accept: application/json, text/event-stream`.
+- **Authorization (D2):** each tool's `requiredScopes` are checked against the caller's
+  granted scopes with **AND** semantics (`hasApiKeyPermission`). Unauthorized tools are
+  neither listed nor registered on the per-request server, so they cannot be called.
+- **Headless boundary:** the registry returns typed pure data; this adapter wraps it in
+  the MCP `CallToolResult` envelope only at the transport edge.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createMcpHonoApp, type McpHonoAppOptions, type McpServerInfo, } from "./server.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { createMcpHonoApp, } from "./server.js";

package/dist/server.d.ts

@@ -0,0 +1,22 @@
+import { type ToolContext, type ToolRegistry } from "@voyant-travel/tools";
+import { type Context, Hono } from "hono";
+export interface McpServerInfo {
+    name: string;
+    version: string;
+}
+export interface McpHonoAppOptions {
+    /** The tool registry to expose. */
+    registry: ToolRegistry;
+    /** Build the per-request tool context from the Hono context (db/actor/audience/scope). */
+    buildContext(c: Context): ToolContext;
+    /** MCP server identity advertised in `initialize`. */
+    serverInfo?: McpServerInfo;
+}
+/**
+ * Build the MCP Hono sub-app. Mount at `/v1/admin/mcp`:
+ * - `POST /` — MCP JSON-RPC (`initialize` / `tools/list` / `tools/call`).
+ * - `GET /manifest` — the tool discovery manifest (contract-versioned), filtered
+ *   to what the caller is authorized for.
+ */
+export declare function createMcpHonoApp(options: McpHonoAppOptions): Hono;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAA;AAM7B,OAAO,EAAE,KAAK,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAGzC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,QAAQ,EAAE,YAAY,CAAA;IACtB,0FAA0F;IAC1F,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,WAAW,CAAA;IACrC,sDAAsD;IACtD,UAAU,CAAC,EAAE,aAAa,CAAA;CAC3B;AAID;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAkCjE"}

package/dist/server.js

@@ -0,0 +1,104 @@
+/**
+ * The in-deployment MCP server (voyant#2792). Exposes a `@voyant-travel/tools`
+ * `ToolRegistry` as a real Model Context Protocol server, mounted as a Hono
+ * route group inside the operator app at `/v1/admin/mcp` — stateless, no Durable
+ * Object (see the Sub-issue 0 spike). External MCP clients connect over the wire.
+ *
+ * Transport: `@modelcontextprotocol/sdk` `McpServer` connected to `@hono/mcp`'s
+ * web-standard `StreamableHTTPTransport`. A fresh server + transport per request
+ * keeps it stateless, so the lazy-route `c.var` hydration (db lease / actor /
+ * scopes / audience) is all the context we need.
+ *
+ * Authorization (D2): each tool's `requiredScopes` are checked against the
+ * caller's granted scopes with **AND** semantics. Unauthorized tools are neither
+ * listed nor registered on the per-request server, so they cannot be called.
+ */
+import { StreamableHTTPTransport } from "@hono/mcp";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TOOL_CONTRACT_VERSION, ToolError, } from "@voyant-travel/tools";
+import { hasApiKeyPermission, permissionStringsToPermissions, } from "@voyant-travel/types/api-keys";
+import { Hono } from "hono";
+import { z } from "zod";
+const DEFAULT_SERVER_INFO = { name: "voyant-mcp", version: "0.1.0" };
+/**
+ * Build the MCP Hono sub-app. Mount at `/v1/admin/mcp`:
+ * - `POST /` — MCP JSON-RPC (`initialize` / `tools/list` / `tools/call`).
+ * - `GET /manifest` — the tool discovery manifest (contract-versioned), filtered
+ *   to what the caller is authorized for.
+ */
+export function createMcpHonoApp(options) {
+    const { registry, buildContext } = options;
+    const serverInfo = options.serverInfo ?? DEFAULT_SERVER_INFO;
+    const app = new Hono();
+    app.get("/manifest", (c) => {
+        const permissions = callerPermissions(c);
+        const tools = registry.list().filter((tool) => isAuthorized(tool.requiredScopes, permissions));
+        return c.json({ version: TOOL_CONTRACT_VERSION, serverInfo, tools });
+    });
+    app.all("/", async (c) => {
+        const permissions = callerPermissions(c);
+        const ctx = buildContext(c);
+        const server = new McpServer(serverInfo);
+        for (const entry of registry.list()) {
+            if (!isAuthorized(entry.requiredScopes, permissions))
+                continue;
+            const def = registry.get(entry.name);
+            if (!def)
+                continue;
+            server.tool(entry.name, entry.description, toRawShape(def.inputSchema), (args) => dispatchToResult(registry, entry.name, args, ctx));
+        }
+        const transport = new StreamableHTTPTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+        });
+        await server.connect(transport);
+        return transport.handleRequest(c);
+    });
+    return app;
+}
+/** Resolve the caller's granted permissions from `c.var.scopes`. */
+function callerPermissions(c) {
+    const scopes = c.var.scopes ?? [];
+    return permissionStringsToPermissions(scopes);
+}
+/** AND semantics — the caller must hold every one of the tool's required scopes. */
+function isAuthorized(requiredScopes, permissions) {
+    return requiredScopes.every((scope) => {
+        const [resource, action] = scope.split(":");
+        return Boolean(resource && action && hasApiKeyPermission(permissions, resource, action));
+    });
+}
+/** Extract a Zod raw shape for the MCP SDK. Tool inputs are objects by convention. */
+function toRawShape(schema) {
+    if (schema instanceof z.ZodObject)
+        return schema.shape;
+    return {};
+}
+/** Dispatch through the registry (validates in + out) and wrap pure data in an MCP envelope. */
+async function dispatchToResult(registry, name, args, ctx) {
+    try {
+        const data = await registry.dispatch(name, args, ctx);
+        return {
+            content: [{ type: "text", text: safeStringify(data) }],
+            structuredContent: toStructuredContent(data),
+        };
+    }
+    catch (err) {
+        const code = err instanceof ToolError ? err.code : "PROVIDER_ERROR";
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `[${code}] ${message}` }] };
+    }
+}
+function toStructuredContent(data) {
+    return data !== null && typeof data === "object" && !Array.isArray(data)
+        ? data
+        : { result: data };
+}
+function safeStringify(data) {
+    try {
+        return JSON.stringify(data, null, 2);
+    }
+    catch {
+        return String(data);
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@voyant-travel/mcp",
+  "version": "0.0.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "lint": "biome check src/",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "@hono/mcp": "^0.3.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@voyant-travel/tools": "workspace:^",
+    "@voyant-travel/types": "workspace:^",
+    "hono": "catalog:",
+    "hono-rate-limiter": "^0.5.3",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@voyant-travel/voyant-typescript-config": "workspace:^",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyant-travel/voyant.git",
+    "directory": "packages/mcp"
+  }
+}