@webpieces/mcp-server 0.4.811 → 0.4.812

package/README.md

@@ -1,8 +1,8 @@
 # @webpieces/mcp-server
 
 Publishes explicitly annotated Webpieces RPC endpoints as MCP tools. The bridge is HANDED the input
-and output JSON Schema — the build extracts them from the contract source and writes `mcp-tools.json`
-— invokes the normal Webpieces filter/controller path, and turns exceptions into safe model-visible
+and output JSON Schema — the build extracts them from the contract source and writes one
+`mcp-<ContractClass>-tools.json` per contract — invokes the normal Webpieces filter/controller path, and turns exceptions into safe model-visible
 MCP results.
 
 `@WpMcpTool` is an opt-in and every tool must also declare `@WpMcpAuthJwt`. MCP user
@@ -51,21 +51,27 @@ Every `@Endpoint` declares one enum-backed operation, independent of its require
 argument: a GET may deliberately write and a POST may be a read. A tool therefore cannot claim to be
 read-only while its endpoint declares `WRITE` — the contradiction is unrepresentable.
 
-## Booting: the server is constructed with the generated catalog
+## Booting: the server is constructed with the generated catalogs
 
-```bash
-wp-openapi --manifest openapi.manifest.json --out dist
-```
-
-writes `mcp-tools.json` beside the OpenAPI documents. Hand it to `McpBindOptions`:
+The api library's build (its `openapi-generate` target — tag the library `generate:openapi`) writes one
+`mcp-<ContractClass>-tools.json` per MCP contract into its build output, beside the OpenAPI documents.
+Hand them to `McpBindOptions` with ONE call that works in every environment:
 
 ```ts
-const catalog = McpToolCatalog.fromJsonText(fs.readFileSync('dist/mcp-tools.json', 'utf8'));
-server.bind(app, new McpBindOptions(path, bindings, catalog, McpDeployment.singleProcess()));
+const catalogs = McpToolCatalog.fromPackages(['@myorg/my-apis'], __dirname);
+server.bind(app, new McpBindOptions(path, bindings, catalogs, McpDeployment.singleProcess()));
 ```
 
-`McpToolRegistry` FAILS FAST at boot when a registered `@WpMcpTool` is absent from the catalog: a tool
-the build never saw is a tool whose schema nobody checked. Tool arguments and structured output are
+`fromPackages` resolves each package from `__dirname` the way node does. A BUILT or published package
+(a Docker image relinking `node_modules/@myorg/*` onto `dist/`) holds the files beside its
+`package.json`; a workspace SOURCE directory (pnpm linking onto `libraries/...` for local dev and
+vitest) holds a `project.json`, and the files are read from the outputPath of the target its
+`openapi-generate` dependsOn — which is why a server's `test` target must dependsOn `^build`.
+
+`McpToolRegistry` FAILS FAST at boot, naming every directory the catalogs were read from, when a bound
+contract has no catalog, a catalog's contract is not bound, or a tool name is declared twice — and when
+a registered `@WpMcpTool` is absent from its contract's catalog: a tool the build never saw is a tool
+whose schema nobody checked. Tool arguments and structured output are
 validated against those same schemas by `ApiJsonSchemaValidator`, so the shape an agent is shown and
 the shape the server accepts are the same bytes rather than two derivations of one contract.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/mcp-server",
-  "version": "0.4.811",
+  "version": "0.4.812",
   "description": "Secure MCP tool generation from annotated Webpieces API contracts",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -24,15 +24,15 @@
   "dependencies": {
     "@modelcontextprotocol/node": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
-    "@webpieces/core-context": "0.4.811",
-    "@webpieces/core-util": "0.4.811",
-    "@webpieces/http-routing": "0.4.811",
-    "@webpieces/http-server": "0.4.811",
+    "@webpieces/core-context": "0.4.812",
+    "@webpieces/core-util": "0.4.812",
+    "@webpieces/http-routing": "0.4.812",
+    "@webpieces/http-server": "0.4.812",
     "express": "5.1.0",
     "reflect-metadata": "0.2.2",
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "@webpieces/http-client-node": "0.4.811"
+    "@webpieces/http-client-node": "0.4.812"
   }
 }

package/src/McpBindOptions.d.ts

@@ -1,16 +1,18 @@
-import { McpToolCatalog } from '@webpieces/core-util';
 import { McpApiBinding } from './McpApiBinding';
 import { McpDeployment } from './McpDeployment';
