@cyanmycelium/mcp-broker 0.2.0 → 0.4.0

package/src/broker/aggregate/aggregate.server.ts

@@ -0,0 +1,178 @@
+import type { IMessageTransport } from "@cyanmycelium/mcp-core";
+import type { InternalClient } from "../../ws.tunnel.js";
+import { AggregateCatalog } from "./aggregate.catalog.js";
+import { ProviderClientSession } from "./provider.client.session.js";
+
+/** MCP protocol version advertised by the aggregate server. */
+const PROTOCOL_VERSION = "2024-11-05";
+
+/** Opens an in-process client to a named provider slot. Supplied by WsTunnel. */
+export type InternalClientFactory = (providerName: string) => InternalClient;
+
+interface ClientMessage {
+    id?: string | number | null;
+    method?: string;
+    params?: unknown;
+}
+
+interface CallParams {
+    name?: string;
+    arguments?: Record<string, unknown>;
+}
+
+/**
+ * The `_all` aggregate MCP server. Presents the union of every opted-in
+ * provider's tools and prompts as a single MCP server, reachable on the
+ * reserved `_all` slot.
+ *
+ * It implements {@link IMessageTransport} so it can be registered on the
+ * WsTunnel as a loopback provider: `send` receives client requests, `onMessage`
+ * (assigned by the tunnel) carries responses and notifications back to clients.
+ */
+export class AggregateServer implements IMessageTransport {
+    /** Reserved provider slot the aggregate is published on. */
+    static readonly SLOT = "_all";
+
+    private readonly _catalog = new AggregateCatalog();
+    private readonly _sessions = new Map<string, ProviderClientSession>();
+    private readonly _openClient: InternalClientFactory;
+    private _running = false;
+
+    onMessage: ((data: string) => void) | null = null;
+    onOpen: (() => void) | null = null;
+    onClose: (() => void) | null = null;
+    onError: ((error: Error) => void) | null = null;
+
+    constructor(openClient: InternalClientFactory) {
+        this._openClient = openClient;
+    }
+
+    get isOpen(): boolean {
+        return this._running;
+    }
+
+    /** Number of providers currently in the aggregate. */
+    get providerCount(): number {
+        return this._sessions.size;
+    }
+
+    /** Marks the aggregate transport open. Call before registering it. */
+    start(): void {
+        this._running = true;
+    }
+
+    /** WsTunnel hands a client request for the `_all` slot here. */
+    send(data: string): void {
+        void this._handleClientMessage(data);
+    }
+
+    /** Closes every provider session and the aggregate transport. */
+    close(): void {
+        if (!this._running) return;
+        this._running = false;
+        for (const session of this._sessions.values()) session.close();
+        this._sessions.clear();
+        this.onClose?.();
+    }
+
+    /**
+     * Adds a provider to the aggregate: opens an internal client, runs the
+     * session handshake, and merges the provider's catalog. A no-op for an
+     * already-aggregated provider or the reserved `_all` slot itself.
+     */
+    async addProvider(name: string): Promise<void> {
+        if (name === AggregateServer.SLOT || this._sessions.has(name)) return;
+
+        const session = new ProviderClientSession(name, this._openClient(name));
+        this._sessions.set(name, session);
+
+        session.onCatalogChanged = (): void => {
+            this._catalog.setProvider(name, { tools: session.tools, prompts: session.prompts });
+            this._emitListChanged();
+        };
+        session.onClosed = (): void => this.removeProvider(name);
+
+        try {
+            await session.initialize();
+        } catch {
+            this.removeProvider(name);
+        }
+    }
+
+    /** Removes a provider from the aggregate. */
+    removeProvider(name: string): void {
+        const session = this._sessions.get(name);
+        if (!session) return;
+        this._sessions.delete(name);
+        session.close();
+        this._catalog.removeProvider(name);
+        this._emitListChanged();
+    }
+
+    private async _handleClientMessage(data: string): Promise<void> {
+        let msg: ClientMessage;
+        try {
+            msg = JSON.parse(data) as ClientMessage;
+        } catch {
+            return;
+        }
+        const id = msg.id;
+        if (id == null) return; // client notification — nothing to answer
+
+        switch (msg.method) {
+            case "initialize":
+                this._reply(id, {
+                    result: {
+                        protocolVersion: PROTOCOL_VERSION,
+                        serverInfo: { name: AggregateServer.SLOT, version: "0" },
+                        capabilities: { tools: { listChanged: true }, prompts: { listChanged: true } },
+                    },
+                });
+                break;
+            case "ping":
+                this._reply(id, { result: {} });
+                break;
+            case "tools/list":
+                this._reply(id, { result: { tools: this._catalog.tools } });
+                break;
+            case "prompts/list":
+                this._reply(id, { result: { prompts: this._catalog.prompts } });
+                break;
+            case "tools/call":
+                await this._route(id, msg.params, "tool");
+                break;
+            case "prompts/get":
+                await this._route(id, msg.params, "prompt");
+                break;
+            default:
+                this._reply(id, { error: { code: -32601, message: `Method not found: ${msg.method ?? "(none)"}` } });
+        }
+    }
+
+    private async _route(id: string | number, params: unknown, kind: "tool" | "prompt"): Promise<void> {
+        const p = (params ?? {}) as CallParams;
+        const route = p.name ? (kind === "tool" ? this._catalog.resolveTool(p.name) : this._catalog.resolvePrompt(p.name)) : undefined;
+        if (!route) {
+            this._reply(id, { error: { code: -32602, message: `Unknown aggregated ${kind}: ${p.name ?? "(none)"}` } });
+            return;
+        }
+        const session = this._sessions.get(route.provider);
+        if (!session) {
+            this._reply(id, { error: { code: -32000, message: `Provider "${route.provider}" is no longer connected` } });
+            return;
+        }
+        const args = p.arguments ?? {};
+        const outcome = kind === "tool" ? await session.callTool(route.original, args) : await session.getPrompt(route.original, args);
+        this._reply(id, outcome.error !== undefined ? { error: outcome.error } : { result: outcome.result });
+    }
+
+    private _reply(id: string | number, body: { result?: unknown; error?: unknown }): void {
+        this.onMessage?.(JSON.stringify({ jsonrpc: "2.0", id, ...body }));
+    }
+
+    private _emitListChanged(): void {
+        if (!this._running) return;
+        this.onMessage?.(JSON.stringify({ jsonrpc: "2.0", method: "notifications/tools/list_changed" }));
+        this.onMessage?.(JSON.stringify({ jsonrpc: "2.0", method: "notifications/prompts/list_changed" }));
+    }
+}

