@cyanmycelium/mcp-broker 0.2.0 → 0.4.0

package/dist/broker/aggregate/provider.client.session.js

@@ -0,0 +1,140 @@
+/** MCP protocol version the aggregate sessions negotiate with sub-providers. */
+const PROTOCOL_VERSION = "2024-11-05";
+/** Per-request timeout for sub-provider calls. */
+const REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * A hand-rolled JSON-RPC client session to one aggregated provider, running
+ * over an in-process {@link InternalClient}.
+ *
+ * Performs the MCP `initialize` handshake, caches the provider's `tools/list`
+ * and `prompts/list`, and re-fetches them when the provider emits a
+ * `list_changed` notification. `tools/call` and `prompts/get` are forwarded and
+ * their raw result or error relayed back unchanged.
+ */
+export class ProviderClientSession {
+    provider;
+    _client;
+    _idPrefix;
+    _pending = new Map();
+    _nextId = 0;
+    _tools = [];
+    _prompts = [];
+    _closed = false;
+    /** Fires after the cached catalog changes (initial load or `list_changed`). */
+    onCatalogChanged = null;
+    /** Fires when the underlying provider slot disconnects. */
+    onClosed = null;
+    constructor(provider, client) {
+        this.provider = provider;
+        this._client = client;
+        this._idPrefix = `agg-${provider}-`;
+        client.onMessage = (data) => this._handleMessage(data);
+        client.onClose = () => {
+            if (this._closed)
+                return;
+            this._rejectAll("provider disconnected");
+            this.onClosed?.();
+        };
+    }
+    get tools() {
+        return this._tools;
+    }
+    get prompts() {
+        return this._prompts;
+    }
+    /** Runs the `initialize` handshake and the first catalog fetch. */
+    async initialize() {
+        await this._request("initialize", {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: "mcp-broker-aggregate", version: "0" },
+        });
+        this._client.send(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }));
+        await this._refresh();
+    }
+    /** Forwards a `tools/call` to the provider, relaying the raw outcome. */
+    callTool(name, args) {
+        return this._request("tools/call", { name, arguments: args });
+    }
+    /** Forwards a `prompts/get` to the provider, relaying the raw outcome. */
+    getPrompt(name, args) {
+        return this._request("prompts/get", { name, arguments: args });
+    }
+    /** Detaches the session and its internal client. */
+    close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        this._rejectAll("session closed");
+        this._client.close();
+    }
+    async _refresh() {
+        this._tools = await this._listAll("tools/list", "tools");
+        this._prompts = await this._listAll("prompts/list", "prompts");
+        this.onCatalogChanged?.();
+    }
+    /**
+     * Calls a list method, following `nextCursor` pagination. A provider that
+     * does not implement the primitive answers with an error, which is treated
+     * as an empty list.
+     */
+    async _listAll(method, key) {
+        const items = [];
+        let cursor;
+        do {
+            const { result, error } = await this._request(method, cursor ? { cursor } : {});
+            if (error)
+                return [];
+            const page = (result ?? {});
+            const list = page[key];
+            if (Array.isArray(list))
+                items.push(...list);
+            cursor = typeof page.nextCursor === "string" ? page.nextCursor : undefined;
+        } while (cursor);
+        return items;
+    }
+    _request(method, params) {
+        return new Promise((resolve) => {
+            if (this._closed) {
+                resolve({ error: { code: -32000, message: "session closed" } });
+                return;
+            }
+            const id = this._idPrefix + String(++this._nextId);
+            const timer = setTimeout(() => {
+                this._pending.delete(id);
+                resolve({ error: { code: -32000, message: `request "${method}" timed out` } });
+            }, REQUEST_TIMEOUT_MS);
+            this._pending.set(id, { resolve, timer });
+            this._client.send(JSON.stringify({ jsonrpc: "2.0", id, method, params }));
+        });
+    }
+    _handleMessage(data) {
+        let msg;
+        try {
+            msg = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (typeof msg.id === "string") {
+            const pending = this._pending.get(msg.id);
+            if (pending) {
+                this._pending.delete(msg.id);
+                clearTimeout(pending.timer);
+                pending.resolve({ result: msg.result, error: msg.error });
+            }
+            return;
+        }
+        if (msg.id == null && (msg.method === "notifications/tools/list_changed" || msg.method === "notifications/prompts/list_changed")) {
+            void this._refresh();
+        }
+    }
+    _rejectAll(reason) {
+        for (const pending of this._pending.values()) {
+            clearTimeout(pending.timer);
+            pending.resolve({ error: { code: -32000, message: reason } });
+        }
+        this._pending.clear();
+    }
+}
+//# sourceMappingURL=provider.client.session.js.map

