@mcp-layer/schema 1.0.3 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @mcp-layer/schema
 
-`@mcp-layer/schema` extracts MCP server definitions (tools, resources, prompts, templates, and MCP Apps metadata) and normalizes them into a unified Zod-backed schema. The output is designed for downstream generators that need a single contract to build CLIs, REST endpoints, UI renderers, or additional MCP layers without re-parsing the MCP protocol surface.
+`@mcp-layer/schema` extracts MCP server definitions (tools, resources, prompts, templates, and MCP Apps metadata) and normalizes them into a unified schema backed by Zod 4. The output is designed for downstream generators that need a single contract to build CLIs, REST endpoints, UI renderers, or additional MCP layers without re-parsing the MCP protocol surface.
 
 ## Table of Contents
 
@@ -11,6 +11,7 @@
 - [MCP Apps support](#mcp-apps-support)
 - [Generator guidance](#generator-guidance)
 - [Responsibilities and lifecycle](#responsibilities-and-lifecycle)
+- [API Reference](#api-reference)
 - [Error handling](#error-handling)
 - [JSON Schema vs Zod](#json-schema-vs-zod)
 - [Runtime Error Reference](#runtime-error-reference)
@@ -30,7 +31,7 @@ yarn add @mcp-layer/schema
 ```js
 import { load } from '@mcp-layer/config';
 import { connect } from '@mcp-layer/connect';
-import { extract } from '@mcp-layer/schema';
+import { composeCatalog, extract } from '@mcp-layer/schema';
 
 const config = await load(undefined, process.cwd());
 const session = await connect(config, 'demo');
@@ -39,15 +40,37 @@ const output = await extract(session);
 console.log(output.server.info);
 console.log(output.items[0]);
 await session.close();
+
+const catalog = composeCatalog({
+  server: {
+    info: { name: 'demo', version: '1.0.0' },
+    capabilities: { tools: {} },
+    instructions: 'Use the local catalog.',
+  },
+  tools: [{
+    name: 'echo',
+    description: 'Echo text.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string' },
+      },
+      required: ['text'],
+    },
+  }],
+});
+
+console.log(catalog.items[0]);
 ```
 
 ## What this package does
 
-1) Reads the MCP server capabilities and metadata from the live client connection.
+1) Reads the MCP server capabilities and metadata from the live client connection with `extract(session)`.
 2) Calls MCP list endpoints (`tools/list`, `resources/list`, `resources/templates/list`, `prompts/list`) using pagination.
-3) Normalizes everything into a unified, type-discriminated schema so generators can consume a single list.
-4) Wraps tool input/output JSON Schemas into Zod validators backed by Ajv, while preserving the original JSON Schema.
-5) Converts prompt arguments into a lightweight JSON Schema so prompts and tools share the same `detail.input` shape.
+3) Composes the same normalized catalog shape from raw definitions with `composeCatalog(...)` when a live session is not available yet.
+4) Normalizes everything into a unified, type-discriminated schema so generators can consume a single list.
+5) Wraps tool input/output JSON Schemas into Zod validators backed by Ajv, while preserving the original JSON Schema.
+6) Converts prompt arguments into a lightweight JSON Schema so prompts and tools share the same `detail.input` shape.
 
 ## Output shape (authoritative)
 
