@ggui-ai/mcp-server 0.14.0 → 0.15.0

package/README.md

@@ -43,6 +43,26 @@ This package deliberately does **not** embed cloud-specific wiring (AWS, DynamoD
 Redis), and it does not implement authoring, pairing, or UI generation — those are
 separate packages and protocol flows.
 
+## TypeScript build
+
+### `tsc` under `moduleResolution: NodeNext` reports errors inside `node_modules/@modelcontextprotocol/ext-apps`
+
+Your own code is fine; the errors sit in a dependency's declarations. With `moduleResolution: "NodeNext"` (or `Node16`), `tsc` reports TS2834 and TS2339 inside `node_modules/@modelcontextprotocol/ext-apps/dist/src/app.d.ts`, and TS2305 / TS2460 on `@ggui-ai/protocol`'s `host-context.d.ts` for the three names it re-exports from there (`McpUiDisplayMode`, `McpUiHostContext`, `McpUiHostCapabilities`).
+
+**Cause.** `@modelcontextprotocol/ext-apps` 1.7.5 ships extensionless relative specifiers in its own `.d.ts` files — a defect in the published package, tracked upstream at [modelcontextprotocol/ext-apps#704](https://github.com/modelcontextprotocol/ext-apps/issues/704). `@ggui-ai/*` re-exports those names rather than forking a frozen spec surface, so the defect surfaces on our line. Every `@ggui-ai/*` declaration itself carries explicit `.js` extensions since 0.15.0.
+
+**Fix.** Until ext-apps ships the upstream fix, set the TypeScript switch for third-party declaration defects in your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "skipLibCheck": true
+  }
+}
+```
+
+`skipLibCheck` skips type-checking of `.d.ts` files only — your own sources still typecheck fully. The dependency bump follows the day the upstream fix is published; nothing in your code changes.
+
 ## License
 
 Apache-2.0

package/dist/mcp-endpoint-routes.d.ts

@@ -3,7 +3,7 @@
  *
  *   POST <universalMcpPath>            — DATA PLANE: agent+runtime tools
  *                                        (default `/mcp`)
- *   POST <pathPrefix>/:appId           — data plane, per-tenant variant
+ *   POST <pathPrefix>/:appId           — data plane, per-app variant
  *                                        (opt-in via `perAppRouting`)
  *   POST /control                      — CONTROL PLANE: design-time
  *                                        spec/discovery (anonymous) +
@@ -31,6 +31,7 @@
  * (`agent` / `runtime` / `protocol` / `ops`) and the wire-name prefix
  * rules.
  */
+import { type JsonValue } from "@ggui-ai/protocol";
 import type { AuthAdapter, AuthResult } from "@ggui-ai/mcp-server-core";
 import type { HandlerContext, SharedHandler } from "@ggui-ai/mcp-server-handlers";
 import type { Express } from "express";
@@ -39,7 +40,7 @@ import type { ZodRawShape } from "zod";
 import { type BuildMcpServerOptions, type ServerInfo } from "./build-mcp.js";
 import type { Logger } from "./logger.js";
 import type { McpService } from "./mcp-mounts.js";
-/** Per-tenant URL routing shape — mirrors `CreateGguiServerOptions.perAppRouting`. */
+/** Per-app URL routing shape — mirrors `CreateGguiServerOptions.perAppRouting`. */
 interface PerAppRouting {
     readonly paramName: string;
     readonly paramPattern: string;
@@ -61,6 +62,13 @@ export interface ErrorMapperResult {
     readonly message: string;
     /** Response headers to set before the JSON body is written. */
     readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * JSON-RPC 2.0 error `data` — any JSON value the deployment wants the
+     * client to read alongside `code` / `message` (a structured reason, a
+     * retry hint). Serialized verbatim on `error.data`; omitted from the
+     * body when absent, so a mapper that never sets it changes nothing.
+     */
+    readonly data?: JsonValue;
 }
 interface MountOptions {
     /** Express app to mount onto. */
@@ -92,9 +100,9 @@ interface MountOptions {
     readonly als: AsyncLocalStorage<HandlerContext>;
     /** Identity → appId resolution rule (SPEC §12.2). */
     readonly appIdFromIdentity: (result: AuthResult) => string;
-    /** Universal endpoint path (default `/mcp`; cloud overrides to `/`). */
+    /** Universal endpoint path (default `/mcp`; a deployment may serve it at `/`). */
     readonly universalMcpPath: string;
-    /** Per-tenant endpoint shape — absent = universal-only deployment. */
+    /** Per-app endpoint shape — absent = universal-only deployment. */
     readonly perAppRouting?: PerAppRouting;
     /** Whether OAuth is enabled (adds `WWW-Authenticate` on 401). */
     readonly oauthEnabled: boolean;

package/dist/mcp-endpoint-routes.d.ts.map

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

package/dist/mcp-endpoint-routes.js

@@ -3,7 +3,7 @@
  *
  *   POST <universalMcpPath>            — DATA PLANE: agent+runtime tools
  *                                        (default `/mcp`)
- *   POST <pathPrefix>/:appId           — data plane, per-tenant variant
+ *   POST <pathPrefix>/:appId           — data plane, per-app variant
  *                                        (opt-in via `perAppRouting`)
  *   POST /control                      — CONTROL PLANE: design-time
  *                                        spec/discovery (anonymous) +
@@ -31,13 +31,50 @@
  * (`agent` / `runtime` / `protocol` / `ops`) and the wire-name prefix
  * rules.
  */
-import { isRecord } from "@ggui-ai/protocol";
+import { MCP_ERROR_CODES, isRecord } from "@ggui-ai/protocol";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { randomUUID } from "node:crypto";
 import { resolveIdentity, UnauthenticatedError } from "./auth.js";
 import { buildMcpServer } from "./build-mcp.js";
 import { CONTROL_PATH, DATA_PLANE_AUDIENCES, filterHandlersByAudience, } from "./control-service.js";
 import { buildWwwAuthenticate, resolveIssuerUrl } from "./oauth.js";
+/** The JSON-RPC error object a mapped result becomes on the wire. */
+function jsonRpcError(mapped) {
+    return {
+        code: mapped.code,
+        message: mapped.message,
+        ...(mapped.data !== undefined ? { data: mapped.data } : {}),
+    };
+}
+/** The two statuses an authorization refusal may carry — a mapper is bounded to them. */
+const AUTHORIZATION_REFUSAL_STATUSES = new Set([401, 403]);
+/**
+ * A deployment's error mapper may attach JSON-RPC `data` (and its own
+ * `code` / `message` / headers) to a per-app authorization refusal, so a
+ * client can read a structured reason instead of parsing prose. The
+ * refusal stays a 401 or a 403: a mapper answering any other status, or
+ * throwing, is ignored and logged, and the default-deny 403 stands
+ * byte-identical to a deployment with no mapper at all.
+ */
+function mapAuthorizationRefusal(err, errorMapper, log) {
+    if (!errorMapper)
+        return undefined;
+    let mapped;
+    try {
+        mapped = errorMapper(err);
+    }
+    catch (mapperErr) {
+        log.warn("error_mapper_failed", { error: String(mapperErr) });
+        return undefined;
+    }
+    if (mapped === undefined)
+        return undefined;
+    if (!AUTHORIZATION_REFUSAL_STATUSES.has(mapped.status)) {
+        log.warn("per_app_authorize_mapper_out_of_bounds", { status: mapped.status });
+        return undefined;
+    }
+    return mapped;
+}
 /**
  * Resolve the resource path that `WWW-Authenticate` should point at
  * for the current request. Per-app `/mcp` requests
@@ -113,7 +150,7 @@ export function mountMcpEndpoints(opts) {
                     identity = { identity: { kind: "builder" }, source: "anonymous" };
                 }
                 else {
-                    // Diagnostic: did a Bearer credential actually reach the pod on
+                    // Diagnostic: did a Bearer credential actually reach the server on
                     // this request? This splits "the client/transport never sent one"
                     // from "we received it but the adapter rejected it" — otherwise
                     // indistinguishable in `auth_failed`. Only a short, non-secret
@@ -145,7 +182,7 @@ export function mountMcpEndpoints(opts) {
                     }
                     res.status(401).json({
                         jsonrpc: "2.0",
-                        error: { code: -32000, message: err.message },
+                        error: { code: MCP_ERROR_CODES.UNAUTHORIZED, message: err.message },
                         id: null,
                     });
                     return;
@@ -171,7 +208,10 @@ export function mountMcpEndpoints(opts) {
             reqLogger.warn("federated_identity_rejected", { route: req.path });
             res.status(403).json({
                 jsonrpc: "2.0",
-                error: { code: -32000, message: "federated identities are not permitted on this route" },
+                error: {
+                    code: MCP_ERROR_CODES.UNAUTHORIZED,
+                    message: "federated identities are not permitted on this route",
+                },
                 id: null,
             });
             return;
@@ -196,7 +236,7 @@ export function mountMcpEndpoints(opts) {
                 res.status(401).json({
                     jsonrpc: "2.0",
                     error: {
-                        code: -32000,
+                        code: MCP_ERROR_CODES.UNAUTHORIZED,
                         message: `${opsToolName} is an operator tool and needs an authenticated caller. ` +
                             `Present a bearer token this deployment accepts, or complete the OAuth flow ` +
                             `advertised in WWW-Authenticate (universal connector keys come from the ` +
@@ -207,10 +247,10 @@ export function mountMcpEndpoints(opts) {
                 return;
             }
         }
-        // Per-tenant URL routing. When `perAppRouting`
+        // Per-app URL routing. When `perAppRouting`
         // is configured AND the request matched the per-app path
         // `/:${paramName}/mcp`, Express populates `req.params[paramName]`
-        // with the validated tenant id. Use it as `ctx.appId` for this
+        // with the validated app id. Use it as `ctx.appId` for this
         // request, overriding `appIdFromIdentity`. The universal `/mcp`
         // route doesn't have the param so it falls through to the
         // identity-based resolution.
@@ -218,11 +258,14 @@ export function mountMcpEndpoints(opts) {
         const hasUrlAppId = typeof urlAppId === "string" && urlAppId.length > 0;
         // Per-app authorize hook — when the deployment configured
         // `perAppRouting.authorize` AND the request matched the per-app
-        // path, invoke the callback. Throwing collapses to a 403 before
-        // the MCP handler ever sees the request, which is the boundary
-        // that prevents cross-user blueprint reads when pod tools bypass
+        // path, invoke the callback. Throwing refuses before the MCP
+        // handler ever sees the request, which is the boundary that
+        // prevents cross-user blueprint reads when a deployment's own tools bypass
         // AppSync owner-auth via raw DDB. Universal-endpoint requests
-        // skip this entirely (no urlAppId).
+        // skip this entirely (no urlAppId). The deployment's `errorMapper`
+        // may give the refusal a structured JSON-RPC `data` (bounded to
+        // 401 / 403, see `mapAuthorizationRefusal`); otherwise — and for
+        // every mapping outside those bounds — the default-deny 403 stands.
         if (hasUrlAppId && perAppRouting?.authorize) {
             try {
                 await perAppRouting.authorize(urlAppId, identity);
@@ -232,9 +275,17 @@ export function mountMcpEndpoints(opts) {
                     urlAppId,
                     reason: err instanceof Error ? err.message : String(err),
                 });
-                res.status(403).json({
+                const mapped = mapAuthorizationRefusal(err, errorMapper, reqLogger);
+                if (mapped?.headers)
+                    res.set(mapped.headers);
+                res.status(mapped?.status ?? 403).json({
                     jsonrpc: "2.0",
-                    error: { code: -32000, message: "Forbidden" },
+                    // #836: a first-party server never answers -32000 — that is the SDK
+                    // client's own ConnectionClosed number, so a refusal and a dropped
+                    // socket would read the same. An authorization refusal is UNAUTHORIZED.
+                    error: mapped
+                        ? jsonRpcError(mapped)
+                        : { code: MCP_ERROR_CODES.UNAUTHORIZED, message: "Unauthorized" },
                     id: null,
                 });
                 return;
@@ -248,11 +299,11 @@ export function mountMcpEndpoints(opts) {
             // handler should branch on the specific mechanism.
             authSource: identity.source,
             // Identity is the canonical source of two mutually-exclusive
-            // hosted fields: `apiKeyHash` for kind=app, `userId` for kind=user.
-            // Threading them onto HandlerContext here means hosted handlers
-            // (the K8s ggui-protocol pod's billing gate + per-user blueprint
-            // scoping) can read identity directly without a parallel pod-only
-            // context shape; OSS handlers continue to ignore both fields.
+            // fields: `apiKeyHash` for kind=app, `userId` for kind=user.
+            // Threading them onto HandlerContext here means a deployment's own
+            // handlers (per-key metering, per-user scoping) can read identity
+            // directly without a parallel context shape; the handlers this
+            // package ships ignore both fields.
             ...(identity.identity.kind === "app" ? { apiKeyHash: identity.identity.apiKeyHash } : {}),
             ...(identity.identity.kind === "user" ? { userId: identity.identity.userId } : {}),
             // What the credential itself may act on, when the adapter
@@ -301,7 +352,7 @@ export function mountMcpEndpoints(opts) {
                         res.set(mapped.headers);
                     res.status(mapped.status).json({
                         jsonrpc: "2.0",
-                        error: { code: mapped.code, message: mapped.message },
+                        error: jsonRpcError(mapped),
                         id: null,
                     });
                 }
@@ -316,7 +367,9 @@ export function mountMcpEndpoints(opts) {
         }
     };
     const methodNotAllowed = (_req, res) => {
-        res.status(405).json({
+        // A 405 names what IS allowed (RFC 9110 §15.5.6); every mount here is
+        // POST-only.
+        res.set("Allow", "POST").status(405).json({
             jsonrpc: "2.0",
             error: {
                 code: -32000,
@@ -341,24 +394,24 @@ export function mountMcpEndpoints(opts) {
         anonymousOpsChallenge: controlOpsToolNames,
     });
     // Universal endpoint — `appId` resolved from the auth identity via
-    // `appIdFromIdentity`. Cloud `mcp.ggui.ai` deployments resolve this
-    // to `User.defaultAppId` via the auth-adapter; OSS deployments fall
-    // through to userId / DEFAULT_BUILDER_APP_ID.
+    // `appIdFromIdentity`. A deployment's auth adapter may resolve it
+    // (e.g. to the user's default app); without one it falls through to
+    // userId / DEFAULT_BUILDER_APP_ID.
     //
-    // Path defaults to `/mcp` (Streamable HTTP convention). Cloud
-    // `mcp.ggui.ai` overrides to `/` so the bare-root URL is the
-    // universal endpoint — domain already says "mcp", no path repeat.
+    // Path defaults to `/mcp` (Streamable HTTP convention). A deployment
+    // whose hostname already says "mcp" may serve it at `/` so the
+    // bare-root URL is the universal endpoint — no path repeat.
     // Exposes audience tags ['agent', 'runtime'] — runtime tools stay
     // routable on the same endpoint but invisible to the agent's
     // `tools/list` via the `_meta.ui.visibility: ['app']` filter.
     app.post(universalMcpPath, agentMcpHandler);
-    // Per-tenant endpoint — only mounted when the deployment opts in
+    // Per-app endpoint — only mounted when the deployment opts in
     // via `perAppRouting`. The same handler reads `req.params[paramName]`
     // and uses it as `ctx.appId` for the request.
     //
     // When `pathPrefix` is set, the route mounts at
-    // `${pathPrefix}/:${paramName}` — cloud uses `/apps` so URLs are
-    // `mcp.ggui.ai/apps/<appId>`. The prefix segments per-tenant traffic
+    // `${pathPrefix}/:${paramName}` — e.g. `/apps`, so URLs read
+    // `<host>/apps/<appId>`. The prefix segments per-app traffic
     // from system routes (`/health`, `/oauth/*`, `/.well-known/*`,
     // `/r/*`) so an opaque appId can never shadow a future static path.
     //
@@ -386,6 +439,12 @@ export function mountMcpEndpoints(opts) {
         });
         const route = pathPrefix !== undefined ? `${pathPrefix}/:${paramName}` : `/:${paramName}`;
         app.post(route, agentMcpHandler);
+        // The per-app endpoint is POST-only like every other mount: GET (a
+        // client's optional SSE listener) and DELETE (session terminate) read
+        // the transport's 405, never Express's text/html 404 — a 404 says "no
+        // such resource" and a client retries it every turn (ggui#850).
+        app.get(route, methodNotAllowed);
+        app.delete(route, methodNotAllowed);
     }
     // /control — the control plane. Hosts every `audience: ['protocol']`
     // tool (design-time spec/discovery, anonymous) and every

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/mcp-server",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Self-hosted MCP server for the ggui protocol. An HTTP/MCP binding layer over @ggui-ai/mcp-server-handlers and the reference adapters from @ggui-ai/mcp-server-core — run it via `ggui serve`.",
   "keywords": [
     "ggui",
@@ -32,17 +32,17 @@
     "resend": "^6.12.2",
     "ws": "^8.20.1",
     "zod": "^4.3.6",
-    "@ggui-ai/console": "0.14.0",
-    "@ggui-ai/design": "0.14.0",
-    "@ggui-ai/iframe-runtime": "0.14.0",
-    "@ggui-ai/mcp-server-handlers": "0.14.0",
-    "@ggui-ai/mcp-server-core": "0.14.0",
-    "@ggui-ai/negotiator": "0.14.0",
-    "@ggui-ai/preview-a2ui": "0.14.0",
-    "@ggui-ai/project-config": "0.14.0",
-    "@ggui-ai/protocol": "0.14.0",
-    "@ggui-ai/ui-registry": "0.14.0",
-    "@ggui-ai/ui-gen": "0.14.0"
+    "@ggui-ai/console": "0.15.0",
+    "@ggui-ai/design": "0.15.0",
+    "@ggui-ai/mcp-server-handlers": "0.15.0",
+    "@ggui-ai/iframe-runtime": "0.15.0",
+    "@ggui-ai/mcp-server-core": "0.15.0",
+    "@ggui-ai/negotiator": "0.15.0",
+    "@ggui-ai/preview-a2ui": "0.15.0",
+    "@ggui-ai/project-config": "0.15.0",
+    "@ggui-ai/protocol": "0.15.0",
+    "@ggui-ai/ui-registry": "0.15.0",
+    "@ggui-ai/ui-gen": "0.15.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
@@ -51,7 +51,7 @@
     "@types/ws": "^8.5.10",
     "typescript": "^5.0.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/protocol-conformance": "0.14.0"
+    "@ggui-ai/protocol-conformance": "0.15.0"
   },
   "repository": {
     "type": "git",