@mcp-layer/schema 1.0.1 → 1.0.3

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
@@ -143,3 +156,36 @@ 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.
+
+## 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.1",
+  "version": "1.0.3",
   "description": "Extract and normalize MCP schemas into a unified Zod-based format.",
   "repository": {
     "type": "git",
@@ -16,8 +16,10 @@
     "prompts"
   ],
   "main": "src/index.js",
+  "types": "./types/index.d.ts",
   "exports": {
     ".": {
+      "types": "./types/index.d.ts",
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
@@ -25,6 +27,7 @@
   },
   "files": [
     "src",
+    "types",
     "LICENSE"
   ],
   "publishConfig": {
@@ -32,15 +35,17 @@
   },
   "dependencies": {
     "ajv": "^8.17.1",
-    "zod": "^3.25.76"
+    "zod": "^3.25.76",
+    "@mcp-layer/error": "0.2.1"
   },
   "devDependencies": {
-    "@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"
+    "@mcp-layer/attach": "1.1.2",
+    "@mcp-layer/config": "1.0.2",
+    "@mcp-layer/connect": "1.2.1",
+    "@mcp-layer/test-server": "1.0.4"
   },
   "scripts": {
-    "test": "node --test --experimental-test-coverage ./test/**/*.js"
+    "build:types": "tsc -p tsconfig.json",
+    "test": "node --test --experimental-test-coverage \"./test/**/*.js\""
   }
 }

package/src/index.js

@@ -1,5 +1,6 @@
 import Ajv from 'ajv';
 import { z } from 'zod';
+import { LayerError } from '@mcp-layer/error';
 
 const ajv = new Ajv({ allErrors: true, strict: false });
 
@@ -18,13 +19,9 @@ function isrecord(value) {
  * @returns {boolean}
  */
 function ismissing(error) {
-  if (!error || typeof error !== 'object') {
-    return false;
-  }
+  if (!error || typeof error !== 'object') return false;
   const code = 'code' in error ? error.code : undefined;
-  if (code === -32601) {
-    return true;
-  }
+  if (code === -32601) return true;
   const message = 'message' in error ? String(error.message) : '';
   return message.includes('Method') && message.includes('not found');
 }
@@ -44,9 +41,7 @@ function refiners(validator, check) {
    */
   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 });
   }
@@ -88,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;
@@ -190,9 +181,7 @@ async function templates(client) {
   try {
     return await page(call, pull);
   } catch (error) {
-    if (ismissing(error)) {
-      return [];
-    }
+    if (ismissing(error)) return [];
     throw error;
   }
 }
@@ -234,12 +223,8 @@ async function prompts(client) {
  */
 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;
 }
 
@@ -250,9 +235,7 @@ function meta(item) {
  */
 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;
 }
 
@@ -262,12 +245,8 @@ function toolmeta(tool) {
  * @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;
 }
 
@@ -277,26 +256,14 @@ function tooltitle(tool) {
  * @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;
 }
 
@@ -311,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',
@@ -375,26 +338,18 @@ function templateitem(template) {
  * @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 = {
@@ -468,7 +423,11 @@ function normalize(data) {
  */
 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;
@@ -483,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);
 

package/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ * @returns {Promise<{ server: { info: Record<string, unknown> | undefined, capabilities: Record<string, unknown> | undefined, instructions: string | undefined }, items: Array<Record<string, unknown>> }>}
+ */
+export function extract(link: any): Promise<{
+    server: {
+        info: Record<string, unknown> | undefined;
+        capabilities: Record<string, unknown> | undefined;
+        instructions: string | undefined;
+    };
+    items: Array<Record<string, unknown>>;
+}>;