@@ -82,7 +105,7 @@ Type discriminator:
 ```js
 detail: {
   input: {
-    schema, // Zod schema (Ajv-backed)
+    schema, // Zod 4 schema (Ajv-backed)
     json,   // original JSON Schema
     error   // optional Ajv compile error message
   },
@@ -143,10 +166,30 @@ Suggested uses for the unified schema:
 
 ## Responsibilities and lifecycle
 
-- This package does not open or close connections. It expects a live `Session` from `@mcp-layer/connect` or `@mcp-layer/attach`.
+- `extract(session)` does not open or close connections. It expects a live `Session` from `@mcp-layer/connect` or `@mcp-layer/attach`.
 - You are responsible for calling `session.close()` after extraction.
+- `composeCatalog(...)` is pure and does not require a connection.
 - If the server doesn't advertise a capability (tools/resources/prompts), extraction skips that surface.
 
+## API Reference
+
+### `composeCatalog(input = {})`
+
+Build a catalog from MCP data that is already available. This function does not connect to a server.
+
+- **Input:** an optional `server` object with `info`, `capabilities`, and `instructions`, plus optional `tools`, `resources`, `templates`, and `prompts` arrays.
+- **Result:** `{ server, items }`. Missing values become `undefined` or add no items. Tool input and output schemas use Zod 4 and Ajv.
+- **Errors:** Ajv compile errors appear in the item's `error` field. This function does not make MCP calls.
+
+### `extract(session)`
+
+Read a catalog from an active `Session`.
+
+- **Input:** a connected `Session` from `@mcp-layer/connect` or `@mcp-layer/attach`.
+- **Result:** `Promise<{ server, items }>` with the same shape as `composeCatalog`.
+- **Errors:** if `session.client` is missing, this function throws `LayerError` with reference `error-49ae61`. It passes MCP call errors to the caller.
+- **Lifecycle:** this function does not close the session.
+
 ## Error handling
 
 - Schema compilation uses Ajv under the hood. If a tool exposes an invalid JSON Schema, extraction still succeeds but `detail.input.error` or `detail.output.error` will be populated for that item.
@@ -155,7 +198,7 @@ Suggested uses for the unified schema:
 
 ## JSON Schema vs Zod
 
-Zod validators are produced to allow direct runtime validation, but the original JSON Schema is preserved in `detail.input.json` and `detail.output.json` so generators can emit OpenAPI, JSON Schema, or other schema formats without losing fidelity.
+The `schema` field contains a Zod 4 validator backed by Ajv. Call `.parse()` or `.safeParse()` to validate data. The original JSON Schema stays in `detail.input.json` and `detail.output.json` for generators that need OpenAPI, JSON Schema, or another schema format.
 
 ## Runtime Error Reference
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-layer/schema",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "description": "Extract and normalize MCP schemas into a unified Zod-based format.",
   "repository": {
     "type": "git",
@@ -34,12 +34,12 @@
     "access": "public"
   },
   "dependencies": {
-    "ajv": "^8.17.1",
-    "zod": "^3.25.76",
+    "ajv": "^8.20.0",
+    "zod": "^4.6.7",
     "@mcp-layer/error": "0.2.1"
   },
   "devDependencies": {
-    "@mcp-layer/attach": "1.1.2",
+    "@mcp-layer/attach": "1.2.0",
     "@mcp-layer/config": "1.0.2",
     "@mcp-layer/connect": "1.2.1",
     "@mcp-layer/test-server": "1.0.4"

package/src/index.js

@@ -416,6 +416,45 @@ function normalize(data) {
   return list;
 }
 
+/**
+ * Derive advertised capabilities from the provided raw MCP definition sets.
+ * @param {{ tools?: Array<Record<string, unknown>>, resources?: Array<Record<string, unknown>>, templates?: Array<Record<string, unknown>>, prompts?: Array<Record<string, unknown>> }} data - Raw MCP definition sets.
+ * @returns {Record<string, unknown> | undefined}
+ */
+function capabilities(data) {
+  const caps = {};
+
+  if (Array.isArray(data.tools)) caps.tools = {};
+  if (Array.isArray(data.resources) || Array.isArray(data.templates)) caps.resources = {};
+  if (Array.isArray(data.prompts)) caps.prompts = {};
+
+  return Object.keys(caps).length > 0 ? caps : undefined;
+}
+
+/**
+ * Compose a unified catalog from raw MCP definitions without a live session.
+ * This lets adapters bootstrap routes from already-known tool/resource shapes
+ * while keeping the output identical to `extract(session)`.
+ *
+ * @param {{ server?: { info?: Record<string, unknown>, capabilities?: Record<string, unknown>, instructions?: string }, tools?: Array<Record<string, unknown>>, resources?: Array<Record<string, unknown>>, templates?: Array<Record<string, unknown>>, prompts?: Array<Record<string, unknown>> }} input - Raw server metadata and MCP definitions.
+ * @returns {{ server: { info: Record<string, unknown> | undefined, capabilities: Record<string, unknown> | undefined, instructions: string | undefined }, items: Array<Record<string, unknown>> }}
+ */
+export function composeCatalog(input = {}) {
+  const server = isrecord(input.server) ? input.server : {};
+  const info = isrecord(server.info) ? server.info : undefined;
+  const caps = isrecord(server.capabilities) ? server.capabilities : capabilities(input);
+  const instructions = typeof server.instructions === 'string' ? server.instructions : undefined;
+
+  return {
+    server: {
+      info,
+      capabilities: caps,
+      instructions,
+    },
+    items: normalize(input),
+  };
+}
+
 /**
  * Extract MCP tool/resource/prompt schemas into a unified Zod-backed format.
  * @param {import('@mcp-layer/session').Session} link - Active session with a connected MCP server.
@@ -451,14 +490,12 @@ export async function extract(link) {
 
   if (caps && caps.prompts) data.prompts = await prompts(client);
 
-  const items = normalize(data);
-
-  return {
+  return composeCatalog({
     server: {
       info,
       capabilities: caps,
-      instructions
+      instructions,
     },
-    items
-  };
+    ...data,
+  });
 }

package/types/index.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Compose a unified catalog from raw MCP definitions without a live session.
+ * This lets adapters bootstrap routes from already-known tool/resource shapes
+ * while keeping the output identical to `extract(session)`.
+ *
+ * @param {{ server?: { info?: Record<string, unknown>, capabilities?: Record<string, unknown>, instructions?: string }, tools?: Array<Record<string, unknown>>, resources?: Array<Record<string, unknown>>, templates?: Array<Record<string, unknown>>, prompts?: Array<Record<string, unknown>> }} input - Raw server metadata and MCP definitions.
+ * @returns {{ server: { info: Record<string, unknown> | undefined, capabilities: Record<string, unknown> | undefined, instructions: string | undefined }, items: Array<Record<string, unknown>> }}
+ */
+export function composeCatalog(input?: {
+    server?: {
+        info?: Record<string, unknown>;
+        capabilities?: Record<string, unknown>;
+        instructions?: string;
+    };
+    tools?: Array<Record<string, unknown>>;
+    resources?: Array<Record<string, unknown>>;
+    templates?: Array<Record<string, unknown>>;
+    prompts?: Array<Record<string, unknown>>;
+}): {
+    server: {
+        info: Record<string, unknown> | undefined;
+        capabilities: Record<string, unknown> | undefined;
+        instructions: string | undefined;
+    };
+    items: Array<Record<string, unknown>>;
+};
 /**
  * Extract MCP tool/resource/prompt schemas into a unified Zod-backed format.
  * @param {import('@mcp-layer/session').Session} link - Active session with a connected MCP server.