@fastagent-sh/fastagent 0.27.0 → 0.29.0

package/dist/mcp/client.js

@@ -0,0 +1,170 @@
+/** Instance-owned MCP clients. The scope also joins refreshes after a caller abandons its wait. */
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { 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";
+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: 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,34 @@
+import * as Schema from "effect/Schema";
+import { type DeclaredSecret } from "../declared-secrets.ts";
+export declare const MCP_FILE = ".mcp.json";
+declare const Configuration: Schema.Struct<{
+    readonly mcpServers: Schema.$Record<Schema.String, 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>>;
+    }>]>>;
+}>;
+export type McpConfiguration = typeof Configuration.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>;
+};
+export declare function readMcpConfiguration(dir: string): McpConfiguration;
+export declare function mcpSecrets(dir: string): DeclaredSecret[];
+export declare function checkMcpUrl(value: string, server?: string): URL;
+export declare function resolveMcpServers(dir: string, env: Readonly<Record<string, string | undefined>>, only?: string): McpServer[];
+export {};

package/dist/mcp/config.js

@@ -0,0 +1,142 @@
+/** The sole MCP declaration: .mcp.json in the agent directory, resolved against this instance's environment. */
+import { readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import { isEnvName } from "../declared-secrets.js";
+import { McpError } from "../mcp-api.js";
+export const MCP_FILE = ".mcp.json";
+const Strings = Schema.Record(Schema.String, Schema.String);
+const Stdio = Schema.Struct({
+    type: Schema.optional(Schema.Literal("stdio")),
+    command: Schema.NonEmptyString,
+    args: Schema.optional(Schema.Array(Schema.String)),
+    env: Schema.optional(Strings),
+});
+const Http = Schema.Struct({
+    type: Schema.Literal("http"),
+    url: Schema.String,
+    headers: Schema.optional(Strings),
+});
+const Configuration = Schema.Struct({ mcpServers: Schema.Record(Schema.String, Schema.Union([Stdio, Http])) });
+export function readMcpConfiguration(dir) {
+    const file = join(dir, MCP_FILE);
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { mcpServers: {} };
+        throw error;
+    }
+    let config;
+    try {
+        config = Schema.decodeUnknownSync(Schema.fromJsonString(Configuration))(text, { onExcessProperty: "error" });
+    }
+    catch (error) {
+        const paths = error instanceof Error && SchemaIssue.isIssue(error.cause)
+            ? SchemaIssue.makeFormatterStandardSchemaV1()(error.cause).issues.map((issue) => issue.path)
+            : [];
+        throw new McpError("configuration", `${file}: invalid MCP configuration at ${JSON.stringify(paths)}; expected stdio command/args/env or http url/headers; unknown fields are refused`);
+    }
+    for (const [name, server] of Object.entries(config.mcpServers)) {
+        if (!/^[a-zA-Z0-9_-]+$/.test(name) || name.includes("__") || name.length > 40) {
+            throw new McpError("configuration", `${file}: server names must be 1–40 letters, digits, hyphens or underscores, without __`);
+        }
+        if (server.type === "http")
+            checkMcpUrl(server.url, name);
+        else
+            for (const key of Object.keys(server.env ?? {})) {
+                if (!isEnvName(key))
+                    throw new McpError("configuration", `${file}: invalid environment variable name for ${name}`, name);
+            }
+        for (const value of configStrings(server))
+            variables(value, name);
+    }
+    return config;
+}
+function configStrings(server) {
+    return server.type === "http"
+        ? Object.values(server.headers ?? {})
+        : [server.command, ...(server.args ?? []), ...Object.values(server.env ?? {})];
+}
+function variables(value, server) {
+    const names = [];
+    const rest = value.replace(/\$\{([^}]*)\}/g, (_match, name) => {
+        if (!isEnvName(name))
+            throw new McpError("configuration", `${MCP_FILE}: ${server} supports only \${NAME} substitutions`, server);
+        names.push(name);
+        return "";
+    });
+    if (rest.includes("${") || rest.includes("$("))
+        throw new McpError("configuration", `${MCP_FILE}: unsupported substitution in ${server}`, server);
+    return names;
+}
+export function mcpSecrets(dir) {
+    return Object.entries(readMcpConfiguration(dir).mcpServers).flatMap(([server, config]) => configStrings(config).flatMap((value) => variables(value, server).map((name) => ({ name, source: `${MCP_FILE} mcpServers.${server}` }))));
+}
+export function checkMcpUrl(value, server) {
+    const url = URL.parse(value);
+    if (!url ||
+        value.includes("${") ||
+        value.includes("$(") ||
+        url.username ||
+        url.password ||
+        url.hash ||
+        (url.protocol !== "https:" &&
+            !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))) {
+        throw new McpError("configuration", `${MCP_FILE}: MCP endpoints require HTTPS (HTTP is allowed only on loopback), without userinfo or fragments`, server);
+    }
+    return url;
+}
+// These are execution necessities, not the other models' or servers' credentials.
+const INHERITED = [
+    "PATH",
+    "HOME",
+    "USERPROFILE",
+    "SystemRoot",
+    "SYSTEMROOT",
+    "TEMP",
+    "TMP",
+    "TMPDIR",
+    "LANG",
+    "LC_ALL",
+];
+export function resolveMcpServers(dir, env, only) {
+    const config = readMcpConfiguration(dir);
+    return Object.entries(config.mcpServers)
+        .filter(([name]) => only === undefined || name === only)
+        .map(([name, server]) => {
+        const expand = (value) => value.replace(/\$\{([^}]*)\}/g, (_match, key) => {
+            const result = env[key];
+            if (!result)
+                throw new McpError("configuration", `${MCP_FILE}: ${name} requires ${key}`, name);
+            return result;
+        });
+        if (server.type === "http") {
+            const headers = Object.fromEntries(Object.entries(server.headers ?? {}).map(([key, value]) => [key, expand(value)]));
+            try {
+                new Headers(headers);
+            }
+            catch {
+                throw new McpError("configuration", `${MCP_FILE}: invalid HTTP headers for ${name}`, name);
+            }
+            return { name, type: "http", url: checkMcpUrl(server.url, name).href, headers };
+        }
+        let command = expand(server.command);
+        if (!isAbsolute(command) && /[/\\]/.test(command))
+            command = resolve(dir, command);
+        return {
+            name,
+            type: "stdio",
+            command,
+            args: (server.args ?? []).map(expand),
+            cwd: resolve(dir),
+            env: {
+                ...Object.fromEntries(INHERITED.flatMap((key) => (env[key] === undefined ? [] : [[key, env[key]]]))),
+                ...Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expand(value)])),
+            },
+        };
+    });
+}

