@ggui-ai/mcp-server 0.1.0-rc.1

package/dist/admin-oauth-providers-transport.js

@@ -0,0 +1,263 @@
+import { resolveIdentity, UnauthenticatedError } from './auth.js';
+export const DEFAULT_ADMIN_OAUTH_PROVIDERS_PATH = '/ggui/admin/oauth-providers';
+function redact(record) {
+    return {
+        providerId: record.providerId,
+        clientId: record.clientId,
+        clientSecret: '<redacted>',
+        source: record.source,
+        enabled: record.enabled,
+    };
+}
+function isEnvOverriddenError(err) {
+    return err instanceof Error && err.message.startsWith('oauth_provider_env_overridden');
+}
+function isInvalidIdError(err) {
+    return (err instanceof Error &&
+        (err.message.startsWith('oauth_provider_invalid_id') ||
+            err.message.startsWith('oauth_provider_invalid_client_id') ||
+            err.message.startsWith('oauth_provider_invalid_client_secret')));
+}
+function isNotFoundError(err) {
+    return err instanceof Error && err.message.startsWith('oauth_provider_not_found');
+}
+export function mountAdminOAuthProvidersTransport(app, opts) {
+    const basePath = opts.path ?? DEFAULT_ADMIN_OAUTH_PROVIDERS_PATH;
+    const auditSink = opts.auditSink;
+    const emitAudit = async (entry, auditLogger) => {
+        if (!auditSink)
+            return;
+        try {
+            await auditSink.record({ at: Date.now(), ...entry });
+        }
+        catch (err) {
+            auditLogger.warn('audit_emit_failed', {
+                action: entry.action,
+                error: String(err),
+            });
+        }
+    };
+    // Builder-identity gate. Same shape as /admin/blueprints — 401 on
+    // missing/invalid bearer, 403 on non-builder. Returns true when
+    // the route handler may proceed; false when a response was already
+    // written.
+    const requireBuilder = async (req, res, reqLogger) => {
+        try {
+            const identity = await resolveIdentity(opts.auth, req);
+            if (identity.identity.kind !== 'builder') {
+                reqLogger.warn('admin_oauth_providers_forbidden', {
+                    identityKind: identity.identity.kind,
+                });
+                res.status(403).json({
+                    error: {
+                        code: 'forbidden',
+                        message: 'Admin OAuth providers requires a builder identity.',
+                    },
+                });
+                return false;
+            }
+            return true;
+        }
+        catch (err) {
+            if (err instanceof UnauthenticatedError) {
+                reqLogger.warn('admin_oauth_providers_unauthenticated', {
+                    reason: err.message,
+                });
+                res.status(401).json({
+                    error: { code: 'unauthenticated', message: err.message },
+                });
+                return false;
+            }
+            reqLogger.error('admin_oauth_providers_unexpected_error', {
+                error: String(err),
+            });
+            res.status(500).json({
+                error: { code: 'internal', message: 'Internal server error' },
+            });
+            return false;
+        }
+    };
+    // --- GET base ---
+    app.get(basePath, async (req, res) => {
+        const reqLogger = opts.logger.child({ route: 'GET ' + basePath });
+        if (!(await requireBuilder(req, res, reqLogger)))
+            return;
+        try {
+            const records = await opts.store.list();
+            res.status(200).json({ providers: records.map(redact) });
+        }
+        catch (err) {
+            reqLogger.error('admin_oauth_providers_list_failed', {
+                error: String(err),
+            });
+            res.status(500).json({
+                error: { code: 'internal', message: 'Internal server error' },
+            });
+        }
+    });
+    // --- PUT base/:providerId ---
+    app.put(`${basePath}/:providerId`, async (req, res) => {
+        const reqLogger = opts.logger.child({ route: 'PUT ' + basePath + '/:providerId' });
+        if (!(await requireBuilder(req, res, reqLogger)))
+            return;
+        const providerId = req.params['providerId'] ?? '';
+        const body = (req.body ?? {});
+        const clientId = typeof body['clientId'] === 'string' ? body['clientId'] : undefined;
+        const clientSecret = typeof body['clientSecret'] === 'string' ? body['clientSecret'] : undefined;
+        const enabled = typeof body['enabled'] === 'boolean' ? body['enabled'] : undefined;
+        if (!clientId || !clientSecret) {
+            reqLogger.debug?.('admin_oauth_providers_bad_request', {
+                hasClientId: clientId !== undefined,
+                hasClientSecret: clientSecret !== undefined,
+            });
+            res.status(400).json({
+                error: {
+                    code: 'bad_request',
+                    message: 'Body requires non-empty string `clientId` and `clientSecret`.',
+                },
+            });
+            return;
+        }
+        try {
+            const record = await opts.store.put({
+                providerId,
+                clientId,
+                clientSecret,
+                ...(enabled !== undefined ? { enabled } : {}),
+            });
+            reqLogger.info('admin_oauth_providers_put', { providerId });
+            await emitAudit({
+                action: 'auth.oauth-config.write',
+                actor: { kind: 'builder' },
+                resource: { kind: 'oauth-provider', id: providerId },
+                metadata: { enabled: record.enabled },
+            }, reqLogger);
+            res.status(200).json(redact(record));
+        }
+        catch (err) {
+            if (isEnvOverriddenError(err)) {
+                reqLogger.warn('admin_oauth_providers_env_overridden', { providerId });
+                res.status(409).json({
+                    error: {
+                        code: 'env_overridden',
+                        message: err.message,
+                    },
+                });
+                return;
+            }
+            if (isInvalidIdError(err)) {
+                reqLogger.warn('admin_oauth_providers_validation_failed', {
+                    providerId,
+                    reason: err.message,
+                });
+                res.status(400).json({
+                    error: { code: 'bad_request', message: err.message },
+                });
+                return;
+            }
+            reqLogger.error('admin_oauth_providers_put_failed', {
+                providerId,
+                error: String(err),
+            });
+            res.status(500).json({
+                error: { code: 'internal', message: 'Internal server error' },
+            });
+        }
+    });
+    // --- POST base/:providerId/toggle ---
+    app.post(`${basePath}/:providerId/toggle`, async (req, res) => {
+        const reqLogger = opts.logger.child({
+            route: 'POST ' + basePath + '/:providerId/toggle',
+        });
+        if (!(await requireBuilder(req, res, reqLogger)))
+            return;
+        const providerId = req.params['providerId'] ?? '';
+        const body = (req.body ?? {});
+        const enabled = typeof body['enabled'] === 'boolean' ? body['enabled'] : undefined;
+        if (enabled === undefined) {
+            res.status(400).json({
+                error: {
+                    code: 'bad_request',
+                    message: 'Body requires boolean `enabled`.',
+                },
+            });
+            return;
+        }
+        try {
+            await opts.store.setEnabled(providerId, enabled);
+            reqLogger.info('admin_oauth_providers_toggle', { providerId, enabled });
+            await emitAudit({
+                action: 'auth.oauth-config.write',
+                actor: { kind: 'builder' },
+                resource: { kind: 'oauth-provider', id: providerId },
+                metadata: { enabled },
+            }, reqLogger);
+            res.status(204).end();
+        }
+        catch (err) {
+            if (isEnvOverriddenError(err)) {
+                reqLogger.warn('admin_oauth_providers_env_overridden', { providerId });
+                res.status(409).json({
+                    error: {
+                        code: 'env_overridden',
+                        message: err.message,
+                    },
+                });
+                return;
+            }
+            if (isNotFoundError(err)) {
+                res.status(404).json({
+                    error: { code: 'not_found', message: err.message },
+                });
+                return;
+            }
+            if (isInvalidIdError(err)) {
+                res.status(400).json({
+                    error: { code: 'bad_request', message: err.message },
+                });
+                return;
+            }
+            reqLogger.error('admin_oauth_providers_toggle_failed', {
+                providerId,
+                error: String(err),
+            });
+            res.status(500).json({
+                error: { code: 'internal', message: 'Internal server error' },
+            });
+        }
+    });
+    // --- DELETE base/:providerId ---
+    app.delete(`${basePath}/:providerId`, async (req, res) => {
+        const reqLogger = opts.logger.child({
+            route: 'DELETE ' + basePath + '/:providerId',
+        });
+        if (!(await requireBuilder(req, res, reqLogger)))
+            return;
+        const providerId = req.params['providerId'] ?? '';
+        try {
+            await opts.store.remove(providerId);
+            reqLogger.info('admin_oauth_providers_remove', { providerId });
+            await emitAudit({
+                action: 'auth.oauth-config.delete',
+                actor: { kind: 'builder' },
+                resource: { kind: 'oauth-provider', id: providerId },
+            }, reqLogger);
+            res.status(204).end();
+        }
+        catch (err) {
+            if (isInvalidIdError(err)) {
+                res.status(400).json({
+                    error: { code: 'bad_request', message: err.message },
+                });
+                return;
+            }
+            reqLogger.error('admin_oauth_providers_remove_failed', {
+                providerId,
+                error: String(err),
+            });
+            res.status(500).json({
+                error: { code: 'internal', message: 'Internal server error' },
+            });
+        }
+    });
+}