package/src/broker/aggregate/provider.client.session.ts

@@ -0,0 +1,172 @@
+import type { InternalClient } from "../../ws.tunnel.js";
+import type { CatalogTool, CatalogPrompt } from "./aggregate.catalog.js";
+
+/** 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;
+
+/** Outcome of a JSON-RPC request: exactly one of `result` / `error` is set. */
+interface RpcOutcome {
+    result?: unknown;
+    error?: unknown;
+}
+
+interface PendingRequest {
+    resolve: (outcome: RpcOutcome) => void;
+    timer: ReturnType<typeof setTimeout>;
+}
+
+interface IncomingMessage {
+    id?: string | number | null;
+    method?: string;
+    result?: unknown;
+    error?: unknown;
+}
+
+/**
+ * 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 {
+    readonly provider: string;
+
+    private readonly _client: InternalClient;
+    private readonly _idPrefix: string;
+    private readonly _pending = new Map<string, PendingRequest>();
+    private _nextId = 0;
+    private _tools: CatalogTool[] = [];
+    private _prompts: CatalogPrompt[] = [];
+    private _closed = false;
+
+    /** Fires after the cached catalog changes (initial load or `list_changed`). */
+    onCatalogChanged: (() => void) | null = null;
+
+    /** Fires when the underlying provider slot disconnects. */
+    onClosed: (() => void) | null = null;
+
+    constructor(provider: string, client: InternalClient) {
+        this.provider = provider;
+        this._client = client;
+        this._idPrefix = `agg-${provider}-`;
+        client.onMessage = (data: string): void => this._handleMessage(data);
+        client.onClose = (): void => {
+            if (this._closed) return;
+            this._rejectAll("provider disconnected");
+            this.onClosed?.();
+        };
+    }
+
+    get tools(): CatalogTool[] {
+        return this._tools;
+    }
+
+    get prompts(): CatalogPrompt[] {
+        return this._prompts;
+    }
+
+    /** Runs the `initialize` handshake and the first catalog fetch. */
+    async initialize(): Promise<void> {
+        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: string, args: Record<string, unknown>): Promise<RpcOutcome> {
+        return this._request("tools/call", { name, arguments: args });
+    }
+
+    /** Forwards a `prompts/get` to the provider, relaying the raw outcome. */
+    getPrompt(name: string, args: Record<string, unknown>): Promise<RpcOutcome> {
+        return this._request("prompts/get", { name, arguments: args });
+    }
+
+    /** Detaches the session and its internal client. */
+    close(): void {
+        if (this._closed) return;
+        this._closed = true;
+        this._rejectAll("session closed");
+        this._client.close();
+    }
+
+    private async _refresh(): Promise<void> {
+        this._tools = await this._listAll<CatalogTool>("tools/list", "tools");
+        this._prompts = await this._listAll<CatalogPrompt>("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.
+     */
+    private async _listAll<T>(method: string, key: string): Promise<T[]> {
+        const items: T[] = [];
+        let cursor: string | undefined;
+        do {
+            const { result, error } = await this._request(method, cursor ? { cursor } : {});
+            if (error) return [];
+            const page = (result ?? {}) as Record<string, unknown>;
+            const list = page[key];
+            if (Array.isArray(list)) items.push(...(list as T[]));
+            cursor = typeof page.nextCursor === "string" ? page.nextCursor : undefined;
+        } while (cursor);
+        return items;
+    }
+
+    private _request(method: string, params: unknown): Promise<RpcOutcome> {
+        return new Promise<RpcOutcome>((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 }));
+        });
+    }
+
+    private _handleMessage(data: string): void {
+        let msg: IncomingMessage;
+        try {
+            msg = JSON.parse(data) as IncomingMessage;
+        } 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();
+        }
+    }
+
+    private _rejectAll(reason: string): void {
+        for (const pending of this._pending.values()) {
+            clearTimeout(pending.timer);
+            pending.resolve({ error: { code: -32000, message: reason } });
+        }
+        this._pending.clear();
+    }
+}