package/dist/mcp/grants.d.ts

@@ -0,0 +1,4 @@
+import { type McpGrantRecord, type McpGrantStore, type McpGrantSummary } from "../mcp-api.ts";
+export declare function checkedGrant(value: unknown): McpGrantRecord;
+export declare function grantSummary(id: string, record: McpGrantRecord): McpGrantSummary;
+export declare function mcpGrantFile(path: string): McpGrantStore;

package/dist/mcp/grants.js

@@ -0,0 +1,132 @@
+/** Durable OAuth grants: explicit writes under the same lock that guards refresh and deletion. */
+import { lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import * as Schema from "effect/Schema";
+import { withLockedFile } from "../locked-file.js";
+import { McpError } from "../mcp-api.js";
+const RecordSchema = Schema.Struct({
+    version: Schema.Literal(1),
+    serverUrl: Schema.NonEmptyString,
+    resource: Schema.NonEmptyString,
+    issuer: Schema.NonEmptyString,
+    client: Schema.Struct({
+        id: Schema.NonEmptyString,
+        secret: Schema.optional(Schema.String),
+        tokenEndpointAuthMethod: Schema.Literals(["none", "client_secret_post", "client_secret_basic"]),
+    }),
+    scopes: Schema.Array(Schema.NonEmptyString),
+    status: Schema.Literals(["ready", "refreshing", "reauthorization_required"]),
+    generation: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    accessToken: Schema.NonEmptyString,
+    refreshToken: Schema.optional(Schema.NonEmptyString),
+    expiresAt: Schema.optional(Schema.Number.check(Schema.isFinite())),
+});
+const FileSchema = Schema.Record(Schema.String, RecordSchema);
+export function checkedGrant(value) {
+    try {
+        return Schema.decodeUnknownSync(RecordSchema)(value, { onExcessProperty: "error" });
+    }
+    catch {
+        throw new McpError("storage", "Invalid MCP grant record; refusing to read or overwrite credentials");
+    }
+}
+export function grantSummary(id, record) {
+    return {
+        id,
+        serverUrl: record.serverUrl,
+        resource: record.resource,
+        issuer: record.issuer,
+        scopes: [...record.scopes],
+        status: record.status,
+        ...(record.expiresAt === undefined ? {} : { expiresAt: record.expiresAt }),
+    };
+}
+function decode(raw, path) {
+    if (raw === undefined)
+        return {};
+    try {
+        return Schema.decodeUnknownSync(Schema.fromJsonString(FileSchema))(raw, { onExcessProperty: "error" });
+    }
+    catch {
+        throw new McpError("storage", `Invalid MCP grant file ${path}; refusing to overwrite it`);
+    }
+}
+function idIsValid(id) {
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(id) || ["__proto__", "constructor", "prototype"].includes(id)) {
+        throw new McpError("storage", "Invalid MCP grant ID");
+    }
+}
+function grantFileTarget(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        const link = lstatSync(path, { throwIfNoEntry: false });
+        return link?.isSymbolicLink()
+            ? grantFileTarget(resolve(dirname(path), readlinkSync(path)))
+            : resolve(grantFileTarget(dirname(path)), basename(path));
+    }
+}
+export function mcpGrantFile(path) {
+    const file = resolve(path);
+    const read = () => {
+        try {
+            return decode(readFileSync(file, "utf8"), file);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return {};
+            throw error;
+        }
+    };
+    return {
+        async read(id) {
+            idIsValid(id);
+            const records = read();
+            return Object.hasOwn(records, id) ? records[id] : undefined;
+        },
+        async list() {
+            return Object.entries(read()).map(([id, value]) => grantSummary(id, value));
+        },
+        withGrant(id, operation) {
+            idIsValid(id);
+            // The shared lock helper preserves pi credential path spellings; MCP locks the backing file itself.
+            return withLockedFile(grantFileTarget(file), async (raw, replace) => {
+                let records = decode(raw, file);
+                const save = (next) => {
+                    replace(`${JSON.stringify(next)}\n`);
+                    records = next;
+                };
+                let active = true;
+                const assertActive = () => {
+                    if (!active)
+                        throw new McpError("storage", "MCP grant access escaped its exclusive scope");
+                };
+                try {
+                    const result = await operation({
+                        read() {
+                            assertActive();
+                            return Object.hasOwn(records, id) ? checkedGrant(records[id]) : undefined;
+                        },
+                        async write(value) {
+                            assertActive();
+                            save({ ...records, [id]: checkedGrant(value) });
+                        },
+                        async remove() {
+                            assertActive();
+                            const next = { ...records };
+                            delete next[id];
+                            save(next);
+                        },
+                    });
+                    return { result };
+                }
+                finally {
+                    active = false;
+                }
+            }, { create: false });
+        },
+    };
+}