package/dist/auth.d.ts

@@ -0,0 +1,39 @@
+/**
+ * HTTP → AuthAdapter bridge.
+ *
+ * Parses `Authorization: Bearer <token>` off the incoming request and
+ * delegates identity resolution to the supplied {@link AuthAdapter}.
+ * Unauthenticated requests are rejected with 401 before the MCP SDK
+ * ever sees the request body.
+ */
+import type { Request } from 'express';
+import type { IncomingHttpHeaders } from 'node:http';
+import type { AuthAdapter, AuthResult } from '@ggui-ai/mcp-server-core';
+export declare class UnauthenticatedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve an identity from a normalized `(headers, remoteAddress)` pair.
+ * Both the Express `/mcp` path and the WebSocket live-channel `/ws`
+ * upgrade path funnel through this — so a single bearer-parsing +
+ * adapter-call codepath covers every OSS ingress point.
+ */
+export declare function resolveIdentityFromHeaders(adapter: AuthAdapter, headers: IncomingHttpHeaders, remoteAddress?: string): Promise<AuthResult>;
+/**
+ * Resolve the caller's identity from the incoming Express request.
+ * Throws {@link UnauthenticatedError} when the adapter returns null
+ * so the HTTP layer can map to a single 401 response shape.
+ */
+export declare function resolveIdentity(adapter: AuthAdapter, req: Request): Promise<AuthResult>;
+/**
+ * Derive a stable `appId` from an auth result.
+ *
+ * In OSS single-user mode every identity collapses to `{kind:'builder'}`
+ * which doesn't carry a tenant id. We fold these into a single
+ * well-known value (`DEFAULT_BUILDER_APP_ID`) so blueprint / vector
+ * scoping still works. Multi-tenant bindings (a hosted closed runtime)
+ * override this by passing `appIdFromIdentity` on `createGguiServer`.
+ */
+export declare const DEFAULT_BUILDER_APP_ID = "builder";
+export declare function defaultAppIdFromIdentity(result: AuthResult): string;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAExE,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,mBAAmB,EAC5B,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,UAAU,CAAC,CAcrB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,UAAU,CAAC,CAMrB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,YAAY,CAAC;AAEhD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAqBnE"}

