@cyanmycelium/mcp-broker 0.1.0

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

@@ -0,0 +1,166 @@
+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.
+ *
+ * The {@link defaultBrokerLocaleResolver} returns the ISO 639-1 prefix of a
+ * BCP-47 tag (`"fr-CA"` → `"fr"`, `"zh-Hans"` → `"zh"`).
+ */
+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.
+ */
+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.).
+ *
+ * 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:
+ *
+ * ```
+ *   raw = "fr-CA"  →  ["fr-ca", "fr", "en"]
+ *   raw = "en-US"  →  ["en-us", "en"]
+ *   raw = "zh"     →  ["zh", "en"]
+ *   raw = ""       →  ["en"]
+ * ```
+ *
+ * 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.
+ */
+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;
+/**
+ * Builds the canonical grammar key for the `(userAgent, locale)` matrix.
+ *
+ * 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.
+ */
+export declare function loadBrokerGrammar(userAgent: BrokerUserAgent, locale: BrokerLocale): McpGrammar | undefined;
+/**
+ * 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 declare function iterBrokerGrammarsFrom(grammarsDir: string): Generator<{
+    userAgent: BrokerUserAgent;
+    locale: BrokerLocale;
+    key: string;
+    grammar: McpGrammar;
+}>;
+/**
+ * Walks the **packaged** grammars directory (the one shipped with the
+ * mcp-broker package). Equivalent to `iterBrokerGrammarsFrom(<packaged-dir>)`.
+ *
+ * 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;
+}>;
+/**
+ * Returns the baseline grammar used by the broker behaviors as their
+ * source-of-truth for inline tool / property descriptions.
+ *
+ * Conventionally this is `default:en`. Session-specific grammars selected by
+ * the resolver override individual entries on top of this baseline.
+ *
+ * Throws if the JSON resource is missing — the broker behaviors cannot be
+ * built without baseline descriptions.
+ */
+export declare function brokerBaselineGrammar(): McpGrammar;
+/**
+ * Convenience accessor for a baseline tool description. Throws when the
+ * tool is not listed in the baseline grammar — i.e. the JSON file is missing
+ * an entry for a tool the code knows about.
+ */
+export declare function brokerBaselineToolDescription(toolName: string): string;
+/**
+ * Convenience accessor for a baseline property description. Throws when the
+ * property is not listed under the tool in the baseline grammar.
+ */
+export declare function brokerBaselinePropertyDescription(toolName: string, propertyName: string): string;
+/**
+ * Convenience accessor for a baseline resource name. Throws when the resource
+ * URI has no entry in the baseline grammar.
+ */
+export declare function brokerBaselineResourceName(uri: string): string;
+/**
+ * Convenience accessor for a baseline resource description. Throws when the
+ * resource URI has no entry in the baseline grammar.
+ */
+export declare function brokerBaselineResourceDescription(uri: string): string;
+/**
+ * Convenience accessor for a baseline resource template name. Throws when the
+ * template URI has no entry in the baseline grammar.
+ */
+export declare function brokerBaselineResourceTemplateName(uriTemplate: string): string;
+/**
+ * Convenience accessor for a baseline resource template description. Throws
+ * when the template URI has no entry in the baseline grammar.
+ */
+export declare function brokerBaselineResourceTemplateDescription(uriTemplate: string): string;

package/dist/broker/broker.grammars.js

