@jangmanj/pi-mcp-ext
MCP 2026-07-28 events and tasks for Pi, alongside builtin:mcp
Package details
Install @jangmanj/pi-mcp-ext from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@jangmanj/pi-mcp-ext- Package
@jangmanj/pi-mcp-ext- Version
0.2.2- Published
- Nov 19, 2026
- Downloads
- 639/mo · 639/wk
- Author
- jangmanj
- License
- MIT
- Types
- extension
- Size
- 390.2 KB
- Dependencies
- 0 dependencies · 3 peers
Pi manifest JSON
{
"extensions": [
"./src/index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
@jangmanj/pi-mcp-ext
Stateless MCP 2026-07-28 capabilities for Pi, running alongside builtin:mcp.
What It Adds Next to builtin:mcp
Pi's builtin:mcp extension speaks MCP 2025-11-25 and owns /mcp, synchronous mcp__<server>__<tool> tools on 2025-11-25 servers, list_mcp_resources / read_mcp_resource, and interactive mcp-auth.json sign-in. @jangmanj/pi-mcp-ext loads in the same Pi session without replacing builtin:mcp and adds the full 2026-07-28 surface on configured stdio and Streamable HTTP servers:
- Stateless discovery and unified
subscriptions/listenmultiplexer: probes enabled servers withserver/discover(closing dormant probes cleanly on legacy2025-11-25servers) and shares at most onesubscriptions/listenstream per server across events, tasks, tools, prompts, and resource watches. - Pure
2026-07-28tools fallback: when a strict2026-07-28server dropsinitializesobuiltin:mcpcannot register itsmcp__<server>__*tools, automatically registers them with fullexposure/toolExposureparity and livetoolsListChangedupdates—standing down completely on dual-stack servers wherebuiltin:mcpsucceeded. - Prompts & Argument Completion (
mcp_prompts,/mcp-prompt,/mcp-prompt:<server>:<prompt>): discovers server prompts viaprompts/list, refreshes onpromptsListChanged, autocompletes prompt and resource-template arguments viacompletion/complete, and sends resolved prompt messages. - Resources & Live Resource Subscriptions (
mcp_resources): lists resources/templates, reads text/image/binary resources (resources/read), browses directories (resources/directory/read), and watchesresourceSubscriptions/resourcesListChangedonsubscriptions/listenwithmcp-resourceturn wakes. - Events (
io.modelcontextprotocol/events,mcp_events): discovers event types viaevents/list, catches up withevents/poll, streams live occurrences viaevents/stream, persists replay cursors in the session branch, deduplicates deliveries, and wakes Pi turns withmcp-eventmessages (pollandpushdelivery;webhook-only event types are skipped since a local CLI session has no inbound webhook endpoint). - Tasks (
io.modelcontextprotocol/tasks,mcp_tasks) + Interactive Elicitation (form&url): invokes task-augmented tools, tracksworkingandinput_requiredtasks acrosssubscriptions/listenand fallbacktasks/getpolling, fulfills interactiveelicitation/createrequests directly viactx.ui(flat primitive forms with review/modify + safe domain-verified external URL consent) before callingtasks/update, cancels viatasks/cancel, and wakes Pi turns withmcp-taskmessages. - Skills over MCP (
io.modelcontextprotocol/skills,mcp_skills): discovers skill manifests without eager file fetches, enforces fail-closed manifest-bound user approval, verifies exact byte sizes +sha256:digests + YAML 1.2 frontmatter + parent directory names, confines supporting-file reads to the skill root, and excludes cached files from filesystem skill discovery to preserve MCP origin. - OAuth 2.0 Client Credentials (
io.modelcontextprotocol/oauth-client-credentials): unattended machine-to-machineclient_secretand RFC 7523 / RFC 10070private_key_jwt(RS*,ES*,EdDSA) authentication with RFC 9728 / RFC 8414 discovery, strict issuer pinning, and in-memory token refresh. - OpenTelemetry Trace Context (
_meta): propagates valid W3Ctraceparent,tracestate, andbaggagefields into outbound_meta. - Task-capability hint, headless settle hold, and read-only config: hints equivalent
mcp_taskscalls on-32021, holds-p/--mode jsonopen while tasks orholdSettlesubscriptions/watches are active, and never writes or locksmcp.jsonormcp-auth.json.
Install
pi install npm:@jangmanj/pi-mcp-ext
Tools
All five tools register directly (and are callable from codemode scripts as tools.mcp_events(...), tools.mcp_tasks(...), tools.mcp_resources(...), tools.mcp_prompts(...), and tools.mcp_skills(...)).
mcp_events
Manage MCP 2026-07-28 event discovery, subscriptions, and polling.
action:"servers" | "list" | "subscribe" | "unsubscribe" | "subscriptions" | "poll"server?: string— MCP server name (required forlist,subscribe,unsubscribe,poll).name?: string— event type name (required forsubscribe,unsubscribe,poll).arguments?: Record<string, unknown>— event filter or subscription arguments validated against the event'sinputSchema.delivery?: "auto" | "push" | "poll"— delivery preference (default"auto", preferring push with poll catch-up).cursor?: string | null— explicit starting cursor (nullstarts from now; omit to resume from the persisted session cursor).maxAgeMs?: number— optional replay age limit in integer milliseconds.maxEvents?: number— optional batch size limit foraction: "poll".holdSettle?: boolean— keep headless (-p/--mode json) runs open until an event arrives orunsubscribeis called.logLevel?: "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency"— per-requestSEP-2575io.modelcontextprotocol/logLevelforlistandpoll; request-scopednotifications/messageframes are appended to the tool result.
mcp_tasks
Invoke and manage MCP 2026-07-28 task-augmented tool calls.
action:"call" | "get" | "update" | "cancel" | "active"server?: string— MCP server name (required forcall,get,update,cancel; optional filter foractive).tool?: string— tool name onserverforaction: "call". Returns the completed tool result immediately if the server finishes synchronously, or tracks the created task if the server returnsresultType: "task".arguments?: Record<string, unknown>— tool arguments foraction: "call".taskId?: string— task identifier forget,update, andcancel.inputResponses?: Record<string, unknown>— responses keyed byinputRequestsid foraction: "update".logLevel?: "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency"— per-requestSEP-2575io.modelcontextprotocol/logLevelforcall,get,update, andcancel; request-scopednotifications/messageframes are appended to the tool result.
action: "active" reads the client's session task ledger directly without issuing a server RPC.
mcp_resources
Read, browse, and subscribe to live updates on 2026-07-28 server resources.
action:"list" | "templates" | "read" | "directory" | "subscribe" | "unsubscribe" | "subscriptions"server?: string— MCP server name (required except forsubscriptions).uri?: string— resource or directory URI (required forread,directory,subscribe,unsubscribe).cursor?: string— pagination cursor forlist,templates, ordirectory.holdSettle?: boolean— keep headless (-p/--mode json) runs open while watchinguri.logLevel?— per-requestSEP-2575log level.
mcp_prompts & /mcp-prompt
Discover prompts, render prompt messages, or autocomplete prompt/resource arguments (completion/complete).
action:"list" | "get" | "complete"server: string— MCP server name.name?: string— prompt name (forgetorcompletewithrefType: "prompt").uri?: string— resource URI or template (forcompletewithrefType: "resource").arguments?: Record<string, string>— prompt arguments forget, or resolvedcontext.argumentsforcomplete.argumentName?: string,argumentValue?: string— active argument forcomplete.- Interactive slash commands:
/mcp-prompt(interactive picker or/mcp-prompt <server>/<prompt> key=value) and dynamic per-prompt/mcp-prompt:<server>:<prompt>with livecompletion/completeargument suggestions.
mcp_skills
Discover, verify, approve, and load Agent Skills over MCP (io.modelcontextprotocol/skills).
action:"list" | "get" | "load" | "read_file" | "directory"server: string— MCP server name.uri?: string— skillSKILL.mdURI (forget,load,read_file) or directory URI (fordirectory).path?: string— relative path or URI within the retained skill manifest (forread_file).cursor?: string— pagination cursor fordirectory.
OAuth 2.0 Client Credentials (clientCredentials)
Global mcp.json or session-registered HTTP servers (over https: or loopback) may configure unattended io.modelcontextprotocol/oauth-client-credentials using either clientSecret or RFC 7523 / RFC 10070 privateKey (RS256/384/512, ES256/384/512, EdDSA) with a required pinned issuer:
{
"mcpServers": {
"ci-remote": {
"url": "https://mcp.example.com/mcp",
"clientCredentials": {
"clientId": "ci-worker",
"privateKey": "${CI_MCP_PRIVATE_KEY_PEM}",
"algorithm": "ES256",
"issuer": "https://auth.example.com"
}
}
}
}
Declarative Subscriptions (subscribe)
Any server entry in global mcp.json, a trusted project .pi/mcp.json (full server definition), or pi.registerMcpServer() may include an optional subscribe array. builtin:mcp ignores unknown fields, while @jangmanj/pi-mcp-ext activates the declared subscriptions automatically on session_start once server/discover confirms io.modelcontextprotocol/events:
{
"mcpServers": {
"alerts": {
"url": "https://alerts.example.com/mcp",
"subscribe": ["*"]
},
"ci": {
"command": "ci-mcp",
"subscribe": [
"build.failed",
{
"name": "deploy.finished",
"arguments": { "env": "prod" },
"delivery": "push",
"maxAgeMs": 600000,
"holdSettle": false
}
]
}
}
}
- Each item is
"*"(all push- or poll-capable events inevents/list), an event name string, or{ name, arguments?, delivery?, maxAgeMs?, holdSettle? }. - Defaults are
delivery: "auto"andholdSettle: false, so declarative subscriptions do not hold headless runs open unlessholdSettle: trueis set. - Subscriptions resume from the latest persisted session cursor when present, or start from
cursor: nullso restarts do not replay previously delivered events. - Invalid
subscribevalues log a warning without blocking the server entry; legacy servers or servers withoutio.modelcontextprotocol/eventsignoresubscribe. - Removing an entry from
subscribedoes not cancel an already-persisted subscription; callmcp_eventswithaction: "unsubscribe"to stop it.
Development
npm run typecheck # Type-check src/ and tests/ with tsc --noEmit
npm test # Run the node:test suite
npm run check # Run typecheck and tests
npm run smoke:pack # Pack tarball, install in a scratch directory, and load in Pi