@wrongstack/mcp 1.0.19 → 1.0.26

package/dist/authorization-callback-server.d.ts

@@ -0,0 +1,24 @@
+export interface MCPOAuthCallbackServerOptions {
+    /** Fixed port when the authorization server requires a preregistered URI. */
+    port?: number | undefined;
+    path?: string | undefined;
+    timeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface MCPOAuthCallbackServer {
+    /** Exact redirect URI to pass to the authorization request. */
+    redirectUri: string;
+    /** Resolves with the full callback URL the browser was redirected to. */
+    waitForCallback(): Promise<string>;
+    close(): void;
+}
+/**
+ * Loopback redirect receiver for the manual OAuth flow.
+ *
+ * Without this the user had to copy the callback URL out of the browser address
+ * bar and paste it back into a second command. The listener binds 127.0.0.1
+ * only — never a routable interface — and answers exactly one path, so nothing
+ * else on the machine can reach it or enumerate its responses.
+ */
+export declare function startMcpOAuthCallbackServer(options?: MCPOAuthCallbackServerOptions): Promise<MCPOAuthCallbackServer>;
+//# sourceMappingURL=authorization-callback-server.d.ts.map

package/dist/authorization-discovery.d.ts

@@ -0,0 +1,96 @@
+export interface MCPAuthorizationChallenge {
+    status: 401;
+    resource: string;
+    resourceMetadataUrl?: string | undefined;
+    scopes: string[];
+    rawScheme: 'Bearer';
+}
+export interface MCPProtectedResourceMetadata {
+    resource: string;
+    authorizationServers: string[];
+    scopesSupported: string[];
+}
+export interface MCPAuthorizationServerMetadata {
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    registrationEndpoint?: string | undefined;
+    authorizationResponseIssuerParameterSupported?: boolean | undefined;
+    scopesSupported: string[];
+}
+export interface MCPAuthorizationDiscoveryResult {
+    resourceMetadataUrl: string;
+    authorizationServerMetadataUrl: string;
+    protectedResource: MCPProtectedResourceMetadata;
+    authorizationServer: MCPAuthorizationServerMetadata;
+}
+export type MCPAuthorizationJsonFetcher = (url: string, signal?: AbortSignal | undefined) => Promise<unknown | undefined>;
+export interface MCPAuthorizationDiscoveryOptions {
+    challengeHeader?: string | null | undefined;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+    maxResponseBytes?: number | undefined;
+    lookup?: BrowserCompatibleDnsLookup | undefined;
+    /** Test/host override. Production callers should use the pinned default. */
+    fetchJson?: MCPAuthorizationJsonFetcher | undefined;
+}
+export type BrowserCompatibleDnsLookup = (hostname: string) => Promise<readonly {
+    address: string;
+    family: number;
+}[]>;
+/** Non-2xx answer from an OAuth endpoint, carrying the HTTP status. */
+export declare class MCPOAuthHttpError extends Error {
+    readonly status: number;
+    readonly name = "MCPOAuthHttpError";
+    constructor(message: string, status: number);
+}
+export declare function canonicalMcpResource(rawUrl: string): string;
+export declare function parseMcpBearerChallenge(header: string | null, resource: string): MCPAuthorizationChallenge;
+/** RFC 9728 fallback order for an MCP endpoint when no challenge URL exists. */
+export declare function protectedResourceMetadataUrls(resource: string): string[];
+/** RFC 8414 + OIDC discovery order required by the MCP authorization spec. */
+export declare function authorizationServerMetadataUrls(issuer: string): string[];
+export declare function parseProtectedResourceMetadata(value: unknown, expectedResource: string): MCPProtectedResourceMetadata;
+export declare function parseAuthorizationServerMetadata(value: unknown, expectedIssuer: string): MCPAuthorizationServerMetadata;
+/**
+ * Discover and validate MCP OAuth metadata without following redirects. The
+ * default fetcher resolves once and opens the socket to that exact IP, making
+ * discovery resistant to DNS rebinding.
+ */
+export declare function discoverMcpAuthorization(resource: string, options?: MCPAuthorizationDiscoveryOptions): Promise<MCPAuthorizationDiscoveryResult>;
+export declare function challengeParameter(parameters: string, name: string): string | undefined;
+export declare function validateMetadataUrl(value: string): string | undefined;
+export declare function record(value: unknown, label: string): Record<string, unknown>;
+export declare function requiredString(value: unknown, field: string): string;
+export declare function optionalString(value: unknown, field: string): string | undefined;
+export declare function optionalBoolean(value: unknown, field: string): boolean | undefined;
+export declare function boundedStringArray(value: unknown, field: string, maxItems: number): string[];
+export declare function optionalStringArray(value: unknown, field: string, maxItems: number): string[];
+export declare function secureOAuthUrl(value: string, label: string): URL;
+export declare function discoverFirst<T>(candidates: readonly string[], fetchJson: MCPAuthorizationJsonFetcher, signal: AbortSignal | undefined, parse: (value: unknown) => T, label: string): Promise<{
+    url: string;
+    value: T;
+}>;
+export declare function requestPinnedJson(rawUrl: string, options: {
+    method?: 'GET' | 'POST' | undefined;
+    body?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+    maxResponseBytes?: number | undefined;
+    lookup?: BrowserCompatibleDnsLookup | undefined;
+    allowedLoopbackHostname?: string | undefined;
+    /** Names the endpoint in errors — token calls were reported as "discovery". */
+    label?: string | undefined;
+}): Promise<unknown | undefined>;
+export declare function resolvePinnedAddress(url: URL, options: {
+    lookup?: BrowserCompatibleDnsLookup | undefined;
+    allowedLoopbackHostname?: string | undefined;
+}): Promise<{
+    address: string;
+    family: 4 | 6;
+}>;
+export declare function assertDiscoveryAddressAllowed(address: string, family: 4 | 6, hostname: string, allowedLoopbackHostname: string | undefined): void;
+export declare function unbracket(hostname: string): string;
+export declare function isLoopbackHttp(url: URL): boolean;
+//# sourceMappingURL=authorization-discovery.d.ts.map

package/dist/authorization-manager.d.ts

@@ -1,24 +1,50 @@
 import { type MCPAuthorizationDiscoveryOptions, type MCPAuthorizationDiscoveryResult, type MCPTokenExchangeOptions, type MCPTokenSet } from './authorization.js';
+import { type MCPClientRegistration, type MCPClientRegistrationOptions } from './authorization-registration.js';
 import type { MCPAuthorizationStateEvent, MCPVaultTokenStore } from './token-store.js';
 type DiscoverAuthorization = (resource: string, options?: MCPAuthorizationDiscoveryOptions) => Promise<MCPAuthorizationDiscoveryResult>;
 type ExchangeAuthorizationCode = (options: MCPTokenExchangeOptions) => Promise<MCPTokenSet>;
+type RegisterClient = (options: MCPClientRegistrationOptions) => Promise<MCPClientRegistration>;
 export interface MCPAuthorizationManagerOptions {
     store: MCPVaultTokenStore;
     pendingTtlMs?: number | undefined;
     discover?: DiscoverAuthorization | undefined;
     exchange?: ExchangeAuthorizationCode | undefined;
+    register?: RegisterClient | undefined;
+    /** `client_name` sent during dynamic registration. */
+    clientName?: string | undefined;
     now?: (() => number) | undefined;
     onStateChange?: ((event: MCPAuthorizationStateEvent) => void) | undefined;
 }
 export interface MCPAuthorizationStartInput {
     serverName: string;
     resource: string;
-    clientId: string;
+    /** Omit to reuse a stored identity or dynamically register one (RFC 7591). */
+    clientId?: string | undefined;
     redirectUri: string;
     scopes?: readonly string[] | undefined;
     challengeHeader?: string | null | undefined;
     signal?: AbortSignal | undefined;
 }
+export interface MCPAuthorizationLoginInput {
+    serverName: string;
+    resource: string;
+    clientId?: string | undefined;
+    scopes?: readonly string[] | undefined;
+    challengeHeader?: string | null | undefined;
+    signal?: AbortSignal | undefined;
+    /** Fixed loopback port, when the server only accepts a preregistered URI. */
+    port?: number | undefined;
+    /** How long to wait for the browser redirect. */
+    timeoutMs?: number | undefined;
+}
+export interface MCPAuthorizationLoginHandle {
+    /** Available immediately: show this to the user. */
+    started: MCPAuthorizationStartResult;
+    /** Settles when the browser redirect arrives and the code is exchanged. */
+    completion: Promise<MCPAuthorizationStatus>;
+    /** Abandon the flow and release the loopback port. */
+    cancel(): void;
+}
 export interface MCPAuthorizationStartResult {
     serverName: string;
     resource: string;
@@ -26,6 +52,8 @@ export interface MCPAuthorizationStartResult {
     redirectUri: string;
     scopes: string[];
     expiresAt: number;
+    /** How the client identity was obtained, for surfacing in status output. */
+    clientIdSource: 'explicit' | 'stored' | 'registered';
 }
 export interface MCPAuthorizationCompleteInput {
     serverName: string;
@@ -50,13 +78,30 @@ export declare class MCPAuthorizationManager {
     private readonly options;
     private readonly pending;
     private readonly starting;
+    /** Registrations reused across servers that share one authorization server. */
+    private readonly registrations;
     private readonly pendingTtlMs;
     private readonly discover;
     private readonly exchange;
+    private readonly register;
     private readonly now;
     constructor(options: MCPAuthorizationManagerOptions);
     begin(input: MCPAuthorizationStartInput): Promise<MCPAuthorizationStartResult>;
     complete(input: MCPAuthorizationCompleteInput): Promise<MCPAuthorizationStatus>;
+    /**
+     * Bind a loopback receiver and start the flow, returning as soon as the URL
+     * exists so a surface can show it without blocking. Completion is awaited
+     * separately — a slash command returns its message immediately and reports
+     * the outcome through `onStateChange`. The two-step `begin`/`complete` pair
+     * stays for surfaces that cannot host a listener.
+     */
+    beginLogin(input: MCPAuthorizationLoginInput): Promise<MCPAuthorizationLoginHandle>;
+    /**
+     * Identity precedence: an explicit id, then the one already stored for this
+     * server (so re-authorizing does not orphan a registration), then the
+     * per-issuer cache, then a fresh dynamic registration.
+     */
+    private resolveClientIdentity;
     status(serverName: string, resource: string): Promise<MCPAuthorizationStatus>;
     disconnect(serverName: string, resource: string): Promise<boolean>;
     private pruneExpired;

package/dist/authorization-registration.d.ts

@@ -0,0 +1,39 @@
+import { type BrowserCompatibleDnsLookup, type MCPAuthorizationServerMetadata, requestPinnedJson } from './authorization-discovery.js';
+/**
+ * Identity this client presents to an authorization server. `clientSecret` is
+ * only present when the server refused the public-client registration we ask
+ * for and issued a confidential client anyway; it is a credential and must
+ * reach the vault-backed store, never config or logs.
+ */
+export interface MCPClientRegistration {
+    clientId: string;
+    clientSecret?: string | undefined;
+    issuer: string;
+    registeredAt: string;
+}
+export interface MCPClientRegistrationOptions {
+    authorizationServer: MCPAuthorizationServerMetadata;
+    redirectUris: readonly string[];
+    clientName?: string | undefined;
+    clientUri?: string | undefined;
+    scopes?: readonly string[] | undefined;
+    /** Canonical MCP resource, used only to allow loopback development servers. */
+    resource?: string | undefined;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+    maxResponseBytes?: number | undefined;
+    lookup?: BrowserCompatibleDnsLookup | undefined;
+    /** Test/host override. Production callers should use the pinned default. */
+    requestJson?: typeof requestPinnedJson | undefined;
+}
+/**
+ * RFC 7591 dynamic client registration.
+ *
+ * Most hosted MCP servers issue no preregistered client IDs at all, so without
+ * this the only way to authorize was for the user to find a client ID by hand.
+ * We register as a public client (`token_endpoint_auth_method: "none"`) because
+ * a CLI cannot keep a secret; a server that overrides that and returns one is
+ * still honored, but the secret goes straight to the vault.
+ */
+export declare function registerMcpOAuthClient(options: MCPClientRegistrationOptions): Promise<MCPClientRegistration>;
+//# sourceMappingURL=authorization-registration.d.ts.map

package/dist/authorization.d.ts

@@ -1,3 +1,5 @@
+import { type BrowserCompatibleDnsLookup, type MCPAuthorizationChallenge, type MCPAuthorizationServerMetadata } from './authorization-discovery.js';
+export { authorizationServerMetadataUrls, canonicalMcpResource, discoverMcpAuthorization, type MCPAuthorizationChallenge, type MCPAuthorizationDiscoveryOptions, type MCPAuthorizationDiscoveryResult, type MCPAuthorizationJsonFetcher, type MCPAuthorizationServerMetadata, MCPOAuthHttpError, type MCPProtectedResourceMetadata, parseAuthorizationServerMetadata, parseMcpBearerChallenge, parseProtectedResourceMetadata, protectedResourceMetadataUrls, } from './authorization-discovery.js';
 export interface MCPAccessToken {
     accessToken: string;
     tokenType?: string | undefined;
@@ -11,42 +13,6 @@ export interface MCPAuthorizationContext {
     resource: string;
     signal?: AbortSignal | undefined;
 }
-export interface MCPAuthorizationChallenge {
-    status: 401;
-    resource: string;
-    resourceMetadataUrl?: string | undefined;
-    scopes: string[];
-    rawScheme: 'Bearer';
-}
-export interface MCPProtectedResourceMetadata {
-    resource: string;
-    authorizationServers: string[];
-    scopesSupported: string[];
-}
-export interface MCPAuthorizationServerMetadata {
-    issuer: string;
-    authorizationEndpoint: string;
-    tokenEndpoint: string;
-    registrationEndpoint?: string | undefined;
-    authorizationResponseIssuerParameterSupported?: boolean | undefined;
-    scopesSupported: string[];
-}
-export interface MCPAuthorizationDiscoveryResult {
-    resourceMetadataUrl: string;
-    authorizationServerMetadataUrl: string;
-    protectedResource: MCPProtectedResourceMetadata;
-    authorizationServer: MCPAuthorizationServerMetadata;
-}
-export type MCPAuthorizationJsonFetcher = (url: string, signal?: AbortSignal | undefined) => Promise<unknown | undefined>;
-export interface MCPAuthorizationDiscoveryOptions {
-    challengeHeader?: string | null | undefined;
-    signal?: AbortSignal | undefined;
-    timeoutMs?: number | undefined;
-    maxResponseBytes?: number | undefined;
-    lookup?: BrowserCompatibleDnsLookup | undefined;
-    /** Test/host override. Production callers should use the pinned default. */
-    fetchJson?: MCPAuthorizationJsonFetcher | undefined;
-}
 export interface MCPAuthorizationSession {
     authorizationUrl: string;
     state: string;
@@ -70,6 +36,8 @@ export interface MCPAuthorizationRequestOptions {
 export interface MCPTokenExchangeOptions {
     authorizationServer: MCPAuthorizationServerMetadata;
     clientId: string;
+    /** Only set when dynamic registration issued a confidential client. */
+    clientSecret?: string | undefined;
     redirectUri: string;
     resource: string;
     code: string;
@@ -82,6 +50,8 @@ export interface MCPTokenExchangeOptions {
 export interface MCPTokenRefreshOptions {
     authorizationServer: MCPAuthorizationServerMetadata;
     clientId: string;
+    /** Only set when dynamic registration issued a confidential client. */
+    clientSecret?: string | undefined;
     resource: string;
     refreshToken: string;
     signal?: AbortSignal | undefined;
@@ -89,10 +59,6 @@ export interface MCPTokenRefreshOptions {
     maxResponseBytes?: number | undefined;
     lookup?: BrowserCompatibleDnsLookup | undefined;
 }
-type BrowserCompatibleDnsLookup = (hostname: string) => Promise<readonly {
-    address: string;
-    family: number;
-}[]>;
 /**
  * Host-owned bridge to vault-backed OAuth state. The MCP package never stores
  * access or refresh tokens itself and never exposes them through config.
@@ -102,36 +68,15 @@ export interface MCPAuthorizationProvider {
     /** Refresh/discover/reauthorize. Return true to retry the HTTP request once. */
     handleUnauthorized?(challenge: MCPAuthorizationChallenge, context: MCPAuthorizationContext): Promise<boolean>;
 }
-/** Non-2xx answer from an OAuth endpoint, carrying the HTTP status. */
-export declare class MCPOAuthHttpError extends Error {
-    readonly status: number;
-    readonly name = "MCPOAuthHttpError";
-    constructor(message: string, status: number);
-}
-export declare function canonicalMcpResource(rawUrl: string): string;
 export declare function authorizationHeaderForToken(token: MCPAccessToken, expectedResource: string, now?: number): string;
-export declare function parseMcpBearerChallenge(header: string | null, resource: string): MCPAuthorizationChallenge;
-/** RFC 9728 fallback order for an MCP endpoint when no challenge URL exists. */
-export declare function protectedResourceMetadataUrls(resource: string): string[];
-/** RFC 8414 + OIDC discovery order required by the MCP authorization spec. */
-export declare function authorizationServerMetadataUrls(issuer: string): string[];
-export declare function parseProtectedResourceMetadata(value: unknown, expectedResource: string): MCPProtectedResourceMetadata;
-export declare function parseAuthorizationServerMetadata(value: unknown, expectedIssuer: string): MCPAuthorizationServerMetadata;
 /**
  * Re-validate the normalized authorization-server shape before it is accepted
  * from host-owned persistence. PKCE support is established during discovery;
  * this guard protects the persisted endpoints and bounded fields themselves.
  */
 export declare function validateMcpAuthorizationServerMetadata(value: unknown): MCPAuthorizationServerMetadata;
-/**
- * Discover and validate MCP OAuth metadata without following redirects. The
- * default fetcher resolves once and opens the socket to that exact IP, making
- * discovery resistant to DNS rebinding.
- */
-export declare function discoverMcpAuthorization(resource: string, options?: MCPAuthorizationDiscoveryOptions): Promise<MCPAuthorizationDiscoveryResult>;
 export declare function createMcpAuthorizationRequest(options: MCPAuthorizationRequestOptions): MCPAuthorizationSession;
 export declare function parseMcpAuthorizationCallback(callbackUrl: string, session: Pick<MCPAuthorizationSession, 'redirectUri' | 'state' | 'issuer' | 'requireIssuerParameter'>): string;
 export declare function exchangeMcpAuthorizationCode(options: MCPTokenExchangeOptions): Promise<MCPTokenSet>;
 export declare function refreshMcpAccessToken(options: MCPTokenRefreshOptions): Promise<MCPTokenSet>;
-export {};
 //# sourceMappingURL=authorization.d.ts.map

package/dist/client-capabilities.d.ts

@@ -0,0 +1,15 @@
+import type { MCPPageOptions, MCPRequestOptions } from './client-types.js';
+import { type MCPGetPromptResult, type MCPListPromptsResult, type MCPListResourcesResult, type MCPListResourceTemplatesResult, type MCPReadResourceResult } from './protocol.js';
+export declare class MCPCapabilityClient {
+    private readonly requestCapability;
+    private readonly requireResourceSubscriptions;
+    constructor(requestCapability: <T>(capability: 'resources' | 'prompts', method: string, params: unknown, parse: (value: unknown) => T, opts: MCPRequestOptions) => Promise<T>, requireResourceSubscriptions: (method: string) => void);
+    listResources(opts?: MCPPageOptions): Promise<MCPListResourcesResult>;
+    listResourceTemplates(opts?: MCPPageOptions): Promise<MCPListResourceTemplatesResult>;
+    readResource(uri: string, opts?: MCPRequestOptions): Promise<MCPReadResourceResult>;
+    subscribeResource(uri: string, opts?: MCPRequestOptions): Promise<void>;
+    unsubscribeResource(uri: string, opts?: MCPRequestOptions): Promise<void>;
+    listPrompts(opts?: MCPPageOptions): Promise<MCPListPromptsResult>;
+    getPrompt(name: string, args?: Record<string, string> | undefined, opts?: MCPRequestOptions): Promise<MCPGetPromptResult>;
+}
+//# sourceMappingURL=client-capabilities.d.ts.map

package/dist/client-http-connection.d.ts

@@ -0,0 +1,22 @@
+import type { MCPClientOptions, ToolsChangedListener } from './client-types.js';
+import type { ConnectionState, MCPTool } from './contracts.js';
+import type { ServerRequestResponder } from './elicitation.js';
+import type { MCPServerMetadata } from './protocol.js';
+import { SSETransport, StreamableHTTPTransport } from './transport.js';
+export interface ClientHttpConnectionHost {
+    opts: MCPClientOptions;
+    state: ConnectionState;
+    sseTransport: SSETransport | undefined;
+    disconnectListeners: Set<() => void>;
+    _tools: MCPTool[];
+    _toolsCache: MCPTool[] | undefined;
+    toolsChangedListeners: Set<ToolsChangedListener>;
+    emitCapabilityChanged: (capability: 'resources' | 'prompts') => void;
+    emitResourceUpdated: (uri: string) => void;
+    _serverMetadata: MCPServerMetadata | undefined;
+    httpTransport: StreamableHTTPTransport | undefined;
+    serverRequests: ServerRequestResponder;
+}
+export declare function connectSSE(host: ClientHttpConnectionHost): Promise<void>;
+export declare function connectStreamableHTTP(host: ClientHttpConnectionHost): Promise<void>;
+//# sourceMappingURL=client-http-connection.d.ts.map

package/dist/client-process.d.ts

@@ -1,4 +1,10 @@
 import { type ChildProcess } from 'node:child_process';
+/** Resolve an HTTP Bearer token without ever persisting the secret itself. */
+export declare function resolveHttpBearerHeaders(options: {
+    headers?: Record<string, string> | undefined;
+    bearerTokenEnv?: string | undefined;
+    name: string;
+}, env?: NodeJS.ProcessEnv): Record<string, string> | undefined;
 /**
  * Force-kill a child and its descendants. On Windows a stdio server is launched
  * through a `.cmd` shim with `shell: true`, so `child` is the `cmd.exe` wrapper

package/dist/client-types.d.ts

@@ -0,0 +1,70 @@
+import type { MCPAuthorizationProvider } from './authorization.js';
+import type { MCPTool } from './contracts.js';
+import type { MCPClientElicitationHandler } from './elicitation.js';
+export type Transport = 'stdio' | 'sse' | 'streamable-http';
+export interface MCPClientOptions {
+    name: string;
+    transport: Transport;
+    command?: string | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    url?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    /** Resolve an HTTP Bearer token from this environment variable at connect time. */
+    bearerTokenEnv?: string | undefined;
+    startupTimeoutMs?: number | undefined;
+    requestTimeoutMs?: number | undefined;
+    /**
+     * Working directory for a stdio server process. Presets address the project
+     * as `--project-root .` / `server-filesystem .`, which resolve against the
+     * spawn cwd — without this the child inherited WrongStack's PROCESS cwd, so
+     * a host serving a project from elsewhere (WebUI, ACP sessions with their
+     * own cwd) pointed those servers at the wrong directory.
+     */
+    cwd?: string | undefined;
+    /** Host-owned, vault-backed authorization for HTTP transports. */
+    authorizationProvider?: MCPAuthorizationProvider | undefined;
+    /**
+     * Allowlist of env var names to forward from the parent process (process.env)
+     * to the child. Values are resolved at spawn time and merged into `env`
+     * via the `extra` path of `buildChildEnv` (unfiltered). This is how built-in
+     * MCP server presets (GitHub, Slack, Brave Search, …) get their API tokens
+     * without storing them in config.json or being scrubbed by the secret filter.
+     */
+    passthroughEnv?: string[] | undefined;
+    /**
+     * Resolution-bound private-network policy for HTTP transports. Default:
+     * private/LAN targets are blocked at dial time (DNS-rebinding safe); the
+     * flag opts this server in. See MCPServerConfig.allowPrivateNetworks.
+     */
+    allowPrivateNetworks?: boolean | undefined;
+    /**
+     * Answers `elicitation/create`. The capability is declared only when this is
+     * set, so a host that can never ask a user should leave it unset.
+     */
+    elicitation?: MCPClientElicitationHandler | undefined;
+}
+export interface MCPRequestOptions {
+    signal?: AbortSignal | undefined;
+}
+export interface MCPPageOptions extends MCPRequestOptions {
+    cursor?: string | undefined;
+}
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: number;
+    method: string;
+    params?: unknown | undefined;
+}
+export type JsonRpcServerRequest = {
+    jsonrpc: '2.0';
+    id: number | string;
+    method: string;
+    params?: unknown | undefined;
+};
+export type ExitListener = (name: string, code: number | null, signal: string | null) => void;
+export type ToolsChangedListener = (name: string, tools: MCPTool[]) => void;
+export type MCPListChangedListener = (name: string) => void;
+/** `notifications/resources/updated` — the payload of a live subscription. */
+export type MCPResourceUpdatedListener = (name: string, uri: string) => void;
+//# sourceMappingURL=client-types.d.ts.map

package/dist/client.d.ts

@@ -1,56 +1,13 @@
-import type { MCPAuthorizationProvider } from './authorization.js';
+import type { ExitListener, MCPClientOptions, MCPListChangedListener, MCPPageOptions, MCPRequestOptions, MCPResourceUpdatedListener, ToolsChangedListener } from './client-types.js';
+import type { ConnectionState, JsonRpcResponse, MCPTool, ToolCallResult } from './contracts.js';
+import { ServerRequestResponder, type UrlElicitation } from './elicitation.js';
 import { type MCPGetPromptResult, type MCPListPromptsResult, type MCPListResourcesResult, type MCPListResourceTemplatesResult, type MCPReadResourceResult, type MCPServerMetadata } from './protocol.js';
 export { forceKillTree } from './client-process.js';
 export { quoteWindowsArg } from './client-protocol-helpers.js';
-export type Transport = 'stdio' | 'sse' | 'streamable-http';
-export interface MCPClientOptions {
-    name: string;
-    transport: Transport;
-    command?: string | undefined;
-    args?: string[] | undefined;
-    env?: Record<string, string> | undefined;
-    url?: string | undefined;
-    headers?: Record<string, string> | undefined;
-    startupTimeoutMs?: number | undefined;
-    requestTimeoutMs?: number | undefined;
-    /**
-     * Working directory for a stdio server process. Presets address the project
-     * as `--project-root .` / `server-filesystem .`, which resolve against the
-     * spawn cwd — without this the child inherited WrongStack's PROCESS cwd, so
-     * a host serving a project from elsewhere (WebUI, ACP sessions with their
-     * own cwd) pointed those servers at the wrong directory.
-     */
-    cwd?: string | undefined;
-    /** Host-owned, vault-backed authorization for HTTP transports. */
-    authorizationProvider?: MCPAuthorizationProvider | undefined;
-    /**
-     * Allowlist of env var names to forward from the parent process (process.env)
-     * to the child. Values are resolved at spawn time and merged into `env`
-     * via the `extra` path of `buildChildEnv` (unfiltered). This is how built-in
-     * MCP server presets (GitHub, Slack, Brave Search, …) get their API tokens
-     * without storing them in config.json or being scrubbed by the secret filter.
-     */
-    passthroughEnv?: string[] | undefined;
-    /**
-     * Resolution-bound private-network policy for HTTP transports. Default:
-     * private/LAN targets are blocked at dial time (DNS-rebinding safe); the
-     * flag opts this server in. See MCPServerConfig.allowPrivateNetworks.
-     */
-    allowPrivateNetworks?: boolean | undefined;
-}
-import type { ConnectionState, JsonRpcResponse, MCPTool, ToolCallResult } from './contracts.js';
 export type { ConnectionState, JsonRpcResponse, MCPTool, ToolCallResult };
-export interface MCPRequestOptions {
-    signal?: AbortSignal | undefined;
-}
-export interface MCPPageOptions extends MCPRequestOptions {
-    cursor?: string | undefined;
-}
-type ExitListener = (name: string, code: number | null, signal: string | null) => void;
-type ToolsChangedListener = (name: string, tools: MCPTool[]) => void;
-export type MCPListChangedListener = (name: string) => void;
 export declare class MCPClient {
     readonly opts: MCPClientOptions;
+    private readonly capabilityClient;
     /**
      * Maximum bytes the rx buffer may accumulate before the connection is
      * forcefully closed. A well-behaved JSON-RPC server emits newline-delimited
@@ -96,8 +53,11 @@ export declare class MCPClient {
     private readonly toolsChangedListeners;
     private readonly resourcesChangedListeners;
     private readonly promptsChangedListeners;
+    private readonly resourceUpdatedListeners;
     /** Notified when an HTTP transport (SSE or streamable-http) disconnects. */
     private readonly disconnectListeners;
+    /** Answers server→client requests (ping, elicitation) on every transport. */
+    private readonly serverRequests;
     constructor(opts: MCPClientOptions);
     getState(): ConnectionState;
     getServerMetadata(): MCPServerMetadata | undefined;
@@ -124,6 +84,11 @@ export declare class MCPClient {
     callTool(name: string, input: unknown, opts?: {
         signal?: AbortSignal | undefined;
     }): Promise<ToolCallResult>;
+    /**
+     * Put the pages of a `-32042` tool-call error to the user (consent first,
+     * nothing opened without it), on the run whose call got the error.
+     */
+    presentUrlElicitations(elicitations: readonly UrlElicitation[], signal: AbortSignal): ReturnType<ServerRequestResponder['presentUrl']>;
     listResources(opts?: MCPPageOptions): Promise<MCPListResourcesResult>;
     listResourceTemplates(opts?: MCPPageOptions): Promise<MCPListResourceTemplatesResult>;
     readResource(uri: string, opts?: MCPRequestOptions): Promise<MCPReadResourceResult>;
@@ -157,8 +122,13 @@ export declare class MCPClient {
     removeToolsChangedListener(listener: ToolsChangedListener): void;
     addResourcesChangedListener(listener: MCPListChangedListener): void;
     removeResourcesChangedListener(listener: MCPListChangedListener): void;
+    addResourceUpdatedListener(listener: MCPResourceUpdatedListener): void;
+    removeResourceUpdatedListener(listener: MCPResourceUpdatedListener): void;
     addPromptsChangedListener(listener: MCPListChangedListener): void;
     removePromptsChangedListener(listener: MCPListChangedListener): void;
+    private emitResourceUpdated;
     private emitCapabilityChanged;
+    private clientHttpConnectionHost;
 }
+export type { MCPClientOptions, MCPListChangedListener, MCPPageOptions, MCPRequestOptions, MCPResourceUpdatedListener, Transport, } from './client-types.js';
 //# sourceMappingURL=client.d.ts.map

package/dist/config-env.d.ts

@@ -0,0 +1,18 @@
+import type { MCPServerConfig } from '@wrongstack/core/types';
+interface ExpandableFields {
+    command?: string | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    url?: string | undefined;
+    headers?: Record<string, string> | undefined;
+}
+/** Every environment variable a server entry reads through placeholders, sorted. */
+export declare function mcpEnvPlaceholders(cfg: Partial<ExpandableFields>): string[];
+/**
+ * The expandable fields with every placeholder resolved from `env`. A variable
+ * that is unset (or empty) with no default is an error naming it: sending the
+ * literal `${TOKEN}` would only fail later, as an opaque 401.
+ */
+export declare function expandMcpEnvPlaceholders(cfg: Readonly<MCPServerConfig>, env?: NodeJS.ProcessEnv): ExpandableFields;
+export {};
+//# sourceMappingURL=config-env.d.ts.map

package/dist/constants.d.ts

@@ -11,11 +11,32 @@
  *
  * Deliberately conservative: a revision belongs here only once its wire
  * requirements are met, because the version we send in `initialize` is a
- * promise about what the peer may then use. WrongStack speaks the 2024-11-05
- * shape — tools, resources, prompts, sampling — and does not implement the
- * additions of later revisions (elicitation, structured tool output, resource
- * links), so listing one of those would advertise capabilities that are not
- * there.
+ * promise about what the peer may then use.
+ *
+ * WrongStack speaks the 2024-11-05 shape: tools, resources, prompts,
+ * pagination, list_changed, resource subscriptions and cancellation. It does
+ * NOT implement sampling (deliberately denied — see below), nor most additions
+ * of later revisions: resource links, `completion/complete`, or progress
+ * notifications. Listing a newer revision here would advertise capabilities
+ * that are not there.
+ *
+ * Known drift, accepted: the HTTP layer already implements Streamable HTTP
+ * (added 2025-03-26), the `MCP-Protocol-Version` header and OAuth resource
+ * indicators (2025-06-18), and the client answers form- and URL-mode
+ * elicitation (2025-06-18 / 2025-11-25) and reads structured tool output
+ * (2025-06-18), even though we negotiate 2024-11-05. Those ride on the
+ * transport, the 401 challenge and the declared client capability rather than
+ * on the negotiated revision, so servers accept them; the declaration is
+ * narrower than the behavior.
+ *
+ * Not gaps, by the spec's own reckoning: Roots, Sampling and Logging were all
+ * Deprecated in revision 2026-07-28 (SEP-2577), with new implementations told
+ * not to adopt them. Not having them is alignment, not lag.
+ *
+ * The current revision (2026-07-28) also replaced the `initialize` handshake
+ * with per-request version negotiation plus a mandatory `server/discover` RPC.
+ * Reaching it is an architectural change, not another entry in this list; the
+ * spec keeps a backward-compatibility path for handshake-based clients.
  *
  * Adding a revision: implement its additions, then put it at the FRONT.
  * `PROTOCOL_VERSION` follows automatically, and the negotiation below starts