@vinkius-core/mcp-fusion 2.6.0 → 2.7.0

package/dist/server/DevServer.js

@@ -0,0 +1,187 @@
+/**
+ * DevServer — HMR-enabled MCP Development Server
+ *
+ * The "killer feature" for MCP DX: `npx mcp-fusion dev` starts a
+ * development server that watches for file changes and performs
+ * automatic Hot Module Replacement without requiring the LLM client
+ * (Claude Desktop, Cursor, etc.) to be restarted.
+ *
+ * ## How It Works
+ *
+ * 1. The dev server starts an MCP stdio server with your tools
+ * 2. When a `.ts`/`.js` file changes, the module cache is invalidated
+ * 3. Tools are re-registered from the updated modules
+ * 4. The MCP `notifications/tools/list_changed` notification is sent
+ * 5. The LLM client picks up the new tool definitions transparently
+ *
+ * ## Usage
+ *
+ * ```bash
+ * # Start dev server watching src/tools/ directory
+ * npx mcp-fusion dev --dir ./src/tools --entry ./src/server.ts
+ *
+ * # With specific file pattern
+ * npx mcp-fusion dev --dir ./src/tools --pattern "*.tool.ts"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using the programmatic API
+ * import { createDevServer } from '@vinkius-core/mcp-fusion/dev';
+ *
+ * const devServer = createDevServer({
+ *   dir: './src/tools',
+ *   setup: async (registry) => {
+ *     // Your setup logic — called on every reload
+ *     await autoDiscover(registry, './src/tools');
+ *   },
+ * });
+ *
+ * await devServer.start();
+ * ```
+ *
+ * @module
+ */
+import { watch } from 'node:fs';
+import { resolve, join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+// ── Module Cache Invalidation ────────────────────────────
+/**
+ * Invalidate Node.js ESM module cache for a given file.
+ *
+ * ESM modules are cached by URL. We use an import timestamp trick
+ * to force re-evaluation on next import.
+ *
+ * For CJS, we clear `require.cache` if available.
+ *
+ * @internal
+ */
+function invalidateModule(filePath) {
+    const absolutePath = resolve(filePath);
+    // CJS cache invalidation (when running in CJS mode)
+    if (typeof require !== 'undefined' && require.cache) {
+        delete require.cache[absolutePath];
+    }
+    // ESM modules can't be uncached directly — the caller must
+    // re-import with a cache-busting query parameter.
+}
+/**
+ * Create a cache-busting import URL for ESM modules.
+ * Appends a timestamp query to force the module to be re-evaluated.
+ * @internal
+ */
+function cacheBustUrl(filePath) {
+    const url = pathToFileURL(resolve(filePath));
+    url.searchParams.set('t', String(Date.now()));
+    return url.href;
+}
+// ── Dev Server Factory ───────────────────────────────────
+/**
+ * Create an HMR-enabled MCP development server.
+ *
+ * Watches a directory for file changes and automatically reloads
+ * tools, then notifies the connected MCP client via the native
+ * `notifications/tools/list_changed` notification.
+ *
+ * @param config - Dev server configuration
+ * @returns A {@link DevServer} instance with start/stop/reload controls
+ *
+ * @example
+ * ```typescript
+ * import { createDevServer, autoDiscover, ToolRegistry } from '@vinkius-core/mcp-fusion';
+ *
+ * const devServer = createDevServer({
+ *   dir: './src/tools',
+ *   setup: async (registry) => {
+ *     await autoDiscover(registry, './src/tools');
+ *   },
+ *   onReload: (file) => console.log(`[HMR] Reloaded: ${file}`),
+ * });
+ *
+ * await devServer.start();
+ * // File changes → auto-reload → LLM client gets notification
+ * ```
+ */
+export function createDevServer(config) {
+    const { dir, extensions = ['.ts', '.js', '.mjs', '.mts'], debounce = 300, setup, onReload, server, } = config;
+    const absoluteDir = resolve(dir);
+    let watcher;
+    let debounceTimer;
+    let reloadCount = 0;
+    /**
+     * Perform a full reload: clear caches, re-run setup, notify MCP client.
+     */
+    async function performReload(changedFile) {
+        reloadCount++;
+        // Invalidate CJS cache for all watched files
+        invalidateModule(changedFile);
+        // Re-run the user's setup callback
+        // The user is responsible for creating a fresh registry or clearing it
+        try {
+            await setup({});
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // eslint-disable-next-line no-console
+            console.error(`[mcp-fusion dev] Reload failed: ${message}`);
+            return;
+        }
+        // Notify MCP client about tool list changes
+        if (server) {
+            const notification = { method: 'notifications/tools/list_changed' };
+            try {
+                if (typeof server.sendNotification === 'function') {
+                    await server.sendNotification(notification);
+                }
+                else if (typeof server.notification === 'function') {
+                    await server.notification(notification);
+                }
+            }
+            catch {
+                // Connection might not be established yet — ignore
+            }
+        }
+        // User callback
+        onReload?.(changedFile);
+    }
+    return {
+        async start() {
+            // Perform initial load
+            await performReload('(initial)');
+            // Start watching
+            const watchOptions = { recursive: true };
+            watcher = watch(absoluteDir, watchOptions, (_eventType, filename) => {
+                if (!filename)
+                    return;
+                // Filter by extension
+                const ext = '.' + filename.split('.').pop();
+                if (!extensions.includes(ext))
+                    return;
+                // Skip test/spec files
+                if (/\.(test|spec|d)\./.test(filename))
+                    return;
+                // Debounce rapid changes
+                if (debounceTimer)
+                    clearTimeout(debounceTimer);
+                debounceTimer = setTimeout(() => {
+                    const fullPath = join(absoluteDir, filename);
+                    void performReload(relative(process.cwd(), fullPath));
+                }, debounce);
+            });
+            // eslint-disable-next-line no-console
+            console.log(`[mcp-fusion dev] Watching ${relative(process.cwd(), absoluteDir)} for changes...`);
+        },
+        stop() {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            watcher?.close();
+            watcher = undefined;
+            // eslint-disable-next-line no-console
+            console.log(`[mcp-fusion dev] Stopped. ${reloadCount} reload(s) performed.`);
+        },
+        async reload(reason) {
+            await performReload(reason ?? '(manual)');
+        },
+    };
+}
+//# sourceMappingURL=DevServer.js.map

package/dist/server/DevServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DevServer.js","sourceRoot":"","sources":["../../src/server/DevServer.ts"],"names":[],"mappings":"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"}

package/dist/server/autoDiscover.d.ts

@@ -0,0 +1,63 @@
+/** Duck-typed ToolBuilder — avoids circular imports */
+interface ToolBuilderLike {
+    getName(): string;
+    buildToolDefinition?(): unknown;
+}
+/** Duck-typed ToolRegistry — avoids circular imports */
+interface ToolRegistryLike {
+    register(builder: ToolBuilderLike): void;
+}
+/**
+ * Options for `autoDiscover()`.
+ */
+export interface AutoDiscoverOptions {
+    /**
+     * Regex pattern to filter files. Only files matching this pattern
+     * are imported. Default: matches `.ts`, `.js`, `.mjs`, `.mts` files,
+     * excluding `.test.`, `.spec.`, and `.d.ts` files.
+     */
+    pattern?: RegExp;
+    /**
+     * Whether to recurse into subdirectories.
+     * @default true
+     */
+    recursive?: boolean;
+    /**
+     * Module resolution style:
+     * - `'esm'` — Uses dynamic `import()` (default for ESM projects)
+     * - `'cjs'` — Uses `require()` (for CommonJS projects)
+     *
+     * @default 'esm'
+     */
+    loader?: 'esm' | 'cjs';
+    /**
+     * Custom export resolver. When provided, this function is called
+     * with the module's exports and must return the tool builder(s).
+     *
+     * Default behavior: looks for `default` export or named `tool` export.
+     */
+    resolve?: (mod: Record<string, unknown>) => ToolBuilderLike | ToolBuilderLike[] | undefined;
+}
+/**
+ * Scan a directory and auto-register all discovered tool builders.
+ *
+ * Eliminates the need for a central `index.ts` that manually imports
+ * and registers every tool. New tools are automatically picked up
+ * when they are dropped into the scanned directory.
+ *
+ * @param registry - A ToolRegistry instance to register discovered tools
+ * @param dir - Path to the tools directory (absolute or relative to CWD)
+ * @param options - Discovery options (pattern, recursive, loader, resolve)
+ * @returns Array of discovered file paths (for logging/debugging)
+ * @throws If the directory does not exist or is not readable
+ *
+ * @example
+ * ```typescript
+ * const registry = new ToolRegistry<AppContext>();
+ * const files = await autoDiscover(registry, './src/tools');
+ * console.log(`Discovered ${files.length} tool files`);
+ * ```
+ */
+export declare function autoDiscover(registry: ToolRegistryLike, dir: string, options?: AutoDiscoverOptions): Promise<string[]>;
+export {};
+//# sourceMappingURL=autoDiscover.d.ts.map

package/dist/server/autoDiscover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoDiscover.d.ts","sourceRoot":"","sources":["../../src/server/autoDiscover.ts"],"names":[],"mappings":"AAkDA,uDAAuD;AACvD,UAAU,eAAe;IACrB,OAAO,IAAI,MAAM,CAAC;IAClB,mBAAmB,CAAC,IAAI,OAAO,CAAC;CACnC;AAED,wDAAwD;AACxD,UAAU,gBAAgB;IACtB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAEvB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,eAAe,GAAG,eAAe,EAAE,GAAG,SAAS,CAAC;CAC/F;AAmED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,YAAY,CAC9B,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,mBAAwB,GAClC,OAAO,CAAC,MAAM,EAAE,CAAC,CA6CnB"}

package/dist/server/autoDiscover.js

@@ -0,0 +1,157 @@
+/**
+ * File-Based Routing — Auto-Discovery of Tools via Directory Structure
+ *
+ * Scans a directory at startup and auto-registers tools based on the
+ * file-system naming convention:
+ *
+ * ```
+ * src/tools/
+ * ├── billing/
+ * │   ├── get_invoice.ts  → billing.get_invoice
+ * │   └── pay.ts          → billing.pay
+ * └── users/
+ *     ├── list.ts         → users.list
+ *     └── ban.ts          → users.ban
+ * ```
+ *
+ * Each file must export a `GroupedToolBuilder` (via `defineTool()`,
+ * `createTool()`, `f.tool()`, etc.) as the **default export** or
+ * a named export called `tool`.
+ *
+ * **Benefits:**
+ * - Zero code orchestration — no central `index.ts` with 50 imports
+ * - Git-friendly — reduced merge conflicts (no shared import file)
+ * - Instant onboarding — "drop a file → it's a tool"
+ *
+ * @example
+ * ```typescript
+ * import { autoDiscover, ToolRegistry } from '@vinkius-core/mcp-fusion';
+ *
+ * const registry = new ToolRegistry<AppContext>();
+ *
+ * // Scan src/tools/ and register everything
+ * await autoDiscover(registry, './src/tools');
+ *
+ * // Or with options
+ * await autoDiscover(registry, './src/tools', {
+ *   pattern: /\.tool\.ts$/,     // only files ending in .tool.ts
+ *   recursive: true,            // scan subdirectories (default: true)
+ *   separator: '.',             // directory separator for tool names
+ * });
+ * ```
+ *
+ * @module
+ */
+import { promises as fs } from 'node:fs';
+import { join, resolve, relative, basename, extname, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+// ── Internal ─────────────────────────────────────────────
+const DEFAULT_PATTERN = /\.(ts|js|mjs|mts)$/;
+const EXCLUDED_PATTERN = /\.(test|spec|d)\./;
+/**
+ * Walk a directory tree and collect file paths matching the filter.
+ * @internal
+ */
+async function walkDir(dir, pattern, recursive) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory() && recursive) {
+            const nested = await walkDir(fullPath, pattern, recursive);
+            files.push(...nested);
+        }
+        else if (entry.isFile() && pattern.test(entry.name) && !EXCLUDED_PATTERN.test(entry.name)) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+/**
+ * Check if a value looks like a ToolBuilder (duck typing).
+ * @internal
+ */
+function isToolBuilder(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.getName === 'function');
+}
+/**
+ * Default export resolver: check default → tool → any exported builder.
+ * @internal
+ */
+function defaultResolver(mod) {
+    // Priority 1: default export
+    const defaultExport = mod['default'];
+    if (isToolBuilder(defaultExport))
+        return defaultExport;
+    // Priority 2: named `tool` export
+    const toolExport = mod['tool'];
+    if (isToolBuilder(toolExport))
+        return toolExport;
+    // Priority 3: collect all exported builders
+    const builders = [];
+    for (const value of Object.values(mod)) {
+        if (isToolBuilder(value)) {
+            builders.push(value);
+        }
+    }
+    return builders.length > 0 ? builders : undefined;
+}
+// ── Public API ───────────────────────────────────────────
+/**
+ * Scan a directory and auto-register all discovered tool builders.
+ *
+ * Eliminates the need for a central `index.ts` that manually imports
+ * and registers every tool. New tools are automatically picked up
+ * when they are dropped into the scanned directory.
+ *
+ * @param registry - A ToolRegistry instance to register discovered tools
+ * @param dir - Path to the tools directory (absolute or relative to CWD)
+ * @param options - Discovery options (pattern, recursive, loader, resolve)
+ * @returns Array of discovered file paths (for logging/debugging)
+ * @throws If the directory does not exist or is not readable
+ *
+ * @example
+ * ```typescript
+ * const registry = new ToolRegistry<AppContext>();
+ * const files = await autoDiscover(registry, './src/tools');
+ * console.log(`Discovered ${files.length} tool files`);
+ * ```
+ */
+export async function autoDiscover(registry, dir, options = {}) {
+    const { pattern = DEFAULT_PATTERN, recursive = true, loader = 'esm', resolve: customResolve, } = options;
+    const absoluteDir = resolve(dir);
+    const files = await walkDir(absoluteDir, pattern, recursive);
+    const discoveredFiles = [];
+    for (const filePath of files) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            let mod;
+            if (loader === 'cjs') {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                mod = require(filePath);
+            }
+            else {
+                const fileUrl = pathToFileURL(filePath).href;
+                mod = await import(fileUrl);
+            }
+            const resolver = customResolve ?? defaultResolver;
+            const result = resolver(mod);
+            if (!result)
+                continue;
+            const builders = Array.isArray(result) ? result : [result];
+            for (const builder of builders) {
+                registry.register(builder);
+            }
+            discoveredFiles.push(filePath);
+        }
+        catch {
+            // Skip files that fail to import (syntax errors, missing deps, etc.)
+            // In production, this should be logged via the observability layer
+            continue;
+        }
+    }
+    return discoveredFiles;
+}
+//# sourceMappingURL=autoDiscover.js.map

