@mcp-layer/schema 1.0.2 → 1.0.4

package/README.md

@@ -30,7 +30,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 +39,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)
 
@@ -143,8 +165,9 @@ 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.
 
 ## Error handling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-layer/schema",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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": {
@@ -33,15 +36,16 @@
   "dependencies": {
     "ajv": "^8.17.1",
     "zod": "^3.25.76",
-    "@mcp-layer/error": "0.2.0"
+    "@mcp-layer/error": "0.2.1"
   },
   "devDependencies": {
-    "@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"
+    "@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

@@ -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

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ * @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>>;
+}>;