package/dist/auth.js

@@ -0,0 +1,75 @@
+/**
+ * HTTP → AuthAdapter bridge.
+ *
+ * Parses `Authorization: Bearer <token>` off the incoming request and
+ * delegates identity resolution to the supplied {@link AuthAdapter}.
+ * Unauthenticated requests are rejected with 401 before the MCP SDK
+ * ever sees the request body.
+ */
+export class UnauthenticatedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnauthenticatedError';
+    }
+}
+/**
+ * Resolve an identity from a normalized `(headers, remoteAddress)` pair.
+ * Both the Express `/mcp` path and the WebSocket live-channel `/ws`
+ * upgrade path funnel through this — so a single bearer-parsing +
+ * adapter-call codepath covers every OSS ingress point.
+ */
+export async function resolveIdentityFromHeaders(adapter, headers, remoteAddress) {
+    const flat = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (typeof v === 'string')
+            flat[k] = v;
+        else if (Array.isArray(v))
+            flat[k] = v[0];
+    }
+    const result = await adapter.getIdentity({
+        headers: flat,
+        remoteAddress,
+    });
+    if (!result) {
+        throw new UnauthenticatedError('No valid credentials');
+    }
+    return result;
+}
+/**
+ * Resolve the caller's identity from the incoming Express request.
+ * Throws {@link UnauthenticatedError} when the adapter returns null
+ * so the HTTP layer can map to a single 401 response shape.
+ */
+export async function resolveIdentity(adapter, req) {
+    return resolveIdentityFromHeaders(adapter, req.headers, req.socket?.remoteAddress ?? req.ip ?? undefined);
+}
+/**
+ * Derive a stable `appId` from an auth result.
+ *
+ * In OSS single-user mode every identity collapses to `{kind:'builder'}`
+ * which doesn't carry a tenant id. We fold these into a single
+ * well-known value (`DEFAULT_BUILDER_APP_ID`) so blueprint / vector
+ * scoping still works. Multi-tenant bindings (a hosted closed runtime)
+ * override this by passing `appIdFromIdentity` on `createGguiServer`.
+ */
+export const DEFAULT_BUILDER_APP_ID = 'builder';
+export function defaultAppIdFromIdentity(result) {
+    if (result.identity.kind === 'user') {
+        // Cloud auth adapters populate `appId` when known — per-app-scoped
+        // bearer key, URL-path-derived, or User.defaultAppId lookup. Read
+        // it with priority so handlers scope to the correct GguiApp.appId.
+        // OSS deployments leave the field undefined and fall through to the
+        // `workspaceId`/`userId` chain.
+        return (result.identity.appId ??
+            result.identity.workspaceId ??
+            result.identity.userId);
+    }
+    // `kind: 'app'` carries the appId directly — surfaced by API-key /
+    // OAuth-bearer adapters (e.g. an ApiKeyAuthAdapter on a hosted
+    // multi-tenant deployment). Falling through to DEFAULT_BUILDER_APP_ID
+    // here would discard the very tenant id the adapter just proved.
+    if (result.identity.kind === 'app') {
+        return result.identity.appId;
+    }
+    return DEFAULT_BUILDER_APP_ID;
+}

