mcp-layer 0.2.1 → 0.2.2

package/README.md

@@ -1,123 +1,85 @@
-# MCP Layer
+# mcp-layer
 
-`mcp-layer` helps engineers bolt extra behaviors on top of existing MCP servers without reimplementing transport or schema parsing. It is a small, focused toolbox for discovering MCP configs, connecting to servers, and extracting a unified schema that can drive CLIs, REST APIs, UI renderers, or additional MCP layers.
+`mcp-layer` is the npm entry point for MCP Layer, a toolkit for building production-ready interfaces on top of any MCP server.
 
-## Table of Contents
+Use it to discover MCP configs, connect sessions, normalize catalogs, and expose those capabilities through CLI, REST, GraphQL, and OpenAPI layers in one cohesive stack.
 
-- [What you can build with this repo](#what-you-can-build-with-this-repo)
-- [Packages](#packages)
-- [CLI quick try](#cli-quick-try)
-- [Quick start (end-to-end)](#quick-start-end-to-end)
-- [Design principles](#design-principles)
-- [Development](#development)
-- [Releasing](#releasing)
-- [Repository guidelines](#repository-guidelines)
+## Install
 
-## What you can build with this repo
-
-- **CLI layers** that expose MCP tools as commands with validated input.
-- **REST gateways** that generate endpoints and schemas from MCP tool definitions.
-- **GraphQL gateways** that expose generated and generic operations on top of MCP catalogs.
-- **UI renderers** that surface MCP Apps resources using `_meta.ui` metadata.
-- **New MCP layers** that programmatically reason about tool/resource catalogs.
-
-## Packages
-
-### mcp-layer
-
-`mcp-layer` aggregates every workspace package under a single namespace export so you can import from one place when prototyping or composing multiple layers. We still recommend consuming the individual packages by default; the root package exists for teams that want a single install with always-matched versions/majors.
-
-```js
-import { attach, cli, config, connect, schema, session, testServer } from 'mcp-layer';
-
-const loaded = await config.load(undefined, process.cwd());
-const link = await connect.connect(loaded, 'demo');
-const catalog = await schema.extract(link);
-await link.close();
-```
-
-### Infrastructure and utilities
-
-| Package | Purpose |
-| --- | --- |
-| [`@mcp-layer/config`](packages/config/README.md) | Discover and normalize MCP server configs across editors/clients. |
-| [`@mcp-layer/session`](packages/session/README.md) | Shared Session handle used by connect and attach. |
-| [`@mcp-layer/connect`](packages/connect/README.md) | Connect to MCP servers over stdio and return a closeable Session. |
-| [`@mcp-layer/attach`](packages/attach/README.md) | Attach to in-process MCP SDK servers or Platformatic Fastify MCP plugins and return a Session. |
-| [`@mcp-layer/schema`](packages/schema/README.md) | Extract tools/resources/prompts/templates into a unified Zod-backed schema (including MCP Apps metadata). |
-| [`@mcp-layer/gateway`](packages/gateway/README.md) | Shared adapter runtime primitives for catalog bootstrap, validation, resilience, telemetry, and deterministic mapping. |
-| [`@mcp-layer/test-server`](packages/test-server/README.md) | Feature-complete MCP server for integration tests and local exploration. |
-| [`@mcp-layer/openapi`](packages/openapi/README.md) | Generate OpenAPI 3.1 specs from MCP catalogs. |
-| [`@mcp-layer/rest`](packages/rest/README.md) | Fastify plugin that exposes MCP servers over REST. |
-
-### Layers and interfaces
-
-| Package | Purpose |
-| --- | --- |
-| [`@mcp-layer/cli`](packages/cli/README.md) | CLI framework for turning MCP schemas into commands. |
-| [`@mcp-layer/openapi`](packages/openapi/README.md) | OpenAPI 3.1 generation for REST surfaces. |
-| [`@mcp-layer/rest`](packages/rest/README.md) | Fastify plugin for HTTP REST exposure. |
-| [`@mcp-layer/graphql`](packages/graphql/README.md) | Fastify plugin and schema builder for GraphQL exposure on MCP catalogs. |
-
-## CLI quick try
-
-If you already have an MCP config on disk, you can try the CLI immediately:
+Use your package manager of choice to install `mcp-layer` in any Node.js project.
 
 ```sh
-mcp-layer servers list
-mcp-layer tools list --server <name>
-mcp-layer tools <tool> --help
+npm install mcp-layer
+pnpm add mcp-layer
+yarn add mcp-layer
 ```
 
-## Quick start (end-to-end)
+## Quick Start
 
-```js
-import { load } from '@mcp-layer/config';
-import { connect } from '@mcp-layer/connect';
-import { extract } from '@mcp-layer/schema';
+This example demonstrates the primary workflow: load MCP configuration, open a session, and extract a normalized catalog from one package import. This matters when you want to wire a prototype quickly without managing multiple top-level dependencies.
 
-const config = await load(undefined, process.cwd());
-const session = await connect(config, 'demo');
+```js
+import { config, connect, schema } from 'mcp-layer';
 
-const schema = await extract(session);
-console.log(schema.items.map((item) => item.name));
+const cfg = await config.load(undefined, process.cwd());
+const session = await connect.connect(cfg, 'demo');
+const catalog = await schema.extract(session);
 
+console.log(catalog.items?.length ?? 0);
 await session.close();
 ```
 
-## Design principles
+Running this script prints the number of discovered catalog items for the selected server.
 
-- **Single source of truth**: normalized schemas flow from the MCP server, not from tool-specific parsing.
-- **Layered adapters**: `schema -> gateway -> rest/graphql` keeps protocol logic centralized while adapters stay thin.
-- **Minimal surface area**: each package does one job and composes cleanly with the others.
-- **Real integration tests**: no mocks; the test server is used as a real MCP target.
+## API Reference
 
-## Development
+`mcp-layer` exports package namespaces. If you are new to MCP Layer, this table explains what each namespace is for and links to full package documentation.
 
-```sh
-pnpm install
-pnpm test
-```
+| Namespace export | Purpose | Documentation |
+| --- | --- | --- |
+| `attach` | Attach to in-process MCP SDK servers without launching external transports. | [`@mcp-layer/attach` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/attach/README.md) |
+| `cli` | Build command-line interfaces for MCP tools, prompts, resources, and templates. | [`@mcp-layer/cli` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/cli/README.md) |
+| `config` | Discover and normalize MCP server configuration across host tools. | [`@mcp-layer/config` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/config/README.md) |
+| `connect` | Connect to MCP servers over stdio, Streamable HTTP, or SSE. | [`@mcp-layer/connect` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/connect/README.md) |
+| `error` | Create structured runtime errors with stable references and docs links. | [`@mcp-layer/error` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/error/README.md) |
+| `gateway` | Reuse shared adapter runtime primitives for mapping, validation, resilience, and telemetry. | [`@mcp-layer/gateway` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/gateway/README.md) |
+| `graphql` | Expose MCP catalogs and operations through GraphQL. | [`@mcp-layer/graphql` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/graphql/README.md) |
+| `manager` | Manage authenticated and shared MCP sessions with reuse and limits. | [`@mcp-layer/manager` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/manager/README.md) |
+| `openapi` | Generate OpenAPI 3.1 documents from MCP catalogs. | [`@mcp-layer/openapi` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/openapi/README.md) |
+| `rest` | Expose MCP sessions as REST endpoints with Fastify. | [`@mcp-layer/rest` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/rest/README.md) |
+| `schema` | Extract and normalize tools, resources, prompts, and templates into a consistent catalog. | [`@mcp-layer/schema` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/schema/README.md) |
+| `session` | Use the shared session abstraction across connectors and adapters. | [`@mcp-layer/session` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/session/README.md) |
+| `testServer` | Run a feature-complete local MCP server for development and integration tests. | [`@mcp-layer/test-server` README](https://github.com/3rd-Eden/mcp-layer/blob/main/packages/test-server/README.md) |
+
+### Error Behavior
+
+This package does not introduce a custom runtime layer. Errors are raised by whichever namespace package you call.
 
-## Releasing
+For structured runtime errors, refer to the package-level error sections in the linked namespace READMEs.
 
-We use Changesets to manage versions and a GitHub Actions release workflow to publish packages. In short:
+<a id="error-58ed2a"></a>
+#### `findWorkspaceRoot`: Unable to locate workspace root from mcp-layer package.
 
-1) Add a changeset: `pnpm changeset`
-2) Merge the Changesets PR
-3) GitHub Actions publishes via npm Trusted Publishing (OIDC)
+This error is raised when `mcp-layer` package generation runs in a directory tree that does not contain `pnpm-workspace.yaml`.
 
-Before publishing, configure npm Trusted Publishers for each package in the npm registry and ensure the release workflow has `id-token: write` permissions.
+Step-by-step resolution:
+1. Run generation from inside a checkout of the MCP Layer repository.
+2. Confirm `pnpm-workspace.yaml` exists at the repository root.
+3. Run `pnpm --filter mcp-layer prepack` from the repository root.
 
-The root package runs `prepack` to regenerate `src/index.js` and sync root `package.json` dependencies to the workspace packages before publishing.
+<details>
+<summary>Debug example</summary>
 
-See `.github/workflows/release.yml` for the pipeline details.
+If you copy `packages/mcp-layer` into a standalone folder and run `node src/generate.js`, `findWorkspaceRoot` cannot locate the workspace marker and throws this error.
+</details>
 
-The publish guard at `.github/workflows/publish-guard.yml` runs after the `Release` workflow completes and locates the open `Version Packages` PR (`changeset-release/main`). It checks npm for workspace package existence and upserts a single PR comment when packages still need first-time bootstrap publishing.
+## Standards and Portability
 
-## Repository guidelines
+MCP behavior follows the official MCP specification and official TypeScript SDK contracts:
 
-See `AGENTS.md` for coding style, testing requirements, and documentation expectations.
+- [Model Context Protocol specification](https://modelcontextprotocol.io/specification)
+- [MCP transport specification](https://modelcontextprotocol.io/specification/latest/basic/transports)
+- [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-layer",
-  "version": "0.2.1",
-  "description": "Layers of functionality that can be add to any MCP server. ",
+  "version": "0.2.2",
+  "description": "Build production-ready CLI, REST, GraphQL, and OpenAPI interfaces on top of any MCP server.",
   "repository": {
     "type": "git",
     "url": "https://github.com/3rd-Eden/mcp-layer"
@@ -23,16 +23,28 @@
   ],
   "license": "MIT",
   "author": "Arnout Kazemier",
-  "packageManager": "pnpm@8.15.4",
   "type": "module",
-  "devDependencies": {
-    "@changesets/cli": "^2.29.2"
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
     "@mcp-layer/attach": "1.1.1",
-    "@mcp-layer/cli": "1.2.0",
+    "@mcp-layer/cli": "1.3.0",
     "@mcp-layer/config": "1.0.1",
-    "@mcp-layer/connect": "1.1.0",
+    "@mcp-layer/connect": "1.2.0",
     "@mcp-layer/error": "0.2.0",
     "@mcp-layer/manager": "0.2.0",
     "@mcp-layer/graphql": "0.2.0",
@@ -41,21 +53,9 @@
     "@mcp-layer/rest": "1.2.1",
     "@mcp-layer/schema": "1.0.2",
     "@mcp-layer/session": "1.0.0",
-    "@mcp-layer/test-server": "1.0.2"
-  },
-  "main": "./src/index.js",
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "exports": {
-    ".": "./src/index.js"
+    "@mcp-layer/test-server": "1.0.3"
   },
   "scripts": {
-    "test": "node --test",
-    "changeset": "changeset",
-    "changeset:version": "changeset version",
-    "changeset:publish": "changeset publish"
+    "test": "node --test ./test/**/*.js"
   }
 }

package/src/generate.js

@@ -1,6 +1,7 @@
 import { access, readFile, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { LayerError } from '@mcp-layer/error';
 
 /**
  * Convert a package folder name into a namespace export name.
@@ -55,8 +56,8 @@ export async function hasPackageJson(pkgPath) {
  * @param {string} rootDir - Repository root directory.
  * @returns {Promise<string>} Generated index.js content.
  */
-export async function buildIndex(rootDir) {
-  const meta = await collectPackageMeta(rootDir);
+export async function buildIndex(rootDir, selfName = 'mcp-layer') {
+  const meta = await collectPackageMeta(rootDir, new Set([selfName]));
   const lines = [];
 
   lines.push('/**');
@@ -84,15 +85,17 @@ export async function buildIndex(rootDir) {
 /**
  * Collect package metadata from workspace folders.
  * @param {string} rootDir - Repository root directory.
+ * @param {Set<string>} omit - Package names to skip.
  * @returns {Promise<Array<{name: string, dir: string}>>} Package metadata.
  */
-export async function collectPackageMeta(rootDir) {
+export async function collectPackageMeta(rootDir, omit = new Set()) {
   const packages = await collectPackages(rootDir);
   const meta = [];
 
   for (const dir of packages) {
     const pkgPath = path.join(rootDir, 'packages', dir, 'package.json');
     const data = await readJson(pkgPath);
+    if (omit.has(data.name)) continue;
     meta.push({ name: data.name, dir });
   }
 
@@ -100,18 +103,21 @@ export async function collectPackageMeta(rootDir) {
 }
 
 /**
- * Update root package.json dependencies to match workspace packages.
+ * Update mcp-layer package dependencies to match workspace packages.
+ * @param {string} pkgDir - mcp-layer package directory.
  * @param {string} rootDir - Repository root directory.
+ * @param {string} selfName - mcp-layer package name.
  * @returns {Promise<void>} Resolves when dependencies are updated.
  */
-export async function syncDependencies(rootDir) {
-  const pkgPath = path.join(rootDir, 'package.json');
+export async function syncDependencies(pkgDir, rootDir, selfName = 'mcp-layer') {
+  const pkgPath = path.join(pkgDir, 'package.json');
   const data = await readJson(pkgPath);
   const deps = { ...(data.dependencies ?? {}) };
-  const meta = await collectPackageMeta(rootDir);
+  const meta = await collectPackageMeta(rootDir, new Set([selfName]));
   const names = new Set();
 
   for (const item of meta) {
+    if (!item.name.startsWith('@mcp-layer/')) continue;
     names.add(item.name);
     deps[item.name] = 'workspace:*';
   }
@@ -130,8 +136,8 @@ export async function syncDependencies(rootDir) {
  * @param {string} outFile - Output file path.
  * @returns {Promise<void>} Resolves when the file is written or unchanged.
  */
-export async function writeIndex(rootDir, outFile) {
-  const next = await buildIndex(rootDir);
+export async function writeIndex(rootDir, outFile, selfName = 'mcp-layer') {
+  const next = await buildIndex(rootDir, selfName);
   const current = await readMaybe(outFile);
 
   if (current === next) return;
@@ -193,16 +199,43 @@ export function sortObject(input) {
   return sorted;
 }
 
+/**
+ * Find the workspace root directory by locating pnpm-workspace.yaml.
+ * @param {string} start - Directory to start searching from.
+ * @returns {Promise<string>} Workspace root directory.
+ */
+export async function findWorkspaceRoot(start) {
+  let current = path.resolve(start);
+
+  while (true) {
+    const marker = path.join(current, 'pnpm-workspace.yaml');
+    if (await hasPackageJson(marker)) return current;
+
+    const parent = path.dirname(current);
+    if (parent === current)
+      throw new LayerError({
+        name: 'mcp-layer',
+        method: 'findWorkspaceRoot',
+        message: 'Unable to locate workspace root from mcp-layer package.',
+      });
+
+    current = parent;
+  }
+}
+
 /**
  * Run the generator when executed as a script.
  * @returns {Promise<void>} Resolves when generation completes.
  */
 export async function run() {
-  const rootDir = process.cwd();
-  const outFile = path.join(rootDir, 'src', 'index.js');
-
-  await syncDependencies(rootDir);
-  await writeIndex(rootDir, outFile);
+  const fileDir = path.dirname(fileURLToPath(import.meta.url));
+  const pkgDir = path.resolve(fileDir, '..');
+  const rootDir = await findWorkspaceRoot(pkgDir);
+  const outFile = path.join(pkgDir, 'src', 'index.js');
+  const data = await readJson(path.join(pkgDir, 'package.json'));
+
+  await syncDependencies(pkgDir, rootDir, data.name);
+  await writeIndex(rootDir, outFile, data.name);
 }
 
 const entry = fileURLToPath(import.meta.url);

package/src/generate.test.js

@@ -1,53 +0,0 @@
-import assert from 'node:assert/strict';
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import test from 'node:test';
-import { buildIndex, collectPackageMeta, readJson } from './generate.js';
-
-/**
- * Ensure the generated index.js matches the committed file.
- * @returns {Promise<void>}
- */
-async function matchesGeneratedOutput() {
-  const rootDir = process.cwd();
-  const outFile = path.join(rootDir, 'src', 'index.js');
-  const expected = await buildIndex(rootDir);
-  const actual = await readFile(outFile, 'utf8');
-
-  assert.equal(actual, expected);
-}
-
-test('mcp-layer index matches generator output', matchesGeneratedOutput);
-
-/**
- * Ensure root package.json dependencies include all workspace packages.
- * @returns {Promise<void>}
- */
-async function matchesDependencies() {
-  const rootDir = process.cwd();
-  const pkgPath = path.join(rootDir, 'package.json');
-  const rootPkg = await readJson(pkgPath);
-  const deps = rootPkg.dependencies ?? {};
-  const meta = await collectPackageMeta(rootDir);
-  const names = new Set();
-
-  for (const item of meta) {
-    names.add(item.name);
-    assert.equal(
-      deps[item.name],
-      'workspace:*',
-      `Expected dependency ${item.name} to be set to workspace:*`,
-    );
-  }
-
-  for (const key of Object.keys(deps)) {
-    if (key.startsWith('@mcp-layer/')) {
-      assert.ok(
-        names.has(key),
-        `Expected dependency ${key} to map to a workspace package`,
-      );
-    }
-  }
-}
-
-test('mcp-layer dependencies include workspace packages', matchesDependencies);