daftari-router 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# daftari-router
+
+Multi-vault MCP router — fan out across N Daftari vaults from one MCP connection.
+
+## Quick start
+
+The router is part of the [daftari repo](https://github.com/mavaali/daftari) and not yet published independently to npm. To run from source:
+
+```bash
+git clone https://github.com/mavaali/daftari.git
+cd daftari/packages/router
+npm install
+npm run build
+node dist/cli.js --config vaults.yaml
+```
+
+(A `daftari-router` npm package and `npx` quick-start will land in a follow-up release.)
+
+The router speaks MCP over stdio. Point any MCP client (Claude Code, Claude Desktop, custom LangGraph agent) at the `daftari-router` binary instead of `daftari`, and it transparently spans multiple vaults.
+
+## Example vaults.yaml
+
+```yaml
+router:
+  transport: stdio
+
+vaults:
+  devops:
+    path: ~/vaults/devops
+    user: agent
+    role: admin
+    description: "Runbooks, incident playbooks, infra architecture"
+  product:
+    path: ~/vaults/product
+    user: agent
+    role: writer
+    description: "Product specs, roadmap decisions, customer research"
+  intel:
+    path: ~/vaults/intel
+    user: agent
+    role: reader
+    description: "Competitive analysis, market positioning, pricing"
+
+defaults:
+  search_limit: 10
+```
+
+## Tool semantics
+
+| Tool | No `vault` arg | With `vault` arg |
+|---|---|---|
+| `vault_read` | error: requires vault | reads from named vault |
+| `vault_index` | aggregates all vaults | filters to that vault |
+| `vault_status` | aggregate health + per-vault breakdown | health of that vault |
+| `vault_search` | fan out + merge by score | search only that vault |
+| `vault_search_related` | error: path is vault-specific | finds related docs in that vault |
+| `vault_reindex` | reindexes all | reindexes that vault |
+| `vault_write` / `vault_append` / `vault_promote` / `vault_deprecate` | error: requires vault | writes to that vault |
+| `vault_tension_log` | error: requires vault | logs in that vault |
+| `vault_lint` | lints all + per-vault breakdown | lints that vault |
+| `vault_provenance` | error: path is vault-specific | provenance in that vault |
+| `vault_themes` | merges themes from all vaults | themes from that vault |
+
+For tools that take a `path` argument, you can use either explicit `vault: "name"` arg or vault-prefixed paths like `devops:runbooks/k8s.md` — the router strips the prefix before forwarding to the child.
+
+Tools with other path-shaped arguments (`vault_provenance` uses `filePath`, `vault_tension_log` uses `sourceA`/`sourceB`) require the explicit `vault:` arg.
+
+## Architecture
+
+```
+                   ┌──────────────────┐
+                   │   MCP Client     │
+                   │ (Claude, agent)  │
+                   └────────┬─────────┘
+                            │ stdio JSON-RPC
+                            ▼
+                   ┌──────────────────┐
+                   │ daftari-router   │
+                   │  ─ catalog       │
+                   │  ─ dispatch      │
+                   │  ─ fan-out merge │
+                   └──┬───────┬───────┘
+                      │       │      stdio JSON-RPC
+            ┌─────────┘       └──────────┐
+            ▼                              ▼
+     ┌─────────────┐                ┌─────────────┐
+     │  daftari    │                │  daftari    │
+     │  (devops)   │       ...      │  (intel)    │
+     └─────────────┘                └─────────────┘
+```
+
+## Requirements
+
+- Node.js >= 20
+- `daftari` >= 1.10.0 installed and on `PATH` (or pass `--daftari-bin <path>`)
+- Each vault directory initialized with `daftari --init`
+
+## Caveats
+
+- **Tool catalog is seeded from the first child's `tools/list`.** If vaults run different daftari versions exposing different tools, the router only exposes the first vault's surface. Mismatches are logged to stderr at startup. Run matched versions across vaults.
+- **Vault names cannot contain `:`** — reserved as the path-prefix separator (e.g., `devops:runbooks/k8s.md`).
+- **Document paths starting with `vault-name:`** collide with the prefix parser. Avoid colons in the first path segment.
+- **v1 search merge assumes homogeneous embedding models** across vaults. Mixing models produces an incoherent ranking. A future Phase 2 normalization pass will fix this.
+- **Write tools never fan out.** You must specify which vault to write to, either via `vault: "name"` arg or a vault-prefixed path. Ambiguous writes are silently rejected as a safety measure.
+- **No auth layer** — the router inherits each child vault's RBAC. Run on trusted infrastructure.
+
+## Running the integration tests
+
+The integration test boots real `daftari` subprocesses against fixture vaults at `test/fixtures/vault-{a,b}`. By default it spawns the daftari CLI at `<repo-root>/dist/cli.js`. Override with the `DAFTARI_BIN` env var to test against an installed version:
+
+```bash
+DAFTARI_BIN=/usr/local/bin/daftari npm test
+```
+
+## What's in Phase 1
+
+- Spawn N children, fan-out search, per-vault dispatch
+- 14-tool surface (read/search/write/curation/themes)
+- Vault-prefixed path convention
+- Graceful shutdown on SIGINT/SIGTERM
+- Per-child handshake timeout
+
+## What's NOT in Phase 1
+
+- Cross-vault lint (`crossVaultTension`, `crossVaultBrokenRef`, `crossVaultStaleChain`)
+- `vault_discover` tool for write-target suggestion
+- HTTP/SSE transport
+- Auth (API key, OAuth)
+- Score normalization across heterogeneous embedding models
+- Child crash auto-restart
+
+See `docs/superpowers/plans/2026-05-29-multivault-router-phase1.md` (in the repo root) for the implementation plan.

package/dist/children.d.ts

@@ -0,0 +1,9 @@
+import { type ChildClient } from "./client.js";
+import type { RouterConfig, VaultConfig } from "./config.js";
+export type ChildPool = {
+    get: (name: string) => ChildClient | null;
+    all: () => ChildClient[];
+    close: () => Promise<void>;
+};
+export declare function createPool(children: ChildClient[]): ChildPool;
+export declare function startPool(config: RouterConfig, daftariBin?: string, spawner?: (vault: VaultConfig, bin: string) => Promise<ChildClient>): Promise<ChildPool>;

package/dist/children.js

@@ -0,0 +1,25 @@
+import { startChild } from "./client.js";
+export function createPool(children) {
+    const byName = new Map(children.map((c) => [c.name, c]));
+    return {
+        get: (n) => byName.get(n) ?? null,
+        all: () => [...children],
+        close: async () => {
+            await Promise.allSettled(children.map((c) => c.close()));
+        },
+    };
+}
+export async function startPool(config, daftariBin = "daftari", spawner = startChild) {
+    const started = [];
+    try {
+        for (const v of config.vaults) {
+            process.stderr.write(`router: starting vault '${v.name}' at ${v.path}\n`);
+            started.push(await spawner(v, daftariBin));
+        }
+        return createPool(started);
+    }
+    catch (e) {
+        await Promise.allSettled(started.map((c) => c.close()));
+        throw e;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from "./index.js";
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    process.stderr.write(`fatal: ${err?.stack ?? String(err)}\n`);
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { VaultConfig } from "./config.js";
+export type CallToolResult = {
+    content: unknown[];
+    isError?: boolean;
+};
+export type ToolDescriptor = {
+    name: string;
+    description?: string;
+    inputSchema: unknown;
+};
+export type ChildClient = {
+    name: string;
+    callTool: (name: string, args: Record<string, unknown>) => Promise<CallToolResult>;
+    listTools: () => Promise<{
+        tools: ToolDescriptor[];
+    }>;
+    close: () => Promise<void>;
+};
+export declare function wrapChildClient(name: string, mcp: Client): ChildClient;
+export declare function startChild(vault: VaultConfig, daftariBin?: string, startTimeoutMs?: number): Promise<ChildClient>;
+export declare function withTimeout<T>(p: Promise<T>, ms: number, onTimeout: () => unknown, msg: string): Promise<T>;

package/dist/client.js

@@ -0,0 +1,51 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+export function wrapChildClient(name, mcp) {
+    return {
+        name,
+        callTool: (toolName, args) => mcp.callTool({ name: toolName, arguments: args }),
+        listTools: () => mcp.listTools(),
+        close: async () => {
+            await mcp.close();
+        },
+    };
+}
+export async function startChild(vault, daftariBin = "daftari", startTimeoutMs = 10_000) {
+    // args[] is passed to cross-spawn with shell:false — no shell injection risk.
+    const transport = new StdioClientTransport({
+        command: daftariBin,
+        args: ["--vault", vault.path, "--user", vault.user, "--role", vault.role],
+    });
+    const mcp = new Client({ name: "daftari-router", version: "0.1.0" }, { capabilities: {} });
+    try {
+        await withTimeout(mcp.connect(transport), startTimeoutMs, () => mcp.close().catch(() => { }), `vault '${vault.name}' did not complete MCP handshake in ${startTimeoutMs}ms`);
+    }
+    catch (err) {
+        await mcp.close().catch(() => { });
+        throw err;
+    }
+    return wrapChildClient(vault.name, mcp);
+}
+export async function withTimeout(p, ms, onTimeout, msg) {
+    let t;
+    try {
+        return await Promise.race([
+            p,
+            new Promise((_, reject) => {
+                t = setTimeout(() => {
+                    try {
+                        onTimeout();
+                    }
+                    catch {
+                        // ignore cleanup errors
+                    }
+                    reject(new Error(msg));
+                }, ms);
+            }),
+        ]);
+    }
+    finally {
+        if (t)
+            clearTimeout(t);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+export type Transport = "stdio";
+export type VaultConfig = {
+    name: string;
+    path: string;
+    user: string;
+    role: string;
+    description: string;
+};
+export type RouterConfig = {
+    transport: Transport;
+    vaults: VaultConfig[];
+    defaults: {
+        searchLimit: number;
+    };
+};
+export declare function parseConfig(yamlText: string): RouterConfig;

package/dist/config.js

@@ -0,0 +1,46 @@
+import { homedir } from "node:os";
+import YAML from "yaml";
+function expandHome(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/"))
+        return `${homedir()}/${p.slice(2)}`;
+    return p;
+}
+export function parseConfig(yamlText) {
+    const raw = YAML.parse(yamlText);
+    if (!raw || typeof raw !== "object")
+        throw new Error("config: empty or non-object root");
+    const router = (raw.router ?? {});
+    const transport = (router.transport ?? "stdio");
+    if (transport !== "stdio")
+        throw new Error(`config: unsupported transport: ${transport}`);
+    const vaultsObj = (raw.vaults ?? {});
+    const names = Object.keys(vaultsObj);
+    if (names.length === 0)
+        throw new Error("config: at least one vault required");
+    const vaults = names.map((name) => {
+        if (name.includes(":"))
+            throw new Error(`config: vault name must not contain colon: ${name}`);
+        const v = vaultsObj[name];
+        for (const f of ["path", "user", "role", "description"]) {
+            if (typeof v?.[f] !== "string" || !v[f])
+                throw new Error(`config: vault ${name} missing ${f}`);
+        }
+        return {
+            name,
+            path: expandHome(v.path),
+            user: v.user,
+            role: v.role,
+            description: v.description,
+        };
+    });
+    const defaults = (raw.defaults ?? {});
+    return {
+        transport,
+        vaults,
+        defaults: {
+            searchLimit: typeof defaults.search_limit === "number" ? defaults.search_limit : 10,
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<number>;

package/dist/index.js

@@ -0,0 +1,110 @@
+import { readFileSync } from "node:fs";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { startPool } from "./children.js";
+import { parseConfig } from "./config.js";
+import { createRouterServer } from "./server.js";
+function flag(argv, name) {
+    const i = argv.indexOf(`--${name}`);
+    if (i !== -1 && argv[i + 1])
+        return argv[i + 1];
+    const prefix = `--${name}=`;
+    const eq = argv.find((a) => a.startsWith(prefix));
+    return eq ? eq.slice(prefix.length) : null;
+}
+export async function main(argv) {
+    const configPath = flag(argv, "config");
+    if (!configPath) {
+        process.stderr.write("usage: daftari-router --config <vaults.yaml>\n");
+        return 2;
+    }
+    // Register shutdown handlers EARLY so SIGINT during slow startup still
+    // cleans up any children that have spawned.
+    let pool = null;
+    let shuttingDown = false;
+    const shutdown = async (sig) => {
+        if (shuttingDown)
+            return; // C2 fix — interlock against double-signal race
+        shuttingDown = true;
+        process.stderr.write(`router: ${sig} — closing children\n`);
+        let exitCode = 0;
+        try {
+            if (pool)
+                await pool.close();
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`router: error during shutdown: ${reason}\n`);
+            exitCode = 1;
+        }
+        finally {
+            process.exit(exitCode);
+        }
+    };
+    process.once("SIGINT", () => void shutdown("SIGINT"));
+    process.once("SIGTERM", () => void shutdown("SIGTERM"));
+    let cfg;
+    try {
+        cfg = parseConfig(readFileSync(configPath, "utf-8"));
+    }
+    catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`router: failed to load config '${configPath}': ${reason}\n`);
+        return 1;
+    }
+    const daftariBin = flag(argv, "daftari-bin") ?? "daftari";
+    try {
+        pool = await startPool(cfg, daftariBin);
+    }
+    catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`router: failed to start pool: ${reason}\n`);
+        return 1;
+    }
+    // Seed catalog from the first child's tools/list. We assume all children
+    // expose the same tool surface (documented in README).
+    const first = pool.all()[0];
+    let toolsResp;
+    try {
+        toolsResp = await first.listTools();
+    }
+    catch (e) {
+        await pool.close();
+        const reason = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`router: failed to list tools from first child: ${reason}\n`);
+        return 1;
+    }
+    // Heterogeneity check: warn if any child exposes a different tool surface.
+    // The catalog is seeded from the first child only; calls to tools the other
+    // children don't have will fail at dispatch time.
+    const firstNames = new Set(toolsResp.tools.map((t) => t.name));
+    for (const child of pool.all().slice(1)) {
+        try {
+            const otherTools = await child.listTools();
+            const otherNames = new Set(otherTools.tools.map((t) => t.name));
+            const missing = [...firstNames].filter((n) => !otherNames.has(n));
+            const extra = [...otherNames].filter((n) => !firstNames.has(n));
+            if (missing.length > 0) {
+                process.stderr.write(`router: warning: vault '${child.name}' is missing tools: ${missing.join(", ")}\n`);
+            }
+            if (extra.length > 0) {
+                process.stderr.write(`router: warning: vault '${child.name}' exposes extra tools (not routed): ${extra.join(", ")}\n`);
+            }
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`router: warning: could not list tools for vault '${child.name}': ${reason}\n`);
+        }
+    }
+    // The SDK's tool shape includes inputSchema typed as `unknown` after our T4
+    // widening. Catalog accepts ChildToolDescriptor (structural). The cast is
+    // safe here because daftari children always return the structural form.
+    const { mcp } = createRouterServer(pool, toolsResp.tools);
+    // Unlike daftari (which opens stdio before indexing to answer initialize
+    // promptly), the router has no usable mode before children are ready —
+    // listTools needs them, callTool needs them. Open the transport last.
+    const transport = new StdioServerTransport();
+    await mcp.connect(transport);
+    process.stderr.write(`router: ready (${cfg.vaults.length} vaults)\n`);
+    // Hold the process open — signal handler will exit.
+    return new Promise(() => { });
+}

package/dist/path.d.ts

@@ -0,0 +1,6 @@
+export type VaultPath = {
+    vault: string | null;
+    path: string;
+};
+export declare function parseVaultPath(raw: string): VaultPath;
+export declare function formatVaultPath(vault: string, path: string): string;

package/dist/path.js

@@ -0,0 +1,9 @@
+export function parseVaultPath(raw) {
+    const idx = raw.indexOf(":");
+    if (idx === -1)
+        return { vault: null, path: raw };
+    return { vault: raw.slice(0, idx), path: raw.slice(idx + 1) };
+}
+export function formatVaultPath(vault, path) {
+    return `${vault}:${path}`;
+}

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { ChildPool } from "./children.js";
+import { type CatalogTool, type ChildToolDescriptor } from "./tools/catalog.js";
+export type Result = {
+    content: unknown[];
+    isError?: boolean;
+};
+export type RouterServer = {
+    mcp: Server;
+    dispatch: (name: string, args: Record<string, unknown>) => Promise<Result>;
+    catalog: CatalogTool[];
+};
+export declare function createRouterServer(pool: ChildPool, childTools: ChildToolDescriptor[]): RouterServer;

package/dist/server.js

@@ -0,0 +1,145 @@
+// server.ts — Router MCP server wiring.
+//
+// Glues the catalog (T6), single-vault dispatch (T7), and fan-out + mergers
+// (T8) behind a single MCP Server instance.
+//
+// Dual dispatch model
+// -------------------
+// `dispatch(name, args)` is exported alongside the SDK `Server`. It is used by:
+//   1. The `CallToolRequestSchema` handler (transport path) — wraps dispatch
+//      in try/catch, so any thrown error becomes an MCP error result and
+//      cannot take the stdio connection down.
+//   2. Tests + in-process embedders (direct path) — invoke `dispatch` without
+//      the SDK transport.
+//
+// Error semantics in both paths:
+//   - Tool-level failures (unknown tool, no merger, child returned isError,
+//     fanout child threw) return `{ isError: true, content: [...] }`.
+//   - The transport path additionally swallows unexpected throws and converts
+//     them to an MCP error. The direct path lets those throws propagate —
+//     they indicate router bugs (e.g. JSON.stringify failing on circular
+//     refs in a merger output), and silently hiding them from tests would
+//     mask regressions. Direct-path callers that want transport semantics
+//     can wrap their dispatch call in the same try/catch.
+//
+// Scale / timeout model
+// ---------------------
+// Fan-out hits every child in `pool.all()` concurrently. The pool is sized at
+// startup from `vaults.yaml` (typically a handful of vaults — Phase 1 is not
+// optimized for hundreds). Per-child timeouts live inside `startChild` (T4);
+// the router does not impose an additional aggregate deadline. If a vault
+// child hangs longer than its own timeout, fanoutCall surfaces it as a
+// per-vault error row rather than failing the whole call.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { parseVaultPath } from "./path.js";
+import { buildCatalog } from "./tools/catalog.js";
+import { fanoutCall } from "./tools/fanout.js";
+import { mergeIndex, mergeLint, mergeReindex, mergeSearch, mergeStatus, mergeThemes, } from "./tools/merge.js";
+import { routeToVault } from "./tools/route.js";
+// Per-tool merger for fanout dispatches. Tools not present here cannot fan
+// out; a fanout call for a tool without a merger is a router bug and surfaces
+// as an MCP error rather than silently swallowing results.
+//
+// The `as never` casts trade strict per-merger input typing for a flat
+// registry — each merger's row shape differs (SearchHit vs IndexEntry vs ...)
+// but they share the VaultResult<T> envelope. The dispatch site only sees
+// `unknown[]` rows from fanoutCall, so a uniform Record signature is the
+// honest type here.
+const MERGERS = {
+    vault_search: mergeSearch,
+    vault_index: mergeIndex,
+    vault_status: mergeStatus,
+    vault_lint: mergeLint,
+    vault_themes: mergeThemes,
+    vault_reindex: mergeReindex,
+};
+const err = (text) => ({
+    isError: true,
+    content: [{ type: "text", text }],
+});
+// Safely encode a merger result. JSON.stringify can throw on circular refs or
+// BigInt; that indicates a router bug, not a user-input bug. We surface it as
+// an MCP error in both dispatch paths so the failure mode is consistent and
+// observable (rather than silently propagating in the direct path only).
+function encodeMerged(merged, tool) {
+    try {
+        return { content: [{ type: "text", text: JSON.stringify(merged, null, 2) }] };
+    }
+    catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        return err(`router: failed to encode '${tool}' merger result: ${reason}`);
+    }
+}
+export function createRouterServer(pool, childTools) {
+    const catalog = buildCatalog(childTools);
+    const byName = new Map(catalog.map((t) => [t.name, t]));
+    const mcp = new Server({ name: "daftari-router", version: "0.1.0" }, { capabilities: { tools: {} } });
+    async function dispatch(name, args) {
+        // Args shape guard. The MCP CallTool schema permits a missing/null
+        // arguments object; the CallToolRequestSchema handler already coalesces
+        // to `{}`, but direct callers might not. Reject anything non-object up
+        // front so downstream code can assume Record<string, unknown>.
+        if (args === null || typeof args !== "object" || Array.isArray(args)) {
+            return err(`router: '${name}' arguments must be an object`);
+        }
+        const tool = byName.get(name);
+        if (!tool)
+            return err(`unknown tool: ${name}`);
+        if (tool.routing === "require-vault") {
+            return routeToVault(pool, name, args);
+        }
+        // routing === "fanout"
+        // For parity with routeToVault, a vault can be specified via either an
+        // explicit args.vault OR a vault-prefixed args.path (e.g. "a:x.md"). Both
+        // signals route to the single-vault path; only an absent/empty vault and
+        // no prefix falls through to fanout.
+        if (hasExplicitVault(args)) {
+            return routeToVault(pool, name, args);
+        }
+        const merger = MERGERS[name];
+        if (!merger) {
+            return err(`router: no merger registered for fanout tool '${name}'`);
+        }
+        // Empty pool is an error rather than a silent empty merge result. An empty
+        // pool at this point means startPool succeeded with zero vaults — likely a
+        // config bug. Surfacing it loudly beats returning {count: 0, hits: []}
+        // and letting the caller wonder why their search found nothing.
+        if (pool.all().length === 0) {
+            return err(`router: cannot fan out '${name}': no vaults are configured`);
+        }
+        const rows = await fanoutCall(pool, name, args);
+        const merged = merger(rows);
+        return encodeMerged(merged, name);
+    }
+    function hasExplicitVault(args) {
+        if (typeof args.vault === "string" && args.vault.length > 0)
+            return true;
+        if (typeof args.path === "string") {
+            const parsed = parseVaultPath(args.path);
+            if (parsed.vault && parsed.vault.length > 0)
+                return true;
+        }
+        return false;
+    }
+    mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+        // The SDK's ListTools schema types inputSchema as a generic object; our
+        // CatalogTool.inputSchema is narrower. This map is the right boundary
+        // for the structural widening.
+        tools: catalog.map((t) => ({
+            name: t.name,
+            description: t.description ?? "",
+            inputSchema: t.inputSchema,
+        })),
+    }));
+    mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
+        try {
+            return await dispatch(req.params.name, (req.params.arguments ?? {}));
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            return err(`router error in ${req.params.name}: ${reason}`);
+        }
+    });
+    return { mcp, dispatch, catalog };
+}