package/dist/broker/aggregate/provider.client.session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.client.session.js","sourceRoot":"","sources":["../../../src/broker/aggregate/provider.client.session.ts"],"names":[],"mappings":"AAGA,gFAAgF;AAChF,MAAM,gBAAgB,GAAG,YAAY,CAAC;AAEtC,kDAAkD;AAClD,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAoBlC;;;;;;;;GAQG;AACH,MAAM,OAAO,qBAAqB;IACrB,QAAQ,CAAS;IAET,OAAO,CAAiB;IACxB,SAAS,CAAS;IAClB,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IACtD,OAAO,GAAG,CAAC,CAAC;IACZ,MAAM,GAAkB,EAAE,CAAC;IAC3B,QAAQ,GAAoB,EAAE,CAAC;IAC/B,OAAO,GAAG,KAAK,CAAC;IAExB,+EAA+E;IAC/E,gBAAgB,GAAwB,IAAI,CAAC;IAE7C,2DAA2D;IAC3D,QAAQ,GAAwB,IAAI,CAAC;IAErC,YAAY,QAAgB,EAAE,MAAsB;QAChD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,SAAS,GAAG,OAAO,QAAQ,GAAG,CAAC;QACpC,MAAM,CAAC,SAAS,GAAG,CAAC,IAAY,EAAQ,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QACrE,MAAM,CAAC,OAAO,GAAG,GAAS,EAAE;YACxB,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO;YACzB,IAAI,CAAC,UAAU,CAAC,uBAAuB,CAAC,CAAC;YACzC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;QACtB,CAAC,CAAC;IACN,CAAC;IAED,IAAI,KAAK;QACL,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,IAAI,OAAO;QACP,OAAO,IAAI,CAAC,QAAQ,CAAC;IACzB,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,UAAU;QACZ,MAAM,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE;YAC9B,eAAe,EAAE,gBAAgB;YACjC,YAAY,EAAE,EAAE;YAChB,UAAU,EAAE,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,GAAG,EAAE;SAC7D,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC,CAAC,CAAC;QAC3F,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC1B,CAAC;IAED,yEAAyE;IACzE,QAAQ,CAAC,IAAY,EAAE,IAA6B;QAChD,OAAO,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,0EAA0E;IAC1E,SAAS,CAAC,IAAY,EAAE,IAA6B;QACjD,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,oDAAoD;IACpD,KAAK;QACD,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IAEO,KAAK,CAAC,QAAQ;QAClB,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAc,YAAY,EAAE,OAAO,CAAC,CAAC;QACtE,IAAI,CAAC,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAgB,cAAc,EAAE,SAAS,CAAC,CAAC;QAC9E,IAAI,CAAC,gBAAgB,EAAE,EAAE,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,QAAQ,CAAI,MAAc,EAAE,GAAW;QACjD,MAAM,KAAK,GAAQ,EAAE,CAAC;QACtB,IAAI,MAA0B,CAAC;QAC/B,GAAG,CAAC;YACA,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAChF,IAAI,KAAK;gBAAE,OAAO,EAAE,CAAC;YACrB,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,CAA4B,CAAC;YACvD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;YACvB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,GAAI,IAAY,CAAC,CAAC;YACtD,MAAM,GAAG,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/E,CAAC,QAAQ,MAAM,EAAE;QACjB,OAAO,KAAK,CAAC;IACjB,CAAC;IAEO,QAAQ,CAAC,MAAc,EAAE,MAAe;QAC5C,OAAO,IAAI,OAAO,CAAa,CAAC,OAAO,EAAE,EAAE;YACvC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACf,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,CAAC,CAAC;gBAChE,OAAO;YACX,CAAC;YACD,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YACnD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC1B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACzB,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,MAAM,aAAa,EAAE,EAAE,CAAC,CAAC;YACnF,CAAC,EAAE,kBAAkB,CAAC,CAAC;YACvB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QAC9E,CAAC,CAAC,CAAC;IACP,CAAC;IAEO,cAAc,CAAC,IAAY;QAC/B,IAAI,GAAoB,CAAC;QACzB,IAAI,CAAC;YACD,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAoB,CAAC;QAC9C,CAAC;QAAC,MAAM,CAAC;YACL,OAAO;QACX,CAAC;QACD,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC1C,IAAI,OAAO,EAAE,CAAC;gBACV,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC7B,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBAC5B,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;YAC9D,CAAC;YACD,OAAO;QACX,CAAC;QACD,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,kCAAkC,IAAI,GAAG,CAAC,MAAM,KAAK,oCAAoC,CAAC,EAAE,CAAC;YAC/H,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;QACzB,CAAC;IACL,CAAC;IAEO,UAAU,CAAC,MAAc;QAC7B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC5B,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACJ"}