package/dist/build-mcp.d.ts

@@ -0,0 +1,128 @@
+/**
+ * buildMcpServer — register every shared handler on a fresh `McpServer`
+ * instance. One server per request (matches the hosted pattern); the
+ * `StreamableHTTPServerTransport` holds per-connection state so pooling
+ * isn't worth the locking.
+ *
+ * Output validation runs here via a zod object built from each handler's
+ * `outputSchema` raw shape. This enforces the ggui convention that every
+ * tool return advertises its shape — wire consumers can trust the output.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ZodRawShape } from 'zod';
+import type { HandlerContext, SharedHandler } from '@ggui-ai/mcp-server-handlers';
+import type { Logger } from './logger.js';
+import { type GguiSessionResourceTemplateOptions } from './mcp-apps-outbound.js';
+export interface ServerInfo {
+    readonly name: string;
+    readonly version: string;
+    readonly description?: string;
+}
+export interface BuildMcpServerOptions {
+    /**
+     * When set, register the MCP Apps outbound wiring on every fresh
+     * server instance — advertises the `io.modelcontextprotocol/ui`
+     * capability and serves `ui://ggui/session` via `resources/read`.
+     *
+     * Tool-declaration `_meta.ui.*` is INDEPENDENT of this flag; it's
+     * carried per-handler on `SharedHandler._meta`. A server can stamp
+     * those without turning the outbound wiring on, but serving the
+     * resource without stamping the declaration is pointless, so the
+     * canonical path is "enable both together" via `createGguiServer`.
+     */
+    readonly mcpAppsOutbound?: boolean;
+    /**
+     * Optional override for the `ui://ggui/session` shell body. Defaults
+     * to whatever shell the server was built with — either a placeholder
+     * or the real thin-shell HTML.
+     */
+    readonly shellHtml?: string;
+    /**
+     * Per-session self-contained shell options. When supplied,
+     * `installMcpAppsOutbound` ALSO registers
+     * `ui://ggui/session/{sessionId}` as a resource template — the URI
+     * `ggui_push.resultMeta` stamps on per-call `_meta.ui.resourceUri`
+     * for third-party MCP Apps hosts (Claude Desktop, claude.ai web)
+     * that don't speak ggui's custom postMessage protocol.
+     *
+     * Absent → only the legacy postMessage shell is registered (first-
+     * party hosts only).
+     */
+    readonly selfContained?: GguiSessionResourceTemplateOptions;
+    /**
+     * Public origin the server is reachable at — forwarded to
+     * `installMcpAppsOutbound` so the static `ui://ggui/session`
+     * resource declares `_meta.ui.csp.{connectDomains,resourceDomains}`.
+     * Without this, spec-compliant hosts (Claude Desktop, claude.ai
+     * Connector, Claude Code) apply their default CSP (`connect-src
+     * 'none'`) and the iframe can't fetch the runtime bundle or open
+     * the WebSocket. Omit when running same-origin behind a first-party
+     * host that owns the iframe CSP itself.
+     */
+    readonly publicBaseUrl?: string;
+    /**
+     * Identity-kind allowlist for tool registration. When set, handlers
+     * whose `allowedFor` field is non-empty AND does NOT intersect this
+     * list are skipped at registration time (NOT registered with the MCP
+     * server, NOT visible in `tools/list`).
+     *
+     * Handlers without `allowedFor` are registered unconditionally per the
+     * "anyone authenticated" default in
+     * `packages/mcp-server-handlers/src/types.ts:151-153`. Omitting this
+     * option (or passing `undefined`) disables filtering entirely —
+     * today's behavior, kept for OSS callers (resolved as
+     * `kind: 'builder'`) so an OSS deployment never accidentally gates
+     * itself off.
+     *
+     * Production postures:
+     *   - agent-builder posture: `allowedKinds: ['app']`
+     *   - end-user / Connector posture: `allowedKinds: ['user']`
+     *   - OSS local: omit (every handler registers regardless)
+     */
+    readonly allowedKinds?: ReadonlyArray<'app' | 'user' | 'builder'>;
+    /**
+     * Server-level instructions string injected into the MCP
+     * `InitializeResult.instructions` field. Hosts (Claude.ai web,
+     * Claude Desktop, MCP Inspector) inject this into the LLM's system
+     * prompt as a top-level block, ABOVE per-tool descriptions —
+     * influencing "how should I behave with this server's tools
+     * generally?" vs. per-tool "should I pick THIS tool right now?"
+     *
+     * Resolved upstream by `resolveMcpInstructions` from a preset name
+     * or arbitrary string. Pass `undefined` here to omit the field
+     * (host falls back to per-tool descriptions only).
+     *
+     * See `instructions-presets.ts` for the supported preset enum and
+     * full rationale.
+     */
+    readonly instructions?: string;
+    /**
+     * Hooks invoked once the per-request `McpServer` is constructed,
+     * after the MCP-Apps outbound install (when enabled) and before
+     * any tool registration. Each entry receives the fresh `McpServer`
+     * and may register additional resources / resource templates.
+     *
+     * Use case: hosted deployments that mount cross-cutting MCP App
+     * UI bundles (e.g. a `ui://`-scheme resource for welcome /
+     * account-status cards) without baking the bundle's wiring into
+     * this OSS factory. The closure runs on every fresh server
+     * instance, mirroring the per-request `installMcpAppsOutbound`
+     * lifecycle.
+     *
+     * Each registrar SHOULD be idempotent across calls (the underlying
+     * SDK throws on duplicate URIs anyway). Errors thrown by a
+     * registrar propagate up — the request fails before any tool can
+     * dispatch, surfacing misconfiguration loudly rather than 404-ing
+     * `resources/read` later.
+     */
+    readonly extraResources?: ReadonlyArray<(server: McpServer) => void>;
+}
+/**
+ * Build a fresh MCP server with every handler registered.
+ *
+ * `getContext` is a late-binding accessor so the HTTP layer can thread
+ * per-request context (via AsyncLocalStorage or a closure) without
+ * leaking the shape into this module.
+ */
+export declare function buildMcpServer(info: ServerInfo, handlers: ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>, getContext: () => HandlerContext, logger: Logger, opts?: BuildMcpServerOptions): McpServer;
+//# sourceMappingURL=build-mcp.d.ts.map