package/dist/tools/catalog.d.ts

@@ -0,0 +1,16 @@
+export type Routing = "fanout" | "require-vault";
+export declare const ROUTING: Record<string, Routing>;
+export type ChildToolDescriptor = {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+};
+export type CatalogTool = ChildToolDescriptor & {
+    routing: Routing;
+};
+export declare function buildCatalog(childTools: ChildToolDescriptor[]): CatalogTool[];

package/dist/tools/catalog.js

@@ -0,0 +1,45 @@
+export const ROUTING = {
+    vault_read: "require-vault",
+    vault_index: "fanout",
+    vault_status: "fanout",
+    vault_search: "fanout",
+    vault_search_related: "require-vault",
+    vault_reindex: "fanout",
+    vault_write: "require-vault",
+    vault_append: "require-vault",
+    vault_promote: "require-vault",
+    vault_deprecate: "require-vault",
+    vault_tension_log: "require-vault",
+    vault_lint: "fanout",
+    vault_provenance: "require-vault",
+    vault_themes: "fanout",
+};
+const VAULT_DESC_FANOUT = "Optional. Limit operation to one vault by name. Omit to fan out to all vaults and merge results.";
+const VAULT_DESC_REQUIRED = "Vault name (required). Alternatively pass a vault-prefixed path like 'devops:runbooks/k8s.md'.";
+function vaultProp(routing) {
+    return {
+        type: "string",
+        description: routing === "fanout" ? VAULT_DESC_FANOUT : VAULT_DESC_REQUIRED,
+    };
+}
+export function buildCatalog(childTools) {
+    return childTools
+        .filter((t) => t.name in ROUTING)
+        .map((t) => {
+        if ("vault" in t.inputSchema.properties) {
+            throw new Error(`tool '${t.name}' already defines a 'vault' property; router cannot add its own vault parameter`);
+        }
+        const routing = ROUTING[t.name];
+        const props = { ...t.inputSchema.properties, vault: vaultProp(routing) };
+        return {
+            ...t,
+            routing,
+            inputSchema: {
+                ...t.inputSchema, // preserves additionalProperties etc.
+                type: "object",
+                properties: props,
+                required: t.inputSchema.required ?? [],
+            },
+        };
+    });
+}