package/dist/broker/broker.grammars.d.ts

@@ -1,99 +1,64 @@
-import type { McpClientInfo } from "@cyanmycelium/mcp-core";
 import { McpGrammar } from "@cyanmycelium/mcp-core";
 /**
  * Locale identifier used to look up a grammar JSON file under
- * `<userAgent>/<locale>.json`. Open string: an application can introduce any
- * value its custom resolver and JSON resources support.
+ * `<userAgent>/<locale>.json`. Open string: a host application can use any
+ * value its grammar resources support.
  *
- * The {@link defaultBrokerLocaleResolver} returns the ISO 639-1 prefix of a
- * BCP-47 tag (`"fr-CA"` → `"fr"`, `"zh-Hans"` → `"zh"`).
+ * The broker registers each `(userAgent, locale)` pair found on disk as a
+ * separate `McpGrammar` keyed by {@link brokerGrammarKey}. The actual
+ * resolution of "which key to use for this session" is delegated to
+ * `@cyanmycelium/mcp-core@0.3.0`'s `grammarResolverFromOptions`, which
+ * handles BCP-47 narrowing (`fr-CA` → `fr` → `en`), agent-family fallback,
+ * and the optional version dimension natively.
  */
 export type BrokerLocale = string;
 /**
  * User-agent family identifier used to look up a grammar JSON file under
- * `<userAgent>/<locale>.json`. Open string. The {@link defaultBrokerUserAgentResolver}
- * recognizes the common LLM families and returns `"default"` for everything else.
+ * `<userAgent>/<locale>.json`. Open string. Conventional values follow
+ * the defaults emitted by `grammarResolverFromOptions`: `claude`, `gpt`,
+ * `mistral`, `copilot`, plus the universal `default`. Custom families
+ * are supported by passing a custom `agents` map in
+ * `StartBrokerServerOptions.grammarResolverOptions`.
  */
 export type BrokerUserAgent = string;
 /**
- * Picks an **ordered fallback chain** of {@link BrokerLocale} values from a raw
- * input. Typically the raw input is `process.env.MCP_BROKER_LOCALE`, but any
- * string source works (HTTP header, session metadata, etc.).
+ * Builds the canonical grammar key for the `(userAgent, locale, version?)`
+ * matrix the broker registers on disk.
  *
- * The returned array is consumed by the broker server most-specific-first, so
- * the resolver controls the BCP-47 narrowing policy. The default resolver
- * follows the standard `lang-region` → `lang` → `en` shape:
+ * Pattern:
+ *   - `"<userAgent>:<locale>"` (no version) — e.g. `"claude:fr"`, `"default:en"`
+ *   - `"<userAgent>:<locale>@<version>"` (versioned) — e.g. `"claude:fr@v2"`
  *
- * ```
- *   raw = "fr-CA"  →  ["fr-ca", "fr", "en"]
- *   raw = "en-US"  →  ["en-us", "en"]
- *   raw = "zh"     →  ["zh", "en"]
- *   raw = ""       →  ["en"]
- * ```
+ * The colon separator is reserved for the `<ua>:<locale>` composition; the
+ * `@` separator is reserved for the optional version suffix. Neither
+ * character is allowed inside the identifier segments. This matches the
+ * default `composeKey` of `grammarResolverFromOptions` exactly, so a
+ * broker-loaded grammar at `claude/fr@v2.json` is automatically picked up
+ * when a Claude session resolves to the `claude:fr@v2` candidate.
+ */
+export declare function brokerGrammarKey(userAgent: BrokerUserAgent, locale: BrokerLocale, version?: string): string;
+/**
+ * Parses a grammar JSON filename of the form `<locale>.json` or
+ * `<locale>@<version>.json` (without the `.json` suffix) into its
+ * components. The first `@` (if any) separates locale from version; any
+ * additional `@` is folded into the version string.
  *
- * A custom resolver may shape the chain however it wants — e.g. inject a
- * project-specific dialect first, skip the bare language prefix, or pull
- * candidates from a session config.
+ * Returns `null` when the input cannot be split into a usable locale.
  */