@@ -0,0 +1,258 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpGrammar } from "@cyanmycelium/mcp-core";
+// ---------------------------------------------------------------------------
+// Default resolvers
+// ---------------------------------------------------------------------------
+/**
+ * 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 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
+// ---------------------------------------------------------------------------
+/**
+ * Builds the canonical grammar key for the `(userAgent, locale)` matrix.
+ *
+ * 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 function brokerGrammarKey(userAgent, locale) {
+    return `${userAgent}:${locale}`;
+}
+// ---------------------------------------------------------------------------
+// JSON resource loading
+// ---------------------------------------------------------------------------
+/**
+ * Absolute path of the directory holding the grammar JSON resources.
+ *
+ * Layout (one folder per user-agent family, one JSON file per locale):
+ * ```
+ * <GRAMMARS_DIR>/
+ * ├── default/
+ * │   ├── en.json
+ * │   ├── fr.json
+ * │   └── zh.json
+ * └── claude/
+ *     ├── en.json
+ *     └── fr.json
+ * ```
+ *
+ * JSON files live alongside this module in `src/broker/grammars/` during
+ * development and are mirrored under `dist/broker/grammars/` at build time
+ * by `scripts/copy-assets.mjs`. Adding a new `(userAgent, locale)` pair is
+ * just a matter of dropping a new JSON file — no code change required.
+ */
+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.
+ */
+export function loadBrokerGrammar(userAgent, locale) {
+    const key = brokerGrammarKey(userAgent, locale);
+    const cached = _cache.get(key);
+    if (cached)
+        return cached;
+    const path = join(GRAMMARS_DIR, userAgent, `${locale}.json`);
+    if (!existsSync(path))
+        return undefined;
+    const raw = readFileSync(path, "utf-8");
+    const data = JSON.parse(raw);
+    const grammar = McpGrammar.fromJSON(data);
+    _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;
+    const userAgents = readdirSync(grammarsDir).sort();
+    for (const userAgent of userAgents) {
+        const uaDir = join(grammarsDir, userAgent);
+        if (!statSync(uaDir).isDirectory())
+            continue;
+        const files = readdirSync(uaDir).sort();
+        for (const file of files) {
+            if (!file.endsWith(".json"))
+                continue;
+            const locale = file.slice(0, -".json".length);
+            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 };
+            }
+            catch (err) {
+                process.stderr.write(`[mcp-broker] Failed to load grammar ${path}: ${err.message}\n`);
+            }
+        }
+    }
+}
+/**
+ * Walks the **packaged** grammars directory (the one shipped with the
+ * mcp-broker package). Equivalent to `iterBrokerGrammarsFrom(<packaged-dir>)`.
+ *
+ * For local user overrides, see {@link iterBrokerGrammarsFrom} with a custom
+ * directory — typically `.mcp-broker/grammars/` next to the config file.
+ */
+export function* iterAvailableBrokerGrammars() {
+    yield* iterBrokerGrammarsFrom(GRAMMARS_DIR);
+}
+// ---------------------------------------------------------------------------
+// Baseline helpers (used by behaviors to source their inline descriptions)
+// ---------------------------------------------------------------------------
+/**
+ * Returns the baseline grammar used by the broker behaviors as their
+ * source-of-truth for inline tool / property descriptions.
+ *
+ * Conventionally this is `default:en`. Session-specific grammars selected by
+ * the resolver override individual entries on top of this baseline.
+ *
+ * Throws if the JSON resource is missing — the broker behaviors cannot be
+ * built without baseline descriptions.
+ */
+export function brokerBaselineGrammar() {
+    const g = loadBrokerGrammar("default", "en");
+    if (!g) {
+        throw new Error(`Required baseline broker grammar "default:en" is missing — expected at ${join(GRAMMARS_DIR, "default", "en.json")}.`);
+    }
+    return g;
+}
+/**
+ * Convenience accessor for a baseline tool description. Throws when the
+ * tool is not listed in the baseline grammar — i.e. the JSON file is missing
+ * an entry for a tool the code knows about.
+ */
+export function brokerBaselineToolDescription(toolName) {
+    const desc = brokerBaselineGrammar().getToolDescription(toolName);
+    if (!desc) {
+        throw new Error(`Missing baseline description for tool "${toolName}" in default/en.json.`);
+    }
+    return desc;
+}
+/**
+ * Convenience accessor for a baseline property description. Throws when the
+ * property is not listed under the tool in the baseline grammar.
+ */
+export function brokerBaselinePropertyDescription(toolName, propertyName) {
+    const desc = brokerBaselineGrammar().getPropertyDescription(toolName, propertyName);
+    if (!desc) {
+        throw new Error(`Missing baseline description for property "${propertyName}" of tool "${toolName}" in default/en.json.`);
+    }
+    return desc;
+}
+/**
+ * Convenience accessor for a baseline resource name. Throws when the resource
+ * URI has no entry in the baseline grammar.
+ */
+export function brokerBaselineResourceName(uri) {
+    const name = brokerBaselineGrammar().getResourceName(uri);
+    if (!name) {
+        throw new Error(`Missing baseline name for resource "${uri}" in default/en.json.`);
+    }
+    return name;
+}
+/**
+ * Convenience accessor for a baseline resource description. Throws when the
+ * resource URI has no entry in the baseline grammar.
+ */
+export function brokerBaselineResourceDescription(uri) {
+    const desc = brokerBaselineGrammar().getResourceDescription(uri);
+    if (!desc) {
+        throw new Error(`Missing baseline description for resource "${uri}" in default/en.json.`);
+    }
+    return desc;
+}
+/**
+ * Convenience accessor for a baseline resource template name. Throws when the
+ * template URI has no entry in the baseline grammar.
+ */
+export function brokerBaselineResourceTemplateName(uriTemplate) {
+    const name = brokerBaselineGrammar().getResourceTemplateName(uriTemplate);
+    if (!name) {
+        throw new Error(`Missing baseline name for resource template "${uriTemplate}" in default/en.json.`);
+    }
+    return name;
+}
+/**
+ * Convenience accessor for a baseline resource template description. Throws
+ * when the template URI has no entry in the baseline grammar.
+ */
+export function brokerBaselineResourceTemplateDescription(uriTemplate) {
+    const desc = brokerBaselineGrammar().getResourceTemplateDescription(uriTemplate);
+    if (!desc) {
+        throw new Error(`Missing baseline description for resource template "${uriTemplate}" in default/en.json.`);
+    }
+    return desc;
+}
+//# sourceMappingURL=broker.grammars.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,64 @@
+import type { IMcpServer, IMessageTransport } from "@cyanmycelium/mcp-core";
+import type { BrokerLocaleResolver, BrokerUserAgentResolver } from "./broker.grammars.js";
+import type { BrokerContext } from "./broker.context.js";
+/**
+ * Reserved provider slot name under which the broker exposes itself as an MCP
+ * server. Clients reach it via `<host>/_broker/mcp` (or any other client transport).
+ *
+ * Prefixed with `_` to make it unambiguously a system slot, and to reduce the
+ * chance of collision with user-supplied provider names.
+ */
+export declare const BROKER_PROVIDER_NAME = "_broker";
+/**
+ * Optional knobs passed to {@link startBrokerServer}. Lets the embedder
+ * replace either resolver with custom logic without touching mcp-broker
+ * internals.
+ */
+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, ...).
+     */
+    localeSource?: () => string | undefined;
+    /**
+     * 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.
+     *
+     * When `undefined` (default), only the packaged grammars are used.
+     */
+    localGrammarsDir?: string;
+}
+/**
+ * Constructs the broker's own MCP server (the Tier-1 introspection behaviors)
+ * and returns the running server plus the loopback transport that must be
+ * registered against the {@link WsTunnel} as the `_broker` provider slot.
+ *
+ * Usage from {@link WsTunnel.start}:
+ * ```ts
+ * const { server, clientTransport } = await startBrokerServer(this, { ... });
+ * this._registerLoopbackProvider(BROKER_PROVIDER_NAME, clientTransport);
+ * ```
+ *
+ * @param context  Read-only view of the broker's state.
+ * @param options  Optional resolver overrides.
+ * @returns The running {@link IMcpServer} (call `.stop()` on shutdown) and the
+ *          loopback transport to attach to the tunnel.
+ */
+export declare function startBrokerServer(context: BrokerContext, options?: StartBrokerServerOptions): Promise<{
+    server: IMcpServer;
+    clientTransport: IMessageTransport;
+}>;