+import { McpToolCatalog } from './McpToolCatalog';
 export declare class McpBindOptions {
     /** Supplied by the application/discovery config; Webpieces never assumes `/mcp`. */
     readonly endpointPath: string;
     readonly bindings: readonly McpApiBinding[];
     /**
-     * The tools this build published — `mcp-tools.json`, written by `wp-openapi` and read with
-     * `McpToolCatalog.fromJsonText`. It is REQUIRED because it is the only source of a tool's
-     * documentation and schemas; there is no reflect-metadata fallback to fall back to.
+     * The tools the build published — ONE catalog per bound contract, each the
+     * `mcp-<ContractClass>-tools.json` `wp-openapi` wrote beside its library's OpenAPI documents,
+     * read with `McpToolCatalog.fromPackages([...], __dirname)`. REQUIRED because it is the only
+     * source of a tool's documentation and schemas; there is no reflect-metadata fallback.
+     * `McpToolRegistry` refuses to boot unless it holds exactly one catalog per bound contract.
      */
-    readonly toolCatalog: McpToolCatalog;
+    readonly toolCatalogs: readonly McpToolCatalog[];
     readonly deployment: McpDeployment;
     /** Requests without Origin remain valid for non-browser MCP clients. */
     readonly allowedOrigins: readonly string[];
@@ -20,11 +22,13 @@ export declare class McpBindOptions {
     /** Supplied by the application/discovery config; Webpieces never assumes `/mcp`. */
     endpointPath: string, bindings: readonly McpApiBinding[], 
     /**
-     * The tools this build published — `mcp-tools.json`, written by `wp-openapi` and read with
-     * `McpToolCatalog.fromJsonText`. It is REQUIRED because it is the only source of a tool's
-     * documentation and schemas; there is no reflect-metadata fallback to fall back to.
+     * The tools the build published — ONE catalog per bound contract, each the
+     * `mcp-<ContractClass>-tools.json` `wp-openapi` wrote beside its library's OpenAPI documents,
+     * read with `McpToolCatalog.fromPackages([...], __dirname)`. REQUIRED because it is the only
+     * source of a tool's documentation and schemas; there is no reflect-metadata fallback.
+     * `McpToolRegistry` refuses to boot unless it holds exactly one catalog per bound contract.
      */
-    toolCatalog: McpToolCatalog, deployment: McpDeployment, 
+    toolCatalogs: readonly McpToolCatalog[], deployment: McpDeployment, 
     /** Requests without Origin remain valid for non-browser MCP clients. */
     allowedOrigins?: readonly string[], maxSubscriptions?: number, keepAliveMs?: number);
 }

package/src/McpBindOptions.js

