@mcp-layer/graphql 0.2.0 → 0.2.2

package/README.md

@@ -88,8 +88,9 @@ Options:
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `session` | `Session` or `Session[]` | required | Bootstrap session(s) used for catalog extraction and static mode. |
-| `manager` | `{ get(request), close?() }` | optional | Per-request session manager (requires bootstrap `session`). |
+| `session` | `Session` or `Session[]` | required unless using `manager` + `catalog` | Bootstrap session(s) used for catalog extraction and static mode. |
+| `catalog` | `{ server?, items? }` | optional | Precomputed bootstrap catalog used when the live session should only be resolved lazily. |
+| `manager` | `{ get(request), close?() }` | optional | Per-request session manager (requires bootstrap `session` or `catalog`). |
 | `prefix` | `string` or `(version, info, name) => string` | derived | Per-session route prefix. |
 | `endpoint` | `string` | `"/graphql"` | GraphQL POST endpoint path under prefix. |
 | `ide.enabled` | `boolean` | `false` | Enables GraphiQL route. |
@@ -599,7 +600,7 @@ Thrown from: `validateRuntimeOptions` (via `@mcp-layer/gateway`)
 This happens when `manager` is provided while `session` is an array.
 
 Step-by-step resolution:
-1. In manager mode, pass one bootstrap `session`.
+1. In manager mode, pass one bootstrap `session` or one bootstrap `catalog`.
 2. For multi-session static mounts, remove `manager`.
 3. Register separate plugin instances per static session surface.
 4. Add startup tests for both architecture modes.