package/dist/mcp/host.d.ts

@@ -0,0 +1,16 @@
+import { type McpAuthorization, type McpOptions, type McpServerSummary } from "../mcp-api.ts";
+import { type McpServer } from "./config.ts";
+export declare function mcpAuthorization(dir: string, env: NodeJS.ProcessEnv, stateRoot: string, options?: McpOptions): McpAuthorization;
+export declare function writeMcpBinding(stateRoot: string, server: string, id: string | undefined): Promise<void>;
+export declare function mcpContext(dir: string, options?: McpOptions): {
+    agentDir: string;
+    environment: {
+        [x: string]: string | undefined;
+    };
+    stateRoot: string;
+    auth: McpAuthorization;
+};
+export declare function httpServer(servers: readonly McpServer[], name: string): Extract<McpServer, {
+    type: "http";
+}>;
+export declare function inspectMcp(dir: string, options?: McpOptions): Promise<McpServerSummary[]>;

package/dist/mcp/host.js

@@ -0,0 +1,120 @@
+/** MCP declarations and authorization bindings before an agent is opened. */
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import * as Schema from "effect/Schema";
+import { McpError } from "../mcp-api.js";
+import { resolveSecretsDir, resolveStateRoot } from "../paths.js";
+import { agentValues, prepareSecretsDirectory, unprotectedSecretsNote } from "../value-file.js";
+import { log } from "../log.js";
+import { withLockedFile } from "../locked-file.js";
+import { checkedGrant, mcpGrantFile } from "./grants.js";
+import { readMcpConfiguration, checkMcpUrl } from "./config.js";
+const Bindings = Schema.Record(Schema.String, Schema.String);
+function decodeBindings(raw) {
+    if (raw === undefined)
+        return {};
+    try {
+        return Schema.decodeUnknownSync(Schema.fromJsonString(Bindings))(raw);
+    }
+    catch {
+        throw new McpError("storage", "Invalid MCP bindings file; refusing to overwrite it");
+    }
+}
+export function mcpAuthorization(dir, env, stateRoot, options = {}) {
+    if ((options.store === undefined) !== (options.bindings === undefined))
+        throw new McpError("configuration", "MCP store and bindings must be supplied together");
+    if (options.store && options.bindings)
+        return { store: options.store, bindings: { ...options.bindings } };
+    const path = join(stateRoot, "mcp-bindings.json");
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const secretsDir = resolveSecretsDir(dir, env);
+    const file = mcpGrantFile(join(secretsDir, "mcp-auth.json"));
+    const protectedWrite = async (write) => {
+        const unprotected = await prepareSecretsDirectory(dir, secretsDir);
+        await write();
+        if (unprotected !== undefined)
+            log.warn(`[fastagent] ${unprotectedSecretsNote(unprotected)}`);
+    };
+    return {
+        store: {
+            ...file,
+            withGrant: (id, operation) => file.withGrant(id, (access) => operation({
+                ...access,
+                write: (record) => protectedWrite(() => access.write(record)),
+                remove: () => protectedWrite(() => access.remove()),
+            })),
+        },
+        bindings: decodeBindings(raw),
+    };
+}
+export async function writeMcpBinding(stateRoot, server, id) {
+    await withLockedFile(join(stateRoot, "mcp-bindings.json"), async (raw) => {
+        const entries = decodeBindings(raw);
+        if (id === undefined)
+            delete entries[server];
+        else
+            entries[server] = id;
+        return { result: undefined, next: `${JSON.stringify(entries)}\n` };
+    }, { create: false });
+}
+export function mcpContext(dir, options = {}) {
+    const agentDir = resolve(dir);
+    const environment = { ...process.env, ...agentValues(agentDir) };
+    const stateRoot = resolveStateRoot(agentDir, environment);
+    return {
+        agentDir,
+        environment,
+        stateRoot,
+        auth: mcpAuthorization(agentDir, environment, stateRoot, options),
+    };
+}
+export function httpServer(servers, name) {
+    const server = servers.find((s) => s.name === name);
+    if (server?.type !== "http")
+        throw new McpError("configuration", "OAuth needs a declared HTTP MCP server", name);
+    if (new Headers(server.headers).has("authorization"))
+        throw new McpError("configuration", "An MCP server cannot use a static Authorization header and an OAuth binding together", name);
+    return server;
+}
+export async function inspectMcp(dir, options = {}) {
+    const { agentDir, auth } = mcpContext(dir, options);
+    return Promise.all(Object.entries(readMcpConfiguration(agentDir).mcpServers).map(async ([name, declaration]) => {
+        const server = { ...declaration, name, type: declaration.type ?? "stdio" };
+        const id = Object.hasOwn(auth.bindings, server.name) ? auth.bindings[server.name] : undefined;
+        const raw = id === undefined ? undefined : await auth.store.read(id);
+        const grant = raw === undefined ? undefined : checkedGrant(raw);
+        let authorization = "not_bound";
+        if (declaration.type !== "http")
+            authorization = id === undefined ? "not_required" : "binding_mismatch";
+        else if (grant) {
+            authorization =
+                grant.serverUrl !== checkMcpUrl(declaration.url).href || new Headers(declaration.headers).has("authorization")
+                    ? "binding_mismatch"
+                    : grant.status !== "ready"
+                        ? "reauthorization_required"
+                        : grant.expiresAt !== undefined && grant.expiresAt <= Date.now() + 30_000
+                            ? grant.refreshToken
+                                ? "refresh_needed"
+                                : "reauthorization_required"
+                            : "ready";
+        }
+        else if (id !== undefined)
+            authorization = "reauthorization_required";
+        else if (declaration.type === "http" && new Headers(declaration.headers).has("authorization"))
+            authorization = "not_required";
+        return {
+            name: server.name,
+            transport: server.type,
+            ...(declaration.type === "http" ? { url: checkMcpUrl(declaration.url).href } : {}),
+            authorization,
+            ...(id === undefined ? {} : { grantId: id }),
+        };
+    }));
+}

package/dist/mcp/network.d.ts

@@ -0,0 +1,12 @@
+export declare function checkMcpTarget(serverUrl: string, value: string): URL;
+export declare function mcpFetch(serverUrl: string, fetchImpl: typeof globalThis.fetch, timeoutMs?: number): typeof globalThis.fetch;
+type Lookup = (host: string) => Promise<readonly {
+    address: string;
+    family: number;
+}[]>;
+export interface McpNetwork {
+    fetch: typeof globalThis.fetch;
+    close(): Promise<void>;
+}
+export declare function openMcpNetwork(serverUrl: string, customFetch?: typeof globalThis.fetch, resolve?: Lookup): Promise<McpNetwork>;
+export {};