@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/mcp/auth.js

@@ -0,0 +1,180 @@
+/** OAuth discovery and refresh policy. Background calls never start an interactive sign-in. */
+import { getSystemErrorMap } from "node:util";
+import { checkResourceAllowed, discoverOAuthProtectedResourceMetadata, discoverAuthorizationServerMetadata, extractWWWAuthenticateParams, refreshAuthorization, OAuthError, OAuthErrorCode, SdkError, SdkErrorCode, SdkHttpError, UnauthorizedError, InsufficientScopeError, IssuerMismatchError, } from "@modelcontextprotocol/client";
+import { McpError } from "../mcp-api.js";
+import { checkMcpTarget } from "./network.js";
+import { checkedGrant } from "./grants.js";
+export async function discoverMcp(url, fetchImpl) {
+    const challenge = await fetchImpl(url, { headers: { Accept: "application/json, text/event-stream" } });
+    await challenge.body?.cancel();
+    if (!challenge.ok && ![401, 403, 404, 405].includes(challenge.status))
+        throw new McpError("connection", `MCP resource probe failed (HTTP ${challenge.status})`);
+    const { resourceMetadataUrl } = extractWWWAuthenticateParams(challenge);
+    const hints = challenge.headers.get("www-authenticate")?.match(/\bresource_metadata\s*=/gi) ?? [];
+    if (hints.length > 1 || (hints.length === 1 && !resourceMetadataUrl))
+        throw new McpError("protocol", "Unusable MCP resource_metadata challenge; refusing default discovery");
+    if (resourceMetadataUrl)
+        checkMcpTarget(url, resourceMetadataUrl.href);
+    const resource = await discoverOAuthProtectedResourceMetadata(url, { resourceMetadataUrl }, fetchImpl);
+    const issuer = resource.authorization_servers?.[0] ?? new URL("/", url).href;
+    checkMcpTarget(url, issuer);
+    const metadata = await discoverAuthorizationServerMetadata(issuer, { fetchFn: fetchImpl });
+    if (!metadata ||
+        !resource ||
+        !checkResourceAllowed({ requestedResource: new URL(url), configuredResource: resource.resource })) {
+        throw new McpError("authorization_mismatch", "MCP authorization discovery did not identify the configured resource and issuer");
+    }
+    checkMcpTarget(url, metadata.issuer);
+    checkMcpTarget(url, metadata.authorization_endpoint);
+    checkMcpTarget(url, metadata.token_endpoint);
+    if (metadata.registration_endpoint)
+        checkMcpTarget(url, metadata.registration_endpoint);
+    return { metadata, resourceMetadata: resource, resource: resource.resource, issuer: metadata.issuer };
+}
+export function checkGrantTarget(record, url, discovery) {
+    if (record.serverUrl !== url ||
+        (discovery && (record.issuer !== discovery.issuer || record.resource !== discovery.resource))) {
+        throw new McpError("authorization_mismatch", "MCP grant belongs to a different endpoint, resource or issuer; sign in explicitly for this server");
+    }
+}
+const safeReasons = new Map([
+    ...getSystemErrorMap().values(),
+    ["ENOTFOUND", "DNS name not found"],
+    ["ERR_SSL_WRONG_VERSION_NUMBER", "TLS peer did not speak the expected protocol"],
+    ["UND_ERR_CONNECT_TIMEOUT", "connection timed out"],
+    ["UND_ERR_HEADERS_TIMEOUT", "response headers timed out"],
+    ["UND_ERR_BODY_TIMEOUT", "response body timed out"],
+    ["UND_ERR_SOCKET", "socket closed or failed"],
+    ["UND_ERR_CLOSED", "HTTP client closed"],
+    ["UND_ERR_DESTROYED", "HTTP client destroyed"],
+    ["ERR_TLS_CERT_ALTNAME_INVALID", "TLS certificate hostname mismatch"],
+    ["CERT_HAS_EXPIRED", "TLS certificate expired"],
+    ["DEPTH_ZERO_SELF_SIGNED_CERT", "untrusted self-signed TLS certificate"],
+    ["SELF_SIGNED_CERT_IN_CHAIN", "untrusted TLS certificate chain"],
+    ["UNABLE_TO_VERIFY_LEAF_SIGNATURE", "TLS certificate could not be verified"],
+    ["UNABLE_TO_GET_ISSUER_CERT_LOCALLY", "TLS certificate issuer is not trusted"],
+]);
+const sdkCodes = new Set([...Object.values(SdkErrorCode), ...Object.values(OAuthErrorCode)]);
+const errorNames = new Set([
+    "Error",
+    "TypeError",
+    "SyntaxError",
+    "RangeError",
+    "ReferenceError",
+    "URIError",
+    "EvalError",
+    "AbortError",
+    "TimeoutError",
+    "AggregateError",
+    "OAuthError",
+    "SdkError",
+]);
+function safeFailureReason(error) {
+    const pending = [error];
+    const seen = new Set();
+    const reasons = new Set();
+    while (pending.length) {
+        const current = pending.pop();
+        if (!(current instanceof Error) || seen.has(current))
+            continue;
+        seen.add(current);
+        const code = "code" in current && typeof current.code === "string" ? current.code : undefined;
+        if (code !== undefined) {
+            const reason = safeReasons.get(code);
+            if (reason !== undefined)
+                reasons.add(`${code}: ${reason}`);
+            else if (sdkCodes.has(code))
+                reasons.add(code);
+        }
+        // SDK 2.4's pinned stdio probe omits structured close data; recognize only its fixed diagnostic prefix.
+        if (current.message === "Connection closed during the version negotiation probe" ||
+            (current instanceof SdkError &&
+                current.code === SdkErrorCode.EraNegotiationFailed &&
+                current.message.startsWith("Version negotiation failed: the connection closed during the server/discover probe before the server offered pinned protocol version ")))
+            reasons.add("CONNECTION_CLOSED: server closed during protocol discovery");
+        if (current instanceof SdkHttpError &&
+            Number.isInteger(current.status) &&
+            current.status >= 100 &&
+            current.status <= 599)
+            reasons.add(`HTTP ${current.status}`);
+        pending.push(current.cause);
+        if (current instanceof AggregateError && Array.isArray(current.errors))
+            pending.push(...current.errors);
+    }
+    if (reasons.size)
+        return [...reasons].join("; ");
+    return error instanceof Error ? (errorNames.has(error.name) ? error.name : "Error") : "unknown error";
+}
+export function mcpFailure(error, operation, server) {
+    if (error instanceof McpError)
+        return error.server || !server ? error : new McpError(error.code, error.message, server);
+    if (error instanceof IssuerMismatchError)
+        return new McpError("authorization_mismatch", `${operation}: OAuth issuer validation failed`, server);
+    if (error instanceof UnauthorizedError || (error instanceof SdkHttpError && error.status === 401))
+        return new McpError("authorization_required", `${operation}: MCP authorization required; sign in for this server`, server);
+    if (error instanceof InsufficientScopeError || (error instanceof SdkHttpError && error.status === 403))
+        return new McpError("insufficient_scope", `${operation}: MCP access refused (HTTP 403); review the grant permissions`, server);
+    // Error messages, paths, args, stderr and raw causes can contain credentials; only allowlisted facts escape.
+    return new McpError("connection", `${operation} failed (${safeFailureReason(error)})`, server);
+}
+export async function grantToken(input) {
+    return input.store.withGrant(input.id, async (access) => {
+        const raw = access.read();
+        if (!raw)
+            throw new McpError("authorization_required", "No MCP grant is stored; sign in before opening this agent");
+        const record = checkedGrant(raw);
+        checkGrantTarget(record, input.url, input.discovery);
+        if (record.status !== "ready")
+            throw new McpError(record.status === "refreshing" ? "refresh_uncertain" : "authorization_required", "MCP authorization must be renewed; the previous grant cannot be refreshed safely");
+        const fresh = record.expiresAt === undefined || record.expiresAt > Date.now() + 30_000;
+        if (fresh && (input.rejectedGeneration === undefined || record.generation !== input.rejectedGeneration)) {
+            return { token: record.accessToken, generation: record.generation };
+        }
+        if (!record.refreshToken) {
+            await access.write({ ...record, status: "reauthorization_required" });
+            throw new McpError("authorization_required", "MCP authorization expired and has no refresh token; sign in again");
+        }
+        const discovery = await discoverMcp(input.url, input.fetch);
+        checkGrantTarget(record, input.url, discovery);
+        // Persist before the remote server can consume the old token. A lost response cannot be replayed safely.
+        await access.write({ ...record, status: "refreshing" });
+        let tokens;
+        try {
+            tokens = await refreshAuthorization(record.issuer, {
+                metadata: discovery.metadata,
+                clientInformation: {
+                    client_id: record.client.id,
+                    ...(record.client.secret === undefined ? {} : { client_secret: record.client.secret }),
+                    token_endpoint_auth_method: record.client.tokenEndpointAuthMethod,
+                },
+                refreshToken: record.refreshToken,
+                resource: record.resource,
+                fetchFn: input.fetch,
+            });
+        }
+        catch (error) {
+            if (error instanceof OAuthError &&
+                ["invalid_grant", "invalid_client", "unauthorized_client"].includes(error.code)) {
+                await access.write({ ...record, status: "reauthorization_required" });
+                throw new McpError("authorization_required", "The MCP authorization server refused the refresh; sign in again");
+            }
+            throw mcpFailure(error, "MCP token refresh");
+        }
+        const scopes = tokens.scope === undefined ? record.scopes : tokens.scope.split(/\s+/).filter(Boolean);
+        if (scopes.some((scope) => !record.scopes.includes(scope)))
+            throw new McpError("insufficient_scope", "MCP refresh unexpectedly expanded the grant's scopes");
+        const next = {
+            ...record,
+            scopes,
+            status: "ready",
+            generation: record.generation + 1,
+            accessToken: tokens.access_token,
+            ...(tokens.refresh_token === undefined ? {} : { refreshToken: tokens.refresh_token }),
+            expiresAt: tokens.expires_in === undefined ? undefined : Date.now() + tokens.expires_in * 1000,
+        };
+        if (tokens.token_type.toLowerCase() !== "bearer")
+            throw new McpError("protocol", "Only bearer MCP grants are supported");
+        await access.write(next);
+        return { token: next.accessToken, generation: next.generation };
+    });
+}