package/dist/tools/fanout.d.ts

@@ -0,0 +1,3 @@
+import type { ChildPool } from "../children.js";
+import type { VaultResult } from "./merge.js";
+export declare function fanoutCall<T = unknown>(pool: ChildPool, tool: string, args: Record<string, unknown>): Promise<VaultResult<T>[]>;

package/dist/tools/fanout.js

@@ -0,0 +1,30 @@
+// fanout.ts — broadcast a single tool call to every child vault concurrently.
+//
+// Per-child failures (thrown exceptions or isError responses) are captured as
+// ok: false rows rather than propagating. The caller decides how to surface
+// them (the mergers pass errors through without failing the aggregate result).
+export async function fanoutCall(pool, tool, args) {
+    // Strip the router-level `vault` arg — children don't know about it.
+    const rest = { ...args };
+    delete rest.vault;
+    const calls = pool.all().map(async (c) => {
+        try {
+            const r = await c.callTool(tool, rest);
+            if (r.isError) {
+                const text = r.content?.[0]?.text ?? "unknown error";
+                return { vault: c.name, ok: false, error: text };
+            }
+            // Tool responses are JSON-encoded in a single text content block.
+            const text = r.content?.[0]?.text ?? "null";
+            return { vault: c.name, ok: true, value: JSON.parse(text) };
+        }
+        catch (e) {
+            return {
+                vault: c.name,
+                ok: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    });
+    return Promise.all(calls);
+}

package/dist/tools/merge.d.ts

@@ -0,0 +1,119 @@
+export type VaultResult<T> = {
+    vault: string;
+    ok: true;
+    value: T;
+} | {
+    vault: string;
+    ok: false;
+    error: string;
+};
+export type VaultError = {
+    vault: string;
+    error: string;
+};
+export declare function splitOks<T>(rows: VaultResult<T>[]): {
+    oks: {
+        vault: string;
+        value: T;
+    }[];
+    errors: VaultError[];
+};
+type SearchHit = {
+    path: string;
+    score: number;
+    collection: string;
+} & Record<string, unknown>;
+export declare function mergeSearch(rows: VaultResult<{
+    count: number;
+    hits: SearchHit[];
+}>[]): {
+    count: number;
+    hits: (SearchHit & {
+        vault: string;
+    })[];
+    errors: VaultError[];
+};
+type IndexEntry = {
+    path: string;
+} & Record<string, unknown>;
+export declare function mergeIndex(rows: VaultResult<{
+    count: number;
+    entries: IndexEntry[];
+}>[]): {
+    count: number;
+    entries: (IndexEntry & {
+        vault: string;
+    })[];
+    errors: VaultError[];
+};
+type StatusValue = {
+    fileCount: number;
+    invalidCount: number;
+    embeddingDimMismatches: number;
+    stalenessDistribution: {
+        fresh: number;
+        aging: number;
+        stale: number;
+        total: number;
+    };
+} & Record<string, unknown>;
+export declare function mergeStatus(rows: VaultResult<StatusValue>[]): {
+    fileCount: number;
+    invalidCount: number;
+    embeddingDimMismatches: number;
+    stalenessDistribution: {
+        fresh: number;
+        aging: number;
+        stale: number;
+        total: number;
+    };
+    generatedAt: string;
+    byVault: Record<string, StatusValue>;
+    errors: VaultError[];
+};
+type LintFinding = {
+    path: string;
+} & Record<string, unknown>;
+type LintValue = {
+    checks: Record<string, LintFinding[]>;
+    totalFindings: number;
+    generatedAt: string;
+    filter: string | null;
+};
+export declare function mergeLint(rows: VaultResult<LintValue>[]): {
+    totalFindings: number;
+    checks: Record<string, (LintFinding & {
+        vault: string;
+    })[]>;
+    byVault: Record<string, LintValue>;
+    errors: VaultError[];
+};
+type VaultTheme = {
+    label: string;
+    documentCount: number;
+    coherence: number | null;
+    representativeDocs: string[];
+    secondaryDocs: string[];
+    relatedTags: string[];
+} & Record<string, unknown>;
+type ThemesValue = {
+    themes: VaultTheme[];
+} & Record<string, unknown>;
+export declare function mergeThemes(rows: VaultResult<ThemesValue>[]): {
+    themes: (VaultTheme & {
+        vault: string;
+    })[];
+    errors: VaultError[];
+};
+type ReindexValue = {
+    vault: string;
+    documentCount?: number;
+    chunkCount?: number;
+} & Record<string, unknown>;
+export declare function mergeReindex(rows: VaultResult<ReindexValue>[]): {
+    documentCount: number;
+    chunkCount: number;
+    byVault: Record<string, ReindexValue>;
+    errors: VaultError[];
+};
+export {};

package/dist/tools/merge.js

@@ -0,0 +1,118 @@
+// merge.ts — fan-out result mergers for each router-dispatched tool.
+//
+// Each merger accepts an array of VaultResult<T> (one per child vault),
+// prefixes all path fields with the vault name (via formatVaultPath),
+// aggregates counters, and passes per-vault errors through without failing
+// the whole call.
+//
+// IMPORTANT: Field names are verified against the actual daftari source:
+//   - vault_themes: VaultTheme has representativeDocs/secondaryDocs (string[]),
+//     NOT sources. The plan's sketch used sources; the real type does not.
+//   - vault_reindex: ReindexResult uses documentCount/chunkCount, NOT
+//     filesProcessed/chunksProcessed. Merger uses real field names.
+import { formatVaultPath } from "../path.js";
+export function splitOks(rows) {
+    const oks = [];
+    const errors = [];
+    for (const r of rows) {
+        if (r.ok)
+            oks.push({ vault: r.vault, value: r.value });
+        else
+            errors.push({ vault: r.vault, error: r.error });
+    }
+    return { oks, errors };
+}
+export function mergeSearch(rows) {
+    const { oks, errors } = splitOks(rows);
+    const hits = oks.flatMap(({ vault, value }) => value.hits.map((h) => ({ ...h, vault, path: formatVaultPath(vault, h.path) })));
+    hits.sort((a, b) => b.score - a.score || a.vault.localeCompare(b.vault) || a.path.localeCompare(b.path));
+    return { count: hits.length, hits, errors };
+}
+export function mergeIndex(rows) {
+    const { oks, errors } = splitOks(rows);
+    const entries = oks.flatMap(({ vault, value }) => value.entries.map((e) => ({ ...e, vault, path: formatVaultPath(vault, e.path) })));
+    entries.sort((a, b) => a.path.localeCompare(b.path));
+    return { count: entries.length, entries, errors };
+}
+export function mergeStatus(rows) {
+    const { oks, errors } = splitOks(rows);
+    // byVault[name] preserves the child's raw result shape — any nested paths
+    // inside byVault entries are NOT prefixed with vault: form. Consumers should
+    // scope by the byVault key or use the flat top-level fields.
+    const byVault = {};
+    let fileCount = 0;
+    let invalidCount = 0;
+    let embeddingDimMismatches = 0;
+    const sd = { fresh: 0, aging: 0, stale: 0, total: 0 };
+    for (const { vault, value } of oks) {
+        byVault[vault] = value;
+        fileCount += value.fileCount;
+        invalidCount += value.invalidCount;
+        embeddingDimMismatches += value.embeddingDimMismatches;
+        sd.fresh += value.stalenessDistribution.fresh;
+        sd.aging += value.stalenessDistribution.aging;
+        sd.stale += value.stalenessDistribution.stale;
+        sd.total += value.stalenessDistribution.total;
+    }
+    return {
+        fileCount,
+        invalidCount,
+        embeddingDimMismatches,
+        stalenessDistribution: sd,
+        generatedAt: new Date().toISOString(),
+        byVault,
+        errors,
+    };
+}
+export function mergeLint(rows) {
+    const { oks, errors } = splitOks(rows);
+    const checks = {};
+    // byVault[name] preserves the child's raw result shape — any nested paths
+    // inside byVault entries are NOT prefixed with vault: form. Consumers should
+    // scope by the byVault key or use the flat top-level fields.
+    const byVault = {};
+    let totalFindings = 0;
+    for (const { vault, value } of oks) {
+        byVault[vault] = value;
+        totalFindings += value.totalFindings;
+        for (const [name, findings] of Object.entries(value.checks)) {
+            const prefixed = findings.map((f) => typeof f.path === "string"
+                ? { ...f, vault, path: formatVaultPath(vault, f.path) }
+                : { ...f, vault });
+            if (!checks[name])
+                checks[name] = [];
+            checks[name].push(...prefixed);
+        }
+    }
+    return { totalFindings, checks, byVault, errors };
+}
+export function mergeThemes(rows) {
+    const { oks, errors } = splitOks(rows);
+    const themes = [];
+    for (const { vault, value } of oks) {
+        for (const cluster of value.themes ?? []) {
+            themes.push({
+                ...cluster,
+                vault,
+                representativeDocs: (cluster.representativeDocs ?? []).map((p) => formatVaultPath(vault, p)),
+                secondaryDocs: (cluster.secondaryDocs ?? []).map((p) => formatVaultPath(vault, p)),
+            });
+        }
+    }
+    return { themes, errors };
+}
+export function mergeReindex(rows) {
+    const { oks, errors } = splitOks(rows);
+    // byVault[name] preserves the child's raw result shape — any nested paths
+    // inside byVault entries are NOT prefixed with vault: form. Consumers should
+    // scope by the byVault key or use the flat top-level fields.
+    const byVault = {};
+    let documentCount = 0;
+    let chunkCount = 0;
+    for (const { vault, value } of oks) {
+        byVault[vault] = value;
+        documentCount += value.documentCount ?? 0;
+        chunkCount += value.chunkCount ?? 0;
+    }
+    return { documentCount, chunkCount, byVault, errors };
+}

package/dist/tools/route.d.ts

@@ -0,0 +1,8 @@
+import type { ChildPool } from "../children.js";
+type Args = Record<string, unknown>;
+type Result = {
+    content: unknown[];
+    isError?: boolean;
+};
+export declare function routeToVault(pool: ChildPool, tool: string, args: Args): Promise<Result>;
+export {};

package/dist/tools/route.js

@@ -0,0 +1,29 @@
+import { parseVaultPath } from "../path.js";
+const err = (text) => ({ isError: true, content: [{ type: "text", text }] });
+export async function routeToVault(pool, tool, args) {
+    let vault = typeof args.vault === "string" && args.vault.length > 0 ? args.vault : null;
+    const rest = { ...args };
+    delete rest.vault;
+    // Prefix-parsing of args.path only runs when no explicit vault was provided.
+    // If both args.vault and a vault-prefixed args.path are set, the prefix is
+    // forwarded verbatim — the caller chose explicit, so we trust them.
+    if (!vault && typeof args.path === "string") {
+        const parsed = parseVaultPath(args.path);
+        if (parsed.vault && parsed.vault.length > 0) {
+            vault = parsed.vault;
+            rest.path = parsed.path;
+        }
+    }
+    if (!vault) {
+        return err(`${tool} requires a vault: pass {vault: name} or a vault-prefixed path like 'name:path/to.md'`);
+    }
+    const child = pool.get(vault);
+    if (!child) {
+        const known = pool
+            .all()
+            .map((c) => c.name)
+            .join(", ") || "(none)";
+        return err(`${tool}: unknown vault '${vault}'. Known vaults: ${known}`);
+    }
+    return child.callTool(tool, rest);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "daftari-router",
+  "version": "0.1.0",
+  "description": "Multi-vault MCP router for Daftari — fans out across N vaults.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": { "daftari-router": "./dist/cli.js" },
+  "engines": { "node": ">=20" },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsx watch src/cli.ts --config test/fixtures/vaults.yaml",
+    "lint": "biome check src test",
+    "lint:fix": "biome check --write src test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}