package/dist/server/autoDiscover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoDiscover.js","sourceRoot":"","sources":["../../src/server/autoDiscover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAkDzC,4DAA4D;AAE5D,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAC7C,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAE7C;;;GAGG;AACH,KAAK,UAAU,OAAO,CAAC,GAAW,EAAE,OAAe,EAAE,SAAkB;IACnE,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAEvC,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,SAAS,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;YAC3D,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;QAC1B,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1F,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAC,KAAc;IACjC,OAAO,CACH,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAAyB,CAAC,OAAO,KAAK,UAAU,CAC3D,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,GAA4B;IACjD,6BAA6B;IAC7B,MAAM,aAAa,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;IACrC,IAAI,aAAa,CAAC,aAAa,CAAC;QAAE,OAAO,aAAa,CAAC;IAEvD,kCAAkC;IAClC,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,IAAI,aAAa,CAAC,UAAU,CAAC;QAAE,OAAO,UAAU,CAAC;IAEjD,4CAA4C;IAC5C,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;YACvB,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AACtD,CAAC;AAED,4DAA4D;AAE5D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAC9B,QAA0B,EAC1B,GAAW,EACX,UAA+B,EAAE;IAEjC,MAAM,EACF,OAAO,GAAG,eAAe,EACzB,SAAS,GAAG,IAAI,EAChB,MAAM,GAAG,KAAK,EACd,OAAO,EAAE,aAAa,GACzB,GAAG,OAAO,CAAC;IAEZ,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAC7D,MAAM,eAAe,GAAa,EAAE,CAAC;IAErC,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC;YACD,8DAA8D;YAC9D,IAAI,GAA4B,CAAC;YAEjC,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;gBACnB,iEAAiE;gBACjE,GAAG,GAAG,OAAO,CAAC,QAAQ,CAA4B,CAAC;YACvD,CAAC;iBAAM,CAAC;gBACJ,MAAM,OAAO,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;gBAC7C,GAAG,GAAG,MAAM,MAAM,CAAC,OAAO,CAA4B,CAAC;YAC3D,CAAC;YAED,MAAM,QAAQ,GAAG,aAAa,IAAI,eAAe,CAAC;YAClD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;YAE7B,IAAI,CAAC,MAAM;gBAAE,SAAS;YAEtB,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAE3D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC7B,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC/B,CAAC;YAED,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACL,qEAAqE;YACrE,mEAAmE;YACnE,SAAS;QACb,CAAC;IACL,CAAC;IAED,OAAO,eAAe,CAAC;AAC3B,CAAC"}

