@mcp-layer/schema 1.0.0 → 1.0.2

package/README.md

@@ -2,6 +2,19 @@
 
 `@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.
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [What this package does](#what-this-package-does)
+- [Output shape (authoritative)](#output-shape-authoritative)
+- [MCP Apps support](#mcp-apps-support)
+- [Generator guidance](#generator-guidance)
+- [Responsibilities and lifecycle](#responsibilities-and-lifecycle)
+- [Error handling](#error-handling)
+- [JSON Schema vs Zod](#json-schema-vs-zod)
+- [Runtime Error Reference](#runtime-error-reference)
+
 ## Installation
 
 ```sh
@@ -138,7 +151,41 @@ Suggested uses for the unified schema:
 
 - 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.
 - Servers that return empty lists produce an empty `items` array (not an error).
+- Servers that support resources but not resource templates are treated as having zero templates.
 
 ## 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.
+
+## Runtime Error Reference
+
+This section is written for high-pressure debugging moments. Each entry maps directly to schema extraction preconditions.
+
+<a id="error-49ae61"></a>
+### Expected a Session instance.
+
+Thrown from: `extract`
+
+This happens when `extract(link)` is called without a connected `Session` object (or with an object that does not expose `.client`). The extractor relies on MCP client capabilities and list calls.
+
+Step-by-step resolution:
+1. Verify you are passing the `Session` returned by `connect(...)` or `attach(...)`.
+2. Confirm session setup completed and `session.client` is available.
+3. Avoid passing raw MCP client objects directly; wrap flows around `Session`.
+4. Add an integration test that extracts from a real connected session.
+
+<details>
+<summary>Fix Example: extract schemas from a connected Session</summary>
+
+```js
+const session = await connect(config, 'local-dev');
+const catalog = await extract(session);
+console.log(catalog.items.length);
+await session.close();
+```
+
+</details>
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-layer/schema",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Extract and normalize MCP schemas into a unified Zod-based format.",
   "repository": {
     "type": "git",
@@ -32,13 +32,14 @@
   },
   "dependencies": {
     "ajv": "^8.17.1",
-    "zod": "^3.25.76"
+    "zod": "^3.25.76",
+    "@mcp-layer/error": "0.2.0"
   },
   "devDependencies": {
-    "@mcp-layer/attach": "1.0.0",
-    "@mcp-layer/config": "1.0.0",
-    "@mcp-layer/connect": "1.0.0",
-    "@mcp-layer/test-server": "1.0.0"
+    "@mcp-layer/attach": "1.1.1",
+    "@mcp-layer/config": "1.0.1",
+    "@mcp-layer/connect": "1.0.1",
+    "@mcp-layer/test-server": "1.0.1"
   },
   "scripts": {
     "test": "node --test --experimental-test-coverage ./test/**/*.js"

package/src/index.js

@@ -1,35 +1,47 @@
 import Ajv from 'ajv';
 import { z } from 'zod';
+import { LayerError } from '@mcp-layer/error';
 
 const ajv = new Ajv({ allErrors: true, strict: false });
 
 /**
  * Test if a value is a plain object.
- * @param {unknown} value
+ * @param {unknown} value - Value to test for plain object shape.
  * @returns {value is Record<string, unknown>}
  */
 function isrecord(value) {
   return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
 
+/**
+ * Determine whether an MCP error indicates a missing method.
+ * @param {unknown} error - Error value to inspect.
+ * @returns {boolean}
+ */
+function ismissing(error) {
+  if (!error || typeof error !== 'object') return false;
+  const code = 'code' in error ? error.code : undefined;
+  if (code === -32601) return true;
+  const message = 'message' in error ? String(error.message) : '';
+  return message.includes('Method') && message.includes('not found');
+}
+
 /**
  * Build a Zod refinement function backed by Ajv.
- * @param {import('ajv').Ajv} validator
- * @param {import('ajv').ValidateFunction} check
+ * @param {import('ajv').Ajv} validator - Ajv instance used to format errors.
+ * @param {import('ajv').ValidateFunction} check - Compiled Ajv validation function.
  * @returns {(value: unknown, ctx: import('zod').RefinementCtx) => void}
  */
 function refiners(validator, check) {
   /**
    * Validate the value and emit Zod issues for Ajv failures.
-   * @param {unknown} value
-   * @param {import('zod').RefinementCtx} ctx
+   * @param {unknown} value - Value to validate.
+   * @param {import('zod').RefinementCtx} ctx - Zod refinement context for reporting issues.
    * @returns {void}
    */
   function apply(value, ctx) {
     const ok = check(value);
-    if (ok) {
-      return;
-    }
+    if (ok) return;
     const text = validator.errorsText(check.errors, { dataVar: 'value' });
     ctx.addIssue({ code: z.ZodIssueCode.custom, message: text });
   }
@@ -39,7 +51,7 @@ function refiners(validator, check) {
 
 /**
  * Wrap a JSON Schema into a Zod schema that delegates validation to Ajv.
- * @param {unknown} json
+ * @param {unknown} json - JSON Schema definition to wrap.
  * @returns {{ schema: import('zod').ZodTypeAny, json: Record<string, unknown> | undefined, error?: string }}
  */
 function wrapschema(json) {
@@ -60,8 +72,8 @@ function wrapschema(json) {
 /**
  * Read all pages for a list request until pagination completes.
  * @template T
- * @param {(cursor?: string) => Promise<T & { nextCursor?: string }>} call
- * @param {(result: T) => Array<unknown>} pull
+ * @param {(cursor?: string) => Promise<T & { nextCursor?: string }>} call - Function that requests a page by cursor.
+ * @param {(result: T) => Array<unknown>} pull - Function that extracts items from each page result.
  * @returns {Promise<Array<unknown>>}
  */
 async function page(call, pull) {
@@ -71,13 +83,9 @@ async function page(call, pull) {
   while (true) {
     const result = await call(cursor);
     const batch = pull(result);
-    if (Array.isArray(batch)) {
-      list.push(...batch);
-    }
+    if (Array.isArray(batch)) list.push(...batch);
     cursor = result.nextCursor;
-    if (!cursor) {
-      break;
-    }
+    if (!cursor) break;
   }
 
   return list;
@@ -85,13 +93,13 @@ async function page(call, pull) {
 
 /**
  * Extract tool entries from a client.
- * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client
+ * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client - MCP client instance.
  * @returns {Promise<Array<Record<string, unknown>>>}
  */
 async function tools(client) {
   /**
    * Fetch a page of tools.
-   * @param {string | undefined} cursor
+   * @param {string | undefined} cursor - Pagination cursor from the previous page.
    * @returns {Promise<{ tools: Array<Record<string, unknown>>, nextCursor?: string }>}
    */
   async function call(cursor) {
@@ -103,7 +111,7 @@ async function tools(client) {
 
   /**
    * Pluck tool definitions from a list response.
-   * @param {{ tools?: Array<Record<string, unknown>> }} result
+   * @param {{ tools?: Array<Record<string, unknown>> }} result - listTools response payload.
    * @returns {Array<Record<string, unknown>>}
    */
   function pull(result) {
@@ -115,13 +123,13 @@ async function tools(client) {
 
 /**
  * Extract resource entries from a client.
- * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client
+ * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client - MCP client instance.
  * @returns {Promise<Array<Record<string, unknown>>>}
  */
 async function resources(client) {
   /**
    * Fetch a page of resources.
-   * @param {string | undefined} cursor
+   * @param {string | undefined} cursor - Pagination cursor from the previous page.
    * @returns {Promise<{ resources: Array<Record<string, unknown>>, nextCursor?: string }>}
    */
   async function call(cursor) {
@@ -133,7 +141,7 @@ async function resources(client) {
 
   /**
    * Pluck resource definitions from a list response.
-   * @param {{ resources?: Array<Record<string, unknown>> }} result
+   * @param {{ resources?: Array<Record<string, unknown>> }} result - listResources response payload.
    * @returns {Array<Record<string, unknown>>}
    */
   function pull(result) {
@@ -145,13 +153,13 @@ async function resources(client) {
 
 /**
  * Extract resource template entries from a client.
- * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client
+ * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client - MCP client instance.
  * @returns {Promise<Array<Record<string, unknown>>>}
  */
 async function templates(client) {
   /**
    * Fetch a page of resource templates.
-   * @param {string | undefined} cursor
+   * @param {string | undefined} cursor - Pagination cursor from the previous page.
    * @returns {Promise<{ resourceTemplates: Array<Record<string, unknown>>, nextCursor?: string }>}
    */
   async function call(cursor) {
@@ -163,25 +171,30 @@ async function templates(client) {
 
   /**
    * Pluck resource template definitions from a list response.
-   * @param {{ resourceTemplates?: Array<Record<string, unknown>> }} result
+   * @param {{ resourceTemplates?: Array<Record<string, unknown>> }} result - listResourceTemplates response payload.
    * @returns {Array<Record<string, unknown>>}
    */
   function pull(result) {
     return Array.isArray(result.resourceTemplates) ? result.resourceTemplates : [];
   }
 
-  return page(call, pull);
+  try {
+    return await page(call, pull);
+  } catch (error) {
+    if (ismissing(error)) return [];
+    throw error;
+  }
 }
 
 /**
  * Extract prompt entries from a client.
- * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client
+ * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client - MCP client instance.
  * @returns {Promise<Array<Record<string, unknown>>>}
  */
 async function prompts(client) {
   /**
    * Fetch a page of prompts.
-   * @param {string | undefined} cursor
+   * @param {string | undefined} cursor - Pagination cursor from the previous page.
    * @returns {Promise<{ prompts: Array<Record<string, unknown>>, nextCursor?: string }>}
    */
   async function call(cursor) {
@@ -193,7 +206,7 @@ async function prompts(client) {
 
   /**
    * Pluck prompt definitions from a list response.
-   * @param {{ prompts?: Array<Record<string, unknown>> }} result
+   * @param {{ prompts?: Array<Record<string, unknown>> }} result - listPrompts response payload.
    * @returns {Array<Record<string, unknown>>}
    */
   function pull(result) {
@@ -205,80 +218,58 @@ async function prompts(client) {
 
 /**
  * Build shared metadata from an MCP item.
- * @param {Record<string, unknown>} item
+ * @param {Record<string, unknown>} item - MCP definition object.
  * @returns {Record<string, unknown>}
  */
 function meta(item) {
   const out = {};
-  if (Array.isArray(item.icons)) {
-    out.icons = item.icons;
-  }
-  if (isrecord(item._meta)) {
-    out._meta = item._meta;
-  }
+  if (Array.isArray(item.icons)) out.icons = item.icons;
+  if (isrecord(item._meta)) out._meta = item._meta;
   return out;
 }
 
 /**
  * Build metadata for tools, including annotations.
- * @param {Record<string, unknown>} tool
+ * @param {Record<string, unknown>} tool - Tool definition object.
  * @returns {Record<string, unknown>}
  */
 function toolmeta(tool) {
   const out = meta(tool);
-  if (isrecord(tool.annotations)) {
-    out.annotations = tool.annotations;
-  }
+  if (isrecord(tool.annotations)) out.annotations = tool.annotations;
   return out;
 }
 
 /**
  * Derive a display title with tool annotation fallback.
- * @param {Record<string, unknown>} tool
+ * @param {Record<string, unknown>} tool - Tool definition object.
  * @returns {string | undefined}
  */
 function tooltitle(tool) {
-  if (typeof tool.title === 'string') {
-    return tool.title;
-  }
-  if (isrecord(tool.annotations) && typeof tool.annotations.title === 'string') {
-    return tool.annotations.title;
-  }
+  if (typeof tool.title === 'string') return tool.title;
+  if (isrecord(tool.annotations) && typeof tool.annotations.title === 'string') return tool.annotations.title;
   return undefined;
 }
 
 /**
  * Extract MCP Apps UI metadata from an item.
- * @param {Record<string, unknown>} item
+ * @param {Record<string, unknown>} item - MCP definition object.
  * @returns {Record<string, unknown> | undefined}
  */
 function uiitem(item) {
-  if (!isrecord(item._meta)) {
-    return undefined;
-  }
-  if (!isrecord(item._meta.ui)) {
-    return undefined;
-  }
+  if (!isrecord(item._meta)) return undefined;
+  if (!isrecord(item._meta.ui)) return undefined;
   const ui = /** @type {Record<string, unknown>} */ (item._meta.ui);
   const out = {};
-  if (typeof ui.resourceUri === 'string') {
-    out.resourceUri = ui.resourceUri;
-  }
-  if (typeof ui.csp === 'string') {
-    out.csp = ui.csp;
-  }
-  if (Array.isArray(ui.permissions)) {
-    out.permissions = ui.permissions;
-  }
-  if (Object.keys(out).length === 0) {
-    return undefined;
-  }
+  if (typeof ui.resourceUri === 'string') out.resourceUri = ui.resourceUri;
+  if (typeof ui.csp === 'string') out.csp = ui.csp;
+  if (Array.isArray(ui.permissions)) out.permissions = ui.permissions;
+  if (Object.keys(out).length === 0) return undefined;
   return out;
 }
 
 /**
  * Normalize a tool definition into the unified schema.
- * @param {Record<string, unknown>} tool
+ * @param {Record<string, unknown>} tool - Raw tool definition from MCP.
  * @returns {Record<string, unknown>}
  */
 function toolitem(tool) {
@@ -287,12 +278,8 @@ function toolitem(tool) {
   const detail = { input };
   const ui = uiitem(tool);
 
-  if (isrecord(tool.outputSchema)) {
-    detail.output = output;
-  }
-  if (ui) {
-    detail.ui = ui;
-  }
+  if (isrecord(tool.outputSchema)) detail.output = output;
+  if (ui) detail.ui = ui;
 
   return {
     type: 'tool',
@@ -306,7 +293,7 @@ function toolitem(tool) {
 
 /**
  * Normalize a resource definition into the unified schema.
- * @param {Record<string, unknown>} resource
+ * @param {Record<string, unknown>} resource - Raw resource definition from MCP.
  * @returns {Record<string, unknown>}
  */
 function resourceitem(resource) {
@@ -328,7 +315,7 @@ function resourceitem(resource) {
 
 /**
  * Normalize a resource template definition into the unified schema.
- * @param {Record<string, unknown>} template
+ * @param {Record<string, unknown>} template - Raw resource template definition from MCP.
  * @returns {Record<string, unknown>}
  */
 function templateitem(template) {
@@ -347,30 +334,22 @@ function templateitem(template) {
 
 /**
  * Build a JSON schema from prompt arguments so prompts share the input schema shape.
- * @param {Record<string, unknown>} prompt
+ * @param {Record<string, unknown>} prompt - Raw prompt definition from MCP.
  * @returns {{ schema: import('zod').ZodTypeAny, json: Record<string, unknown> | undefined, error?: string }}
  */
 function promptinput(prompt) {
-  if (!Array.isArray(prompt.arguments)) {
-    return wrapschema(undefined);
-  }
+  if (!Array.isArray(prompt.arguments)) return wrapschema(undefined);
 
   const properties = {};
   const required = [];
 
   for (const item of prompt.arguments) {
-    if (!isrecord(item)) {
-      continue;
-    }
-    if (typeof item.name !== 'string' || item.name.length === 0) {
-      continue;
-    }
+    if (!isrecord(item)) continue;
+    if (typeof item.name !== 'string' || item.name.length === 0) continue;
     properties[item.name] = {
       description: typeof item.description === 'string' ? item.description : undefined
     };
-    if (item.required === true) {
-      required.push(item.name);
-    }
+    if (item.required === true) required.push(item.name);
   }
 
   const json = {
@@ -385,7 +364,7 @@ function promptinput(prompt) {
 
 /**
  * Normalize a prompt definition into the unified schema.
- * @param {Record<string, unknown>} prompt
+ * @param {Record<string, unknown>} prompt - Raw prompt definition from MCP.
  * @returns {Record<string, unknown>}
  */
 function promptitem(prompt) {
@@ -404,7 +383,7 @@ function promptitem(prompt) {
 
 /**
  * Convert a set of MCP definitions into a unified item list.
- * @param {{ tools?: Array<Record<string, unknown>>, resources?: Array<Record<string, unknown>>, templates?: Array<Record<string, unknown>>, prompts?: Array<Record<string, unknown>> }} data
+ * @param {{ tools?: Array<Record<string, unknown>>, resources?: Array<Record<string, unknown>>, templates?: Array<Record<string, unknown>>, prompts?: Array<Record<string, unknown>> }} data - Aggregated MCP list responses.
  * @returns {Array<Record<string, unknown>>}
  */
 function normalize(data) {
@@ -439,12 +418,16 @@ function normalize(data) {
 
 /**
  * Extract MCP tool/resource/prompt schemas into a unified Zod-backed format.
- * @param {import('@mcp-layer/session').Session} link
+ * @param {import('@mcp-layer/session').Session} link - Active session with a connected MCP server.
  * @returns {Promise<{ server: { info: Record<string, unknown> | undefined, capabilities: Record<string, unknown> | undefined, instructions: string | undefined }, items: Array<Record<string, unknown>> }>}
  */
 export async function extract(link) {
   if (!link || !link.client) {
-    throw new Error('Expected a Session instance.');
+    throw new LayerError({
+      name: 'schema',
+      method: 'extract',
+      message: 'Expected a Session instance.',
+    });
   }
 
   const client = link.client;
@@ -459,18 +442,14 @@ export async function extract(link) {
     prompts: undefined
   };
 
-  if (caps && caps.tools) {
-    data.tools = await tools(client);
-  }
+  if (caps && caps.tools) data.tools = await tools(client);
 
   if (caps && caps.resources) {
     data.resources = await resources(client);
     data.templates = await templates(client);
   }
 
-  if (caps && caps.prompts) {
-    data.prompts = await prompts(client);
-  }
+  if (caps && caps.prompts) data.prompts = await prompts(client);
 
   const items = normalize(data);