@mcp-layer/schema 1.0.0 → 1.0.1

package/README.md

@@ -138,6 +138,7 @@ 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-layer/schema",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Extract and normalize MCP schemas into a unified Zod-based format.",
   "repository": {
     "type": "git",
@@ -35,7 +35,7 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@mcp-layer/attach": "1.0.0",
+    "@mcp-layer/attach": "1.1.0",
     "@mcp-layer/config": "1.0.0",
     "@mcp-layer/connect": "1.0.0",
     "@mcp-layer/test-server": "1.0.0"

package/src/index.js

@@ -5,24 +5,41 @@ 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) {
@@ -39,7 +56,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 +77,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) {
@@ -85,13 +102,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 +120,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 +132,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 +150,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 +162,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 +180,32 @@ 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 +217,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,7 +229,7 @@ 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) {
@@ -221,7 +245,7 @@ function meta(item) {
 
 /**
  * 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) {
@@ -234,7 +258,7 @@ function toolmeta(tool) {
 
 /**
  * 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) {
@@ -249,7 +273,7 @@ function tooltitle(tool) {
 
 /**
  * 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) {
@@ -278,7 +302,7 @@ function uiitem(item) {
 
 /**
  * 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) {
@@ -306,7 +330,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 +352,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,7 +371,7 @@ 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) {
@@ -385,7 +409,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 +428,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,7 +463,7 @@ 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) {