@@ -4,7 +4,7 @@ exports.McpBindOptions = void 0;
 class McpBindOptions {
     endpointPath;
     bindings;
-    toolCatalog;
+    toolCatalogs;
     deployment;
     allowedOrigins;
     maxSubscriptions;
@@ -13,16 +13,18 @@ class McpBindOptions {
     /** Supplied by the application/discovery config; Webpieces never assumes `/mcp`. */
     endpointPath, bindings, 
     /**
-     * The tools this build published — `mcp-tools.json`, written by `wp-openapi` and read with
-     * `McpToolCatalog.fromJsonText`. It is REQUIRED because it is the only source of a tool's
-     * documentation and schemas; there is no reflect-metadata fallback to fall back to.
+     * The tools the build published — ONE catalog per bound contract, each the
+     * `mcp-<ContractClass>-tools.json` `wp-openapi` wrote beside its library's OpenAPI documents,
+     * read with `McpToolCatalog.fromPackages([...], __dirname)`. REQUIRED because it is the only
+     * source of a tool's documentation and schemas; there is no reflect-metadata fallback.
+     * `McpToolRegistry` refuses to boot unless it holds exactly one catalog per bound contract.
      */
-    toolCatalog, deployment, 
+    toolCatalogs, deployment, 
     /** Requests without Origin remain valid for non-browser MCP clients. */
     allowedOrigins = [], maxSubscriptions = 1024, keepAliveMs = 15_000) {
         this.endpointPath = endpointPath;
         this.bindings = bindings;
-        this.toolCatalog = toolCatalog;
+        this.toolCatalogs = toolCatalogs;
         this.deployment = deployment;
         this.allowedOrigins = allowedOrigins;
         this.maxSubscriptions = maxSubscriptions;

package/src/McpBindOptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"McpBindOptions.js","sourceRoot":"","sources":["../../../../../packages/http/mcp-server/src/McpBindOptions.ts"],"names":[],"mappings":";;;AAIA,MAAa,cAAc;IAGH;IACA;IAMA;IACA;IAEA;IACA;IACA;IAdpB;IACI,oFAAoF;IACpE,YAAoB,EACpB,QAAkC;IAClD;;;;OAIG;IACa,WAA2B,EAC3B,UAAyB;IACzC,wEAAwE;IACxD,iBAAoC,EAAE,EACtC,mBAAmB,IAAI,EACvB,cAAc,MAAM;QAZpB,iBAAY,GAAZ,YAAY,CAAQ;QACpB,aAAQ,GAAR,QAAQ,CAA0B;QAMlC,gBAAW,GAAX,WAAW,CAAgB;QAC3B,eAAU,GAAV,UAAU,CAAe;QAEzB,mBAAc,GAAd,cAAc,CAAwB;QACtC,qBAAgB,GAAhB,gBAAgB,CAAO;QACvB,gBAAW,GAAX,WAAW,CAAS;QAEpC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;QACzF,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACvE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,gBAAgB,CAAC,IAAI,gBAAgB,IAAI,CAAC,EAAE,CAAC;YAC/D,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QAC1E,CAAC;IACL,CAAC;CACJ;AA7BD,wCA6BC","sourcesContent":["import { McpToolCatalog } from '@webpieces/core-util';\nimport { McpApiBinding } from './McpApiBinding';\nimport { McpDeployment } from './McpDeployment';\n\nexport class McpBindOptions {\n    constructor(\n        /** Supplied by the application/discovery config; Webpieces never assumes `/mcp`. */\n        public readonly endpointPath: string,\n        public readonly bindings: readonly McpApiBinding[],\n        /**\n         * The tools this build published — `mcp-tools.json`, written by `wp-openapi` and read with\n         * `McpToolCatalog.fromJsonText`. It is REQUIRED because it is the only source of a tool's\n         * documentation and schemas; there is no reflect-metadata fallback to fall back to.\n         */\n        public readonly toolCatalog: McpToolCatalog,\n        public readonly deployment: McpDeployment,\n        /** Requests without Origin remain valid for non-browser MCP clients. */\n        public readonly allowedOrigins: readonly string[] = [],\n        public readonly maxSubscriptions = 1024,\n        public readonly keepAliveMs = 15_000,\n    ) {\n        if (!endpointPath.startsWith('/') || endpointPath.includes('?')) {\n            throw new Error('MCP endpointPath must be an absolute path without a query string.');\n        }\n        if (bindings.length === 0)\n            throw new Error('MCP binding requires at least one API contract.');\n        if (!Number.isInteger(maxSubscriptions) || maxSubscriptions <= 0) {\n            throw new Error('MCP maxSubscriptions must be a positive integer.');\n        }\n        if (!Number.isFinite(keepAliveMs) || keepAliveMs < 0) {\n            throw new Error('MCP keepAliveMs must be zero or a positive number.');\n        }\n    }\n}\n"]}
+{"version":3,"file":"McpBindOptions.js","sourceRoot":"","sources":["../../../../../packages/http/mcp-server/src/McpBindOptions.ts"],"names":[],"mappings":";;;AAIA,MAAa,cAAc;IAGH;IACA;IAQA;IACA;IAEA;IACA;IACA;IAhBpB;IACI,oFAAoF;IACpE,YAAoB,EACpB,QAAkC;IAClD;;;;;;OAMG;IACa,YAAuC,EACvC,UAAyB;IACzC,wEAAwE;IACxD,iBAAoC,EAAE,EACtC,mBAAmB,IAAI,EACvB,cAAc,MAAM;QAdpB,iBAAY,GAAZ,YAAY,CAAQ;QACpB,aAAQ,GAAR,QAAQ,CAA0B;QAQlC,iBAAY,GAAZ,YAAY,CAA2B;QACvC,eAAU,GAAV,UAAU,CAAe;QAEzB,mBAAc,GAAd,cAAc,CAAwB;QACtC,qBAAgB,GAAhB,gBAAgB,CAAO;QACvB,gBAAW,GAAX,WAAW,CAAS;QAEpC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;QACzF,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACvE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,gBAAgB,CAAC,IAAI,gBAAgB,IAAI,CAAC,EAAE,CAAC;YAC/D,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QAC1E,CAAC;IACL,CAAC;CACJ;AA/BD,wCA+BC","sourcesContent":["import { McpApiBinding } from './McpApiBinding';\nimport { McpDeployment } from './McpDeployment';\nimport { McpToolCatalog } from './McpToolCatalog';\n\nexport class McpBindOptions {\n    constructor(\n        /** Supplied by the application/discovery config; Webpieces never assumes `/mcp`. */\n        public readonly endpointPath: string,\n        public readonly bindings: readonly McpApiBinding[],\n        /**\n         * The tools the build published — ONE catalog per bound contract, each the\n         * `mcp-<ContractClass>-tools.json` `wp-openapi` wrote beside its library's OpenAPI documents,\n         * read with `McpToolCatalog.fromPackages([...], __dirname)`. REQUIRED because it is the only\n         * source of a tool's documentation and schemas; there is no reflect-metadata fallback.\n         * `McpToolRegistry` refuses to boot unless it holds exactly one catalog per bound contract.\n         */\n        public readonly toolCatalogs: readonly McpToolCatalog[],\n        public readonly deployment: McpDeployment,\n        /** Requests without Origin remain valid for non-browser MCP clients. */\n        public readonly allowedOrigins: readonly string[] = [],\n        public readonly maxSubscriptions = 1024,\n        public readonly keepAliveMs = 15_000,\n    ) {\n        if (!endpointPath.startsWith('/') || endpointPath.includes('?')) {\n            throw new Error('MCP endpointPath must be an absolute path without a query string.');\n        }\n        if (bindings.length === 0)\n            throw new Error('MCP binding requires at least one API contract.');\n        if (!Number.isInteger(maxSubscriptions) || maxSubscriptions <= 0) {\n            throw new Error('MCP maxSubscriptions must be a positive integer.');\n        }\n        if (!Number.isFinite(keepAliveMs) || keepAliveMs < 0) {\n            throw new Error('MCP keepAliveMs must be zero or a positive number.');\n        }\n    }\n}\n"]}

package/src/McpToolCatalog.d.ts

@@ -0,0 +1,47 @@
+import { McpToolCatalogFile, McpToolDefinition } from '@webpieces/core-util';
+/**
+ * ONE contract's MCP tools as a server boots them: the generated `mcp-<ContractClass>-tools.json`, and
+ * the directory it was read from, so a boot refusal can name every directory it searched.
+ *
+ * `WpMcpServer` is handed a LIST of these (`McpBindOptions.toolCatalogs`), and `McpToolRegistry` checks
+ * each `McpApiBinding` against the catalog of exactly its own contract (#1021).
+ *
+ * Build them with {@link McpToolCatalog.fromPackages}, the one call that works in every environment a
+ * server runs in. The constructor is for a spec that hands the server catalogs it built in memory.
+ */
+export declare class McpToolCatalog {
+    readonly file: McpToolCatalogFile;
+    /** Where it was read from — an absolute directory, or a label for a catalog built in memory. */
+    readonly directory: string;
+    constructor(file: McpToolCatalogFile, 
+    /** Where it was read from — an absolute directory, or a label for a catalog built in memory. */
+    directory: string);
+    get contractName(): string;
+    find(name: string): McpToolDefinition | undefined;
+    names(): readonly string[];
+    /**
+     * Every MCP tool catalog the named api-library packages carry — ONE call, in every environment:
+     *
+     * ```typescript
+     * McpToolCatalog.fromPackages(['@myorg/lang-website-apis'], __dirname)
+     * ```
+     *
+     * Each package is found the way node's own resolution finds it: `node_modules/<pkg>` in
+     * `resolveFrom` and every directory above it, symlinks followed. What that directory holds decides
+     * where the files are:
+     *
+     * - `mcp-*-tools.json` beside its `package.json` → a BUILT or PUBLISHED package (a Docker image that
+     *   relinks `node_modules/@myorg/*` onto `dist/libraries/**`, or an npm consumer) → read them there;
+     * - a `project.json` → a workspace SOURCE directory (pnpm links `node_modules/@myorg/x` onto
+     *   `libraries/.../x` for local dev and vitest) → read the `outputPath` of the target its
+     *   `openapi-generate` dependsOn, resolved against the nx workspace root (found by walking up to
+     *   `nx.json`), and read the files there. That is the SAME lookup the executor used to decide where
+     *   to write them (`GeneratedApiDocsLayout`).
+     *
+     * @param resolveFrom where node resolution starts — pass `__dirname` of the calling file. It is
+     *   required because the right answer is the CALLER's `node_modules`: in a pnpm workspace the api
+     *   library is linked into the server project's own `node_modules`, which neither the process's cwd
+     *   nor this package's install location can see.
+     */
+    static fromPackages(packages: readonly string[], resolveFrom: string): McpToolCatalog[];
+}

package/src/McpToolCatalog.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpToolCatalog = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const core_util_1 = require("@webpieces/core-util");
+/** How every catalog failure is fixed: build the api library, whose `openapi-generate` writes them. */
+const BUILD_IT = 'Build the api library that declares the contracts (`nx run <api-lib>:build`, which runs its ' +
+    '`openapi-generate` target) — or, for a spec that boots the MCP server, give its `test` target ' +
+    '`"dependsOn": ["^build"]` so the library is built first.';
+/**
+ * ONE contract's MCP tools as a server boots them: the generated `mcp-<ContractClass>-tools.json`, and
+ * the directory it was read from, so a boot refusal can name every directory it searched.
+ *
+ * `WpMcpServer` is handed a LIST of these (`McpBindOptions.toolCatalogs`), and `McpToolRegistry` checks
+ * each `McpApiBinding` against the catalog of exactly its own contract (#1021).
+ *
+ * Build them with {@link McpToolCatalog.fromPackages}, the one call that works in every environment a
+ * server runs in. The constructor is for a spec that hands the server catalogs it built in memory.
+ */
+class McpToolCatalog {
+    file;
+    directory;
+    constructor(file, 
+    /** Where it was read from — an absolute directory, or a label for a catalog built in memory. */
+    directory) {
+        this.file = file;
+        this.directory = directory;
+    }
+    get contractName() {
+        return this.file.contractName;
+    }
+    find(name) {
+        return this.file.find(name);
+    }
+    names() {
+        return this.file.names();
+    }
+    /**
+     * Every MCP tool catalog the named api-library packages carry — ONE call, in every environment:
+     *
+     * ```typescript
+     * McpToolCatalog.fromPackages(['@myorg/lang-website-apis'], __dirname)
+     * ```
+     *
+     * Each package is found the way node's own resolution finds it: `node_modules/<pkg>` in
+     * `resolveFrom` and every directory above it, symlinks followed. What that directory holds decides
+     * where the files are:
+     *
+     * - `mcp-*-tools.json` beside its `package.json` → a BUILT or PUBLISHED package (a Docker image that
+     *   relinks `node_modules/@myorg/*` onto `dist/libraries/**`, or an npm consumer) → read them there;
+     * - a `project.json` → a workspace SOURCE directory (pnpm links `node_modules/@myorg/x` onto
+     *   `libraries/.../x` for local dev and vitest) → read the `outputPath` of the target its
+     *   `openapi-generate` dependsOn, resolved against the nx workspace root (found by walking up to
+     *   `nx.json`), and read the files there. That is the SAME lookup the executor used to decide where
+     *   to write them (`GeneratedApiDocsLayout`).
+     *
+     * @param resolveFrom where node resolution starts — pass `__dirname` of the calling file. It is
+     *   required because the right answer is the CALLER's `node_modules`: in a pnpm workspace the api
+     *   library is linked into the server project's own `node_modules`, which neither the process's cwd
+     *   nor this package's install location can see.
+     */
+    // webpieces-disable no-function-outside-class -- static factory of this class
+    static fromPackages(packages, resolveFrom) {
+        if (packages.length === 0) {
+            throw new core_util_1.McpToolCatalogError('McpToolCatalog.fromPackages was given no packages.', "Name every api library whose contracts this server binds, e.g. fromPackages(['@myorg/my-apis'], __dirname).");
+        }
+        const loader = new McpPackageCatalogs(resolveFrom);
+        return packages.flatMap((packageName) => loader.load(packageName));
+    }
+}
+exports.McpToolCatalog = McpToolCatalog;
+/** The filesystem half of {@link McpToolCatalog.fromPackages}: resolve, classify, read. */
+class McpPackageCatalogs {
+    resolveFrom;
+    constructor(resolveFrom) {
+        this.resolveFrom = resolveFrom;
+    }
+    load(packageName) {
+        const packageDir = this.resolve(packageName);
+        if (this.catalogFiles(packageDir).length > 0) {
+            return this.read(packageName, packageDir, packageDir);
+        }
+        if (fs.existsSync(path.join(packageDir, 'project.json'))) {
+            return this.read(packageName, packageDir, this.outputDirOfSource(packageName, packageDir));
+        }
+        throw new core_util_1.McpToolCatalogError(`${packageName} resolved to ${packageDir}, which holds neither an mcp-<ContractClass>-tools.json ` +
+            '(a built package) nor a project.json (a workspace source directory).', BUILD_IT);
+    }
+    /** `<dir>/node_modules/<pkg>/package.json` in `resolveFrom` and every parent — node's own walk. */
+    resolve(packageName) {
+        const searched = [];
+        let dir = path.resolve(this.resolveFrom);
+        for (;;) {
+            const candidate = path.join(dir, 'node_modules', ...packageName.split('/'));
+            searched.push(candidate);
+            if (fs.existsSync(path.join(candidate, 'package.json')))
+                return fs.realpathSync(candidate);
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        throw new core_util_1.McpToolCatalogError(`${packageName} is not installed where the MCP server can see it. Searched:\n` +
+            searched.map((each) => `  ${each}`).join('\n'), `Add ${packageName} as a dependency of the server project, and pass the calling file's ` +
+            '__dirname as fromPackages(...)\'s resolveFrom.');
+    }
+    /**
+     * A workspace SOURCE directory: the outputPath of the target its `openapi-generate` dependsOn,
+     * against the workspace root — never an assumed `dist/`.
+     */
+    outputDirOfSource(packageName, packageDir) {
+        const workspaceRoot = this.workspaceRootAbove(packageName, packageDir);
+        const project = JSON.parse(fs.readFileSync(path.join(packageDir, 'project.json'), 'utf8'));
+        const projectRoot = path.relative(workspaceRoot, packageDir).split(path.sep).join('/');
+        const lookup = new core_util_1.GeneratedApiDocsLayout(projectRoot, project.name ?? projectRoot, project.targets ?? {})
+            .outputTarget();
+        if (lookup.found === undefined) {
+            throw new core_util_1.McpToolCatalogError(`${packageName} is the workspace source directory ${packageDir}, and its generated MCP tool ` +
+                `catalogs cannot be located: ${lookup.problem.problem}`, lookup.problem.cure);
+        }
+        return path.resolve(workspaceRoot, lookup.found.outputPath);
+    }
+    workspaceRootAbove(packageName, packageDir) {
+        let dir = packageDir;
+        for (;;) {
+            if (fs.existsSync(path.join(dir, 'nx.json')))
+                return dir;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        throw new core_util_1.McpToolCatalogError(`${packageName} resolved to ${packageDir}, which has a project.json but no nx.json above it, ` +
+            'so there is no nx workspace to resolve its build outputPath against.', 'Link the BUILT package instead (its directory holds the mcp-<ContractClass>-tools.json files).');
+    }
+    read(packageName, packageDir, dir) {
+        const files = this.catalogFiles(dir);
+        if (files.length === 0) {
+            throw new core_util_1.McpToolCatalogError(`${packageName} (${packageDir}) has no mcp-<ContractClass>-tools.json in ${dir}` +
+                (fs.existsSync(dir) ? '.' : ' — the directory does not exist, so the library was never built.'), BUILD_IT);
+        }
+        return files.map((file) => new McpToolCatalog(core_util_1.McpToolCatalogFile.fromJsonText(file, fs.readFileSync(path.join(dir, file), 'utf8')), dir));
+    }
+    catalogFiles(dir) {
+        if (!fs.existsSync(dir))
+            return [];
+        return fs
+            .readdirSync(dir)
+            .filter((file) => core_util_1.McpToolCatalogFile.contractNameOf(file) !== undefined)
+            .sort();
+    }
+}
+//# sourceMappingURL=McpToolCatalog.js.map

package/src/McpToolCatalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpToolCatalog.js","sourceRoot":"","sources":["../../../../../packages/http/mcp-server/src/McpToolCatalog.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport {\n    GeneratedApiDocsLayout,\n    LayoutTargets,\n    McpToolCatalogError,\n    McpToolCatalogFile,\n    McpToolDefinition,\n} from '@webpieces/core-util';\n\n/** How every catalog failure is fixed: build the api library, whose `openapi-generate` writes them. */\nconst BUILD_IT =\n    'Build the api library that declares the contracts (`nx run <api-lib>:build`, which runs its ' +\n    '`openapi-generate` target) — or, for a spec that boots the MCP server, give its `test` target ' +\n    '`\"dependsOn\": [\"^build\"]` so the library is built first.';\n\n/** The two fields of an nx `project.json` this loader reads. */\ntype ProjectJson = { readonly name?: string; readonly targets?: LayoutTargets };\n\n/**\n * ONE contract's MCP tools as a server boots them: the generated `mcp-<ContractClass>-tools.json`, and\n * the directory it was read from, so a boot refusal can name every directory it searched.\n *\n * `WpMcpServer` is handed a LIST of these (`McpBindOptions.toolCatalogs`), and `McpToolRegistry` checks\n * each `McpApiBinding` against the catalog of exactly its own contract (#1021).\n *\n * Build them with {@link McpToolCatalog.fromPackages}, the one call that works in every environment a\n * server runs in. The constructor is for a spec that hands the server catalogs it built in memory.\n */\nexport class McpToolCatalog {\n    constructor(\n        readonly file: McpToolCatalogFile,\n        /** Where it was read from — an absolute directory, or a label for a catalog built in memory. */\n        readonly directory: string,\n    ) {}\n\n    get contractName(): string {\n        return this.file.contractName;\n    }\n\n    find(name: string): McpToolDefinition | undefined {\n        return this.file.find(name);\n    }\n\n    names(): readonly string[] {\n        return this.file.names();\n    }\n\n    /**\n     * Every MCP tool catalog the named api-library packages carry — ONE call, in every environment:\n     *\n     * ```typescript\n     * McpToolCatalog.fromPackages(['@myorg/lang-website-apis'], __dirname)\n     * ```\n     *\n     * Each package is found the way node's own resolution finds it: `node_modules/<pkg>` in\n     * `resolveFrom` and every directory above it, symlinks followed. What that directory holds decides\n     * where the files are:\n     *\n     * - `mcp-*-tools.json` beside its `package.json` → a BUILT or PUBLISHED package (a Docker image that\n     *   relinks `node_modules/@myorg/*` onto `dist/libraries/**`, or an npm consumer) → read them there;\n     * - a `project.json` → a workspace SOURCE directory (pnpm links `node_modules/@myorg/x` onto\n     *   `libraries/.../x` for local dev and vitest) → read the `outputPath` of the target its\n     *   `openapi-generate` dependsOn, resolved against the nx workspace root (found by walking up to\n     *   `nx.json`), and read the files there. That is the SAME lookup the executor used to decide where\n     *   to write them (`GeneratedApiDocsLayout`).\n     *\n     * @param resolveFrom where node resolution starts — pass `__dirname` of the calling file. It is\n     *   required because the right answer is the CALLER's `node_modules`: in a pnpm workspace the api\n     *   library is linked into the server project's own `node_modules`, which neither the process's cwd\n     *   nor this package's install location can see.\n     */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static fromPackages(packages: readonly string[], resolveFrom: string): McpToolCatalog[] {\n        if (packages.length === 0) {\n            throw new McpToolCatalogError(\n                'McpToolCatalog.fromPackages was given no packages.',\n                \"Name every api library whose contracts this server binds, e.g. fromPackages(['@myorg/my-apis'], __dirname).\",\n            );\n        }\n        const loader = new McpPackageCatalogs(resolveFrom);\n        return packages.flatMap((packageName: string) => loader.load(packageName));\n    }\n}\n\n/** The filesystem half of {@link McpToolCatalog.fromPackages}: resolve, classify, read. */\nclass McpPackageCatalogs {\n    constructor(private readonly resolveFrom: string) {}\n\n    load(packageName: string): McpToolCatalog[] {\n        const packageDir = this.resolve(packageName);\n        if (this.catalogFiles(packageDir).length > 0) {\n            return this.read(packageName, packageDir, packageDir);\n        }\n        if (fs.existsSync(path.join(packageDir, 'project.json'))) {\n            return this.read(packageName, packageDir, this.outputDirOfSource(packageName, packageDir));\n        }\n        throw new McpToolCatalogError(\n            `${packageName} resolved to ${packageDir}, which holds neither an mcp-<ContractClass>-tools.json ` +\n                '(a built package) nor a project.json (a workspace source directory).',\n            BUILD_IT,\n        );\n    }\n\n    /** `<dir>/node_modules/<pkg>/package.json` in `resolveFrom` and every parent — node's own walk. */\n    private resolve(packageName: string): string {\n        const searched: string[] = [];\n        let dir = path.resolve(this.resolveFrom);\n        for (;;) {\n            const candidate = path.join(dir, 'node_modules', ...packageName.split('/'));\n            searched.push(candidate);\n            if (fs.existsSync(path.join(candidate, 'package.json'))) return fs.realpathSync(candidate);\n            const parent = path.dirname(dir);\n            if (parent === dir) break;\n            dir = parent;\n        }\n        throw new McpToolCatalogError(\n            `${packageName} is not installed where the MCP server can see it. Searched:\\n` +\n                searched.map((each: string) => `  ${each}`).join('\\n'),\n            `Add ${packageName} as a dependency of the server project, and pass the calling file's ` +\n                '__dirname as fromPackages(...)\\'s resolveFrom.',\n        );\n    }\n\n    /**\n     * A workspace SOURCE directory: the outputPath of the target its `openapi-generate` dependsOn,\n     * against the workspace root — never an assumed `dist/`.\n     */\n    private outputDirOfSource(packageName: string, packageDir: string): string {\n        const workspaceRoot = this.workspaceRootAbove(packageName, packageDir);\n        const project = JSON.parse(fs.readFileSync(path.join(packageDir, 'project.json'), 'utf8')) as ProjectJson;\n        const projectRoot = path.relative(workspaceRoot, packageDir).split(path.sep).join('/');\n        const lookup = new GeneratedApiDocsLayout(projectRoot, project.name ?? projectRoot, project.targets ?? {})\n            .outputTarget();\n        if (lookup.found === undefined) {\n            throw new McpToolCatalogError(\n                `${packageName} is the workspace source directory ${packageDir}, and its generated MCP tool ` +\n                    `catalogs cannot be located: ${lookup.problem!.problem}`,\n                lookup.problem!.cure,\n            );\n        }\n        return path.resolve(workspaceRoot, lookup.found.outputPath);\n    }\n\n    private workspaceRootAbove(packageName: string, packageDir: string): string {\n        let dir = packageDir;\n        for (;;) {\n            if (fs.existsSync(path.join(dir, 'nx.json'))) return dir;\n            const parent = path.dirname(dir);\n            if (parent === dir) break;\n            dir = parent;\n        }\n        throw new McpToolCatalogError(\n            `${packageName} resolved to ${packageDir}, which has a project.json but no nx.json above it, ` +\n                'so there is no nx workspace to resolve its build outputPath against.',\n            'Link the BUILT package instead (its directory holds the mcp-<ContractClass>-tools.json files).',\n        );\n    }\n\n    private read(packageName: string, packageDir: string, dir: string): McpToolCatalog[] {\n        const files = this.catalogFiles(dir);\n        if (files.length === 0) {\n            throw new McpToolCatalogError(\n                `${packageName} (${packageDir}) has no mcp-<ContractClass>-tools.json in ${dir}` +\n                    (fs.existsSync(dir) ? '.' : ' — the directory does not exist, so the library was never built.'),\n                BUILD_IT,\n            );\n        }\n        return files.map(\n            (file: string) =>\n                new McpToolCatalog(\n                    McpToolCatalogFile.fromJsonText(file, fs.readFileSync(path.join(dir, file), 'utf8')),\n                    dir,\n                ),\n        );\n    }\n\n    private catalogFiles(dir: string): string[] {\n        if (!fs.existsSync(dir)) return [];\n        return fs\n            .readdirSync(dir)\n            .filter((file: string) => McpToolCatalogFile.contractNameOf(file) !== undefined)\n            .sort();\n    }\n}\n"]}

package/src/McpToolRegistry.d.ts

@@ -1,6 +1,7 @@
-import { ApiJsonSchema, AuthMeta, EndpointOperation, McpToolCatalog, WpMcpJwtAuthMetadata, WpMcpToolHints } from '@webpieces/core-util';
+import { ApiJsonSchema, AuthMeta, EndpointOperation, WpMcpJwtAuthMetadata, WpMcpToolHints } from '@webpieces/core-util';
 import { ClassType } from '@webpieces/http-routing';
 import { McpApiBinding } from './McpApiBinding';
+import { McpToolCatalog } from './McpToolCatalog';
 /** Fully resolved contract metadata for one MCP tool. */
 export declare class RegisteredMcpTool {
     readonly apiClass: ClassType;
@@ -20,7 +21,7 @@ export declare class RegisteredMcpTool {
 }
 /**
  * Fail-fast registry: the CONTRACT says which methods are tools and how they are authorized, and the
- * build's generated catalog says what each tool's documentation and schemas are.
+ * build's generated catalog OF THAT CONTRACT says what each tool's documentation and schemas are.
  *
  * ## Why the schemas come from the catalog and not from here
  *
@@ -29,17 +30,30 @@ export declare class RegisteredMcpTool {
  * contract, free to disagree; and it could not see a field's declared TYPE at all, so every fact
  * about a field had to be restated in a `@WpDtoField` argument. #983 measured the compiler against
  * it and found the compiler reproduces all of it, so #984 deleted the decorator and this registry
- * now READS the same `mcp-tools.json` the documents were rendered from.
+ * now READS the same catalogs the documents were rendered beside.
  *
- * A registered `@WpMcpTool` the catalog does not name is a HARD FAILURE, not a fallback: a tool the
- * build never saw is a tool whose schema nobody checked.
+ * ## One catalog per bound contract, exactly (#1021)
+ *
+ * `wp-openapi` writes one `mcp-<ContractClass>-tools.json` per contract, and this registry pairs every
+ * `McpApiBinding` with the file of its own contract. Three mismatches refuse the boot, all reported at
+ * once, each naming every directory the catalogs were read from:
+ *
+ * - a bound contract with no catalog — its tools were never given a schema by the build;
+ * - a catalog whose contract is not bound — the server was handed tools it does not serve;
+ * - a tool name declared twice — the protocol namespace is flat.
+ *
+ * A registered `@WpMcpTool` the catalog does not name is likewise a HARD FAILURE, not a fallback: a
+ * tool the build never saw is a tool whose schema nobody checked.
  */
 export declare class McpToolRegistry {
-    private readonly catalog;
     readonly tools: readonly RegisteredMcpTool[];
-    constructor(bindings: readonly McpApiBinding[], catalog: McpToolCatalog);
+    constructor(bindings: readonly McpApiBinding[], catalogs: readonly McpToolCatalog[]);
     find(name: string): RegisteredMcpTool | undefined;
+    /**
+     * The contract checks THROW at once — they are about the contract source, not the build. A tool
+     * missing from its catalog is RECORDED on `pairing`, so one boot names every catalog mismatch.
+     */
     private resolve;
-    /** The generated entry for this tool, or a refusal naming what the build DID publish. */
+    /** The generated entry for this tool, or a recorded refusal naming what the build DID publish. */
     private published;
 }