mcp-layer 0.0.0 → 0.1.1

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,120 @@
+# 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.
+
+## Table of Contents
+
+- [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)
+
+## 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.
+- **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/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. |
+
+## CLI quick try
+
+If you already have an MCP config on disk, you can try the CLI immediately:
+
+```sh
+mcp-layer servers list
+mcp-layer tools list --server <name>
+mcp-layer tools <tool> --help
+```
+
+## Quick start (end-to-end)
+
+```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 schema = await extract(session);
+console.log(schema.items.map((item) => item.name));
+
+await session.close();
+```
+
+## Design principles
+
+- **Single source of truth**: normalized schemas flow from the MCP server, not from tool-specific parsing.
+- **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.
+
+## Development
+
+```sh
+pnpm install
+pnpm test
+```
+
+## Releasing
+
+We use Changesets to manage versions and a GitHub Actions release workflow to publish packages. In short:
+
+1) Add a changeset: `pnpm changeset`
+2) Merge the Changesets PR
+3) GitHub Actions publishes via npm Trusted Publishing (OIDC)
+
+Before publishing, configure npm Trusted Publishers for each package in the npm registry and ensure the release workflow has `id-token: write` permissions.
+
+The root package runs `prepack` to regenerate `src/index.js` and sync root `package.json` dependencies to the workspace packages before publishing.
+
+See `.github/workflows/release.yml` for the pipeline 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.
+
+## Repository guidelines
+
+See `AGENTS.md` for coding style, testing requirements, and documentation expectations.
+
+## License
+
+MIT

package/package.json

@@ -1,20 +1,59 @@
 {
   "name": "mcp-layer",
-  "version": "0.0.0",
-  "description": "Layers on top of your MCP servers",
+  "version": "0.1.1",
+  "description": "Layers of functionality that can be add to any MCP server. ",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/3rd-Eden/mcp-layer"
+  },
   "keywords": [
-    "layer",
     "mcp",
-    "modelcontextprotocol",
-    "model",
-    "context",
-    "protocol"
+    "layer",
+    "mcp-layer",
+    "communication",
+    "cli",
+    "api",
+    "http",
+    "graphql",
+    "openapi",
+    "swagger",
+    "protocol",
+    "ui",
+    "rendering"
   ],
   "license": "MIT",
   "author": "Arnout Kazemier",
+  "packageManager": "pnpm@8.15.4",
   "type": "module",
-  "main": "index.js",
+  "devDependencies": {
+    "@changesets/cli": "^2.29.2"
+  },
+  "dependencies": {
+    "@mcp-layer/attach": "1.1.1",
+    "@mcp-layer/cli": "1.1.1",
+    "@mcp-layer/config": "1.0.1",
+    "@mcp-layer/connect": "1.0.1",
+    "@mcp-layer/error": "0.2.0",
+    "@mcp-layer/manager": "0.2.0",
+    "@mcp-layer/openapi": "1.1.1",
+    "@mcp-layer/rest": "1.2.0",
+    "@mcp-layer/schema": "1.0.2",
+    "@mcp-layer/session": "1.0.0",
+    "@mcp-layer/test-server": "1.0.1"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.js"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "changeset:publish": "changeset publish"
   }
-}
+}

package/src/generate.js