package/dist/server/index.d.ts

@@ -3,4 +3,8 @@ export { resolveServer } from './ServerResolver.js';
 export { attachToServer, type AttachOptions, type DetachFn, type RegistryDelegate, } from './ServerAttachment.js';
 export type { ToolExposition, ExpositionConfig } from '../exposition/index.js';
 export { compileExposition, type FlatRoute, type ExpositionResult } from '../exposition/index.js';
+export { autoDiscover } from './autoDiscover.js';
+export type { AutoDiscoverOptions } from './autoDiscover.js';
+export { createDevServer } from './DevServer.js';
+export type { DevServerConfig, DevServer } from './DevServer.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACH,cAAc,EACd,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,gBAAgB,GAC3D,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACH,cAAc,EACd,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,gBAAgB,GAC3D,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAGlG,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/server/index.js

@@ -2,4 +2,8 @@
 export { resolveServer } from './ServerResolver.js';
 export { attachToServer, } from './ServerAttachment.js';
 export { compileExposition } from '../exposition/index.js';
+// ── File-Based Routing ───────────────────────────────────
+export { autoDiscover } from './autoDiscover.js';
+// ── Dev Server (HMR) ────────────────────────────────────
+export { createDevServer } from './DevServer.js';
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACH,cAAc,GAEjB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,iBAAiB,EAAyC,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACH,cAAc,GAEjB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,iBAAiB,EAAyC,MAAM,wBAAwB,CAAC;AAElG,4DAA4D;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,2DAA2D;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/state-sync/PolicyValidator.d.ts