package/dist/build-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-mcp.d.ts","sourceRoot":"","sources":["../src/build-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAK,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACd,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAEL,KAAK,kCAAkC,EACxC,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,kCAAkC,CAAC;IAC5D;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IAElE;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC,CAAC;CACtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EAChE,UAAU,EAAE,MAAM,cAAc,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,qBAA0B,GAC/B,SAAS,CA6FX"}

package/dist/build-mcp.js

@@ -0,0 +1,113 @@
+/**
+ * buildMcpServer — register every shared handler on a fresh `McpServer`
+ * instance. One server per request (matches the hosted pattern); the
+ * `StreamableHTTPServerTransport` holds per-connection state so pooling
+ * isn't worth the locking.
+ *
+ * Output validation runs here via a zod object built from each handler's
+ * `outputSchema` raw shape. This enforces the ggui convention that every
+ * tool return advertises its shape — wire consumers can trust the output.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { installMcpAppsOutbound, } from './mcp-apps-outbound.js';
+/**
+ * Build a fresh MCP server with every handler registered.
+ *
+ * `getContext` is a late-binding accessor so the HTTP layer can thread
+ * per-request context (via AsyncLocalStorage or a closure) without
+ * leaking the shape into this module.
+ */
+export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
+    const server = new McpServer({
+        name: info.name,
+        version: info.version,
+        ...(info.description ? { description: info.description } : {}),
+        ...(opts.instructions ? { instructions: opts.instructions } : {}),
+    });
+    if (opts.mcpAppsOutbound) {
+        installMcpAppsOutbound(server, {
+            ...(opts.shellHtml !== undefined ? { shellHtml: opts.shellHtml } : {}),
+            ...(opts.selfContained !== undefined
+                ? { selfContained: opts.selfContained }
+                : {}),
+            ...(opts.publicBaseUrl !== undefined
+                ? { publicBaseUrl: opts.publicBaseUrl }
+                : {}),
+        });
+    }
+    // Per-request resource registrars supplied by the host. Run BEFORE
+    // tool registration so `tools/list` ordering is unaffected and any
+    // registrar-thrown error fails the request before tool dispatch.
+    if (opts.extraResources) {
+        for (const register of opts.extraResources) {
+            register(server);
+        }
+    }
+    const allowedKinds = opts.allowedKinds;
+    for (const handler of handlers) {
+        // Identity-kind gate. Skipping at registration time (rather than at
+        // call dispatch) means a curated deployment's `tools/list` reflects
+        // exactly what callers can use — no "ghost" tools that 401 on
+        // invocation. Handlers without `allowedFor` register regardless.
+        if (allowedKinds !== undefined
+            && handler.allowedFor !== undefined
+            && handler.allowedFor.length > 0
+            && !handler.allowedFor.some((kind) => allowedKinds.includes(kind))) {
+            continue;
+        }
+        server.registerTool(handler.name, {
+            ...(handler.title ? { title: handler.title } : {}),
+            description: handler.description,
+            inputSchema: handler.inputSchema,
+            outputSchema: handler.outputSchema,
+            // Forward declaration-level `_meta` (e.g. `_meta.ui.resourceUri`
+            // / `_meta.ui.visibility` stamped by the MCP Apps outbound path).
+            // Opaque to the transport — hosts consume it per their own spec.
+            ...(handler._meta ? { _meta: handler._meta } : {}),
+        }, async (input) => {
+            const ctx = getContext();
+            const start = Date.now();
+            try {
+                const data = await handler.handler(input, ctx);
+                const validated = z.object(handler.outputSchema).parse(data);
+                // Per-result `_meta` — NOT merged into structuredContent, so
+                // agents that typecheck against the tool signature never see
+                // it. This is where view-only bootstrap material lives.
+                const meta = await handler.resultMeta?.(data, input, ctx);
+                logger.info('tool_invoked', {
+                    tool: handler.name,
+                    appId: ctx.appId,
+                    outcome: 'success',
+                    elapsedMs: Date.now() - start,
+                });
+                return {
+                    structuredContent: validated,
+                    content: [
+                        { type: 'text', text: JSON.stringify(validated) },
+                    ],
+                    ...(meta !== undefined ? { _meta: meta } : {}),
+                };
+            }
+            catch (err) {
+                logger.warn('tool_invoked', {
+                    tool: handler.name,
+                    appId: ctx.appId,
+                    outcome: 'error',
+                    errorClass: errorClassName(err),
+                    elapsedMs: Date.now() - start,
+                });
+                throw err;
+            }
+        });
+    }
+    return server;
+}
+function errorClassName(err) {
+    if (err instanceof Error) {
+        if (err.name && err.name !== 'Error')
+            return err.name;
+        return err.constructor.name || 'Error';
+    }
+    return 'Unknown';
+}

