@bevel-software/platform-core-backend 0.1.0

package/dist/modules/mcp/mcp.service.d.ts

@@ -0,0 +1,198 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { type CallToolResult, type Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
+import '@utcp/http';
+import '@utcp/mcp';
+import { type JsonSchema, type Tool as UtcpTool } from '@utcp/sdk';
+import { type ISecretsVaultService } from '../secrets-vault/secrets-vault.contract.js';
+import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
+import type { SpillStore } from '../workspace/spill-store.js';
+import type { McpSessionStore } from './mcp-session-store.js';
+import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
+/**
+ * Configuration for the loopback proxy. `loopbackBaseUrl` is the backend's own
+ * address (`http://127.0.0.1:<port>`) and `manualName` is BOTH the UTCP manual
+ * namespace the per-session client registers under AND the prefix its `${VAR}`
+ * placeholders resolve through (`<manualName>_API_URL` / `_CONNECTION_KEY`).
+ */
+export interface McpProxyOptions {
+    loopbackBaseUrl: string;
+    manualName: string;
+    /** Shared spill store for oversized `call_tool_chain` results (parity with the in-process agent). */
+    spillStore: SpillStore;
+    /** Public web address of the frontend, for the needs-authorization setup link. */
+    publicFrontendUrl: string;
+}
+/**
+ * The MCP server is a GENERIC proxy over the UTCP tool surface. It owns no tool
+ * logic: per MCP session it stands up a `UtcpClient` pointed at the backend's
+ * own `GET /api/agent/utcp` manual (over loopback, authenticated with the
+ * caller's connection key), discovers every tool, and re-exposes each one to
+ * the MCP client. A tool call is dispatched straight back through the same REST
+ * endpoint the tool's UTCP `tool_call_template` names — so the agent logic,
+ * thread continuity, and per-key token metering all live ONCE behind that REST
+ * endpoint (`AgentAskService` for `ask`), never duplicated here.
+ *
+ * Dispatch always uses `callToolStreaming`, which is uniform across tool kinds:
+ * a plain `http` tool yields exactly one chunk (its final result, emitted as
+ * the tool result with no progress), while a `streamable_http` tool yields many
+ * (the all-but-last become `notifications/progress`, the last is the result).
+ * Because of that, adding — or later upgrading a tool to streaming — never
+ * touches this file.
+ *
+ * Auth note: `/api/agent/*` accepts connection keys and internal tokens only.
+ * Connection-key sessions pass the caller's own key through to the loopback;
+ * OAuth/JWT sessions can't (their bearer would 401 there), so `createSession`
+ * mints a least-privilege internal token for the resolved user and uses THAT
+ * as the session's loopback bearer instead.
+ */
+export declare class McpService {
+    private readonly sessionStore;
+    private readonly opts;
+    private readonly secretsVault?;
+    private readonly toolManuals?;
+    private readonly internalTokens?;
+    private readonly revokeOAuthAccess?;
+    constructor(sessionStore: McpSessionStore, opts: McpProxyOptions, secretsVault?: ISecretsVaultService | undefined, toolManuals?: IToolManualService | undefined, internalTokens?: InternalTokenService | undefined, revokeOAuthAccess?: ((bearer: string) => Promise<void>) | undefined);
+    /**
+     * Subscribe to store-driven evictions (idle-TTL sweep, size-cap eviction) so
+     * the route layer can drop its transport mirror. Returns an unsubscribe fn.
+     */
+    onSessionEvicted(listener: (sessionId: string) => void): () => void;
+    /**
+     * Build a fresh per-session (transport, server) pair. Async because tool
+     * discovery (a loopback round-trip authenticated with `bearer`) happens here,
+     * before the server is returned, so `tools/list` is ready the moment the
+     * client asks. The route awaits this, then `server.connect(transport)`.
+     */
+    createSession(userId: string, tokenId: string | null, bearer: string, onSessionInitialized: (sessionId: string) => void): Promise<{
+        transport: StreamableHTTPServerTransport;
+        server: Server;
+    }>;
+    /** Loopback GET of the default-branch skill catalog (via the `list_skills` tool). */
+    private fetchSkillList;
+    /** Loopback GET of one skill's body (via the `get_skill` tool); null if unavailable. */
+    private fetchSkill;
+    /**
+     * The ONE loopback round-trip: fetch `path` on our own REST surface with the
+     * caller's bearer, parse JSON. Failures are logged under `label` (never the
+     * bearer) and degrade to null — a loopback hiccup must not throw into the
+     * MCP session. GET when `json` is absent, POST with a JSON body when present.
+     * Bounded: a hung loopback (e.g. mid-restart) must not block `createSession`
+     * or a prompts handler indefinitely; a timeout aborts and degrades to null
+     * like any other failure.
+     */
+    private loopbackJson;
+    /** POST a skill tool endpoint over loopback with the caller's bearer; parsed JSON or null. */
+    private loopbackTool;
+    /**
+     * Loopback GET of the caller's manual list (KB + accessible `.tool` manuals),
+     * validated into `CallTemplate`s at the boundary. The KB manual is guaranteed
+     * present (a fallback covers an unavailable endpoint); a user manual that
+     * fails validation is dropped + logged so one bad `.tool` can't break the
+     * session. HTTP transport loses the `CallTemplate` type, so we re-validate the
+     * received JSON even though the producing endpoint already validated it.
+     */
+    private fetchManualTemplates;
+    /** The KB manual's discovery template — the fallback if `all-tools` is unavailable. */
+    private kbManualTemplate;
+    /**
+     * One `CodeModeUtcpClient` per session. Reserved `API_URL`/`CONNECTION_KEY` are
+     * seeded (namespaced) ONLY for Bevel-hosted manuals — the KB manual and inline
+     * `.tool` sub-manuals, whose discovery template targets the loopback (`${API_URL}`).
+     * Third-party http/mcp `.tool`s point at arbitrary user URLs, so we must NOT seed
+     * them the caller's bearer: a malicious `.tool` referencing `${CONNECTION_KEY}`
+     * would otherwise exfiltrate the caller's token to its own endpoint. Tool
+     * `${SECRET}` refs resolve lazily via the per-user `bevel-secrets` loader.
+     */
+    private buildClient;
+    /**
+     * Register EVERY manual on the client, then flatten each discovered tool into
+     * the proxy's advertised shape. A failure registering a user `.tool` is
+     * isolated (logged + skipped) so one broken manual never breaks the session;
+     * the KB manual failing is fatal (the core toolset is unusable).
+     */
+    private discoverTools;
+    /**
+     * Run one tool call through `callToolStreaming` with a one-chunk lookahead:
+     * every chunk except the last becomes a progress notification, the last is
+     * the result. Continuity is the caller's: a tool that supports it (e.g.
+     * `ask`) returns its `sessionId` in the result verbatim, and the caller
+     * echoes it back per the tool's own schema — the proxy never rewrites args.
+     */
+    /**
+     * If the tool declares per-user credentials the caller hasn't set, return a
+     * needs-authorization result (naming the tool + a setup link); otherwise null
+     * to proceed. Reads the manual's `user`-scoped variables and asks the vault,
+     * with the SAME keys `resolve` uses, which the caller has configured — so the
+     * check can't drift from the actual resolution. A no-op when the vault/manual
+     * services aren't wired, or the tool's manual declares no per-user credential
+     * (e.g. the built-in KB tools).
+     */
+    private checkUserSecrets;
+    /**
+     * The per-user variables of `tool`'s manual the caller has NOT satisfied.
+     * Shared by the call-time needs-authorization check above and the
+     * listing-time filter for connection-key sessions (which registers only
+     * ready tools). Empty when the vault/manual services aren't wired or the
+     * manual declares no per-user credential.
+     */
+    private missingUserSecrets;
+    private dispatch;
+    /**
+     * Handle a code-mode meta-tool. `list_tools`/`tools_info` reflect on the
+     * session client's discovered catalog; `call_tool_chain` runs the caller's
+     * JavaScript in the client's isolated-vm, where every tool is reachable as
+     * `<manual>.tool(...)` and resolves over loopback with the caller's key.
+     */
+    private dispatchMetaTool;
+}
+/** A tool discovered from the manual, flattened into what the proxy advertises. */
+export interface ProxiedTool {
+    utcpName: string;
+    mcpName: string;
+    description: string;
+    inputSchema: JsonSchema;
+    /** The UTCP manual this tool came from (the `<manual>` in `<manual>.<tool>`),
+     * used to look up the manual's declared per-user credentials before dispatch. */
+    manualName: string;
+}
+/** A discovered tool as an MCP listing entry, or null if its name can't be listed. */
+export declare function toListedTool(tool: ProxiedTool): McpTool | null;
+/**
+ * Make a remote server's JSON Schema safe for the Anthropic tool validator:
+ *  - inline local `$ref` pointers (`#/$defs/...`, `#/definitions/...`) and drop
+ *    the now-unreferenced `$defs`/`definitions` blocks (the API restricts `$ref`
+ *    and MCP clients converting our schemas reject it outright);
+ *  - drop non-standard `format` values (OpenAPI's `int32`/`byte`/… — only the
+ *    JSON-Schema-standard formats above are accepted; `format` is advisory, so
+ *    dropping it doesn't change tool behavior).
+ * Depth-bounded so a recursive schema degrades to a permissive `{}` node instead
+ * of hanging or emitting the unsupported recursion; non-local/external refs
+ * degrade the same way. Exported for direct testing.
+ */
+export declare function sanitizeInputSchema(schema: unknown): unknown;
+export declare function flattenManualTool(tool: UtcpTool): ProxiedTool;
+/**
+ * Flatten one discovered UTCP tool into the proxy's advertised shape: strip the
+ * `<manual>.` namespace prefix for the MCP name and keep the UTCP input schema
+ * verbatim (Bevel-hosted HTTP tools show their `{body}` envelope, exactly as in
+ * `call_tool_chain`).
+ */
+export declare function flattenDiscoveredTool(prefix: string, tool: UtcpTool): ProxiedTool;
+/**
+ * Extract a human-meaningful failure message from a tool-call error. UTCP's
+ * HTTP protocol surfaces a non-2xx as an axios-style error whose `.response.data`
+ * is the REST endpoint's JSON body (`{ error: "..." }`). Pull that out so the
+ * MCP caller sees the tool's real message instead of a bare "status code 500".
+ */
+export declare function describeToolFailure(err: unknown): string;
+export declare function toCallToolResult(value: unknown): CallToolResult;
+/**
+ * The result returned when the caller is missing personal credentials a tool
+ * needs. Marked `isError` so the external agent surfaces it to the person rather
+ * than treating it as tool output. Names the tool, lists the missing items, and
+ * gives the absolute setup-page URL so the person can provide them and retry.
+ */
+export declare function needsAuthorizationResult(toolName: string, missing: string[], connectUrl: string): CallToolResult;
+//# sourceMappingURL=mcp.service.d.ts.map

package/dist/modules/mcp/mcp.service.d.ts.map

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