-export type BrokerLocaleResolver = (raw: string | undefined) => BrokerLocale[];
-/**
- * Picks a {@link BrokerUserAgent} from the connecting client's identity. Called
- * by the embedded broker `McpServer` once per session, during the MCP
- * `initialize` handshake.
- */
-export type BrokerUserAgentResolver = (clientInfo: McpClientInfo | undefined) => BrokerUserAgent;
-/**
- * Default locale resolver — emits the BCP-47 narrowing chain for a raw locale
- * tag, from most specific to least specific, always ending with the universal
- * `"en"` fallback.
- *
- * Steps for an input `raw`:
- * 1. Lowercase the input.
- * 2. Push it as the most-specific candidate (only if non-empty).
- * 3. If it contains a `-` separator, push its bare language prefix next.
- * 4. Always push `"en"` last as the universal fallback.
- *
- * The broker server tries each candidate in turn against `<userAgent>/<locale>.json`
- * — so dropping a `claude/fr-ca.json` lets Canadian-French Claude clients
- * pick up that specific dialect, while clients with `fr` or `fr-FR` fall back
- * to `claude/fr.json` or `default/fr.json` automatically.
- *
- * Examples:
- * - `"fr-CA"`  → `["fr-ca", "fr", "en"]`
- * - `"fr"`     → `["fr", "en"]`
- * - `"zh-CN"`  → `["zh-cn", "zh", "en"]`
- * - `"en-US"`  → `["en-us", "en"]`
- * - `""` / `undefined` → `["en"]`
- */
-export declare const defaultBrokerLocaleResolver: BrokerLocaleResolver;
-/**
- * Default user-agent resolver — substring match on `clientInfo.name` against
- * a list of known LLM family hints. Unknown clients fall through to
- * `"default"` which is the universal baseline.
- *
- * This is intentionally a heuristic: MCP does not yet standardize an
- * agent-family field in `clientInfo`. Override the resolver in the broker
- * options if you need richer logic (header inspection, allow-list, etc.).
- */
-export declare const defaultBrokerUserAgentResolver: BrokerUserAgentResolver;
-/** @deprecated Use {@link defaultBrokerLocaleResolver}. Kept as backward-compat alias. */
-export declare const resolveBrokerLocale: BrokerLocaleResolver;
-/** @deprecated Use {@link defaultBrokerUserAgentResolver}. Kept as backward-compat alias. */
-export declare const resolveBrokerUserAgent: (clientName: string | undefined) => BrokerUserAgent;
+export declare function parseBrokerGrammarStem(stem: string): {
+    locale: BrokerLocale;
+    version?: string;
+} | null;
 /**
- * Builds the canonical grammar key for the `(userAgent, locale)` matrix.
+ * Loads and caches the grammar for a given `(userAgent, locale, version?)`
+ * combination. Returns `undefined` (instead of throwing) when the resource
+ * file is missing, so the caller can implement a fallback chain.
  *
- * Pattern: `"<userAgent>:<locale>"` — e.g. `"claude:fr"`, `"default:en"`.
- * The colon separator is reserved for this composition and never appears in
- * user-agent or locale identifiers.
- */
-export declare function brokerGrammarKey(userAgent: BrokerUserAgent, locale: BrokerLocale): string;
-/**
- * Loads and caches the grammar for a given `(userAgent, locale)` combination.
- * Returns `undefined` (instead of throwing) when the resource file is missing,
- * so the caller can implement a fallback chain.
+ * Filename convention on disk:
+ *   - `<userAgent>/<locale>.json` (no version)
+ *   - `<userAgent>/<locale>@<version>.json` (versioned)
  */