@@ -618,20 +619,20 @@ await fastify.register(mcpGraphql, {
 
 </details>
 
-<a id="error-126799"></a>
-### `session is required when manager is provided (used for catalog bootstrap).`
+<a id="error-aae9b3"></a>
+### `session or catalog is required when manager is provided (used for catalog bootstrap).`
 
 Thrown from: `validateRuntimeOptions` (via `@mcp-layer/gateway`)
 
-This happens when `manager` is configured without a bootstrap `session`.
+This happens when `manager` is configured without a bootstrap `session` or `catalog`.
 
 Step-by-step resolution:
-1. Always provide a bootstrap `session` with `manager`.
-2. Ensure bootstrap session is connected before registration.
+1. Always provide a bootstrap `session` or `catalog` with `manager`.
+2. Ensure the bootstrap session is connected before registration, or ensure the bootstrap catalog matches the managed session surface.
 3. Keep bootstrap and managed sessions aligned in capability surface.
-4. Add tests that fail fast without bootstrap session.
+4. Add tests that fail fast without bootstrap metadata.
 
-Canonical gateway reference: [`@mcp-layer/gateway` runtime errors](../gateway/README.md#error-c773d9).
+Canonical gateway reference: [`@mcp-layer/gateway` runtime errors](../gateway/README.md#error-b010d3).
 
 <details>
 <summary>Fix Example: include bootstrap session in manager mode</summary>
@@ -645,6 +646,50 @@ await fastify.register(mcpGraphql, {
 
 </details>
 
+<details>
+<summary>Fix Example: include bootstrap catalog in manager mode</summary>
+
+```js
+await fastify.register(mcpGraphql, {
+  catalog,
+  manager
+});
+```
+
+</details>
+
+<a id="error-f184e1"></a>
+### `catalog must be an object.`
+
+Thrown from: `validateRuntimeOptions` (via `@mcp-layer/gateway`)
+
+This happens when `catalog` is passed as a primitive, array, or serialized payload instead of the composed catalog object the GraphQL plugin expects at bootstrap.
+
+Step-by-step resolution:
+1. Pass the bootstrap catalog as a plain object.
+2. Do not pass stringified JSON or only the `items` array.
+3. Ensure the object shape matches the extracted/composed catalog surface.
+4. Add registration tests that reject malformed catalog bootstrap values.
+
+Canonical gateway reference: [`@mcp-layer/gateway` runtime errors](../gateway/README.md#error-17712f).
+
+<details>
+<summary>Fix Example: provide bootstrap catalog as an object</summary>
+
+```js
+await fastify.register(mcpGraphql, {
+  catalog: {
+    server: {
+      info: { name: 'example-server', version: '1.0.0' }
+    },
+    items: []
+  },
+  manager
+});
+```
+
+</details>
+
 <a id="error-66da32"></a>
 ### `session or manager option is required.`
 
@@ -654,7 +699,7 @@ This happens when plugin options omit both `session` and `manager`.
 
 Step-by-step resolution:
 1. Pass a connected `session` for static mode.
-2. Or pass `manager` plus bootstrap `session` for dynamic mode.
+2. Or pass `manager` plus bootstrap `session` or `catalog` for dynamic mode.
 3. Assert required options before `register`.
 4. Add tests that validate registration failure on missing session source.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-layer/graphql",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Fastify GraphQL plugin and schema builder for MCP catalogs with shared gateway runtime primitives.",
   "repository": {
     "type": "git",
@@ -18,8 +18,10 @@
     "gateway"
   ],
   "main": "src/index.js",
+  "types": "./types/index.d.ts",
   "exports": {
     ".": {
+      "types": "./types/index.d.ts",
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
@@ -27,6 +29,7 @@
   },
   "files": [
     "src",
+    "types",
     "LICENSE"
   ],
   "publishConfig": {
@@ -39,19 +42,20 @@
     "graphql-type-json": "^0.3.2",
     "mercurius": "^16.7.0",
     "uri-template": "^2.0.0",
-    "@mcp-layer/error": "0.2.0",
-    "@mcp-layer/gateway": "0.2.0"
+    "@mcp-layer/error": "0.2.1",
+    "@mcp-layer/gateway": "0.2.2"
   },
   "peerDependencies": {
     "fastify": "^5.0.0"
   },
   "devDependencies": {
     "fastify": "^5.7.4",
-    "@mcp-layer/attach": "1.1.1",
-    "@mcp-layer/manager": "0.2.0",
-    "@mcp-layer/test-server": "1.0.1"
+    "@mcp-layer/attach": "1.1.2",
+    "@mcp-layer/manager": "0.2.1",
+    "@mcp-layer/test-server": "1.0.4"
   },
   "scripts": {
-    "test": "node --test --experimental-test-coverage ./test/**/*.test.js"
+    "build:types": "tsc -p tsconfig.json",
+    "test": "node --test --experimental-test-coverage \"./test/**/*.test.js\""
   }
 }

package/types/config/defaults.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Default configuration values for the GraphQL plugin.
+ * @type {{ prefix: string | undefined, validation: { trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }, resilience: { enabled: boolean, timeout: number, errorThresholdPercentage: number, resetTimeout: number, volumeThreshold: number }, telemetry: { enabled: boolean, serviceName: string, metricPrefix: string, api?: import('@opentelemetry/api') }, errors: { exposeDetails: boolean }, endpoint: string, ide: { enabled: boolean, path: string }, operations: { generated: boolean, generic: boolean } }}
+ */
+export const DEFAULTS: {
+    prefix: string | undefined;
+    validation: {
+        trustSchemas: "auto" | true | false;
+        maxSchemaDepth: number;
+        maxSchemaSize: number;
+        maxPatternLength: number;
+        maxToolNameLength: number;
+        maxTemplateParamLength: number;
+    };
+    resilience: {
+        enabled: boolean;
+        timeout: number;
+        errorThresholdPercentage: number;
+        resetTimeout: number;
+        volumeThreshold: number;
+    };
+    telemetry: {
+        enabled: boolean;
+        serviceName: string;
+        metricPrefix: string;
+        api?: any;
+    };
+    errors: {
+        exposeDetails: boolean;
+    };
+    endpoint: string;
+    ide: {
+        enabled: boolean;
+        path: string;
+    };
+    operations: {
+        generated: boolean;
+        generic: boolean;
+    };
+};

package/types/config/validate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Validate GraphQL adapter options.
+ * @param {Record<string, unknown>} opts - User options.
+ * @returns {{ session: unknown, manager?: { get: (request: import('fastify').FastifyRequest) => Promise<import('@mcp-layer/session').Session>, close?: () => Promise<void> }, prefix?: string | ((version: string, info: Record<string, unknown> | undefined, name: string) => string), validation: { trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }, resilience: { enabled: boolean, timeout: number, errorThresholdPercentage: number, resetTimeout: number, volumeThreshold: number }, telemetry: { enabled: boolean, serviceName: string, metricPrefix: string, api?: import('@opentelemetry/api') }, errors: { exposeDetails: boolean }, endpoint: string, ide: { enabled: boolean, path: string }, operations: { generated: boolean, generic: boolean } }}
+ */
+export function validateOptions(opts: Record<string, unknown>): {
+    session: unknown;
+    manager?: {
+        get: (request: import("fastify").FastifyRequest) => Promise<any>;
+        close?: () => Promise<void>;
+    };
+    prefix?: string | ((version: string, info: Record<string, unknown> | undefined, name: string) => string);
+    validation: {
+        trustSchemas: "auto" | true | false;
+        maxSchemaDepth: number;
+        maxSchemaSize: number;
+        maxPatternLength: number;
+        maxToolNameLength: number;
+        maxTemplateParamLength: number;
+    };
+    resilience: {
+        enabled: boolean;
+        timeout: number;
+        errorThresholdPercentage: number;
+        resetTimeout: number;
+        volumeThreshold: number;
+    };
+    telemetry: {
+        enabled: boolean;
+        serviceName: string;
+        metricPrefix: string;
+        api?: any;
+    };
+    errors: {
+        exposeDetails: boolean;
+    };
+    endpoint: string;
+    ide: {
+        enabled: boolean;
+        path: string;
+    };
+    operations: {
+        generated: boolean;
+        generic: boolean;
+    };
+};

package/types/index.d.ts

@@ -0,0 +1,3 @@
+export { schema } from "./schema.js";
+export { map } from "./mapping.js";
+export { default, plugin } from "./plugin.js";

package/types/mapping.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Build deterministic GraphQL mapping metadata from a catalog.
+ * @param {{ items?: Array<Record<string, unknown>> }} catalog - Extracted catalog.
+ * @param {Record<string, unknown>} [options] - Reserved for future mapping customization.
+ * @returns {ReturnType<typeof createMap>}
+ */
+export function map(catalog: {
+    items?: Array<Record<string, unknown>>;
+}, options?: Record<string, unknown>): ReturnType<typeof createMap>;
+import { createMap } from '@mcp-layer/gateway';

package/types/plugin.d.ts

@@ -0,0 +1,8 @@
+export default plugin;
+/**
+ * Fastify plugin that exposes MCP sessions as GraphQL endpoints.
+ * @param {import('fastify').FastifyInstance} fastify - Fastify instance.
+ * @param {Record<string, unknown>} opts - Plugin options.
+ * @returns {Promise<void>}
+ */
+export function plugin(fastify: import("fastify").FastifyInstance, opts: Record<string, unknown>): Promise<void>;

package/types/schema.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Build an executable GraphQL schema from an MCP catalog.
+ * @param {{ items?: Array<Record<string, unknown>> }} catalog - Extracted catalog.
+ * @param {{ operations?: { generated?: boolean, generic?: boolean } }} [options] - Build options.
+ * @returns {{ schema: import('graphql').GraphQLSchema, typeDefs: string, resolvers: Record<string, unknown>, mapping: ReturnType<typeof map> }}
+ */
+export function schema(catalog?: {
+    items?: Array<Record<string, unknown>>;
+}, options?: {
+    operations?: {
+        generated?: boolean;
+        generic?: boolean;
+    };
+}): {
+    schema: import("graphql").GraphQLSchema;
+    typeDefs: string;
+    resolvers: Record<string, unknown>;
+    mapping: ReturnType<typeof map>;
+};
+import { map } from './mapping.js';