@@ -0,0 +1,209 @@
+import { access, readFile, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Convert a package folder name into a namespace export name.
+ * @param {string} name - Package folder name.
+ * @returns {string} Namespace export name.
+ */
+export function toNamespace(name) {
+  return name.replace(/-([a-z0-9])/g, function toCamel(_, next) {
+    return next.toUpperCase();
+  });
+}
+
+/**
+ * Collect package folder names from the workspace packages directory.
+ * @param {string} rootDir - Repository root directory.
+ * @returns {Promise<string[]>} Package folder names.
+ */
+export async function collectPackages(rootDir) {
+  const packagesDir = path.join(rootDir, 'packages');
+  const entries = await readdir(packagesDir, { withFileTypes: true });
+  const packages = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const pkgPath = path.join(packagesDir, entry.name, 'package.json');
+    const exists = await hasPackageJson(pkgPath);
+
+    if (exists) packages.push(entry.name);
+  }
+
+  packages.sort();
+  return packages;
+}
+
+/**
+ * Check whether a package.json exists for the given path.
+ * @param {string} pkgPath - Expected package.json path.
+ * @returns {Promise<boolean>} Whether the package.json exists.
+ */
+export async function hasPackageJson(pkgPath) {
+  try {
+    await access(pkgPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build the root index.js content from workspace packages.
+ * @param {string} rootDir - Repository root directory.
+ * @returns {Promise<string>} Generated index.js content.
+ */
+export async function buildIndex(rootDir) {
+  const meta = await collectPackageMeta(rootDir);
+  const lines = [];
+
+  lines.push('/**');
+  lines.push(' * @module mcp-layer');
+  lines.push(' * @description Aggregate entrypoint for the MCP Layer workspace packages.');
+  lines.push(' * @note This file is autogenerated by src/generate.js. Manual edits will be overwritten.');
+  lines.push(' */');
+  lines.push('');
+
+  for (const item of meta) {
+    const namespace = toNamespace(item.dir);
+    const importPath = item.name;
+
+    lines.push('/**');
+    lines.push(` * Package namespace from \`${item.name}\`.`);
+    lines.push(` * @type {typeof import('${importPath}')}`);
+    lines.push(' */');
+    lines.push(`export * as ${namespace} from '${importPath}';`);
+    lines.push('');
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Collect package metadata from workspace folders.
+ * @param {string} rootDir - Repository root directory.
+ * @returns {Promise<Array<{name: string, dir: string}>>} Package metadata.
+ */
+export async function collectPackageMeta(rootDir) {
+  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);
+    meta.push({ name: data.name, dir });
+  }
+
+  return meta;
+}
+
+/**
+ * Update root package.json dependencies to match workspace packages.
+ * @param {string} rootDir - Repository root directory.
+ * @returns {Promise<void>} Resolves when dependencies are updated.
+ */
+export async function syncDependencies(rootDir) {
+  const pkgPath = path.join(rootDir, 'package.json');
+  const data = await readJson(pkgPath);
+  const deps = { ...(data.dependencies ?? {}) };
+  const meta = await collectPackageMeta(rootDir);
+  const names = new Set();
+
+  for (const item of meta) {
+    names.add(item.name);
+    deps[item.name] = 'workspace:*';
+  }
+
+  for (const key of Object.keys(deps)) {
+    if (key.startsWith('@mcp-layer/') && !names.has(key)) delete deps[key];
+  }
+
+  data.dependencies = sortObject(deps);
+  await writeJson(pkgPath, data);
+}
+
+/**
+ * Write the generated index.js file if contents differ.
+ * @param {string} rootDir - Repository root directory.
+ * @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);
+  const current = await readMaybe(outFile);
+
+  if (current === next) return;
+
+  await writeFile(outFile, next, 'utf8');
+}
+
+/**
+ * Read a file if it exists, otherwise return null.
+ * @param {string} filePath - File path to read.
+ * @returns {Promise<string | null>} File contents or null.
+ */
+export async function readMaybe(filePath) {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read and parse a JSON file.
+ * @param {string} filePath - JSON file path.
+ * @returns {Promise<Record<string, any>>} Parsed JSON data.
+ */
+export async function readJson(filePath) {
+  const raw = await readFile(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Write a JSON file with stable formatting.
+ * @param {string} filePath - JSON file path.
+ * @param {Record<string, any>} data - JSON data to write.
+ * @returns {Promise<void>} Resolves when the file is written.
+ */
+export async function writeJson(filePath, data) {
+  const next = `${JSON.stringify(data, null, 2)}\n`;
+  const current = await readMaybe(filePath);
+
+  if (current === next) return;
+
+  await writeFile(filePath, next, 'utf8');
+}
+
+/**
+ * Sort an object's keys alphabetically.
+ * @param {Record<string, string>} input - Object to sort.
+ * @returns {Record<string, string>} Sorted object.
+ */
+export function sortObject(input) {
+  const keys = Object.keys(input).sort();
+  const sorted = {};
+
+  for (const key of keys) {
+    sorted[key] = input[key];
+  }
+
+  return sorted;
+}
+
+/**
+ * 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 entry = fileURLToPath(import.meta.url);
+if (process.argv[1] === entry) run();

package/src/generate.test.js

@@ -0,0 +1,53 @@
+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);

package/src/index.js

@@ -0,0 +1,72 @@
+/**
+ * @module mcp-layer
+ * @description Aggregate entrypoint for the MCP Layer workspace packages.
+ * @note This file is autogenerated by src/generate.js. Manual edits will be overwritten.
+ */
+
+/**
+ * Package namespace from `@mcp-layer/attach`.
+ * @type {typeof import('@mcp-layer/attach')}
+ */
+export * as attach from '@mcp-layer/attach';
+
+/**
+ * Package namespace from `@mcp-layer/cli`.
+ * @type {typeof import('@mcp-layer/cli')}
+ */
+export * as cli from '@mcp-layer/cli';
+
+/**
+ * Package namespace from `@mcp-layer/config`.
+ * @type {typeof import('@mcp-layer/config')}
+ */
+export * as config from '@mcp-layer/config';
+
+/**
+ * Package namespace from `@mcp-layer/connect`.
+ * @type {typeof import('@mcp-layer/connect')}
+ */
+export * as connect from '@mcp-layer/connect';
+
+/**
+ * Package namespace from `@mcp-layer/error`.
+ * @type {typeof import('@mcp-layer/error')}
+ */
+export * as error from '@mcp-layer/error';
+
+/**
+ * Package namespace from `@mcp-layer/manager`.
+ * @type {typeof import('@mcp-layer/manager')}
+ */
+export * as manager from '@mcp-layer/manager';
+
+/**
+ * Package namespace from `@mcp-layer/openapi`.
+ * @type {typeof import('@mcp-layer/openapi')}
+ */
+export * as openapi from '@mcp-layer/openapi';
+
+/**
+ * Package namespace from `@mcp-layer/rest`.
+ * @type {typeof import('@mcp-layer/rest')}
+ */
+export * as rest from '@mcp-layer/rest';
+
+/**
+ * Package namespace from `@mcp-layer/schema`.
+ * @type {typeof import('@mcp-layer/schema')}
+ */
+export * as schema from '@mcp-layer/schema';
+
+/**
+ * Package namespace from `@mcp-layer/session`.
+ * @type {typeof import('@mcp-layer/session')}
+ */
+export * as session from '@mcp-layer/session';
+
+/**
+ * Package namespace from `@mcp-layer/test-server`.
+ * @type {typeof import('@mcp-layer/test-server')}
+ */
+export * as testServer from '@mcp-layer/test-server';
+