-export declare function loadBrokerGrammar(userAgent: BrokerUserAgent, locale: BrokerLocale): McpGrammar | undefined;
+export declare function loadBrokerGrammar(userAgent: BrokerUserAgent, locale: BrokerLocale, version?: string): McpGrammar | undefined;
 /**
  * Walks a grammars directory and yields every `(userAgent, locale)` pair
  * found on disk. The directory must follow the layout
@@ -103,12 +68,16 @@ export declare function loadBrokerGrammar(userAgent: BrokerUserAgent, locale: Br
  * grammars and any local overrides. No hard-coded list of supported
  * user-agents or locales — adding a new grammar is dropping a JSON file.
  */
-export declare function iterBrokerGrammarsFrom(grammarsDir: string): Generator<{
+export interface BrokerGrammarEntry {
     userAgent: BrokerUserAgent;
     locale: BrokerLocale;
+    /** Set only for filenames carrying an `@<version>` suffix. */
+    version?: string;
+    /** Composed via {@link brokerGrammarKey} from the three segments above. */
     key: string;
     grammar: McpGrammar;
-}>;
+}
+export declare function iterBrokerGrammarsFrom(grammarsDir: string): Generator<BrokerGrammarEntry>;
 /**
  * Walks the **packaged** grammars directory (the one shipped with the
  * mcp-broker package). Equivalent to `iterBrokerGrammarsFrom(<packaged-dir>)`.
@@ -116,12 +85,7 @@ export declare function iterBrokerGrammarsFrom(grammarsDir: string): Generator<{
  * For local user overrides, see {@link iterBrokerGrammarsFrom} with a custom
  * directory — typically `.mcp-broker/grammars/` next to the config file.
  */