package/src/broker/broker.grammars.ts

@@ -1,7 +1,6 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { McpClientInfo } from "@cyanmycelium/mcp-core";
 import { McpGrammar } from "@cyanmycelium/mcp-core";
 
 // ---------------------------------------------------------------------------
@@ -10,131 +9,67 @@ 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;
 
 // ---------------------------------------------------------------------------
-// Resolver function types
-// ---------------------------------------------------------------------------
-
-/**
- * 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 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.
- *
- * 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: BrokerLocaleResolver = (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.
+ * Pattern:
+ *   - `"<userAgent>:<locale>"` (no version) — e.g. `"claude:fr"`, `"default:en"`
+ *   - `"<userAgent>:<locale>@<version>"` (versioned) — e.g. `"claude:fr@v2"`
  *
- * 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.).
+ * 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 defaultBrokerUserAgentResolver: BrokerUserAgentResolver = (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: string | undefined) => BrokerUserAgent = (clientName) => defaultBrokerUserAgentResolver({ name: clientName ?? "", version: "" });
-
-// ---------------------------------------------------------------------------
-// Canonical grammar key
-// ---------------------------------------------------------------------------
+export function brokerGrammarKey(userAgent: BrokerUserAgent, locale: BrokerLocale, version?: string): string {
+    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: BrokerUserAgent, locale: BrokerLocale): string {
-    return `${userAgent}:${locale}`;
+export function parseBrokerGrammarStem(stem: string): { locale: BrokerLocale; version?: string } | null {
+    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 };
 }
 
 // ---------------------------------------------------------------------------
@@ -166,16 +101,21 @@ const GRAMMARS_DIR = join(dirname(fileURLToPath(import.meta.url)), "grammars");
 const _cache = new Map<string, McpGrammar>();
 
 /**
- * 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: BrokerUserAgent, locale: BrokerLocale): McpGrammar | undefined {
-    const key = brokerGrammarKey(userAgent, locale);
+export function loadBrokerGrammar(userAgent: BrokerUserAgent, locale: BrokerLocale, version?: string): McpGrammar | undefined {
+    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");
@@ -194,12 +134,17 @@ export function loadBrokerGrammar(userAgent: BrokerUserAgent, locale: BrokerLoca
  * 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: 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 function* iterBrokerGrammarsFrom(grammarsDir: string): Generator<BrokerGrammarEntry> {
     if (!existsSync(grammarsDir)) return;
 
     const userAgents = readdirSync(grammarsDir).sort();
@@ -210,13 +155,25 @@ export function* iterBrokerGrammarsFrom(grammarsDir: string): Generator<{
         const files = readdirSync(uaDir).sort();
         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 as Error).message}\n`);
             }
@@ -231,12 +188,7 @@ export 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 function* iterAvailableBrokerGrammars(): Generator<{
-    userAgent: BrokerUserAgent;
-    locale: BrokerLocale;
-    key: string;
-    grammar: McpGrammar;
-}> {
+export function* iterAvailableBrokerGrammars(): Generator<BrokerGrammarEntry> {
     yield* iterBrokerGrammarsFrom(GRAMMARS_DIR);
 }