MCP integration package
Overview
Path-routing coverage: this doc owns packages/mcp/**, including the package entrypoints, MCP protocol/client abstractions, stdio/HTTP/pipe transports, OAuth helpers, test-only transport exports, third-party notices, README/changelog, and tests under packages/mcp/test/**.
packages/mcp publishes the standalone @earendil-works/pi-mcp package. packages/…/package.json exposes three public entrypoints: . from packages/…/index.ts, ./oauth from packages/…/index.ts, and ./testing from packages/…/index.ts. The package is ESM, targets Node >=22.19.0, has no dependency on the official MCP SDK, and keeps the official SDK's MIT notice in packages/…/modelcontextprotocol-typescript-sdk.txt because several OAuth files are adapted from it.
The root entrypoint packages/…/index.ts re-exports the transport-neutral client, protocol/content types, JSON-RPC helpers and errors, transport classes, config validation, LLM-facing content utilities, shared naming helpers, and output limiting. The testing entrypoint packages/…/index.ts only exposes the in-memory transport pair for adapter/client tests. The OAuth entrypoint packages/…/index.ts gathers the lower-level OAuth flow primitives, the stateful provider, the loopback callback server, and the higher-level two-half sign-in/auth-provider helpers.
The client core is packages/…/client.ts. McpClient.connect() attaches listeners to an McpTransport, starts it, sends initialize with LATEST_PROTOCOL_VERSION from packages/…/types.ts, accepts negotiated versions listed in SUPPORTED_PROTOCOL_VERSIONS, sends notifications/initialized, and stores server info/capabilities/instructions. Requests are correlated by monotonically increasing JSON-RPC IDs, time out after the per-request override, client default, or 30 seconds, and may carry _meta.progressToken; progress notifications renew the timeout and dispatch to the request's callback. Abort and timeout reject the pending request, abort the transport send controller so delayed transports do not dispatch stale messages, and send notifications/cancelled except for initialize. The client also handles server-originated JSON-RPC requests: ping is built in, roots/list is registered when McpClientOptions.roots is present, and custom request/notification/error/close handlers can be installed by callers.
Protocol surface is intentionally small and structural. packages/…/jsonrpc.ts defines JSON-RPC message guards, parser, standard JSON-RPC error codes, and MCP-specific error classes (McpError, connection-closed, timeout, abort). packages/…/types.ts models initialization, tools, resources, templates, progress/cancel notifications, and protocol versions. packages/…/content.ts models MCP content blocks and toLlmContent(), which converts text/images through, unwraps embedded text/image resources, turns audio/resource links/other binary resources into short text placeholders, and falls back to JSON-stringified structuredContent when a tool returns no content blocks. packages/…/input-schema.ts, packages/…/naming.ts, and packages/…/output-limit.ts are model-facing adapters: they normalize tool schemas to object schemas with properties, produce provider-safe mcp__<server>__<tool> names capped at 64 chars with stable hash suffixes, derive server namespaces/summaries, and truncate combined text output at MCP_OUTPUT_MAX_BYTES (20 KiB) while optionally saving the full text.
Configuration validation lives in packages/…/config.ts. validateMcpServerConfig() validates the shared mcpServers shape at a configuration trust boundary, preserving unknown fields for application-specific checks after it classifies entries as stdio (command) or Streamable HTTP (url). It accepts type: "streamable-http" as HTTP, rejects legacy type: "sse", validates shared enabled/description/timeout, validates stdio args/env/cwd, and validates HTTP headers plus OAuth settings such as loopback callback URL/port, scopes, client registration mode, and optional authorization-server metadata URL. isMcpServerOverride() identifies entries with no command, url, or type, for applications that let a less-trusted config override fields of an existing server.
All transports implement McpTransport from packages/…/transport.ts, which standardizes start(), send(), close(), listener registration, optional protocol-version propagation, and send cancellation. TransportEvents centralizes listener bookkeeping and ensures close is emitted at most once. packages/…/lines.ts provides stdio framing shared by local and remote process transports: it reads newline-delimited JSON-RPC from stdout, enforces DEFAULT_MAX_MESSAGE_BYTES unless overridden, drops oversized messages while continuing to read later ones, reports an incomplete final line, and keeps a bounded stderr tail for diagnostics.
packages/…/stdio.ts starts a local MCP server with cross-spawn, writes one JSON-RPC line per send, decodes stdout/stderr through JsonRpcLineReader, and shuts down by closing stdin, then sending SIGTERM, then SIGKILL after closeTimeoutMs. On Unix it starts the server in its own process group and kills the group so wrappers such as npx and child processes do not remain. On Windows it uses taskkill /T /F for tree cleanup. It installs a process exit hook to terminate live process groups if the host exits without closing them.
packages/…/pipe.ts speaks the same stdio framing over a caller-provided McpPipe, intended for programs started elsewhere such as @earendil-works/pi-env remote processes. Its open() option receives stdout/stderr handlers and returns write/closeStdin/close/exited primitives. Close mirrors stdio shutdown by closing stdin and killing via the pipe only after closeTimeoutMs; a program exit closes the transport, and an unexpected rejected exited promise is reported as an error before close. packages/…/in-memory.ts provides a microtask-delivered paired transport used by tests.
packages/…/streamable-http.ts implements MCP Streamable HTTP. StreamableHttpTransport.send() POSTs JSON-RPC messages with Accept: application/json, text/event-stream, captures Mcp-Session-Id, adds MCP-Protocol-Version after initialization, and adds bearer tokens supplied by an AuthProvider from packages/…/auth-provider.ts. Notifications/responses are expected to be acknowledged with no protocol reply; requests accept either a single/batch JSON response or an SSE response stream. After notifications/initialized, the transport optionally opens the server-to-client GET SSE stream. Both GET streams and request response streams parse SSE with consumeSseStream(), enforce per-event/message limits, track event IDs and retry: delays, and reconnect with exponential backoff and Last-Event-ID where resumption is possible. HTTP failures are classified as auth-required (401), session-expired (404 with a session), or generic McpHttpError; 401 and 403 with insufficient_scope are handed once to the auth provider and retried if recovery succeeds.
OAuth support is split between reusable flow primitives and application-facing helpers. packages/…/types.ts provides dependency-free structural parsers for protected-resource metadata, authorization-server metadata, token responses, and client registration responses; it deliberately accepts only HTTP(S) URLs for server-supplied metadata/endpoints. packages/…/discovery.ts implements MCP protected-resource discovery, OAuth/OIDC authorization-server discovery, WWW-Authenticate parsing, issuer validation, configured metadata override, and protected-resource selection that requires the advertised resource to match the MCP server origin/path. packages/…/flow.ts implements PKCE authorization-code flow, dynamic client registration, Client ID Metadata Document use, token refresh, client-auth method selection, scope merging for step-up authorization, credential invalidation/retry on invalid_client/invalid_grant, and adaptOAuthProvider() for direct use with StreamableHttpTransport.
The stateful OAuth layer is in packages/…/provider.ts, packages/…/client-settings.ts, packages/…/auth-provider.ts, packages/…/sign-in.ts, packages/…/callback.ts, and packages/…/loopback.ts. McpOAuthProvider stores one server URL's client information, tokens, PKCE verifier, state, and discovery cache behind an injectable McpOAuthStateStore, ignoring stored state for another server URL. client-settings.ts converts application settings into provider metadata, chooses between configured clients, Client ID Metadata Documents, and dynamic client registration, derives server-specific callback paths, bounds authorization-server requests with timedFetch(), and derives loopback callback settings. createMcpAuthProvider() reads/stores tokens through a McpOAuthServerStore with a refresh lock; it refreshes near-expired or rejected tokens without launching a browser and throws McpOAuthAuthorizationRequiredError when user interaction is required. startMcpSignIn()/completeMcpSignIn() split sign-in into a persistable browser step and later code exchange, first trying refresh under the lock unless this is step-up authorization. OAuthCallbackServer and loopback.ts handle local callback URLs, server-specific redirect paths, pasted redirect URLs, timeout/cancel behavior, and closing all browser-held connections on shutdown.
Tests under packages/mcp/test/** are part of the package's behavioral contract. client.test.ts covers initialization, pagination, resources, structured tool content, progress timeout renewal, cancellation, older protocol negotiation, close listeners, and server requests. streamable-http.test.ts exercises SSE parsing, size-limit cancellation, session/protocol headers, auth error classification, request-specific stream failures, GET stream ordering/resumption, retry behavior, and HTTP body limits. stdio.test.ts, pipe.test.ts, and lines.test.ts cover stdio framing and shutdown behavior including child cleanup and bounded stderr. oauth.test.ts, sign-in.test.ts, auth-provider.test.ts, loopback.test.ts, and authorization-server.ts exercise discovery, PKCE, DCR/CIMD, issuer checks, refresh locks, step-up scopes, callback/pasted URL validation, and token rotation. Small adapter tests cover config validation, naming, input schema normalization, content conversion, and output limiting.
Coupling
- If
McpTransport.send()behavior changes in packages/…/transport.ts, also verify packages/…/client.ts request cancellation: the client aborts the per-send signal after a request settles and relies on transports such as packages/…/streamable-http.ts not dispatching delayed/retried requests after that point. - If JSON-RPC message guards or accepted IDs change in packages/…/jsonrpc.ts, verify all framing/parsing callers: packages/…/lines.ts drops invalid stdio messages and continues, while packages/…/streamable-http.ts turns invalid response-stream messages into request errors or transport errors.
- If
LATEST_PROTOCOL_VERSIONorSUPPORTED_PROTOCOL_VERSIONSchanges in packages/…/types.ts, update handshake expectations in packages/…/client.ts and HTTP headers/discovery requests in packages/…/streamable-http.ts and packages/…/discovery.ts; tests in packages/…/client.test.ts and packages/…/streamable-http.test.ts assert negotiated versions and headers. - If stdio framing or message-size limits change in packages/…/lines.ts, verify both packages/…/stdio.ts and packages/…/pipe.ts; they share the reader and expose its stderr tail and parse errors as transport diagnostics.
- If Streamable HTTP auth retry logic changes in packages/…/streamable-http.ts, verify both auth-provider layers: the generic
AuthProvidercontract in packages/…/auth-provider.ts and the OAuth adapters in packages/…/flow.ts and packages/…/auth-provider.ts.403 insufficient_scopeis intentionally treated like a challenge but must trigger browser step-up, not a plain refresh. - If OAuth discovery or metadata validation changes in packages/…/discovery.ts or packages/…/types.ts, verify packages/…/flow.ts, packages/…/client-settings.ts, and packages/…/config.ts; configured metadata URLs are trusted after config validation, while discovered metadata enforces issuer/resource matching.
- If
McpOAuthStatechanges in packages/…/provider.ts, update every store-facing helper in packages/…/auth-provider.ts, packages/…/sign-in.ts, and packages/…/client-settings.ts; token refresh, PKCE verifier, OAuth state, discovery cache, and registered client information are persisted and invalidated independently. - If Client ID Metadata Document routing changes in packages/…/client-settings.ts, verify callback path handling in packages/…/callback.ts, packages/…/loopback.ts, and sign-in completion in packages/…/sign-in.ts; a server-specific redirect URI is used to avoid mixing responses from different authorization servers when RFC 9207
isssupport is absent. - If public exports are added or moved in packages/…/index.ts, packages/…/index.ts, or packages/…/index.ts, keep packages/…/package.json exports and packages/…/README.md examples aligned so package consumers can import the documented symbols.
- If package code adapted from the official SDK is expanded beyond current OAuth files (packages/…/types.ts, packages/…/flow.ts, packages/…/discovery.ts), verify packages/…/modelcontextprotocol-typescript-sdk.txt still covers the copied material and package
filesincludes the notices.
Risks
- packages/…/stdio.ts process cleanup is fragile across platforms: if process group creation, exit hooks, or the Windows
taskkillpath are changed, stdio servers started through wrappers can leave children running after close. Recent package history includes fixes for child cleanup after server exit (fix(mcp): clean up server children on stdio close after the server exited) and tests in packages/…/stdio.test.ts cover stubborn children and children holding pipes. - packages/…/streamable-http.ts SSE/body limit handling has had multiple recent fixes. If stream cancellation or JSON/SSE byte limits change, oversized streams can remain open or buffer too much data; package history includes fixes for applying
maxMessageBytesto HTTP JSON responses, cancelling failed SSE streams, and CR-only SSE line endings, with regression coverage in packages/…/streamable-http.test.ts. - packages/…/callback.ts must close outstanding browser connections during shutdown. Without
server.closeAllConnections(), browsers may keep preconnect/keep-alive sockets open and hang sign-in cleanup; recent history includes a fix for OAuth callback close hangs, and callback lifecycle is covered by OAuth/loopback tests underpackages/mcp/test/**. - packages/…/auth-provider.ts and packages/…/sign-in.ts depend on the store refresh lock to avoid two processes using the same rotating refresh token. If
McpOAuthServerStore.withRefreshLock()is bypassed or made reentrant by callers, one refresh can invalidate another process's grant and force a new sign-in.