-export declare function iterAvailableBrokerGrammars(): Generator<{
-    userAgent: BrokerUserAgent;
-    locale: BrokerLocale;
-    key: string;
-    grammar: McpGrammar;
-}>;
+export declare function iterAvailableBrokerGrammars(): Generator<BrokerGrammarEntry>;
 /**
  * Returns the baseline grammar used by the broker behaviors as their
  * source-of-truth for inline tool / property descriptions.

package/dist/broker/broker.grammars.js

@@ -3,81 +3,44 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { McpGrammar } from "@cyanmycelium/mcp-core";
 // ---------------------------------------------------------------------------
-// Default resolvers
+// Canonical grammar key
 // ---------------------------------------------------------------------------
 /**
- * Default locale resolver — emits the BCP-47 narrowing chain for a raw locale
- * tag, from most specific to least specific, always ending with the universal
- * `"en"` fallback.
- *
- * Steps for an input `raw`:
- * 1. Lowercase the input.
- * 2. Push it as the most-specific candidate (only if non-empty).
- * 3. If it contains a `-` separator, push its bare language prefix next.
- * 4. Always push `"en"` last as the universal fallback.
+ * Builds the canonical grammar key for the `(userAgent, locale, version?)`
+ * matrix the broker registers on disk.
  *
- * The broker server tries each candidate in turn against `<userAgent>/<locale>.json`
- * — so dropping a `claude/fr-ca.json` lets Canadian-French Claude clients
- * pick up that specific dialect, while clients with `fr` or `fr-FR` fall back
- * to `claude/fr.json` or `default/fr.json` automatically.
+ * Pattern:
+ *   - `"<userAgent>:<locale>"` (no version) — e.g. `"claude:fr"`, `"default:en"`
+ *   - `"<userAgent>:<locale>@<version>"` (versioned) — e.g. `"claude:fr@v2"`
  *
- * Examples:
- * - `"fr-CA"`  → `["fr-ca", "fr", "en"]`
- * - `"fr"`     → `["fr", "en"]`
- * - `"zh-CN"`  → `["zh-cn", "zh", "en"]`
- * - `"en-US"`  → `["en-us", "en"]`
- * - `""` / `undefined` → `["en"]`
+ * The colon separator is reserved for the `<ua>:<locale>` composition; the
+ * `@` separator is reserved for the optional version suffix. Neither
+ * character is allowed inside the identifier segments. This matches the
+ * default `composeKey` of `grammarResolverFromOptions` exactly, so a
+ * broker-loaded grammar at `claude/fr@v2.json` is automatically picked up
+ * when a Claude session resolves to the `claude:fr@v2` candidate.
  */
-export const defaultBrokerLocaleResolver = (raw) => {
-    const a = [];
-    if (raw) {
-        const sep = "-";
-        raw = raw.toLowerCase();
-        a.push(raw);
-        if (raw.indexOf(sep) !== -1) {
-            a.push(raw.split(sep)[0]);
-        }
-    }
-    a.push("en");
-    return a;
-};
-/**
- * Default user-agent resolver — substring match on `clientInfo.name` against
- * a list of known LLM family hints. Unknown clients fall through to
- * `"default"` which is the universal baseline.
- *
- * This is intentionally a heuristic: MCP does not yet standardize an
- * agent-family field in `clientInfo`. Override the resolver in the broker
- * options if you need richer logic (header inspection, allow-list, etc.).
- */
-export const defaultBrokerUserAgentResolver = (clientInfo) => {
-    const n = (clientInfo?.name ?? "").toLowerCase();
-    if (n.includes("claude"))
-        return "claude";
-    if (n.includes("gpt") || n.includes("openai"))
-        return "gpt";
-    if (n.includes("mistral"))
-        return "mistral";
-    if (n.includes("copilot"))
-        return "copilot";
-    return "default";
-};
-/** @deprecated Use {@link defaultBrokerLocaleResolver}. Kept as backward-compat alias. */
-export const resolveBrokerLocale = defaultBrokerLocaleResolver;
-/** @deprecated Use {@link defaultBrokerUserAgentResolver}. Kept as backward-compat alias. */
-export const resolveBrokerUserAgent = (clientName) => defaultBrokerUserAgentResolver({ name: clientName ?? "", version: "" });
-// ---------------------------------------------------------------------------
-// Canonical grammar key
-// ---------------------------------------------------------------------------
+export function brokerGrammarKey(userAgent, locale, version) {
+    const base = `${userAgent}:${locale}`;
+    return version ? `${base}@${version}` : base;
+}
 /**
- * Builds the canonical grammar key for the `(userAgent, locale)` matrix.
+ * Parses a grammar JSON filename of the form `<locale>.json` or
+ * `<locale>@<version>.json` (without the `.json` suffix) into its
+ * components. The first `@` (if any) separates locale from version; any
+ * additional `@` is folded into the version string.
  *
- * Pattern: `"<userAgent>:<locale>"` — e.g. `"claude:fr"`, `"default:en"`.
- * The colon separator is reserved for this composition and never appears in
- * user-agent or locale identifiers.
+ * Returns `null` when the input cannot be split into a usable locale.
  */