package/dist/broker/broker.server.js

@@ -0,0 +1,111 @@
+import { McpGrammar, McpServerBuilder, LoopbackTransport } from "@cyanmycelium/mcp-core";
+import { BrokerInfoBehavior } from "./behaviors/broker.behavior.info.js";
+import { BrokerProvidersBehavior } from "./behaviors/broker.behavior.providers.js";
+import { brokerGrammarKey, defaultBrokerLocaleResolver, defaultBrokerUserAgentResolver, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom } from "./broker.grammars.js";
+/**
+ * Reserved provider slot name under which the broker exposes itself as an MCP
+ * server. Clients reach it via `<host>/_broker/mcp` (or any other client transport).
+ *
+ * Prefixed with `_` to make it unambiguously a system slot, and to reduce the
+ * chance of collision with user-supplied provider names.
+ */
+export const BROKER_PROVIDER_NAME = "_broker";
+/**
+ * Constructs the broker's own MCP server (the Tier-1 introspection behaviors)
+ * and returns the running server plus the loopback transport that must be
+ * registered against the {@link WsTunnel} as the `_broker` provider slot.
+ *
+ * Usage from {@link WsTunnel.start}:
+ * ```ts
+ * const { server, clientTransport } = await startBrokerServer(this, { ... });
+ * this._registerLoopbackProvider(BROKER_PROVIDER_NAME, clientTransport);
+ * ```
+ *
+ * @param context  Read-only view of the broker's state.
+ * @param options  Optional resolver overrides.
+ * @returns The running {@link IMcpServer} (call `.stop()` on shutdown) and the
+ *          loopback transport to attach to the tunnel.
+ */
+export async function startBrokerServer(context, options = {}) {
+    const localeResolver = options.localeResolver ?? defaultBrokerLocaleResolver;
+    const userAgentResolver = options.userAgentResolver ?? defaultBrokerUserAgentResolver;
+    const localeSource = options.localeSource ?? (() => process.env["MCP_BROKER_LOCALE"]);
+    const [serverEnd, clientEnd] = LoopbackTransport.createPair();
+    const builder = new McpServerBuilder().withName(BROKER_PROVIDER_NAME).withTransport(serverEnd).register(new BrokerInfoBehavior(context), new BrokerProvidersBehavior(context));
+    // Discover every grammar by scanning two directories:
+    //   1. The packaged grammars shipped with the broker.
+    //   2. Optionally, a user-supplied directory whose entries are merged
+    //      ON TOP of the packaged ones (local wins on conflicts).
+    //
+    // Then build the (userAgent × locale) matrix. Within each user-agent,
+    // the grammar cascades on top of "default:<locale>" so per-user-agent
+    // files can stay partial.
+    const defaults = new Map(); // locale → grammar
+    const overrides = new Map(); // userAgent → locale → grammar
+    function ingest(entry, isOverride) {
+        if (entry.userAgent === "default") {
+            const existing = defaults.get(entry.locale);
+            const merged = existing && isOverride ? McpGrammar.merge(existing, entry.grammar) : entry.grammar;
+            defaults.set(entry.locale, merged);
+        }
+        else {
+            let byLocale = overrides.get(entry.userAgent);
+            if (!byLocale) {
+                byLocale = new Map();
+                overrides.set(entry.userAgent, byLocale);
+            }
+            const existing = byLocale.get(entry.locale);
+            const merged = existing && isOverride ? McpGrammar.merge(existing, entry.grammar) : entry.grammar;
+            byLocale.set(entry.locale, merged);
+        }
+    }
+    for (const entry of iterAvailableBrokerGrammars())
+        ingest(entry, false);
+    if (options.localGrammarsDir) {
+        for (const entry of iterBrokerGrammarsFrom(options.localGrammarsDir))
+            ingest(entry, true);
+    }
+    const availableKeys = new Set();
+    // Register every "default:<locale>" as-is.
+    for (const [locale, grammar] of defaults) {
+        const key = brokerGrammarKey("default", locale);
+        builder.withGrammar(key, grammar);
+        availableKeys.add(key);
+    }
+    // Register every "<userAgent>:<locale>" as merge(default:<locale>, ua:<locale>).
+    // The user-agent grammar wins per entry; missing entries cascade from default.
+    for (const [agent, byLocale] of overrides) {
+        for (const [locale, uaGrammar] of byLocale) {
+            const baseline = defaults.get(locale);
+            const merged = baseline ? McpGrammar.merge(baseline, uaGrammar) : uaGrammar;
+            const key = brokerGrammarKey(agent, locale);
+            builder.withGrammar(key, merged);
+            availableKeys.add(key);
+        }
+    }
+    builder.withGrammarResolver((clientInfo) => {
+        // localeResolver returns the full fallback chain (most specific first),
+        // ending with the universal "en". The user-agent axis is the broker's
+        // own concern: per locale, prefer the user-agent-specific grammar, then
+        // fall back to the "default" agent.
+        const locales = localeResolver(localeSource());
+        const userAgent = userAgentResolver(clientInfo);
+        const userAgents = userAgent === "default" ? ["default"] : [userAgent, "default"];
+        for (const locale of locales) {
+            for (const ua of userAgents) {
+                const key = brokerGrammarKey(ua, locale);
+                if (availableKeys.has(key))
+                    return key;
+            }
+        }
+        // None of the candidates is on disk → return an empty key. McpServer
+        // then falls back to the behavior's baseline descriptions (English).
+        return "";
+    });
+    // No reconnect policy → the McpServer does not attempt to reopen the loopback
+    // when WsTunnel.stop() closes it. Clean shutdown.
+    const server = builder.build();
+    await server.start();
+    return { server, clientTransport: clientEnd };
+}
+//# sourceMappingURL=broker.server.js.map