@@ -28,4 +28,40 @@ export declare function validatePolicies(policies: readonly SyncPolicy[]): void;
 export declare function validateDefaults(defaults?: {
     readonly cacheControl?: CacheDirective;
 }): void;
+/**
+ * Warning produced when two policies potentially overlap.
+ *
+ * Overlapping policies are not an error (first-match-wins is deterministic),
+ * but they can cause subtle configuration bugs when the user expects a
+ * more-specific policy to fire but a broader one shadows it.
+ *
+ * @example
+ * ```typescript
+ * const warnings = detectOverlaps(policies);
+ * warnings.forEach(w => console.warn(`[StateSync] ${w.message}`));
+ * ```
+ */
+export interface OverlapWarning {
+    /** Human-readable description of the overlap. */
+    readonly message: string;
+    /** Index of the shadowing (earlier) policy. */
+    readonly shadowingIndex: number;
+    /** Index of the shadowed (later) policy. */
+    readonly shadowedIndex: number;
+}
+/**
+ * Detect potentially overlapping glob policies.
+ *
+ * Checks if a broader policy at index `i` could shadow a more-specific
+ * policy at index `j > i`. Uses GlobMatcher to test if the earlier
+ * pattern matches the later pattern's literal segments.
+ *
+ * This is a heuristic: it only catches cases where the later policy's
+ * `match` string (treated as a literal tool name) would match the
+ * earlier policy's glob. It does NOT do full set-intersection analysis.
+ *
+ * @param policies - The policies array to analyze
+ * @returns Array of overlap warnings (empty if no overlaps detected)
+ */
+export declare function detectOverlaps(policies: readonly SyncPolicy[]): readonly OverlapWarning[];
 //# sourceMappingURL=PolicyValidator.d.ts.map