package/dist/code-store-fs.d.ts

@@ -0,0 +1,19 @@
+import { type CodeStore } from '@ggui-ai/mcp-server-core';
+/** Options for {@link FileSystemCodeStore}. */
+export interface FileSystemCodeStoreOptions {
+    /**
+     * Filesystem root for the cache. Defaults to `~/.ggui/code-cache/`.
+     * Tests typically override to a project-local tmp dir.
+     */
+    readonly root?: string;
+}
+export declare class FileSystemCodeStore implements CodeStore {
+    private readonly root;
+    constructor(opts?: FileSystemCodeStoreOptions);
+    /** Absolute on-disk path for a given hash. Two-level sharded layout. */
+    private absPath;
+    put(hash: string, code: string): Promise<void>;
+    get(hash: string): Promise<string | null>;
+    hashOf(code: string): string;
+}
+//# sourceMappingURL=code-store-fs.d.ts.map

package/dist/code-store-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-store-fs.d.ts","sourceRoot":"","sources":["../src/code-store-fs.ts"],"names":[],"mappings":"AAmDA,OAAO,EAEL,KAAK,SAAS,EACf,MAAM,0BAA0B,CAAC;AAElC,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,mBAAoB,YAAW,SAAS;IACnD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,IAAI,GAAE,0BAA+B;IAIjD,wEAAwE;IACxE,OAAO,CAAC,OAAO;IAMT,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAU/C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAG7B"}