@mcp-layer/schema 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arnout Kazemier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# @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.
+
+## Installation
+
+```sh
+pnpm add @mcp-layer/schema
+# or
+npm install @mcp-layer/schema
+# or
+yarn add @mcp-layer/schema
+```
+
+## Usage
+
+```js
+import { load } from '@mcp-layer/config';
+import { connect } from '@mcp-layer/connect';
+import { extract } from '@mcp-layer/schema';
+
+const config = await load(undefined, process.cwd());
+const session = await connect(config, 'demo');
+const output = await extract(session);
+
+console.log(output.server.info);
+console.log(output.items[0]);
+await session.close();
+```
+
+## What this package does
+
+1) Reads the MCP server capabilities and metadata from the live client connection.
+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.
+
+## Output shape (authoritative)
+
+The package returns:
+
+```js
+{
+  server: {
+    info,          // initialize.serverInfo
+    capabilities,  // initialize.capabilities
+    instructions   // initialize.instructions (optional)
+  },
+  items: [
+    {
+      type,         // "tool" | "resource" | "resource-template" | "prompt"
+      name,
+      title,
+      description,
+      meta,         // icons, annotations, _meta
+      detail        // type-specific data
+    }
+  ]
+}
+```
+
+Type discriminator:
+- `tool`, `resource`, `resource-template`, `prompt`
+- MCP Apps do not introduce a new `type`; tools remain `tool` and UI resources remain `resource`.
+
+### detail: tools
+
+```js
+detail: {
+  input: {
+    schema, // Zod schema (Ajv-backed)
+    json,   // original JSON Schema
+    error   // optional Ajv compile error message
+  },
+  output: { schema, json, error }, // only when the tool advertises outputSchema
+  ui: { resourceUri, csp, permissions } // when _meta.ui is present (MCP Apps)
+}
+```
+
+### detail: resources
+
+```js
+detail: {
+  uri,
+  mimeType,
+  size,
+  ui: { resourceUri, csp, permissions } // when _meta.ui is present (MCP Apps)
+}
+```
+
+### detail: resource templates
+
+```js
+detail: {
+  uriTemplate,
+  mimeType
+}
+```
+
+### detail: prompts
+
+```js
+detail: {
+  input: {
+    schema, // Zod schema derived from prompt arguments
+    json,   // JSON Schema derived from prompt arguments
+    error   // optional Ajv compile error message
+  }
+}
+```
+
+## MCP Apps support
+
+If a server exposes MCP Apps metadata:
+- Tools may include `_meta.ui.resourceUri` pointing to a `ui://` resource.
+- UI resources may include `_meta.ui` with CSP and permissions.
+
+This package normalizes those fields into `detail.ui` so generators can:
+- Detect which tools expect UI rendering.
+- Resolve and render the `ui://` resource.
+- Apply CSP and permissions when hosting the UI in a webview or browser sandbox.
+
+## Generator guidance
+
+Suggested uses for the unified schema:
+- CLI: Use `name`, `description`, and `detail.input` to build flags and help text.
+- REST: Use `name` for endpoints, `detail.input.json` for request validation, and `detail.output` for response schema.
+- UI: Use `detail.ui.resourceUri` to locate the UI and read `detail.ui.csp` / `permissions`.
+
+## Responsibilities and lifecycle
+
+- This package 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.
+- If the server doesn't advertise a capability (tools/resources/prompts), extraction skips that surface.
+
+## 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.
+- Servers that return empty lists produce an empty `items` array (not an error).
+
+## 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.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@mcp-layer/schema",
+  "version": "0.0.0",
+  "description": "Extract and normalize MCP schemas into a unified Zod-based format.",
+  "type": "module",
+  "keywords": [
+    "mcp",
+    "schema",
+    "zod",
+    "tools",
+    "resources",
+    "prompts"
+  ],
+  "scripts": {
+    "test": "node --test --experimental-test-coverage ./test/**/*.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@mcp-layer/attach": "workspace:*",
+    "@mcp-layer/config": "workspace:*",
+    "@mcp-layer/connect": "workspace:*",
+    "@mcp-layer/test-server": "workspace:*"
+  }
+}

package/src/index.js