-export function brokerGrammarKey(userAgent, locale) {
-    return `${userAgent}:${locale}`;
+export function parseBrokerGrammarStem(stem) {
+    const at = stem.indexOf("@");
+    if (at < 0)
+        return stem.length > 0 ? { locale: stem } : null;
+    const locale = stem.slice(0, at);
+    const version = stem.slice(at + 1);
+    if (locale.length === 0 || version.length === 0)
+        return null;
+    return { locale, version };
 }
 // ---------------------------------------------------------------------------
 // JSON resource loading
@@ -105,16 +68,21 @@ export function brokerGrammarKey(userAgent, locale) {
 const GRAMMARS_DIR = join(dirname(fileURLToPath(import.meta.url)), "grammars");
 const _cache = new Map();
 /**
- * Loads and caches the grammar for a given `(userAgent, locale)` combination.
- * Returns `undefined` (instead of throwing) when the resource file is missing,
- * so the caller can implement a fallback chain.
+ * Loads and caches the grammar for a given `(userAgent, locale, version?)`
+ * combination. Returns `undefined` (instead of throwing) when the resource
+ * file is missing, so the caller can implement a fallback chain.
+ *
+ * Filename convention on disk:
+ *   - `<userAgent>/<locale>.json` (no version)
+ *   - `<userAgent>/<locale>@<version>.json` (versioned)
  */
-export function loadBrokerGrammar(userAgent, locale) {
-    const key = brokerGrammarKey(userAgent, locale);
+export function loadBrokerGrammar(userAgent, locale, version) {
+    const key = brokerGrammarKey(userAgent, locale, version);
     const cached = _cache.get(key);
     if (cached)
         return cached;
-    const path = join(GRAMMARS_DIR, userAgent, `${locale}.json`);
+    const filename = version ? `${locale}@${version}.json` : `${locale}.json`;
+    const path = join(GRAMMARS_DIR, userAgent, filename);
     if (!existsSync(path))
         return undefined;
     const raw = readFileSync(path, "utf-8");
@@ -123,15 +91,6 @@ export function loadBrokerGrammar(userAgent, locale) {
     _cache.set(key, grammar);
     return grammar;
 }
-/**
- * Walks a grammars directory and yields every `(userAgent, locale)` pair
- * found on disk. The directory must follow the layout
- * `<dir>/<userAgent>/<locale>.json`.
- *
- * Used by the broker server at startup to bulk-register both the packaged
- * grammars and any local overrides. No hard-coded list of supported
- * user-agents or locales — adding a new grammar is dropping a JSON file.
- */
 export function* iterBrokerGrammarsFrom(grammarsDir) {
     if (!existsSync(grammarsDir))
         return;
@@ -144,13 +103,25 @@ export function* iterBrokerGrammarsFrom(grammarsDir) {
         for (const file of files) {
             if (!file.endsWith(".json"))
                 continue;
-            const locale = file.slice(0, -".json".length);
+            const stem = file.slice(0, -".json".length);
+            const parsed = parseBrokerGrammarStem(stem);
+            if (!parsed) {
+                process.stderr.write(`[mcp-broker] Skipping unparseable grammar filename ${file} in ${uaDir}\n`);
+                continue;
+            }
+            const { locale, version } = parsed;
             const path = join(uaDir, file);
             try {
                 const raw = readFileSync(path, "utf-8");
                 const data = JSON.parse(raw);
                 const grammar = McpGrammar.fromJSON(data);
-                yield { userAgent, locale, key: brokerGrammarKey(userAgent, locale), grammar };
+                yield {
+                    userAgent,
+                    locale,
+                    version,
+                    key: brokerGrammarKey(userAgent, locale, version),
+                    grammar,
+                };
             }
             catch (err) {
                 process.stderr.write(`[mcp-broker] Failed to load grammar ${path}: ${err.message}\n`);

package/dist/broker/broker.grammars.js.map

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

package/dist/broker/broker.server.d.ts

@@ -1,5 +1,4 @@
-import type { IMcpServer, IMessageTransport } from "@cyanmycelium/mcp-core";
-import type { BrokerLocaleResolver, BrokerUserAgentResolver } from "./broker.grammars.js";
+import type { GrammarResolverOptions, IMcpServer, IMessageTransport } from "@cyanmycelium/mcp-core";
 import type { BrokerContext } from "./broker.context.js";
 /**
  * Reserved provider slot name under which the broker exposes itself as an MCP
@@ -16,29 +15,32 @@ export declare const BROKER_PROVIDER_NAME = "_broker";
  */
 export interface StartBrokerServerOptions {
     /**
-     * Picks a locale (BCP-47 base language, by convention) for the current
-     * session. Defaults to {@link defaultBrokerLocaleResolver} which reads
-     * `MCP_BROKER_LOCALE` and keeps the ISO 639-1 prefix.
-     */
-    localeResolver?: BrokerLocaleResolver;
-    /**
-     * Picks a user-agent family for the connecting client. Defaults to
-     * {@link defaultBrokerUserAgentResolver} which substring-matches
-     * `clientInfo.name` against known LLM families.
-     */
-    userAgentResolver?: BrokerUserAgentResolver;
-    /**
-     * Source of the raw locale string fed to the locale resolver. Defaults
-     * to `process.env.MCP_BROKER_LOCALE`. Override when the locale lives
-     * somewhere else (config file, session metadata, HTTP header proxy, ...).
+     * Overrides for the built-in grammar resolver from `@cyanmycelium/mcp-core`.
+     *
+     * The broker installs sensible defaults: `localeSource` reads
+     * `process.env.MCP_BROKER_LOCALE`, the `agents` map uses the mcp-core
+     * defaults (`claude`, `gpt`, `mistral`, `copilot`, `default`), the
+     * narrowing chain is BCP-47-style, and `fallbackKey` is `default:en`
+     * so the baseline grammar always matches as last resort.
+     *
+     * Pass partial overrides here to inject a custom `localeSource` (e.g.
+     * pull from an HTTP header proxied by your transport), enable the
+     * `versionFrom` dimension, or extend the `agents` map with additional
+     * LLM families. Anything you omit keeps the broker default.
      */
-    localeSource?: () => string | undefined;
+    grammarResolverOptions?: Partial<GrammarResolverOptions>;
     /**
      * Path to a user-supplied grammars directory whose `<userAgent>/<locale>.json`
-     * files are merged **on top of** the packaged grammars. Local entries win
-     * on conflicts; missing entries fall through to the packaged values.
+     * files are registered **in addition to** the packaged grammars.
+     *
+     * Both packaged and local entries are registered raw against the server
+     * via `withGrammar(brokerGrammarKey(ua, locale), grammar)`. The
+     * candidate-chain resolution implemented by `McpServer.initialize` in
+     * mcp-core@0.3.0 then walks the chain and merges the four layers
+     * (behavior, adapter, static, store) for the first matching key —
+     * the old hand-rolled pre-merge cascade is no longer needed.
      *
-     * When `undefined` (default), only the packaged grammars are used.
+     * When `undefined` (default), only the packaged grammars are loaded.
      */
     localGrammarsDir?: string;
 }