package/dist/state-sync/PolicyValidator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PolicyValidator.d.ts","sourceRoot":"","sources":["../../src/state-sync/PolicyValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAI7D,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAsC,CAAC;AAiExF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAetE;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC5B,QAAQ,CAAC,EAAE;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAA;CAAE,GACtD,IAAI,CAON"}
+{"version":3,"file":"PolicyValidator.d.ts","sourceRoot":"","sources":["../../src/state-sync/PolicyValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAK7D,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAsC,CAAC;AAiExF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAetE;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC5B,QAAQ,CAAC,EAAE;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAA;CAAE,GACtD,IAAI,CAON;AAID;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,cAAc,EAAE,CAuBzF"}

package/dist/state-sync/PolicyValidator.js

@@ -1,3 +1,4 @@
+import { matchGlob } from './GlobMatcher.js';
 // ── Constants ────────────────────────────────────────────
 /** Valid cache directives — binary vocabulary, no max-age. */
 export const VALID_DIRECTIVES = new Set(['no-store', 'immutable']);
@@ -84,4 +85,38 @@ export function validateDefaults(defaults) {
             `Allowed: "no-store", "immutable".`);
     }
 }
+/**
+ * Detect potentially overlapping glob policies.
+ *
+ * Checks if a broader policy at index `i` could shadow a more-specific
+ * policy at index `j > i`. Uses GlobMatcher to test if the earlier
+ * pattern matches the later pattern's literal segments.
+ *
+ * This is a heuristic: it only catches cases where the later policy's
+ * `match` string (treated as a literal tool name) would match the
+ * earlier policy's glob. It does NOT do full set-intersection analysis.
+ *
+ * @param policies - The policies array to analyze
+ * @returns Array of overlap warnings (empty if no overlaps detected)
+ */
+export function detectOverlaps(policies) {
+    const warnings = [];
+    for (let i = 0; i < policies.length; i++) {
+        for (let j = i + 1; j < policies.length; j++) {
+            const earlier = policies[i].match;
+            const later = policies[j].match;
+            // If the later policy's match pattern (as a literal name)
+            // would be caught by the earlier policy's glob, it's shadowed.
+            if (matchGlob(earlier, later)) {
+                warnings.push({
+                    message: `policy[${i}] (match: "${earlier}") shadows policy[${j}] (match: "${later}"). ` +
+                        `The later policy will never match because first-match-wins applies.`,
+                    shadowingIndex: i,
+                    shadowedIndex: j,
+                });
+            }
+        }
+    }
+    return warnings;
+}
 //# sourceMappingURL=PolicyValidator.js.map

