@vibesdotdev/mcp 0.0.0-stage → 1.0.0-rc.0

package/dist/adapters/mcp/tool-audit.js

@@ -0,0 +1,168 @@
+/**
+ * Tool-exposure audit — the czar cycle's reusable core.
+ *
+ * ONE implementation of "is every declared tool reachable and wire-honest",
+ * consumed by both the `vibes dev audit tools` CLI command and (future) a
+ * `tools/tool` runtime capability. It does NOT re-implement the exposure funnel:
+ * it drives the real `explainMcpToolSelection` (the same mirror the serve path
+ * logs) across every MCP client preset, over the real runtime descriptor
+ * catalog.
+ *
+ * SCOPE — this is the POLICY view (world-independent): it audits what each preset
+ * *intends* to expose from the declared catalog, plus wire-shape properties of the
+ * descriptors. It deliberately does NOT assert loader-resolvability, because that
+ * depends on which plugins the *running* world composed — the ambient CLI world
+ * is not the MCP serve world, so a bare `available()` here under-reports and would
+ * cry "zombie" for tools the serve path loads fine. Serve-world reachability +
+ * served-vs-authored schema drift is the job of the live "Wire Selfie" handshake
+ * (the earned next in docs/proposals/universal-tools-czar/), which spawns a real
+ * serve per preset and diffs tools/list. Keeping v1 honest beats a plausible-wrong
+ * verdict. Distinct from the static `scripts/check-tool-coverage.ts` gate (source
+ * text scan for descriptor↔loader drift): this drives the LIVE registry policy.
+ */
+import { listMcpClientPresetIds, runtimePurposePresets } from '@vibesdotdev/tools/schemas/presets/registry';
+import { explainMcpToolSelection } from "./tool-selection.js";
+// The audit's limit MUST be the schema's limit. This was a local `const … = 160`
+// under a comment asserting it tracked the schema — it did not, and silently
+// drifted the moment the budget moved (2026-07-24, 160 → 1024). Import it.
+import { MCP_DESCRIPTION_LIMIT } from '@vibesdotdev/tools/schemas/schema';
+function isAuditedTool(descriptor) {
+    return descriptor.kind === 'tools/tool';
+}
+/**
+ * Run the exposure POLICY audit against the live runtime catalog. Pure of
+ * process/stdout so the CLI, a scheduled guard, a test, and a future tools/tool
+ * can all consume it.
+ */
+export function runToolExposureAudit(runtime, configured) {
+    const customPresets = runtimePurposePresets(runtime, configured);
+    const all = runtime.assets('tools/tool').descriptors().filter(isAuditedTool);
+    const findings = [];
+    // Base `mcp` preset (clientId undefined) plus every MCP client preset.
+    const targets = [
+        { presetId: 'mcp', clientId: undefined },
+        ...listMcpClientPresetIds(customPresets).map((presetId) => ({
+            presetId,
+            clientId: presetId.startsWith('mcp:') ? presetId.slice('mcp:'.length) : presetId
+        }))
+    ];
+    const presets = [];
+    // A tool HAS A HOME if any audited preset exposes it — catch-all presets
+    // included. This used to count only curated (non-`*`) presets, on the theory
+    // that a wildcard (then only mcp:cloud) absorbs everything and would hide an
+    // accidental orphan. Under the full-catalog doctrine (2026-08-28) every
+    // harness preset inherits `mcp`'s `*` by design, so that rule reported
+    // 63/129 tools "reachable by zero MCP clients" while every one of them was on
+    // claude's wire (2026-09-01). A tool served to claude is not orphaned.
+    // Loader-reality on cloud hardware is the Wire Selfie's job, not this view's.
+    const exposedByAnyPreset = new Set();
+    // Per tool: the set of exclusion reasons observed across presets. Used to tell
+    // an ACCIDENTAL orphan (falls through enabledPatterns everywhere) apart from an
+    // INTENTIONAL disable (run-command is denylisted on purpose for safety).
+    const exclusionReasons = new Map();
+    for (const target of targets) {
+        // No availableIds: POLICY view over the declared catalog (see header).
+        const explanation = explainMcpToolSelection(all, { mcpClientId: target.clientId, customPresets });
+        for (const id of explanation.included)
+            exposedByAnyPreset.add(id);
+        for (const excluded of explanation.excluded) {
+            const reasonKind = excluded.reason.split(':')[0] ?? excluded.reason;
+            const set = exclusionReasons.get(excluded.id) ?? new Set();
+            set.add(reasonKind);
+            exclusionReasons.set(excluded.id, set);
+        }
+        // Aggregate context cost of this preset's tools/list. Uses the same
+        // resolution order the wire does: mcpDescription when present, else the
+        // long description (see resolveMcpDescription).
+        const byId = new Map(all.map((d) => [d.id, d]));
+        const descriptionBudgetChars = explanation.included.reduce((sum, id) => {
+            const d = byId.get(id);
+            return sum + (d?.mcpDescription ?? d?.description ?? '').length;
+        }, 0);
+        const exposure = {
+            presetId: target.presetId,
+            clientId: target.clientId,
+            exposedCount: explanation.included.length,
+            exposed: explanation.included,
+            descriptionBudgetChars
+        };
+        if (explanation.limitedFrom !== undefined)
+            exposure.limitedFrom = explanation.limitedFrom;
+        presets.push(exposure);
+        // NO description-budget finding here by ruling (2026-07-25,
+        // claude-context-steward-3a3e4795 → claude-tools-czar-b96b3723). There was a
+        // `preset-description-budget-exceeded` finding at 24,000 chars. It measured
+        // ~4% of the catalog and passed at 1,621/24,000 while `mcp:claude` actually
+        // served 224,730 bytes (~62K tokens) — a second, friendlier number sitting
+        // beside the real one, which is how a green signal starts lying. ONE catalog
+        // budget, taken where the catalog is serialized: WIRE_CATALOG_BUDGET_BYTES in
+        // ./tool-audit-live.ts. `descriptionBudgetChars` survives above as a labelled
+        // sub-metric; do not restore a pass/fail on it.
+    }
+    for (const descriptor of all) {
+        const purpose = descriptor.purpose ?? [];
+        if (!purpose.includes('mcp'))
+            continue;
+        const reasons = exclusionReasons.get(descriptor.id) ?? new Set();
+        // ACCIDENTAL orphan: declares purpose:mcp, exposed by no preset, and was
+        // never explicitly disabled — it simply falls through every preset's
+        // enabledPatterns. This is the diagnostics.run / search / dashboard-stats
+        // case: declared-but-never-projected (czar §R4). An intentionally
+        // denylisted tool (run-command) is NOT flagged.
+        if (isAccidentalOrphan(exposedByAnyPreset.has(descriptor.id), reasons)) {
+            findings.push({
+                severity: 'medium',
+                code: 'orphan-purpose',
+                toolId: descriptor.id,
+                detail: 'declares purpose:mcp but is enabled by no preset (falls through every ' +
+                    'enabledPatterns) — reachable by zero MCP clients. Add a preset home or drop the mcp purpose.'
+            });
+        }
+    }
+    // Wire-safety: mcpDescription over the client-safe limit (world-independent).
+    for (const descriptor of all) {
+        const mcpDescription = descriptor.mcpDescription;
+        if (mcpDescription !== undefined && mcpDescription.length > MCP_DESCRIPTION_LIMIT) {
+            findings.push({
+                severity: 'low',
+                code: 'mcp-description-too-long',
+                toolId: descriptor.id,
+                detail: `mcpDescription is ${mcpDescription.length} chars (limit ${MCP_DESCRIPTION_LIMIT})`
+            });
+        }
+    }
+    findings.sort((a, b) => severityRank(a.severity) - severityRank(b.severity) ||
+        a.code.localeCompare(b.code) ||
+        a.toolId.localeCompare(b.toolId));
+    return {
+        view: 'policy',
+        // The strict verdict — see ToolAuditReport.ok. The policy view never emits
+        // 'high', so "no high findings" was a constant `true` that contradicted the
+        // --strict exit code. A verdict must be a function of the findings it sits
+        // beside.
+        ok: findings.length === 0,
+        generatedForPresets: targets.map((t) => t.presetId),
+        totalDescriptors: all.length,
+        presets,
+        findings
+    };
+}
+/**
+ * The orphan rule, extracted so it stays falsifiable: the registry offers no
+ * injection point for a synthetic preset set, and under a `*` base catalog no
+ * real descriptor can currently trip it end-to-end.
+ *
+ * A tool is an ACCIDENTAL orphan when no audited preset exposes it AND no
+ * preset excluded it on purpose (`disabled-pattern` / `preset-explicit-disable`).
+ * Exposure through a catch-all preset counts — a tool served to claude is not
+ * orphaned.
+ */
+export function isAccidentalOrphan(exposedByAnyPreset, exclusionReasons) {
+    if (exposedByAnyPreset)
+        return false;
+    return !(exclusionReasons.has('disabled-pattern') || exclusionReasons.has('preset-explicit-disable'));
+}
+function severityRank(severity) {
+    return severity === 'high' ? 0 : severity === 'medium' ? 1 : 2;
+}
+//# sourceMappingURL=tool-audit.js.map

