Introducing a new way to review your PRs.

Read the announcement

earendil-works / pi

AI agent toolkit: unified LLM API, agent loop, TUI, coding agent CLI

View on GitHub

13 documents · Updated Nov 19, 2026

docs / mcp

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

Risks

  • packages/…/stdio.ts process cleanup is fragile across platforms: if process group creation, exit hooks, or the Windows taskkill path 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 maxMessageBytes to 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 under packages/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.