nicobailon/pi-mcp-adapter v2.28.0

on GitHub

Pi MCP Adapter 2.28.0 makes MCP sessions steadier and easier to operate. Servers can fail, recover, refresh catalogs, or report progress with less surprise in the model-facing tools. Direct tools also get safer host contracts, and downstream hosts get cleaner public helper imports. This release also fixes package install friction and improves several user-facing diagnostics.

Highlights

• MCP connections are less fragile when servers fail, recover, move slowly, or refresh their catalogs.
• Direct MCP tools are safer to expose, with stricter input checks and bounded result details when hosts opt in.
• Other Pi extensions can register MCP servers at runtime without sharing module state.
• Proxy calls now show live server progress in the interactive UI.
• Package installs and public helper imports are easier to use from downstream hosts.

Need to know

No migration is required. If you install from Git with omitted dev dependencies, installs no longer run the public helper build during prepare; published packages and Git installs still include the built public exports.

Full changelog

Highlights

• MCP connections are less fragile when servers fail, recover, move slowly, or refresh their catalogs.
• Direct MCP tools are safer to expose, with stricter input checks and bounded result details when hosts opt in.
• Other Pi extensions can register MCP servers at runtime without sharing module state.
• Proxy calls now show live server progress in the interactive UI.
• Package installs and public helper imports are easier to use from downstream hosts.

Added

• Persistent metadata cache entries now honor server ttlMs hints without extending the default max age. Thanks to @Seinra for #431.
• Proxy tool calls now forward server progress notifications to the interactive UI. Thanks to @Seinra for PR #440 and for mapping the area in #431.
• Added a pure mcp: reference resolver API for consumers that validate adapter tool names from explicit config and cache inputs. Thanks to @abdwhb-png for PR #420.
• Direct tools can opt into strict advertised-schema validation with one-layer JSON recovery for object and array properties. Thanks to @4ndr3wxh1ll for PR #430.
• Direct tools can opt into guarded raw MCP result details, retaining bounded structured fields while summarizing oversized values.
• Embedding hosts can import the configuration loader and metadata cache helpers from public package subpaths, and can validate cached metadata against an explicit private process environment.

Fixed

• Runtime MCP registration now works across separately loaded Pi extensions through a versioned shared event contract. Thanks to @fmoda3 for #443.
• Stdio MCP startup errors now identify a configured missing or non-directory cwd instead of blaming the executable. Thanks to @SoyElf for #442.
• Package installs with --omit=dev no longer run the public helper build during prepare; Git installs and package tarballs still include the built public exports. Thanks to @KripaMishra for #441.
• MCP gateway descriptions now stay stable across metadata-only refreshes and keep live counts behind mcp({}). Thanks to @voidfreud for PR #432.
• Failed MCP servers in active backoff no longer remain advertised through cached direct tools, gateway list/search/describe results, or status tool counts. Thanks to @voidfreud for PR #434.
• OAuth token invalidation now preserves credentials replaced by another Pi process instead of letting a stale refresh delete newly authorized shared credentials. Thanks to @mjlbach for PR #422.
• Failed first-time MCP initialization no longer leaves the session permanently stuck with only MCP not initialized; the gateway keeps the failure reason and retries initialization on the next mcp(...) call. Thanks to @hara-seihun for #428.
• HTTP 202 and unauthenticated HTTP 401 endpoint probes now report ambiguous endpoint shape instead of claiming the URL is not MCP. Thanks to @jayshah5696 for #415.
• Expanded mcpScript calls now show bounded submitted code. Thanks to @DenisBalan for #413.
• Gateway parameters nested inside args now fail with top-level guidance instead of dispatching inconsistently. Thanks to @voidfreud for PR #417.
• Large direct-tool advisories now explain how to hide them with settings.warnOnLargeDirectTools: false. Thanks to @afrodao2394 for #412.
• Namespace proxy tools now use valid cached metadata, include resource-only proxy servers, clean up only prior namespace registrations, follow MCP_DIRECT_TOOLS selection, and skip ambiguous normalized server names. Thanks to @abdwhb-png for PR #414.
• Kept transient HTTP 503 connection failures as availability errors without multiplying gateway retries or misdiagnosing the endpoint as non-MCP. Thanks to @elkaix for PR #411.
• Preserved cached keep-alive catalogs during transient 503 refresh outages while deferred recovery continues with bounded backoff.
• Startup connections that fail with a transient HTTP 503 now surface one quiet "temporarily unavailable; retry later" warning instead of the full hard failure; documented lifecycle behavior is unchanged, and keep-alive health checks continue their existing self-healing path. Thanks to @elkaix for PR #424.