@@ -0,0 +1,485 @@
+import Ajv from 'ajv';
+import { z } from 'zod';
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+
+/**
+ * Test if a value is a plain object.
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isrecord(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+/**
+ * Build a Zod refinement function backed by Ajv.
+ * @param {import('ajv').Ajv} validator
+ * @param {import('ajv').ValidateFunction} check
+ * @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
+   * @returns {void}
+   */
+  function apply(value, ctx) {
+    const ok = check(value);
+    if (ok) {
+      return;
+    }
+    const text = validator.errorsText(check.errors, { dataVar: 'value' });
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: text });
+  }
+
+  return apply;
+}
+
+/**
+ * Wrap a JSON Schema into a Zod schema that delegates validation to Ajv.
+ * @param {unknown} json
+ * @returns {{ schema: import('zod').ZodTypeAny, json: Record<string, unknown> | undefined, error?: string }}
+ */
+function wrapschema(json) {
+  if (!isrecord(json)) {
+    return { schema: z.unknown(), json: undefined };
+  }
+
+  try {
+    const check = ajv.compile(json);
+    const refine = refiners(ajv, check);
+    return { schema: z.any().superRefine(refine), json };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { schema: z.unknown(), json, error: message };
+  }
+}
+
+/**
+ * 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
+ * @returns {Promise<Array<unknown>>}
+ */
+async function page(call, pull) {
+  let cursor;
+  const list = [];
+
+  while (true) {
+    const result = await call(cursor);
+    const batch = pull(result);
+    if (Array.isArray(batch)) {
+      list.push(...batch);
+    }
+    cursor = result.nextCursor;
+    if (!cursor) {
+      break;
+    }
+  }
+
+  return list;
+}
+
+/**
+ * Extract tool entries from a client.
+ * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client
+ * @returns {Promise<Array<Record<string, unknown>>>}
+ */
+async function tools(client) {
+  /**
+   * Fetch a page of tools.
+   * @param {string | undefined} cursor
+   * @returns {Promise<{ tools: Array<Record<string, unknown>>, nextCursor?: string }>}
+   */
+  async function call(cursor) {
+    if (cursor) {
+      return client.listTools({ cursor });
+    }
+    return client.listTools();
+  }
+
+  /**
+   * Pluck tool definitions from a list response.
+   * @param {{ tools?: Array<Record<string, unknown>> }} result
+   * @returns {Array<Record<string, unknown>>}
+   */
+  function pull(result) {
+    return Array.isArray(result.tools) ? result.tools : [];
+  }
+
+  return page(call, pull);
+}
+
+/**
+ * Extract resource entries from a client.
+ * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client
+ * @returns {Promise<Array<Record<string, unknown>>>}
+ */
+async function resources(client) {
+  /**
+   * Fetch a page of resources.
+   * @param {string | undefined} cursor
+   * @returns {Promise<{ resources: Array<Record<string, unknown>>, nextCursor?: string }>}
+   */
+  async function call(cursor) {
+    if (cursor) {
+      return client.listResources({ cursor });
+    }
+    return client.listResources();
+  }
+
+  /**
+   * Pluck resource definitions from a list response.
+   * @param {{ resources?: Array<Record<string, unknown>> }} result
+   * @returns {Array<Record<string, unknown>>}
+   */
+  function pull(result) {
+    return Array.isArray(result.resources) ? result.resources : [];
+  }
+
+  return page(call, pull);
+}
+
+/**
+ * Extract resource template entries from a client.
+ * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client
+ * @returns {Promise<Array<Record<string, unknown>>>}
+ */
+async function templates(client) {
+  /**
+   * Fetch a page of resource templates.
+   * @param {string | undefined} cursor
+   * @returns {Promise<{ resourceTemplates: Array<Record<string, unknown>>, nextCursor?: string }>}
+   */
+  async function call(cursor) {
+    if (cursor) {
+      return client.listResourceTemplates({ cursor });
+    }
+    return client.listResourceTemplates();
+  }
+
+  /**
+   * Pluck resource template definitions from a list response.
+   * @param {{ resourceTemplates?: Array<Record<string, unknown>> }} result
+   * @returns {Array<Record<string, unknown>>}
+   */
+  function pull(result) {
+    return Array.isArray(result.resourceTemplates) ? result.resourceTemplates : [];
+  }
+
+  return page(call, pull);
+}
+
+/**
+ * Extract prompt entries from a client.
+ * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client
+ * @returns {Promise<Array<Record<string, unknown>>>}
+ */
+async function prompts(client) {
+  /**
+   * Fetch a page of prompts.
+   * @param {string | undefined} cursor
+   * @returns {Promise<{ prompts: Array<Record<string, unknown>>, nextCursor?: string }>}
+   */
+  async function call(cursor) {
+    if (cursor) {
+      return client.listPrompts({ cursor });
+    }
+    return client.listPrompts();
+  }
+
+  /**
+   * Pluck prompt definitions from a list response.
+   * @param {{ prompts?: Array<Record<string, unknown>> }} result
+   * @returns {Array<Record<string, unknown>>}
+   */
+  function pull(result) {
+    return Array.isArray(result.prompts) ? result.prompts : [];
+  }
+
+  return page(call, pull);
+}
+
+/**
+ * Build shared metadata from an MCP item.
+ * @param {Record<string, unknown>} item
+ * @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;
+  }
+  return out;
+}
+
+/**
+ * Build metadata for tools, including annotations.
+ * @param {Record<string, unknown>} tool
+ * @returns {Record<string, unknown>}
+ */
+function toolmeta(tool) {
+  const out = meta(tool);
+  if (isrecord(tool.annotations)) {
+    out.annotations = tool.annotations;
+  }
+  return out;
+}
+
+/**
+ * Derive a display title with tool annotation fallback.
+ * @param {Record<string, unknown>} 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;
+  }
+  return undefined;
+}
+
+/**
+ * Extract MCP Apps UI metadata from an item.
+ * @param {Record<string, unknown>} item
+ * @returns {Record<string, unknown> | undefined}
+ */
+function uiitem(item) {
+  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;
+  }
+  return out;
+}
+
+/**
+ * Normalize a tool definition into the unified schema.
+ * @param {Record<string, unknown>} tool
+ * @returns {Record<string, unknown>}
+ */
+function toolitem(tool) {
+  const input = wrapschema(tool.inputSchema);
+  const output = wrapschema(tool.outputSchema);
+  const detail = { input };
+  const ui = uiitem(tool);
+
+  if (isrecord(tool.outputSchema)) {
+    detail.output = output;
+  }
+  if (ui) {
+    detail.ui = ui;
+  }
+
+  return {
+    type: 'tool',
+    name: typeof tool.name === 'string' ? tool.name : 'tool',
+    title: tooltitle(tool),
+    description: typeof tool.description === 'string' ? tool.description : undefined,
+    meta: toolmeta(tool),
+    detail
+  };
+}
+
+/**
+ * Normalize a resource definition into the unified schema.
+ * @param {Record<string, unknown>} resource
+ * @returns {Record<string, unknown>}
+ */
+function resourceitem(resource) {
+  const ui = uiitem(resource);
+  return {
+    type: 'resource',
+    name: typeof resource.name === 'string' ? resource.name : 'resource',
+    title: typeof resource.title === 'string' ? resource.title : undefined,
+    description: typeof resource.description === 'string' ? resource.description : undefined,
+    meta: meta(resource),
+    detail: {
+      uri: typeof resource.uri === 'string' ? resource.uri : undefined,
+      mimeType: typeof resource.mimeType === 'string' ? resource.mimeType : undefined,
+      size: typeof resource.size === 'number' ? resource.size : undefined,
+      ui
+    }
+  };
+}
+
+/**
+ * Normalize a resource template definition into the unified schema.
+ * @param {Record<string, unknown>} template
+ * @returns {Record<string, unknown>}
+ */
+function templateitem(template) {
+  return {
+    type: 'resource-template',
+    name: typeof template.name === 'string' ? template.name : 'resource-template',
+    title: typeof template.title === 'string' ? template.title : undefined,
+    description: typeof template.description === 'string' ? template.description : undefined,
+    meta: meta(template),
+    detail: {
+      uriTemplate: typeof template.uriTemplate === 'string' ? template.uriTemplate : undefined,
+      mimeType: typeof template.mimeType === 'string' ? template.mimeType : undefined
+    }
+  };
+}
+
+/**
+ * Build a JSON schema from prompt arguments so prompts share the input schema shape.
+ * @param {Record<string, unknown>} prompt
+ * @returns {{ schema: import('zod').ZodTypeAny, json: Record<string, unknown> | undefined, error?: string }}
+ */
+function promptinput(prompt) {
+  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;
+    }
+    properties[item.name] = {
+      description: typeof item.description === 'string' ? item.description : undefined
+    };
+    if (item.required === true) {
+      required.push(item.name);
+    }
+  }
+
+  const json = {
+    type: 'object',
+    properties,
+    required: required.length > 0 ? required : undefined,
+    additionalProperties: true
+  };
+
+  return wrapschema(json);
+}
+
+/**
+ * Normalize a prompt definition into the unified schema.
+ * @param {Record<string, unknown>} prompt
+ * @returns {Record<string, unknown>}
+ */
+function promptitem(prompt) {
+  const input = promptinput(prompt);
+  return {
+    type: 'prompt',
+    name: typeof prompt.name === 'string' ? prompt.name : 'prompt',
+    title: typeof prompt.title === 'string' ? prompt.title : undefined,
+    description: typeof prompt.description === 'string' ? prompt.description : undefined,
+    meta: meta(prompt),
+    detail: {
+      input
+    }
+  };
+}
+
+/**
+ * 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
+ * @returns {Array<Record<string, unknown>>}
+ */
+function normalize(data) {
+  const list = [];
+
+  if (Array.isArray(data.tools)) {
+    for (const item of data.tools) {
+      list.push(toolitem(item));
+    }
+  }
+
+  if (Array.isArray(data.resources)) {
+    for (const item of data.resources) {
+      list.push(resourceitem(item));
+    }
+  }
+
+  if (Array.isArray(data.templates)) {
+    for (const item of data.templates) {
+      list.push(templateitem(item));
+    }
+  }
+
+  if (Array.isArray(data.prompts)) {
+    for (const item of data.prompts) {
+      list.push(promptitem(item));
+    }
+  }
+
+  return list;
+}
+
+/**
+ * Extract MCP tool/resource/prompt schemas into a unified Zod-backed format.
+ * @param {import('@mcp-layer/session').Session} link
+ * @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.');
+  }
+
+  const client = link.client;
+  const caps = client.getServerCapabilities();
+  const info = client.getServerVersion();
+  const instructions = client.getInstructions();
+
+  const data = {
+    tools: undefined,
+    resources: undefined,
+    templates: undefined,
+    prompts: undefined
+  };
+
+  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);
+  }
+
+  const items = normalize(data);
+
+  return {
+    server: {
+      info,
+      capabilities: caps,
+      instructions
+    },
+    items
+  };
+}