package/dist/adapters/mcp/tool-audit.js.map

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

package/dist/adapters/mcp/tool-catalog.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The MCP tool catalog: what this runtime serves, computed once per registry
+ * revision instead of once per connection.
+ *
+ * WHY THIS IS A SEPARATE MODULE. `buildServer` used to do two unrelated things
+ * in one pass: (1) ask the runtime registry what tools exist, filter them to
+ * enabled, select by preset, and compose the `instructions` banner; and (2)
+ * construct an `McpServer` and register that selection on it. Only (2) is
+ * per-connection — an `McpServer` owns transport state and cannot be shared.
+ * (1) is a pure fold over the registry and is byte-identical for identical
+ * inputs, yet the HTTP session handler called it on every `initialize`. On this
+ * machine that ran 7,291 times in 53 hours of uptime, logging a full discovery
+ * block each time. `host-registry.ts` already documents the intended contract —
+ * "a host resolves its tool catalog ONCE at boot … and bakes it into a single
+ * McpServer" — and this module is what makes the HTTP path keep it.
+ *
+ * WHY A REVISION KEY AND NOT A TTL. A memoized catalog that serves a stale
+ * toolset is worse than no memo: an agent quietly holding the wrong tools is
+ * exactly the injury class this file's warnings exist to prevent, and a TTL
+ * guarantees a window where that is true. `runtime.descriptorRevision` is a
+ * monotonic counter the runtime bumps on every registration, retraction, kind
+ * change, plugin install and plugin retraction — so with hot reload landed
+ * (`retractPlugin`/`swapPlugin`), registry mutation is *observable* and the
+ * cache can be exact. If the revision has not moved, no descriptor, kind,
+ * plugin or enablement flag has moved either, and the fold cannot differ.
+ *
+ * The project-local tool ids (the tools discovery registered from
+ * `.vibes/tools`, or the caller's explicit set) are part of the key too —
+ * supplied by the caller, because reading them is a node-scoped import and
+ * this fold stays isomorphic.
+ */
+import type { VibesRuntime } from '@vibesdotdev/kernel/api/runtime';
+import type { LoggerImplementation } from '@vibesdotdev/logging/kinds/logger';
+import type { ToolAssetDescriptor } from '@vibesdotdev/tools/schemas/runtime/descriptors';
+import type { McpAdapterOptions } from '@vibesdotdev/mcp';
+import type { PurposePreset } from '@vibesdotdev/tools/schemas/presets/schema';
+import type { SelectMcpToolsResult } from './schemas/index.ts';
+export type McpServerCapabilities = {
+    tools: {
+        listChanged: true;
+    };
+    resources?: {
+        listChanged: true;
+    };
+    prompts?: {
+        listChanged: true;
+    };
+};
+/**
+ * How a fold treats descriptors whose loader is not resolvable at fold time.
+ *
+ * `runtime.assets('tools/tool').available()` is time- and scope-sensitive:
+ * session-* loaders can arrive through the session bridge after the first
+ * build, and scope qualifiers can move. So excluding unavailable descriptors
+ * is a decision only the CALLER can make honestly — the fold cannot tell a
+ * zombie from a tool whose loader is still settling.
+ *
+ * - `'advisory'` (the default): keep every enabled descriptor and warn about
+ *   `zombieCandidates`. Every caller that cannot bound registration keeps
+ *   this, including the serve-startup exposure selection that also decides
+ *   whether the session bridge warms at all.
+ * - `'settled'`: the caller asserts that registration is bound for the scope
+ *   this fold is served under — every loader that can still arrive for these
+ *   descriptors arrives through the runtime (`registerLoader`,
+ *   `registerVariantLoader`, `registerDynamicAsset`, `registerPlugin`), which
+ *   bumps `descriptorRevision`. Because every connection is built from a
+ *   revision-keyed cache (`createMcpToolCatalogCache`), an excluded descriptor
+ *   is re-evaluated on the next fold: a loader that registers later is
+ *   ADMITTED, never silently dropped for the session's lifetime. 2026-06-11:
+ *   a filter with no such bound silently excluded the whole session family.
+ *
+ * The settlement decision is a constructor argument of a cache, never a key
+ * input: one cache serves one policy for its whole life, and mixing policies
+ * through one cache would make the fold unreproducible from its key.
+ */
+export type McpLoaderSettlement = 'advisory' | 'settled';
+/**
+ * Everything `buildServer` needs that does not depend on the `McpServer`
+ * instance. Frozen at the revision it was computed for.
+ */
+export type McpToolCatalog = {
+    /** `runtime.descriptorRevision` this catalog was folded from. */
+    readonly revision: number;
+    readonly purposePresets: Record<string, PurposePreset>;
+    /** Cache key: revision plus every input the revision does not cover. */
+    readonly key: string;
+    /** The caller's registration bound this fold was computed under. */
+    readonly loaderSettlement: McpLoaderSettlement;
+    /**
+     * True when `tools/tool` is not registered at all. The server is still
+     * built — an empty tools/list must not look healthy — but nothing is
+     * selected and `instructions` carries the degradation banner.
+     */
+    readonly degradedKind: boolean;
+    readonly capabilities: McpServerCapabilities;
+    readonly instructions: string;
+    /** Selected descriptors, in registration order. */
+    readonly descriptors: readonly ToolAssetDescriptor[];
+    /** Enabled (pre-selection) descriptors — the client auto-detect upgrade re-selects from these. */
+    readonly enabledDescriptors: readonly ToolAssetDescriptor[];
+    readonly selected: SelectMcpToolsResult | null;
+    readonly localToolIds: readonly string[];
+    readonly totalDescriptors: number;
+    /** Selected descriptors that carry no input schema and cannot be advertised. */
+    readonly preScanFailedTools: readonly string[];
+    /** Selected ids that would throw "No implementation registered" if called right now (advisory). */
+    readonly zombieCandidates: readonly string[];
+    /**
+     * Whether the per-connection registration summary has already been logged at
+     * INFO for this fold. Mutable on purpose: the FIRST connection served by a
+     * catalog announces what got registered, every later connection repeats the
+     * identical work and logs it at DEBUG. Without this the registration block
+     * still floods the log once per connection even though the catalog behind it
+     * never moved — which is the symptom the memo exists to remove.
+     */
+    announced: boolean;
+};
+export declare function hasMcpResources(descriptor: ToolAssetDescriptor): boolean;
+export declare function hasMcpPrompts(descriptor: ToolAssetDescriptor, options: {
+    canResolvePromptIds: boolean;
+}): boolean;
+export declare function formatRegistrationFailureInstructions(failedTools: readonly string[]): string;
+/**
+ * Every input to the fold that `descriptorRevision` does not already cover.
+ *
+ * Keep this honest: anything read by `computeMcpToolCatalog` that can change
+ * without a registry mutation MUST appear here, or the cache serves stale.
+ */
+export declare function catalogCacheKey(runtime: VibesRuntime, localToolIds: readonly string[], configured?: Record<string, PurposePreset>): string;
+/**
+ * Fold the runtime registry into the catalog this surface serves.
+ *
+ * Pure with respect to the registry: no `McpServer`, no transport, no
+ * per-connection state. Logs the discovery block, so callers that memoize get
+ * one block per revision rather than one per connection.
+ */
+export declare function computeMcpToolCatalog(runtime: VibesRuntime, options: McpAdapterOptions, logger: LoggerImplementation, 
+/** Project-local catalog ids (CLI list source=local parity), already resolved. */
+localToolIds: readonly string[], 
+/**
+ * The caller's registration bound for this fold. Defaults to `'advisory'`:
+ * unavailable descriptors stay selected and are warned about. Only a caller
+ * that can name the bound (see {@link McpLoaderSettlement}) passes
+ * `'settled'` to exclude them.
+ */
+loaderSettlement?: McpLoaderSettlement): McpToolCatalog;
+export type McpToolCatalogCache = {
+    /** The catalog for the registry as it stands right now, folding only if it moved. */
+    get(): McpToolCatalog;
+    /** Folds performed, and connections served from an existing fold. */
+    stats(): {
+        folds: number;
+        hits: number;
+        key: string | null;
+    };
+    /** Drop the memo. Correctness never depends on this — the key does. */
+    invalidate(): void;
+};
+/**
+ * Memoize `computeMcpToolCatalog` against the runtime's registry revision.
+ *
+ * One cache per serving surface (the HTTP session handler builds one and every
+ * session draws from it). The `McpServer` stays per-connection; only the fold
+ * is shared.
+ *
+ * `loaderSettlement` is fixed for the cache's whole life — it is the caller's
+ * registration bound, not a per-call option. It deliberately does not enter
+ * the cache key: the key must describe the registry state this fold was
+ * computed from, and a cache that could flip policies would report one key for
+ * two different folds.
+ */
+export declare function createMcpToolCatalogCache(runtime: VibesRuntime, options: McpAdapterOptions, logger: LoggerImplementation, 
+/**
+ * Resolves the project-local tool ids at call time. Injected rather than
+ * imported: reading them is node-scoped, and this module is in the
+ * isomorphic root closure.
+ */
+resolveLocalToolIds: () => readonly string[], loaderSettlement?: McpLoaderSettlement): McpToolCatalogCache;
+//# sourceMappingURL=tool-catalog.d.ts.map

package/dist/adapters/mcp/tool-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-catalog.d.ts","sourceRoot":"","sources":["../../../src/adapters/mcp/tool-catalog.ts"],"names":[],"mappings":"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"}