@cat-factory/server 0.217.0 → 0.219.0

package/dist/modules/toolServers/declaredToolServers.js

@@ -0,0 +1,108 @@
+import { isAllowedMcpHttpUrl, isLoopbackMcpHttpUrl, mcpServableHarnesses, redactSecrets, } from '@cat-factory/kernel';
+import { stripUrlCredentials } from '../../agents/agentContextRecord.js';
+/**
+ * Every declared tool server by id — the ONE resolution both halves of this surface use.
+ *
+ * Shared rather than re-derived per caller, because the two halves disagreeing about which
+ * definition an id names is invisible and mean: the row would describe one endpoint while the Test
+ * button probed another, both labelled with the same id. So the LIST and the PROBE ask this.
+ *
+ * Two sources, unioned, because neither is complete on its own:
+ *
+ *   - walking `kindsWithCapabilities()` finds servers a kind actually gets, inline definitions
+ *     included, and is the only way to learn WHICH kinds get them (`assignToolServers('coder', …)`
+ *     is the recommended attachment path and no built-in is a registry entry, which is the hole
+ *     `kindsWithCapabilities` exists to close);
+ *   - `allToolServers()` finds registrations attached to NOTHING, which the walk structurally
+ *     cannot see and which nothing else in the platform reports. Such a server never reaches a
+ *     dispatch, so its credentials are keys an operator fills in for no run — reported with an
+ *     empty `declaredBy` rather than filtered out, because only the operator can tell a
+ *     work-in-progress registration from a kind that lost its assignment in a refactor.
+ *
+ * First definition wins, matching `normalizeToolRefs`: a kind may declare an id inline while another
+ * references the registration, and the dispatch resolves per kind. What one surface can honestly
+ * show is one row per id, so it shows the first and names every kind.
+ */
+export function resolveDeclaredToolServers(registry) {
+    const declared = new Map();
+    for (const kind of registry.kindsWithCapabilities()) {
+        for (const server of registry.toolServersFor(kind).servers) {
+            const existing = declared.get(server.id);
+            if (existing)
+                existing.declaredBy.push(kind);
+            else
+                declared.set(server.id, { definition: server, declaredBy: [kind] });
+        }
+    }
+    for (const server of registry.allToolServers()) {
+        if (!declared.has(server.id))
+            declared.set(server.id, { definition: server, declaredBy: [] });
+    }
+    return declared;
+}
+/** Every declared tool server, projected non-secretly and sorted by id. */
+export function collectDeclaredToolServers(input) {
+    return [...resolveDeclaredToolServers(input.agentKindRegistry).values()]
+        .map((declared) => toView(declared.definition, declared.declaredBy))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Project one definition into its non-secret operator-facing view. */
+function toView(definition, declaredBy) {
+    const notProbeable = notProbeableReason(definition);
+    return {
+        id: definition.id,
+        label: definition.label ?? definition.id,
+        transport: definition.transport.kind,
+        target: describeTarget(definition),
+        ...(definition.guidance ? { guidance: definition.guidance } : {}),
+        declaredBy: [...declaredBy].sort(),
+        servableHarnesses: mcpServableHarnesses(definition),
+        ...(definition.allowedTools?.length ? { allowedTools: definition.allowedTools } : {}),
+        credentials: (definition.secretKeys ?? []).map((secret) => ({
+            key: secret.key,
+            // `required` defaults to TRUE at the declaration site: a credential a server bothered to
+            // declare is one it needs. Resolved here so no reader repeats the default.
+            required: secret.required !== false,
+            ...(secret.usage ? { usage: secret.usage } : {}),
+        })),
+        probeable: notProbeable === undefined,
+        ...(notProbeable ? { notProbeableReason: notProbeable } : {}),
+    };
+}
+/**
+ * What the declaration points at, for recognition on the surface.
+ *
+ * BOTH shapes are scrubbed before they reach a browser, because both are places a credential can
+ * legitimately sit. A url carries userinfo: `https://user:token@mcp.example` is a declaration this
+ * platform accepts (`isAllowedMcpHttpUrl` only rules on the scheme and host), so it goes through
+ * `stripUrlCredentials`. A `stdio` command line carries `--token=…` just as easily, and it is the
+ * more tempting spot of the two for a deployment that has not found `secretKeys` yet — so the joined
+ * argv goes through `redactSecrets`. Values in the credential store are write-only, which makes this
+ * the one place on the surface where a pasted secret could otherwise be READ back.
+ */
+function describeTarget(definition) {
+    if (definition.transport.kind === 'http')
+        return stripUrlCredentials(definition.transport.url);
+    const args = definition.transport.args ?? [];
+    return redactSecrets([definition.transport.command, ...args].join(' ')) ?? '';
+}
+/**
+ * Why this deployment cannot probe the definition, or undefined when it can.
+ *
+ * The order matters: the transport question comes first because a `stdio` server has no url to
+ * judge at all, and answering `url_not_allowed` for one would name a fault it does not have.
+ */
+export function notProbeableReason(definition) {
+    if (definition.transport.kind === 'stdio')
+        return 'stdio_transport';
+    const url = definition.transport.url;
+    if (!isAllowedMcpHttpUrl(url))
+        return 'url_not_allowed';
+    // A loopback endpoint means "beside the agent, inside its own container". The backend's loopback
+    // is a different machine, so probing it would answer about the wrong process whether it succeeded
+    // or failed — and a success would be the more misleading of the two.
+    if (isLoopbackMcpHttpUrl(url))
+        return 'container_local_url';
+    return undefined;
+}
+//# sourceMappingURL=declaredToolServers.js.map

package/dist/modules/toolServers/declaredToolServers.js.map

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

package/dist/modules/toolServers/mcpProbe.d.ts

@@ -0,0 +1,50 @@
+export interface McpProbeTarget {
+    url: string;
+    /** The non-secret headers the DECLARATION itself carries (`transport.headers`). */
+    headers: Record<string, string>;
+    /**
+     * The resolved credential headers. Never logged, never returned.
+     *
+     * Kept APART from `headers` rather than merged by the caller, because the two are treated
+     * differently at a redirect: a hop that leaves the declared origin is refused while these are
+     * present, and a declaration's own `x-tenant` is not a reason to refuse anything.
+     */
+    credentialHeaders: Record<string, string>;
+}
+export interface McpProbeDeps {
+    /** Injected for tests; defaults to the global fetch. */
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    maxPages?: number;
+}
+export interface McpProbeSuccess {
+    status: 'ok';
+    serverName: string;
+    serverVersion: string;
+    /** The version the SERVER negotiated, which is what the agent's CLI will speak to it. */
+    protocolVersion: string;
+    /** Every tool name read, uncapped — the caller caps what reaches the wire. */
+    tools: string[];
+    /** False when a `nextCursor` was still outstanding at {@link MCP_PROBE_MAX_PAGES}. */
+    toolsComplete: boolean;
+}
+export type McpProbeFailure = {
+    status: 'unreachable';
+    error: string;
+} | {
+    status: 'http_error';
+    httpStatus: number;
+    error: string;
+} | {
+    status: 'protocol_error';
+    error: string;
+};
+export type McpProbeOutcome = McpProbeSuccess | McpProbeFailure;
+/**
+ * Speak MCP to `target` and report what happened.
+ *
+ * The caller owns the DECISION to probe at all (a stdio server has no url; a loopback one is not
+ * ours to reach) and the credential resolution that fills `headers`. This owns only the protocol.
+ */
+export declare function probeMcpHttpServer(target: McpProbeTarget, deps?: McpProbeDeps): Promise<McpProbeOutcome>;
+//# sourceMappingURL=mcpProbe.d.ts.map

package/dist/modules/toolServers/mcpProbe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpProbe.d.ts","sourceRoot":"","sources":["../../../src/modules/toolServers/mcpProbe.ts"],"names":[],"mappings":"AAiEA,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B;;;;;;OAMG;IACH,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC1C;AAED,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,IAAI,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,yFAAyF;IACzF,eAAe,EAAE,MAAM,CAAA;IACvB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,sFAAsF;IACtF,aAAa,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAE/C,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,eAAe,CAAA;AAO/D;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,eAAe,CAAC,CAoB1B"}