package/dist/broker/broker.server.js.map

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

package/dist/broker/grammars/claude/en.json

@@ -0,0 +1,16 @@
+{
+    "tools": {
+        "broker_info": {
+            "description": "Get the broker's identity: name, version, uptime, host, port, TLS, and URL paths. Call this first when you need to know what you are talking to."
+        },
+        "providers_list": {
+            "description": "List every provider slot on this broker, connected or not. Each entry tells you the transport kind, current client count, and how many requests are in flight. Use this to discover what you can route to."
+        },
+        "provider_status": {
+            "description": "Get the full status of one provider slot by name. Returns an error if the slot does not exist — start with providers_list if you are not sure of the name.",
+            "properties": {
+                "name": "The exact provider slot name. Case-sensitive. Use providers_list to discover valid values."
+            }
+        }
+    }
+}

package/dist/broker/grammars/claude/fr.json

@@ -0,0 +1,16 @@
+{
+    "tools": {
+        "broker_info": {
+            "description": "Récupère l'identité du broker : nom, version, uptime, hôte, port, TLS et chemins URL. À appeler en premier pour savoir à qui tu parles."
+        },
+        "providers_list": {
+            "description": "Liste tous les emplacements de providers de ce broker, connectés ou non. Chaque entrée indique le type de transport, le nombre de clients actuels et le nombre de requêtes en cours. Utilise-le pour découvrir vers qui tu peux router."
+        },
+        "provider_status": {
+            "description": "Récupère le statut complet d'un emplacement de provider par son nom. Retourne une erreur si l'emplacement n'existe pas — commence par providers_list si tu n'es pas sûr du nom.",
+            "properties": {
+                "name": "Le nom exact de l'emplacement provider. Sensible à la casse. Utilise providers_list pour découvrir les valeurs valides."
+            }
+        }
+    }
+}