package/dist/state-sync/PolicyValidator.js.map

@@ -1 +1 @@
-{"version":3,"file":"PolicyValidator.js","sourceRoot":"","sources":["../../src/state-sync/PolicyValidator.ts"],"names":[],"mappings":"AAaA,4DAA4D;AAE5D,8DAA8D;AAC9D,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;AAExF,6DAA6D;AAC7D,MAAM,aAAa,GAAG,4BAA4B,CAAC;AAEnD,4DAA4D;AAE5D;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,OAAe,EAAE,KAAa,EAAE,MAAc;IACnE,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,KAAK,KAAK,8BAA8B,CAAC,CAAC;IACvE,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACX,GAAG,MAAM,KAAK,KAAK,aAAa,OAAO,0BAA0B,GAAG,KAAK;gBACzE,6CAA6C,CAChD,CAAC;QACN,CAAC;IACL,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAS,oBAAoB,CAAC,SAAiB,EAAE,MAAc;IAC3D,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACX,GAAG,MAAM,2BAA2B,SAAS,KAAK;YAClD,mCAAmC,CACtC,CAAC;IACN,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAS,sBAAsB,CAAC,WAAoB,EAAE,MAAc;IAChE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,mCAAmC,CAAC,CAAC;IAClE,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,WAAuB,EAAE,CAAC;QAC5C,eAAe,CAAC,OAAO,EAAE,wDAAwD,EAAE,MAAM,CAAC,CAAC;IAC/F,CAAC;AACL,CAAC;AAED,4DAA4D;AAE5D;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAA+B;IAC5D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC;QACvB,MAAM,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAAC;QAExC,eAAe,CAAC,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;QAE5C,IAAI,CAAC,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,oBAAoB,CAAC,CAAC,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;QACjD,CAAC;QAED,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,sBAAsB,CAAC,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAClD,CAAC;IACL,CAAC;AACL,CAAC;AAED,4DAA4D;AAE5D;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC5B,QAAqD;IAErD,IAAI,QAAQ,EAAE,YAAY,KAAK,SAAS,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,KAAK,CACX,mCAAmC,QAAQ,CAAC,YAAY,gBAAgB;YACxE,mCAAmC,CACtC,CAAC;IACN,CAAC;AACL,CAAC"}
+{"version":3,"file":"PolicyValidator.js","sourceRoot":"","sources":["../../src/state-sync/PolicyValidator.ts"],"names":[],"mappings":"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"}