package/dist/mcp/client.d.ts

@@ -0,0 +1,15 @@
+/** Instance-owned MCP clients. The scope also joins refreshes after a caller abandons its wait. */
+import { type Tool, type CallToolResult } from "@modelcontextprotocol/client";
+import { type McpAuthorization, type McpOptions } from "../mcp-api.ts";
+import type { McpServer } from "./config.ts";
+export interface McpTool {
+    name: string;
+    server: string;
+    definition: Tool;
+    call(args: Record<string, unknown>, signal?: AbortSignal, progress?: (text: string) => void): Promise<CallToolResult>;
+}
+export interface McpClients {
+    tools: McpTool[];
+    close(): Promise<void>;
+}
+export declare function openMcpClients(servers: readonly McpServer[], auth: McpAuthorization, options?: Pick<McpOptions, "fetch">): Promise<McpClients>;

package/dist/mcp/client.js

@@ -0,0 +1,179 @@
+/** Instance-owned MCP clients. The scope also joins refreshes after a caller abandons its wait. */
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { DEFAULT_INHERITED_ENV_VARS, StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Scope from "effect/Scope";
+import { portAbort, portJoin, portError } from "../effect-port.js";
+import { McpError } from "../mcp-api.js";
+import { checkGrantTarget, discoverMcp, grantToken, mcpFailure } from "./auth.js";
+import { mcpFetch, openMcpNetwork } from "./network.js";
+import { checkedGrant } from "./grants.js";
+import { log } from "../log.js";
+/**
+ * The SDK starts a stdio server over `{ ...getDefaultEnvironment(), ...env }`, which adds this process's own `HOME`,
+ * `PATH`, `USER` and the like under whatever is given. Naming each of them with no value, where `env` holds none,
+ * leaves the server with exactly `env`: Node drops a variable whose value is undefined.
+ */
+function ownEnvironment(env) {
+    const withheld = Object.fromEntries(DEFAULT_INHERITED_ENV_VARS.filter((name) => !(name in env)).map((name) => [name, undefined]));
+    return { ...withheld, ...env };
+}
+export async function openMcpClients(servers, auth, options = {}) {
+    const lifetime = Scope.makeUnsafe();
+    const cleanupErrors = [];
+    const tools = [];
+    const names = new Set();
+    let closing;
+    const run = async (work) => {
+        if (closing)
+            throw new McpError("connection", "MCP clients are closed");
+        const result = await Effect.runPromiseExit(Effect.forkIn(work, lifetime).pipe(Effect.flatMap(Fiber.join)));
+        if (Exit.isFailure(result))
+            throw portError(result.cause);
+        return result.value;
+    };
+    const close = () => (closing ??= (async () => {
+        await Effect.runPromise(Scope.close(lifetime, Exit.void));
+        if (cleanupErrors.length)
+            throw new AggregateError(cleanupErrors, "MCP cleanup failed");
+    })());
+    let openingServer;
+    try {
+        for (const server of servers) {
+            openingServer = server.name;
+            const client = new Client({ name: "FastAgent", version: "1" }, { versionNegotiation: { mode: { pin: "2026-07-28" }, probe: { timeoutMs: 15_000, maxRetries: 0 } } });
+            await Effect.runPromise(Scope.addFinalizer(lifetime, portJoin(() => client.close()).pipe(Effect.catchCause((cause) => Effect.sync(() => {
+                cleanupErrors.push(mcpFailure(portError(cause), "MCP cleanup", server.name));
+            })))));
+            client.onerror = (error) => log.warn(`[mcp] ${mcpFailure(error, "Protocol error", server.name).message}`);
+            let disconnected = false;
+            client.onclose = () => {
+                disconnected = true;
+            };
+            const grantId = Object.hasOwn(auth.bindings, server.name) ? auth.bindings[server.name] : undefined;
+            let transport;
+            if (server.type === "stdio") {
+                if (grantId !== undefined)
+                    throw new McpError("configuration", "A stdio MCP server cannot have an OAuth grant binding", server.name);
+                transport = new StdioClientTransport({
+                    command: server.command,
+                    args: server.args,
+                    cwd: server.cwd,
+                    env: ownEnvironment(server.env),
+                    stderr: "pipe",
+                });
+                // Draining prevents a noisy child from blocking. Raw stderr can contain its supplied secrets.
+                transport.stderr?.on("data", () => { });
+            }
+            else {
+                const network = await openMcpNetwork(server.url, options.fetch);
+                await Effect.runPromise(Scope.addFinalizer(lifetime, portJoin(() => network.close()).pipe(Effect.catchCause((cause) => Effect.sync(() => {
+                    cleanupErrors.push(mcpFailure(portError(cause), "MCP network cleanup", server.name));
+                })))));
+                const fetchImpl = mcpFetch(server.url, network.fetch);
+                const requestFetch = mcpFetch(server.url, network.fetch, 60_000);
+                if (grantId !== undefined && new Headers(server.headers).has("authorization"))
+                    throw new McpError("configuration", "Static Authorization and OAuth cannot be combined", server.name);
+                if (grantId !== undefined) {
+                    const held = await auth.store.read(grantId);
+                    if (!held)
+                        throw new McpError("authorization_required", "No grant found for this MCP binding; sign in again", server.name);
+                    checkGrantTarget(checkedGrant(held), server.url, await discoverMcp(server.url, fetchImpl));
+                }
+                const request = (input, init) => run(portJoin(async () => {
+                    if (grantId === undefined)
+                        return requestFetch(input, init);
+                    const url = input instanceof Request ? input.url : String(input);
+                    if (url !== server.url)
+                        throw new McpError("authorization_mismatch", "Refusing to send an MCP token to another URL", server.name);
+                    const token = await grantToken({ store: auth.store, id: grantId, url: server.url, fetch: fetchImpl });
+                    init?.signal?.throwIfAborted();
+                    const headers = new Headers(init?.headers);
+                    headers.set("Authorization", `Bearer ${token.token}`);
+                    const response = await requestFetch(input, { ...init, headers });
+                    if (response.status !== 401)
+                        return response;
+                    await response.body?.cancel();
+                    const refreshed = await grantToken({
+                        store: auth.store,
+                        id: grantId,
+                        url: server.url,
+                        fetch: fetchImpl,
+                        rejectedGeneration: token.generation,
+                    });
+                    init?.signal?.throwIfAborted();
+                    headers.set("Authorization", `Bearer ${refreshed.token}`);
+                    const retry = await requestFetch(input, { ...init, headers });
+                    if (retry.status === 401) {
+                        await retry.body?.cancel();
+                        await auth.store.withGrant(grantId, async (access) => {
+                            const current = access.read();
+                            if (current?.generation === refreshed.generation)
+                                await access.write({ ...current, status: "reauthorization_required" });
+                        });
+                        throw new McpError("authorization_required", "MCP server refused the refreshed grant; sign in again", server.name);
+                    }
+                    return retry;
+                }));
+                transport = new StreamableHTTPClientTransport(new URL(server.url), {
+                    fetch: request,
+                    requestInit: { headers: server.headers },
+                    onInsufficientScope: "throw",
+                });
+            }
+            // Register the transport separately: SDK discovery can fail before Client takes ownership of it.
+            await Effect.runPromise(Scope.addFinalizer(lifetime, portJoin(() => transport.close()).pipe(Effect.catchCause((cause) => Effect.sync(() => {
+                cleanupErrors.push(mcpFailure(portError(cause), "MCP transport cleanup", server.name));
+            })))));
+            await client.connect(transport, { timeout: 30_000 });
+            if (!client.getServerCapabilities()?.tools)
+                throw new McpError("protocol", "MCP server does not offer tools; other capabilities are not supported", server.name);
+            const listed = await client.listTools(undefined, { timeout: 30_000 });
+            for (const definition of listed.tools) {
+                const name = `mcp__${server.name}__${definition.name}`;
+                if (!/^[a-zA-Z0-9_-]{1,64}$/.test(name) || names.has(name))
+                    throw new McpError("configuration", `Invalid or duplicate MCP tool name ${name}`, server.name);
+                names.add(name);
+                tools.push({
+                    name,
+                    server: server.name,
+                    definition,
+                    async call(args, signal, progress) {
+                        if (disconnected)
+                            throw new McpError("connection", "MCP server disconnected; reopen the agent to reconnect", server.name);
+                        const abort = new AbortController();
+                        const forwarded = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal;
+                        try {
+                            return await run(portAbort("MCP tool", () => client.callTool({ name: definition.name, arguments: args }, {
+                                signal: forwarded,
+                                timeout: 60_000,
+                                ...(progress
+                                    ? {
+                                        onprogress: (value) => progress(`MCP ${server.name}: ${value.progress}${value.total === undefined ? "" : `/${value.total}`}`),
+                                    }
+                                    : {}),
+                            }), () => abort.abort()));
+                        }
+                        catch (error) {
+                            if (forwarded.aborted)
+                                throw forwarded.reason;
+                            throw mcpFailure(error, "MCP tool call", server.name);
+                        }
+                    },
+                });
+            }
+        }
+        return { tools, close };
+    }
+    catch (error) {
+        try {
+            await close();
+        }
+        catch (cleanup) {
+            throw new AggregateError([mcpFailure(error, "MCP open", openingServer), cleanup], "MCP open and cleanup failed");
+        }
+        throw mcpFailure(error, "MCP open", openingServer);
+    }
+}

package/dist/mcp/config.d.ts

@@ -0,0 +1,86 @@
+import * as Schema from "effect/Schema";
+import { type DeclaredSecret } from "../declared-secrets.ts";
+import { type McpConfigInput } from "../mcp-api.ts";
+declare const Declaration: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.optional<Schema.Literal<"stdio">>;
+    readonly command: Schema.NonEmptyString;
+    readonly args: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"http">;
+    readonly url: Schema.String;
+    readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+}>]>;
+/** One server as an `mcpServers` map holds it. */
+export type McpServerDeclaration = typeof Declaration.Type;
+export type McpServer = {
+    name: string;
+    type: "stdio";
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    cwd: string;
+} | {
+    name: string;
+    type: "http";
+    url: string;
+    headers: Record<string, string>;
+};
+/** A server and where it was declared: what its refusals name, and what a relative command is relative to. */
+export interface McpDeclaration {
+    name: string;
+    server: McpServerDeclaration;
+    /** The file that declared it, as a refusal names it. */
+    file: string;
+    /** The directory that file is in. None for an object, whose commands with a path must be absolute. */
+    base?: string;
+    origin: "program" | "instance";
+}
+/** The instance configuration as far as MCP reads it: its `mcpServers`, and where it is from. */
+export interface McpInstance {
+    values: unknown;
+    label: string;
+    directory?: string;
+}
+/** An instance's servers, checked: what `resolveConfig` asks of a configuration, so its refusal is the file's. */
+export declare function checkInstanceServers(instance: McpInstance): void;
+/**
+ * The servers of the program in `dir` and of `instance`. An instance only adds: a name both declare is refused, naming
+ * both, so nothing is shadowed.
+ */
+export declare function declareMcp(dir: string, instance?: McpInstance): McpDeclaration[];
+/** An instance configuration given to `inspectMcp` or `signInMcp`: an object, or the absolute path of a `fastagent.json`. */
+export declare function mcpInstance(config: McpConfigInput | undefined): McpInstance | undefined;
+/** The secrets the servers' `${NAME}` references need: each required, declared where the server is. */
+export declare function mcpSecrets(declarations: readonly McpDeclaration[]): DeclaredSecret[];
+/**
+ * The header and environment values with no `${VAR}` in them: the format allows a literal credential, and where the
+ * file travels (a build publishes it, a deploy bakes or delivers it) each is said. FastAgent cannot tell a secret from a
+ * setting, so a caller warns and never refuses.
+ */
+export declare function literalCredentials(declarations: readonly McpDeclaration[]): {
+    file: string;
+    server: string;
+    field: "headers" | "env";
+    key: string;
+}[];
+/**
+ * The stdio servers whose command is a path relative to the file that declares it, as it is written: what a build or a
+ * deploy has to be able to deliver, since a script is not found on a `PATH`. A command that starts with a `${VAR}` is
+ * left to the variable, and `args` are never read as paths, since FastAgent cannot know which strings are.
+ */
+export declare function relativeCommands(declarations: readonly McpDeclaration[]): (McpDeclaration & {
+    command: string;
+})[];
+/** What to write instead of a literal credential, which a header's value usually carries a scheme in front of. */
+export declare function literalCredentialAdvice({ field, key }: {
+    field: "headers" | "env";
+    key: string;
+}): string;
+export declare function checkMcpUrl(value: string, server?: string, file?: string): URL;
+export declare function resolveMcpServers(declarations: readonly McpDeclaration[], env: Readonly<Record<string, string | undefined>>, only: string | undefined, 
+/** Where a stdio server runs: the instance's workspace, whoever declared it. */
+cwd: string, 
+/** What every process the instance starts gets (child-env.ts), under a stdio server's own `env`. */
+processEnv: Readonly<Record<string, string>>): McpServer[];
+export {};