package/dist/state-sync/ResponseDecorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ResponseDecorator.d.ts","sourceRoot":"","sources":["../../src/state-sync/ResponseDecorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,MAAM,GACjB,YAAY,CAUd"}
+{"version":3,"file":"ResponseDecorator.d.ts","sourceRoot":"","sources":["../../src/state-sync/ResponseDecorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,MAAM,GACjB,YAAY,CAUd"}

package/dist/state-sync/ResponseDecorator.js

@@ -1,3 +1,4 @@
+import { escapeXmlAttr } from '../core/response.js';
 /**
  * Prepend a System invalidation content block to a tool call response.
  *
@@ -11,7 +12,7 @@ export function decorateResponse(result, patterns, causedBy) {
     return {
         ...result,
         content: [
-            { type: 'text', text: `<cache_invalidation cause="${causedBy}" domains="${domains}" />` },
+            { type: 'text', text: `<cache_invalidation cause="${escapeXmlAttr(causedBy)}" domains="${escapeXmlAttr(domains)}" />` },
             ...result.content,
         ],
     };

package/dist/state-sync/ResponseDecorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"ResponseDecorator.js","sourceRoot":"","sources":["../../src/state-sync/ResponseDecorator.ts"],"names":[],"mappings":"AAwBA;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC5B,MAAoB,EACpB,QAA2B,EAC3B,QAAgB;IAEhB,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEpC,OAAO;QACH,GAAG,MAAM;QACT,OAAO,EAAE;YACL,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,8BAA8B,QAAQ,cAAc,OAAO,MAAM,EAAE;YAClG,GAAG,MAAM,CAAC,OAAO;SACpB;KACJ,CAAC;AACN,CAAC"}
+{"version":3,"file":"ResponseDecorator.js","sourceRoot":"","sources":["../../src/state-sync/ResponseDecorator.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC5B,MAAoB,EACpB,QAA2B,EAC3B,QAAgB;IAEhB,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEpC,OAAO;QACH,GAAG,MAAM;QACT,OAAO,EAAE;YACL,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,8BAA8B,aAAa,CAAC,QAAQ,CAAC,cAAc,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE;YAChI,GAAG,MAAM,CAAC,OAAO;SACpB;KACJ,CAAC;AACN,CAAC"}

package/dist/state-sync/StateSyncLayer.d.ts

@@ -40,6 +40,8 @@ import type { ToolResponse } from '../core/response.js';
 import type { StateSyncConfig } from './types.js';
 export declare class StateSyncLayer {
     private readonly _engine;
+    private readonly _onInvalidation?;
+    private readonly _notificationSink?;
     /**
      * Per-tool-name cache of decorated McpTool objects.
      *
@@ -49,10 +51,9 @@ export declare class StateSyncLayer {
      * on every `tools/list` request — which is the hottest path since
      * it runs at the start of every LLM conversation.
      *
-     * The cache key is the tool name + JSON input schema hash to detect
-     * changes in the underlying tool definition. In practice, tool
-     * definitions are immutable after registration, so the cache
-     * hit rate approaches 100%.
+     * The cache key is the tool name — tool definitions are immutable
+     * after registration, so the name alone is sufficient.
+     * Cache hit rate approaches 100%.
      */
     private readonly _decoratedToolCache;
     /**

package/dist/state-sync/StateSyncLayer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StateSyncLayer.d.ts","sourceRoot":"","sources":["../../src/state-sync/StateSyncLayer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,KAAK,IAAI,IAAI,OAAO,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMlD,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA8B;IAElE;;;;;;;;;OASG;gBACS,MAAM,EAAE,eAAe;IAInC;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;IAI1C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,YAAY;IAapE;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;CAQ9B"}
+{"version":3,"file":"StateSyncLayer.d.ts","sourceRoot":"","sources":["../../src/state-sync/StateSyncLayer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,KAAK,IAAI,IAAI,OAAO,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAA2C,MAAM,YAAY,CAAC;AAM3F,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAmD;IACpF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAA6E;IAEhH;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA8B;IAElE;;;;;;;;;OASG;gBACS,MAAM,EAAE,eAAe;IAMnC;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;IAI1C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,YAAY;IAuCpE;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;CAQ9B"}