summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--LICENSE18
-rw-r--r--PLAN.md556
-rw-r--r--README.md110
-rw-r--r--TODOs.md13
-rw-r--r--_selfcheck.lua2247
-rw-r--r--init.lua76
-rw-r--r--mise.toml53
-rw-r--r--panto-mcp-0.1.0-1.rockspec49
-rw-r--r--panto_mcp/async.lua59
-rw-r--r--panto_mcp/cache.lua95
-rw-r--r--panto_mcp/client.lua334
-rw-r--r--panto_mcp/config.lua176
-rw-r--r--panto_mcp/docs.lua43
-rw-r--r--panto_mcp/eager.lua60
-rw-r--r--panto_mcp/hash.lua41
-rw-r--r--panto_mcp/http.lua680
-rw-r--r--panto_mcp/jsonrpc.lua75
-rw-r--r--panto_mcp/manager.lua229
-rw-r--r--panto_mcp/namespace.lua31
-rw-r--r--panto_mcp/oauth.lua458
-rw-r--r--panto_mcp/prompts.lua267
-rw-r--r--panto_mcp/results.lua89
-rw-r--r--panto_mcp/search.lua83
-rw-r--r--panto_mcp/stdio.lua108
-rw-r--r--panto_mcp/supervisor.lua65
-rw-r--r--panto_mcp/tools.lua97
-rw-r--r--panto_mcp/validate.lua134
27 files changed, 6246 insertions, 0 deletions
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..876f03c
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Travis Parker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/PLAN.md b/PLAN.md
new file mode 100644
index 0000000..a0003c8
--- /dev/null
+++ b/PLAN.md
@@ -0,0 +1,556 @@
+# panto-mcp: plan
+
+An MCP client for panto, shipped as an out-of-tree Lua extension (rock
+`panto-mcp`, entry name `mcp`), plus the general-purpose panto core additions
+it needs. Written 2026-11-16 from a planning session; readable without that
+conversation.
+
+Research reports referenced below were written to `/tmp` (volatile); the facts
+this plan depends on are restated inline.
+
+- `/tmp/mcp-research.md`: spec revisions, transports, lifecycle, auth, configs.
+- `/tmp/mcp-discovery-research.md`: opencode/pi discovery, provider-native
+ deferred tools, generic-dispatch prior art.
+- `/tmp/mcp-optional-features.md`: prompts, resources, elicitation, tasks.
+- `/tmp/whiteboard-mcp-optional-features.html`: whiteboard of the above.
+
+## Goals
+
+- Configure MCP servers in panto's layered `config.toml`: remote by URL, local
+ by command.
+- Speak the latest released revision (**2026-07-28**) and fall back to
+ **2025-11-25** (and the 2025-06-18 / 2025-03-26 versions it negotiates down
+ to). Most servers in the wild still speak the handshake revisions.
+- Never leave orphaned server processes under any normal or abnormal panto
+ exit (one accepted gap, below).
+- Make large MCP catalogs cheap: deferred discovery through `mcp.search` /
+ `mcp.call`, and "code mode" through an `mcp` namespace in `std.lua`.
+- Tools, resources and prompts. Remote OAuth.
+
+## Non-goals (v1)
+
+| Feature | Why not | Revisit when |
+|---|---|---|
+| Elicitation | Needs core "user input for extensions" (TODOs.md). Not advertised, so servers must not send it; GitHub hides `delete_repository`. | After that core project; noted on its TODOs.md entry. |
+| Tasks (2026 extension) | No popular server needs it for ordinary calls. Travis plans background-able tool calls first. | After background-able tool calls. |
+| Tasks (2025 experimental wire) | Superseded, wire-incompatible. | Never, unless a concrete server requires it. |
+| Sampling, roots, logging | Deprecated in 2026-07-28. Not advertised. | — |
+| Resource subscriptions / `subscriptions/listen` | Long-lived stream, ack/demux/reconnect; on-demand reads suffice. | A real server workflow needs push updates. |
+| 2024-11-05 HTTP+SSE transport | Deprecated; SHOULD NOT adopt. | A user hits a server that only speaks it. |
+| Native provider deferred loading (`defer_loading`) | Only Anthropic Messages and OpenAI Responses have it; both still need the catalog up front. `mcp.search`/`mcp.call` is provider-neutral and cache-stable. | — |
+| Importing `.mcp.json` / Claude Desktop configs | Not needed at first. | Later convenience. |
+| Persistent broker surviving `/new`/`/resume`/`/reload` | Restarting is far simpler; remote servers dominate; switches are infrequent. | Startup cost becomes a real complaint. |
+| Windows | panto doesn't target it. | — |
+
+## Key facts that shape the design
+
+- **stdio is newline-delimited JSON-RPC** on the child's stdin/stdout; stderr is
+ free-form logging. No port handoff exists. A local server that speaks HTTP is
+ configured by URL.
+- **2026-07-28 is stateless.** No `initialize`, no sessions, no ping, no SSE
+ resumability. Every request carries `_meta` protocol version, client
+ capabilities and client info; servers MUST implement `server/discover`.
+ Results carry `resultType`. HTTP is one POST per request, answered with JSON
+ or a request-scoped SSE stream, with required `MCP-Protocol-Version`,
+ `Mcp-Method` and (for `tools/call`, `resources/read`, `prompts/get`)
+ `Mcp-Name` headers.
+- **2025-11-25 is handshake-based:** `initialize` → `notifications/initialized`,
+ optional `Mcp-Session-Id`, GET notification stream, DELETE to end a session.
+- **MCP has no tool search.** All proposals were closed or are dormant; the
+ official client guidance puts progressive discovery in the host.
+- **Spec shutdown order for stdio:** close the server's stdin, wait, SIGTERM,
+ wait, SIGKILL (current opencode: 2s / 2s, whole process group).
+- **panto constraints found in code:**
+ - Tools and commands are harvested only during `activate()`
+ (`src/lua_runtime.zig` `activateEntry`); a `ToolSource`'s `tools` slice is
+ fixed at registration.
+ - `panto.ext.http_request` is GET-only, fully buffered, `keep_alive = false`,
+ 120s max timeout, 16 global concurrent requests, auth over HTTPS only
+ (`src/lua_http.zig`). Its `Service` is created per Lua runtime and
+ destroyed on every session switch (`src/live_session.zig`).
+ - The TUI's SIGINT/SIGTERM/SIGHUP handlers restore the terminal and re-raise
+ without running `session_end` (`src/tui_terminal.zig`), so extension
+ cleanup cannot be relied on for abnormal exits.
+ - `session_end` gets at most 16 non-blocking loop passes before teardown
+ (`src/main.zig`), so it cannot wait out grace periods.
+ - Core auth has API keys and device-code OAuth only (libpantograph
+ `src/auth.zig`); no authorization-code + PKCE flow.
+ - `agent:conversation()` on the host agent returns a borrowed, mutable view
+ with `add_user_blocks` / `add_assistant_message`; `agent:submit` accepts
+ blocks. Persistence and rendering of view edits are unverified (spike S2).
+
+## Architecture
+
+```mermaid
+flowchart LR
+ subgraph panto["panto process (Lua runtime, rebuilt per session)"]
+ EXT["mcp extension<br/>config · catalog · search · validate"]
+ NS["std.lua `mcp` namespace"]
+ T["tools: mcp.search / mcp.call / mcp.read_resource<br/>+ eager mcp.&lt;server&gt;.&lt;tool&gt;"]
+ C["commands: /mcp:&lt;server&gt;:&lt;prompt&gt;"]
+ H["core http_request<br/>(process-lifetime pool)"]
+ A["core auth (oauth_pkce)"]
+ MC[("metadata cache<br/>(disk, per server)")]
+ end
+ SUP["panto lua supervisor<br/>(own process group)"]
+ SRV["stdio server<br/>(own process group)"]
+ REM["remote server"]
+ EXT --- NS & T & C
+ EXT <-->|"load at activation · save on connect"| MC
+ EXT -- "stdin/stdout NDJSON (pipes)" --> SRV
+ EXT -- "fd 3 lifeline" --> SUP
+ SUP -- "owns / signals group" --> SRV
+ EXT -- "POST · JSON or SSE" --> H --> REM
+ H -. "Bearer" .- A
+```
+
+### Lifetime
+
+One Lua runtime per session. Servers start **lazily**, driven by a disk
+metadata cache, so a session switch normally spawns nothing. On `session_end`
+the extension closes everything without waiting (the supervisor finishes local
+teardown; HTTP requests are cancelled). Running servers simply restart on
+their next use after `/new`, `/resume`, `/reload`.
+
+**Metadata cache.** Every successful connect saves the server's discovery
+result: detected era, server info/instructions, capabilities, and the full
+tool, prompt, resource and resource-template lists.
+
+- One JSON file per server, keyed by a **config fingerprint**: a hash (FNV in
+ Lua) of the connection identity (`url`, or `command`/`args`/`env`/`cwd`,
+ plus `auth`). A config change means a cold cache. Writes are atomic
+ (temp file + rename).
+- Location: `${XDG_DATA_HOME:-$HOME/.local/share}/panto-mcp/`, resolved in
+ Lua with the same XDG rule panto uses (`$XDG_DATA_HOME` if set and
+ non-empty, else `$HOME/.local/share`). The extension owns this directory;
+ no core cache-dir API.
+- Replaces the earlier plan to keep the detected era in `panto.ext.state`.
+
+**Activation:**
+
+- **Warm cache** (entry with a matching fingerprint): register
+ `/mcp:<server>:<prompt>` commands and any eager `mcp.<server>.<tool>` tools
+ straight from the cache. **No process starts.** Eager tools are therefore
+ present from the first turn, without post-activation registration.
+- **Cold cache** (first run, or config changed): connect that server in the
+ background (non-blocking) to populate the cache, then register its prompts
+ and eager tools post-activation (core C1/C2).
+
+**What starts a server:** `mcp.call`, an eager tool call,
+`mcp.read_resource`, running a prompt command, or `/mcp refresh [server]`.
+`mcp.search` searches the cache and starts nothing (a cold server still
+connecting is waited for). Every connect re-lists everything, rewrites the
+cache, and reconciles registrations: new prompts/eager tools are registered,
+removed ones unregistered (C1/C2; an eager change busts the prompt cache once,
+which is acceptable for a rare server-side change).
+
+**Staleness:** the cache is refreshed on every connect (no `ttlMs`-based
+expiry in v1). `mcp.call` validates against the **live** schema, since the
+connect it triggers re-lists first. A tool missing after the refresh errors
+with the closest matches; a removed prompt fails on `prompts/get` and its
+command is unregistered.
+
+A call to a server that is still connecting waits for it (bounded by the
+server's startup timeout). A failed connection is retried lazily on the next
+use, with the error visible in `mcp.search` / `/mcp` status.
+
+### Configuration
+
+Extension-owned tables, read from `panto.ext.config` (merged layers; rigs and
+project configs may define servers, which is no worse than shipping Lua).
+
+```toml
+[mcp]
+startup_timeout_ms = 30000 # per server: spawn/connect + discovery
+call_timeout_ms = 300000 # per request; progress does not extend past this
+idle_timeout_ms = 60000 # HTTP streams: max silence between bytes
+
+[mcp.servers.github]
+url = "https://api.githubcopilot.com/mcp/"
+expose = "search" # "search" (default) | "eager"
+auth = "mcp.github" # optional: named panto [auth.*] session
+headers = { "X-Tenant" = "acme" } # non-secret; ${env:VAR} expanded
+enabled = true
+enabled_tools = [] # empty = all
+disabled_tools = ["delete_*"] # glob over MCP tool names; applied after enabled_tools
+
+[mcp.servers.fs]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "${project_root}"]
+env = { "TOKEN" = "${env:FS_TOKEN}" }
+cwd = "." # relative to project root
+```
+
+- Exactly one of `url` / `command` per server; invalid servers are reported and
+ skipped, never fatal to panto.
+- `panto.ext.config` leaves `${env:VAR}` literal; the extension expands it in
+ `args`, `env`, `headers`, `url`. `${project_root}` comes from
+ `panto.ext.dirs`. Missing env → empty string, matching core semantics.
+- Server names use `^[A-Za-z0-9_-]+$`, but also cannot contain `__` or end in
+ `_`: panto decodes `__` as a provider-name separator, so those names make
+ server/tool boundaries ambiguous. Invalid server entries are warned about
+ and skipped, never fatal to panto.
+- Secrets for remote servers should go through `auth = "<session>"` so they
+ never pass through Lua; `headers` with `${env:}` remain possible.
+- For automatic OAuth, omit `auth`; optional `[mcp.servers.<name>.oauth]` accepts
+ `client_id`, required matching `issuer` with that ID, optional `client_secret`
+ (`${env:VAR}` expanded) and fallback `scopes`. Otherwise use public DCR.
+- Child env: inherit panto's environment plus `env`. (Codex-style `env_vars`
+ allowlisting is skipped; add if needed.)
+
+### Tool surface and token cost
+
+Every registered tool costs context tokens, so nothing is unconditional.
+
+| Exposed to model | When |
+|---|---|
+| `mcp.search`, `mcp.call`, `mcp.read_resource` | At activation, iff ≥1 enabled server has `expose = "search"`. Static declarations: cache-stable for the session. |
+| `mcp.<server>.<tool>` per eager tool | At activation from a warm cache; otherwise after that eager server's first connect (post-activation registration, C1), visible from the next provider request. |
+| `mcp.read_resource` (eager-only configs) | Registered when the first eager server (cached or live) advertises `resources`. |
+| std.lua `mcp` namespace | Iff ≥1 enabled server. No tool cost; a short hint. |
+| System hint | Iff ≥1 enabled server: one line per server (name, transport, mode) built from **config only**, so it never changes mid-session; points at search tools when exposed, otherwise at eager tools and docs. |
+
+Eager tools can miss the first turn only on a cold cache (the user submits
+before the first-ever connect finishes). Search mode has no such race
+(`mcp.call` waits).
+
+**`mcp.search {query?, server?, limit?}`**: connects the relevant servers if
+needed and searches the cached catalog (tools, resources, resource templates)
+client-side. Ranking: simple term scoring over name, title, description and
+parameter names/descriptions (BM25-ish; no dependency). Each hit returns
+`server`, `name`, title/description and the **full input schema**, so search
+doubles as describe. Server `instructions` (from discover/initialize) are
+returned when `server` is given, truncated.
+
+**`mcp.call {server, tool, input}`**: exact `server` + `tool` only; never fuzzy
+execution. Unknown names return an error listing the closest matches.
+`input` is validated against the tool's live input schema before sending;
+failure returns the validation errors plus the schema. Declared non-strict
+(an `any`-shaped `input` cannot be expressed in OpenAI/Anthropic strict mode).
+
+**`mcp.read_resource {server, uri}`**: `resources/read` on the originating server.
+Never fetches arbitrary URLs itself; a `resource_link` in a tool result names
+its server.
+
+Eager tool names are `mcp.<server>.<tool>`, with the MCP tool name sanitized
+to `[A-Za-z0-9_-]` and `__` collapsed (panto encodes `.` as `__` on the wire).
+Every tool gets a suffix derived only from its own MCP name, so adding another
+tool cannot rename it. Truncation keeps the encoded wire name within **64
+bytes**. The limit is the strictest declared provider cap checked: Anthropic
+Messages tool names allow 128 characters; OpenAI Chat Completions function
+names cap at 64; OpenAI Responses documents function names as strings without
+a stated limit. Sources: [Anthropic Messages](https://platform.claude.com/docs/en/api/http/messages/create),
+[OpenAI Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create),
+[OpenAI Responses](https://developers.openai.com/api/reference/resources/responses/methods/create).
+Eager tools are validated the same way as `mcp.call` (panto has no schema
+validation of its own).
+
+### std.lua `mcp` namespace ("code mode")
+
+Registered with `require("_std").lua_namespace("mcp", factory)`; available to
+child agents too. Functions run in the std.lua handler coroutine and yield on
+luv:
+
+```lua
+mcp.servers() -- name, transport, mode, era, state, error
+mcp.search(query, {server=, limit=})
+mcp.call(server, tool, input) -- validated; returns {text, attachments, structured, is_error}
+mcp.start(server, tool, input) -- handle; handle:await(); for parallel calls
+mcp.read_resource(server, uri)
+mcp.prompts(server), mcp.prompt(server, name, args)
+```
+
+Reference docs ship as a require-able module (`require("panto_mcp.docs")`),
+like `subagents.docs` and `_std.docs`: discovery, examples, result shapes,
+errors. Only the one-line hint is injected. Per-server proxy sugar
+(`mcp.github.create_issue{}`) is skipped; add it if models reach for it.
+
+### Input validation
+
+A pure-Lua JSON Schema subset validator, ported from panto-subagents'
+`workflow.lua` (copied, not a dependency). Covers `type`, `properties`,
+`required`, `additionalProperties`, `enum`/`const`, `items`/`prefixItems`,
+numeric/string/array bounds, `anyOf`/`oneOf`/`allOf`/`not`, local `$ref`/
+`$defs`. Unknown keywords (including `pattern`/`format` if unsupported) are
+**ignored, not rejected**: validation exists to catch cheap mistakes, and a
+false rejection would block a valid call. Errors carry JSON-pointer paths.
+
+### Result mapping (tool calls, resources, prompts)
+
+| MCP content | panto result |
+|---|---|
+| `text` | text |
+| `image` | attachment (base64 decoded in Lua; size-capped) |
+| `audio` | text placeholder with MIME type and size |
+| `resource` (embedded text) | text, prefixed with its URI |
+| `resource` (embedded blob) | attachment if image, else placeholder |
+| `resource_link` | text line: name, URI, description, and "read with `mcp.read_resource{server=…, uri=…}`" (or `mcp.read_resource` in std.lua) |
+| `structuredContent` | JSON text, only if no text block already carries it |
+| `isError: true` | tool error (model-visible) with the content |
+| JSON-RPC `error` | tool error: `<server>: <message> (<code>)` |
+| `resultType: input_required` | tool error: server requested user input, which panto does not support yet |
+
+Output is capped (configurable later if needed); truncation is stated in the
+result.
+
+### Prompts
+
+- Each server prompt becomes a slash command **`/mcp:<server>:<prompt>`**,
+ registered at activation from the metadata cache, or after the first connect
+ on a cold cache (core C2), and unregistered if a later connect shows it gone. Description = prompt title/description plus its argument names, so the
+ fuzzy command selector finds it.
+- Arguments: `name=value` tokens with shell-style quoting; a prompt with exactly
+ one argument accepts the trimmed raw remainder when no matching `name=` token
+ appears. Missing required arguments → error listing them.
+- On invoke, start `prompts/get` in an async coroutine from the synchronous
+ command callback. Refuse if a turn or non-prompt command is active, and
+ re-check when the result arrives. Prompt responses append real user/assistant
+ roles to the borrowed host conversation; a trailing user message is submitted
+ to start a turn. Assistant media is represented by text placeholders.
+- Prompt names the core rejects (slash/whitespace) are skipped with a warning
+ visible in `/mcp`. Async failures mount a visible error above the input until
+ the next `command_start`. One-argument positional values preserve the trimmed
+ raw remainder when no matching `name=` argument is present.
+- **Assistant-tail rule:** if the prompt does not end with a user message,
+ append all messages and skip `agent:submit`. Emit `agent_submission` so the
+ idle TUI sync renders and persists the tail without starting a turn.
+- All prompt message blocks are mapped before conversation mutation. Only
+ `image/*` content becomes user media; assistant media and non-image blobs
+ become text placeholders. This avoids partial history from rejected media.
+
+- **Conversation sync verified in ws-1:** idle `onPaint` syncs the conversation
+ tail and calls `flushPersist`; idle submission draining syncs/persists before
+ queued `agent:submit` work starts. Assistant-tail prompts emit
+ `agent_submission` to request that same idle sync. No C5 core change is needed.
+
+### Resources
+
+Built in v1 because tool results can carry `resource_link`s that are only
+usable with `resources/read`.
+
+- Catalog: `resources/list` and `resources/templates/list` (paginated, cached
+ per `ttlMs`), searchable through `mcp.search`.
+- Reading: `mcp.read_resource` tool and namespace function; templates are filled by the
+ model/user into a concrete URI, then read.
+- Only servers advertising `resources` are queried. Some legacy clients treat
+ `-32601` from list methods as fatal; we never call unadvertised methods.
+
+## Protocol client
+
+Layers (each a module; transports are interchangeable under the client):
+
+1. **Transport**
+ - *stdio:* NDJSON framing over luv pipes; partial-line buffering; stderr
+ captured into a bounded per-server ring for diagnostics (never treated as
+ an error signal).
+ - *HTTP (modern):* POST per request with the required headers; response is
+ JSON or a request-scoped SSE stream parsed in Lua. `x-mcp-header` tool
+ annotations are validated and mirrored as `Mcp-Param-*` headers.
+ Cancellation = cancel the request (close its stream).
+ - *HTTP (legacy 2025-11-25):* adds `Mcp-Session-Id` capture/echo, re-init on
+ 404, best-effort DELETE on close. The optional GET notification stream opens
+ for eager servers advertising `tools.listChanged`, closes with the session,
+ retries after an established stream ends, and is replaced after legacy re-init.
+2. **JSON-RPC:** id allocation, pending-request table, per-request timeout
+ (`call_timeout_ms`), cancellation (`notifications/cancelled` on stdio),
+ late responses to cancelled ids ignored. Progress notifications are accepted
+ and ignored (no progress token is sent in v1).
+3. **Era negotiation:**
+ - Modern first: `server/discover` with 2026-07-28 `_meta`. Success → modern;
+ `UnsupportedProtocolVersion (-32022)` → pick from `supported`.
+ - Any other error, a recognizable legacy rejection, an empty/unrecognized
+ HTTP 400, or a probe timeout → legacy `initialize` (offer `2025-11-25`,
+ accept the server's counter-offer among versions we implement), then
+ `notifications/initialized`.
+ - The detected era is stored in the server's metadata cache entry to skip
+ the probe next time; if the cached era fails, re-probe.
+4. **Capabilities advertised:** none (`{}`): no elicitation, sampling, roots,
+ tasks. Client info `{name = "panto-mcp", version}`.
+5. **Server→client traffic (legacy):** answer `ping`; reply `-32601` to any
+ other request. Handle `notifications/tools|resources|prompts/list_changed`
+ by re-listing (eager: unregister/re-register; search: invalidate catalog;
+ prompts: re-register commands).
+
+## Local server lifecycle (no orphans)
+
+```mermaid
+sequenceDiagram
+ participant P as panto (extension)
+ participant W as supervisor (panto lua)
+ participant S as server
+ P->>W: spawn detached: fds 0,1,2 = server pipes, fd 3 = lifeline
+ W->>S: spawn detached (new process group), inheriting fds 0,1,2
+ W-->>W: close own copies of 0/1; report server pid on stderr marker
+ P->>S: JSON-RPC over the pipes (no relaying through W)
+ alt normal session_end / quit
+ P->>S: close stdin write end
+ P->>W: close lifeline (fd 3)
+ else panto dies (SIGKILL, crash, SIGHUP, OOM)
+ Note over P,W: kernel closes panto's fds: stdin EOF + lifeline EOF
+ end
+ W->>W: wait grace (2s) for S to exit
+ W->>S: SIGTERM process group, wait 2s
+ W->>S: SIGKILL process group
+ W-->>W: exit once group is gone
+```
+
+- One supervisor per local server: `uv.spawn(uv.exepath(), {"lua",
+ supervisor_path, ...})`, starts in ~16ms. `supervisor_path` resolved via
+ `package.searchpath` so it works from a rock or a checkout.
+- Both supervisor and server run in their own process groups (`detached`), so
+ terminal Ctrl+C / Ctrl+Z / SIGHUP do not hit them directly; panto's death is
+ observed only through the lifeline. The supervisor also traps
+ INT/TERM/HUP and runs the same teardown.
+- The server's group is signalled, catching `npx`/`docker`-style wrappers that
+ leave grandchildren.
+- panto never waits during `session_end`: it closes two fds and returns; process
+ handles are unref'd so they don't hold the loop.
+- **Accepted gap:** if panto and the supervisor are both SIGKILLed at once, a
+ server that ignores stdin EOF survives. No pidfile sweep (rare enough).
+- Precedent: `../panto-claudesub/panto-claudesub/_session.lua` (detached group,
+ bounded TERM → KILL escalation, confirmed exit).
+
+## Remote auth
+
+Order of preference per server: `auth = "<session>"` (static API key or OAuth
+session in `[auth.*]`), then automatic MCP OAuth on a 401.
+
+**Extension (MCP policy):**
+1. On 401, parse `WWW-Authenticate` for `resource_metadata`; else try the
+ RFC 9728 well-known PRM URIs (endpoint path, then origin root).
+2. Fetch authorization-server metadata (RFC 8414, then OIDC discovery
+ variants); require an exact `issuer` match and PKCE (`S256`) support.
+3. Client registration: configured `client_id` requires an exact `oauth.issuer`
+ binding (optional env-expanded `client_secret`) → public Dynamic Client Registration.
+ Confidential DCR is refused; no client secret is stored in `panto.ext.state`.
+ Public registrations are stored per issuer and retained on every failure. Any
+ configured issuer pins selection from authorization_servers, even without a client ID.
+ CIMD is deferred (`TODOs.md`).
+4. Define a runtime `oauth_pkce` session `mcp.<server>.<identity-hash>` (≤128 bytes),
+ using 128 bits of SHA-256 over canonical resource, exact issuer and client ID.
+ Retire the old name with core logout on changes. Use discovered endpoints,
+ challenge → PRM → configured scopes, and `resource` = canonical server URI.
+ Warm activation restores discovery without network work; no attestation flag.
+5. Login is user-initiated: `/mcp-login <server> [callback-url | --reregister]`.
+ Reuse a definition unless missing or core login fails; keep registrations on all
+ failures. Only a changed discovered issuer or explicit --reregister discards one.
+ The escape hatch rediscovers/registers once; errors mention it. Consent with an
+ existing usable token does not lock out tools, and give-up clears login_required.
+6. Authenticated 401: one forced refresh, then one retry; parallel calls await the
+ shared refresh. Scope 403 redefines the scope union and asks for re-consent,
+ without disabling working calls or an artificial attempt counter. Other 403s
+ report permission errors; explicit non-PKCE auth errors point to core auth.
+ Legacy GET reconnect backs off to 60 seconds and stops with a /mcp warning on 401.
+7. Root PRM fallback validates `resource` against the origin. Loopback discovery/
+ endpoints require a loopback resource; reject leading-zero IPv4 octets. Cache
+ status reads/poll at ~1 second and back off failed discovery from 5 to 60 seconds.
+
+**Core (credential mechanism, C4):** generic `oauth_pkce` auth type
+(authorization code + PKCE S256, `state` check, optional `iss` validation,
+`resource` parameter, loopback callback on an ephemeral port, **pasted
+callback URL fallback** for SSH/headless, token storage under `auth/`,
+refresh, header injection) plus `panto.ext` APIs to define a named session at
+runtime and start its login. Requests then use `http_request{auth = name}`;
+tokens never enter Lua.
+
+## Core additions (pantograph / libpanto)
+
+New `panto.ext` surfaces are co-designed with Travis before building; each
+passes the AGENTS.md tests (second consumer, no "mcp" in core names, mechanism
+not policy).
+
+| # | Addition | Second consumer |
+|---|---|---|
+| C1 | `register_tool` after activation + `unregister_tool(name)`. Changes take effect at the next turn (per-turn snapshot); in-flight calls unaffected; same collision rules; child agents sharing the Lua tool source see it. Needs copy-on-write declarations in the Lua `ToolSource` (provider serialization reads them off the owner thread). | Any extension whose tools depend on async discovery: plugin loaders, per-skill tools, a tool set that changes with project state. |
+| C2 | `register_command` after activation + `unregister_command(name)`; the fuzzy selector and `render_header` command list pick them up. | subagents' `/workflow:<name>` when profiles change on disk; skills exposed as commands. |
+| C3 | `http_request`: `method` (GET/POST/PUT/PATCH/DELETE), `body`; streaming via `on_head(head)` / `on_data(chunk)` hooks (presence of `on_data` disables buffering; final callback still fires with status/headers or error); `idle_timeout_ms`; no total cap for streams (`timeout_ms = 0`); keep-alive with a process-lifetime connection pool (callbacks still die with the runtime); auth allowed over plain HTTP to loopback; streams counted separately from the 16 buffered slots; bounded chunk queue for backpressure. | Lua protocol providers streaming a custom wire API; webhook/REST clients; the messaging bridge's long-poll. |
+| C4 | `oauth_pkce` auth type + runtime session definition and login APIs (above). Seeded `config.toml` documents the new auth fields. | Messaging bridge (Slack/Telegram OAuth); any extension calling an OAuth-protected API. |
+| C5 | *Only if spike S2 fails:* host-agent method to append arbitrary-role messages that persists and renders. | Fork/import tools, transcript surgery extensions, prompt-library extensions. |
+
+Draft Lua shape for C3 (to be co-designed):
+
+```lua
+local handle, err = panto.ext.http_request({
+ url = url, method = "POST", body = json, auth = "mcp.github",
+ headers = { ["content-type"] = "application/json",
+ accept = "application/json, text/event-stream" },
+ timeout_ms = 0, idle_timeout_ms = 60000,
+ on_head = function(head) end, -- {status, headers}
+ on_data = function(chunk) end, -- raw bytes; SSE parsing is the caller's
+}, function(response, err) end) -- buffered: {status, body, headers}; streamed: no body
+handle:cancel()
+```
+
+## Build phases
+
+Spikes first, then extension work proceeds in parallel with core work
+(stdio + search mode needs no core change).
+
+- [x] **S1 supervisor spike:** luv `spawn` with a 4th stdio slot from Lua;
+ detached supervisor + detached server; EOF propagation when panto is
+ `kill -9`ed; group kill of an `sh -c 'trap "" TERM; sleep …'` tree.
+- [x] **S2 conversation spike:** source-verified: asynchronous idle edits sync
+ through `onPaint`; `agent:submit` synchronizes before the TUI drains its
+ queued work. Assistant-tail prompts explicitly emit `agent_submission`
+ to wake that same render/persist path. C5 is unnecessary.
+- [x] **S3 tool-source mutability:** read libpanto's registry/`ToolSource`
+ snapshot path to size C1.
+- [x] **E1 core client:** rock skeleton (`panto-mcp` → `init.lua`,
+ `panto_mcp.*` modules), config parsing/expansion, JSON-RPC, stdio
+ transport + supervisor, era negotiation, catalog + metadata cache
+ (lazy start), `mcp.search` /
+ `mcp.call`, validator, result mapping, `session_end` teardown, `/mcp`
+ status command.
+- [x] **E2 code mode:** std.lua `mcp` namespace, `panto_mcp.docs`, system hint.
+- [x] **C3 HTTP** → **E3 HTTP transport:** modern POST/SSE, legacy sessions,
+ static headers and `auth = "<session>"`.
+- [x] **E4 resources:** list/templates/read, `mcp.read_resource`, resource blocks in
+ results, catalog search over resources.
+- [x] **C1/C2 dynamic registration** → **E5 eager mode** (including legacy HTTP
+ GET notifications) and **E6 prompts** (`/mcp:<server>:<prompt>`); no C5 fix.
+- [x] **C4 OAuth** → **E7 MCP OAuth:** PRM/AS discovery, configured/DCR registration,
+ `/mcp-login` (loopback + pasted callback), refresh-on-401 and non-blocking scope step-up;
+ issuer-bound configured clients, identity-scoped sessions, public-only DCR,
+ rediscovery/backoff/status caching, warm restoration and real-core TCP-fake checks.
+ Real-provider pass remains below.
+- [ ] **E8 release:** README, rockspec, mise tasks (copy panto-web's
+ `version`/`release`), luarocks upload. Files done; tag/upload left to Travis.
+- [x] Note on pantograph `TODOs.md` "User input for extensions" that it enables
+ MCP elicitation in panto-mcp.
+
+## Testing
+
+Per pantograph AGENTS.md: never test timeouts by sleeping; inject the clock /
+timer factory so timeouts fire deterministically.
+
+- `_selfcheck.lua` run with `panto lua` (like panto-web/panto-claudesub):
+ fake stdio servers written in Lua for both eras (modern discover; legacy
+ initialize; legacy server that errors on pre-initialize requests; server that
+ ignores EOF; server that spawns a grandchild), and a luv TCP fake for HTTP
+ (JSON response, SSE response, legacy session 404 → re-init, 401 → PRM).
+- Eager tools/prompts: warm activation is idle; a cold `mcp.search` connect
+ reconciles eager declarations; `list_changed` reconciles add/remove/schema
+ changes. Tests cover multi-server prompt preservation, `/compact` command
+ busy state, visible async failures, image-only media and all-message preflight,
+ raw one-argument remainders, invalid command/server names, stable eager names,
+ exact cache pruning, and legacy GET reconnect/re-init.
+- Validator, SSE parser, NDJSON framer, result mapping, name sanitizing, arg
+ parsing: table-driven unit checks in the same selfcheck.
+- OAuth: table-driven challenge/URL/issuer/S256/scope checks; injected HTTP/auth/timers
+ cover discovery → public DCR → user login → reconnect, refresh and scope upgrades.
+ Regressions cover foreign-issuer credentials, identity-scoped sessions, non-locking
+ 403s, concurrent refresh calls, confidential-DCR refusal, rediscovery and backoff.
+ `PANTO_MCP_HTTP_E2E=1` adds a new-core browser/pasted-callback flow, forced refresh,
+ scope re-consent and warm reuse against a local TCP fake (no real credentials).
+- Orphan check: spawn supervisor+server from a stand-in parent process,
+ `kill -9` the parent, wait on the server group's exit event (bounded), assert
+ nothing survives.
+- Core additions get Zig tests in pantograph/libpanto alongside their code.
+- One manual end-to-end pass against real servers: a filesystem stdio server
+ via `npx`, a remote legacy server, a remote 2026 server, and one OAuth server
+ (GitHub or Linear).
+
+## Resolved design checks
+
+- **Provider tool-name limits:** use 64 encoded wire bytes, the strictest declared
+ bound in the primary provider docs linked above.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6419a31
--- /dev/null
+++ b/README.md
@@ -0,0 +1,110 @@
+# panto-mcp
+
+An extension for connecting panto to Model Context Protocol (MCP) servers. It
+supports supervised local stdio servers and remote Streamable HTTP servers,
+with deferred tool discovery/calls, resource reads, prompts, and a `std.lua`
+namespace. It adds no Lua dependencies; local server programs must be installed
+separately.
+
+## Install
+
+Install the rock through panto:
+
+```sh
+panto extensions install rock:panto-mcp
+```
+
+Alternatively add it to panto's `config.toml`:
+
+```toml
+[extensions]
+rocks = ["panto-mcp"]
+```
+
+Configure servers in `config.toml`:
+
+```toml
+[mcp]
+startup_timeout_ms = 30000
+call_timeout_ms = 300000
+idle_timeout_ms = 60000
+
+[mcp.servers.files]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "${project_root}"]
+# cwd = "."
+# env = { "TOKEN" = "${env:FILES_TOKEN}" }
+# enabled = true
+# expose = "search"
+# enabled_tools = []
+# disabled_tools = ["delete_*"]
+
+[mcp.servers.remote]
+url = "https://example.com/mcp"
+# auth = "mcp.remote" # named panto auth session
+# headers = { "X-Tenant" = "acme" } # ${env:VAR} is expanded
+# expose = "search"
+# oauth = { scopes = ["read"] }
+```
+
+Global timeout fields are positive integer milliseconds: `startup_timeout_ms`
+(connect and discovery), `call_timeout_ms` (request), and `idle_timeout_ms`
+(maximum silent interval for HTTP streams). Each server accepts exactly one of
+`url` (HTTP(S)) or `command` (stdio), plus `args` (string array), `env`
+(string-to-string table), `cwd` (string), `enabled` (boolean), `expose`
+(`"search"` default or `"eager"`), `headers` (string-to-string table), `auth`
+(named auth session), and `enabled_tools` / `disabled_tools` (glob arrays,
+filtered in that order). HTTP servers may also set `oauth` with `scopes` (array
+of strings), `client_id`, `issuer`, and `client_secret`; a client ID requires
+its exact `issuer`, and a secret requires a client ID. An issuer without a client
+ID pins public DCR discovery too (the matching advertised issuer is selected). `${env:NAME}` expands
+from the process environment and `${project_root}` from panto's project root
+in supported string values. Invalid server entries are skipped with warnings.
+
+## Use
+
+The session header lists enabled MCP servers by their configured names, even
+before they connect. Use `/mcp` to check connection status.
+
+Search-mode servers provide `mcp.search`, `mcp.call`, and (when resources are
+available) `mcp.read_resource`. Set `expose = "eager"` to expose individual
+`mcp.<server>.<tool>` tools. Server prompts are commands of the form
+`/mcp:<server>:<prompt>`; `/mcp` shows status and `/mcp refresh [server]`
+refreshes metadata. The `std.lua` code-mode API is documented at
+`require("panto_mcp.docs").discovery` (and related docs fields).
+
+For automatic HTTP OAuth, omit `auth` and run `/mcp-login <server>`; open the
+URL shown, or paste the full callback URL using `/mcp-login <server>
+<callback-url>` in a headless session. A configured `auth` uses the named panto
+auth session instead of automatic OAuth.
+
+Public DCR registrations are reused across logins and all failures, including
+network/refresh errors: a transient error never creates a new client. If the
+client was deleted or is otherwise stale, explicitly run
+`/mcp-login <server> --reregister` to discard that registration and definition,
+rediscover, and register once. It is only for automatic public DCR clients;
+confidential DCR is refused. Normal login rediscovers only for a missing
+or failed definition. A changed discovered issuer discards the old registration.
+Configured client secrets stay out of extension state and catalog caches.
+Registrations are issuer-wide in panto state; `--reregister` intentionally replaces
+that shared registration.
+
+Automatic session names use a 128-bit SHA-256 prefix of resource, issuer and
+client ID (within 128 bytes); a name change logs out the old session. Consent
+login with a usable token keeps working tools usable, even if consent is abandoned.
+Legacy notification streams retry with exponential backoff up to 60 seconds;
+a 401 stops retries and shows a `/mcp` warning. Simple eager tool names stay
+readable; sanitized/truncated or encoded-looking names get stable suffixes.
+
+**Core API requirement:** remote HTTP, eager tool registration, prompt commands,
+and OAuth require a panto build with post-activation register/unregister,
+`http_request` methods and streaming, and `panto.ext.auth`. On older panto
+builds stdio plus search mode works; unsupported capabilities degrade with a
+clear error.
+
+## Limits
+
+Catalogs are cached locally and refreshed on connection; search does not start
+servers. There is no resource subscription, elicitation, task support, legacy
+HTTP+SSE transport, or persistent server process across panto sessions. Local
+stdio server executables are not bundled.
diff --git a/TODOs.md b/TODOs.md
new file mode 100644
index 0000000..7de5ca4
--- /dev/null
+++ b/TODOs.md
@@ -0,0 +1,13 @@
+# Deferred work
+
+## OAuth Client ID Metadata Documents (CIMD)
+
+- MCP's preferred OAuth client registration (2026-07-28) after a pre-configured
+ `client_id`; Dynamic Client Registration is deprecated but kept for older
+ authorization servers.
+- Needs panto-mcp's client metadata JSON hosted at a stable HTTPS URL (e.g.
+ under `tjp.lol/pantograph/`); that URL *is* the `client_id`.
+- v1 ships configured `client_id` + DCR only. Revisit when an authorization
+ server we care about requires CIMD, or once the document is hosted.
+- Spec note: the 2026-07-28 release cites the CIMD draft `-00`; the current
+ MCP draft moves to `-03`. Implement whichever is current when this lands.
diff --git a/_selfcheck.lua b/_selfcheck.lua
new file mode 100644
index 0000000..1662ae3
--- /dev/null
+++ b/_selfcheck.lua
@@ -0,0 +1,2247 @@
+-- panto lua _selfcheck.lua; no network/provider tokens. Child modes reuse this file.
+local uv=require('luv')
+local json=require('panto').ext.json
+local here=debug.getinfo(1,'S').source:match('^@(.*)/[^/]+$') or '.'
+here=uv.fs_realpath(here)
+package.path=here .. '/?.lua;' .. here .. '/?/init.lua;' .. package.path
+local async=require('panto_mcp.async')
+local function close(h) async.close(h) end
+local function write(path,text)
+ local f=assert(io.open(path,'wb')); assert(f:write(text)); f:close()
+end
+local function read(path)
+ local f=io.open(path,'rb'); if not f then return nil end
+ local s=f:read('a'); f:close(); return s
+end
+-- A stand-in parent dies without running extension teardown. Its inherited
+-- stderr reports the actual server/group pid to the outer test.
+if arg[1]=='--parent' then
+ local transport=assert(require('panto_mcp.stdio').new({command=uv.exepath(),args={'lua',here .. '/_selfcheck.lua','--fake','grandchild'},env={}}))
+ local reported=false
+ local watchdog=uv.new_timer(); watchdog:start(0,10,function()
+ if transport.server_pid and transport.stderr_tail:find('GRANDCHILD=%d+') and not reported then
+ io.stdout:write('SERVER=',transport.server_pid,'\n'); io.stdout:flush(); reported=true
+ end
+ end)
+ uv.run(); return
+end
+if arg[1]=='--fake' then
+ local mode=arg[2]
+ if mode=='banner' then io.stdout:write('starting fake server\n'); io.stdout:flush(); mode='modern' end
+ if mode=='exit-on-eof' then
+ local pipe=uv.new_pipe(false); assert(pipe:open(0))
+ pipe:read_start(function(_,data) if not data then close(pipe) end end)
+ uv.run(); return
+ end
+ if mode=='noisy-exit' then
+ io.stderr:write('diagnostic-tail-from-child'); io.stderr:flush()
+ io.stdout:write('diagnostic-tail-from-child\n'); io.stdout:flush(); return
+ end
+ if mode=='env-check' then
+ assert(os.getenv('PANTO_MCP_TEST_CHILD_ENV')=='child','server env not applied')
+ mode='modern'
+ end
+ if mode=='ignore' or mode=='grandchild' then
+ local keep=uv.new_timer(); keep:start(100000,100000,function() end)
+ local signal=uv.new_signal(); signal:start('sigterm',function() end)
+ if mode=='grandchild' then
+ local child,pid=assert(uv.spawn('sh',{args={'-c','trap "" TERM; sleep 1000 & wait'},stdio={nil,nil,2}},function() end))
+ io.stderr:write('GRANDCHILD=',pid,'\n'); io.stderr:flush(); child:unref()
+ end
+ local pipe=uv.new_pipe(false); assert(pipe:open(0)); pipe:read_start(function() end)
+ uv.run(); return
+ end
+ local initialized=false; local changed=false; local removed=false
+ local function send(msg) io.stdout:write(json.encode(msg),'\r\n'); io.stdout:flush() end
+ local pipe=uv.new_pipe(false); assert(pipe:open(0))
+ local feed=require('panto_mcp.stdio').framer(function(req)
+ if not req.method then return end
+ if req.id==nil then return end
+ local function result(r) send({jsonrpc='2.0',id=req.id,result=r}) end
+ local function err(code,msg,data) send({jsonrpc='2.0',id=req.id,error={code=code,message=msg,data=data}}) end
+ local caps={tools={listChanged=true},prompts={},resources={}}
+ if mode=='tools-only' then caps={tools={}} end
+ if req.method=='server/discover' then
+ if mode=='legacy-close' then close(pipe); return end
+ if mode~='modern' then err(-32600,'initialize first'); return end
+ assert(req.params._meta['io.modelcontextprotocol/protocolVersion']=='2026-07-28')
+ result({resultType='complete',supportedVersions={'2026-07-28'},capabilities=caps,instructions='Fake server instructions',_meta={['io.modelcontextprotocol/serverInfo']={name='fake'}}}); return
+ end
+ if req.method=='initialize' then
+ assert(mode~='modern','modern must never initialize'); initialized=true
+ result({protocolVersion='2025-06-18',capabilities=caps,serverInfo={name='fake'},instructions='Fake server instructions'}); return
+ end
+ if mode=='modern' then assert(req.params._meta and req.params._meta['io.modelcontextprotocol/clientCapabilities'])
+ else assert(initialized,'legacy request before initialize') end
+ if req.method=='tools/list' then
+ if removed then result({tools={}})
+ elseif req.params.cursor then result({tools={{name='other',description='Other tool',inputSchema={type='object'}}}})
+ else
+ local tools={{name='echo',description='Echo a message',inputSchema={type='object',properties={message={type='string'}},required={'message'},additionalProperties=false}}}
+ if changed then tools[#tools+1]={name='new_tool',inputSchema={type='object'}} end
+ result({tools=tools,nextCursor='page2'})
+ end
+ elseif req.method=='prompts/list' then
+ assert(mode~='tools-only')
+ result({prompts=removed and {} or {{name=changed and 'wave' or 'greet',arguments={{name='name',required=true}}}}})
+ elseif req.method=='resources/list' then assert(mode~='tools-only'); result({resources={{name='guide',uri='docs://guide',description='Guide document'}}})
+ elseif req.method=='resources/templates/list' then
+ if mode=='missing-templates' then err(-32601,'not implemented') else result({resourceTemplates={{name='entry',uriTemplate='docs://{name}'}}}) end
+ elseif req.method=='resources/read' then result({contents={{uri=req.params.uri,text='resource body'}}})
+ elseif req.method=='prompts/get' then result({messages={{role='user',content={type='text',text='Hello'}}}})
+ elseif req.method=='tools/call' then
+ result({content={{type='text',text=(req.params.arguments or {}).message or 'ok'}}})
+ if req.params.arguments and req.params.arguments.message=='change' then
+ changed=true; send({jsonrpc='2.0',method='notifications/tools/list_changed'})
+ elseif req.params.arguments and req.params.arguments.message=='remove' then
+ removed=true; send({jsonrpc='2.0',method='notifications/tools/list_changed'}); send({jsonrpc='2.0',method='notifications/prompts/list_changed'})
+ end
+ else err(-32601,'not implemented') end
+ end)
+ pipe:read_start(function(e,data) assert(not e,e); if data then assert(feed(data)) else close(pipe) end end)
+ uv.run(); return
+end
+
+local checks=0
+local function check(v,label) assert(v,label); checks=checks+1 end
+local function eq(a,b,label) check(a==b,(label or '') .. ': ' .. tostring(a) .. ' ~= ' .. tostring(b)) end
+local config=require('panto_mcp.config')
+local cache=require('panto_mcp.cache')
+local validate=require('panto_mcp.validate')
+local results=require('panto_mcp.results')
+local stdio=require('panto_mcp.stdio')
+local Rpc=require('panto_mcp.jsonrpc')
+local Manager=require('panto_mcp.manager')
+local search=require('panto_mcp.search')
+local prompts=require('panto_mcp.prompts')
+local namespace=require('panto_mcp.namespace')
+check(require('panto_mcp.docs').discovery:find('Search is the default',1,true),'docs describe search as default')
+local manifest_environment={}
+assert(loadfile(here .. '/panto-mcp-0.1.0-1.rockspec','t',manifest_environment))()
+local module_scan=assert(uv.fs_scandir(here .. '/panto_mcp'))
+while true do
+ local file=uv.fs_scandir_next(module_scan); if not file then break end
+ local stem=file:match('^(.*)%.lua$')
+ if stem then check(manifest_environment.build.modules['panto_mcp.' .. stem]=='panto_mcp/' .. file,'rock manifest: ' .. file) end
+end
+local temp=assert(uv.fs_mkdtemp('/tmp/panto-mcp-check-XXXXXX'))
+local function timers()
+ local ts={}
+ local function factory(ms,fn)
+ local t={ms=ms,fn=fn,closed=false}
+ function t:is_closing() return self.closed end
+ function t:close() self.closed=true end
+ function t:fire() if not self.closed then self:close(); self.fn() end end
+ ts[#ts+1]=t; return t
+ end
+ return ts,factory
+end
+local function fake_transport()
+ local t={sent={},cancels={}}
+ function t:set_callbacks(message,err) self.message=message; self.error=err end
+ function t:send(msg,opts) self.sent[#self.sent+1]={msg=msg,opts=opts}; return {} end
+ function t:cancel(id) self.cancels[#self.cancels+1]=id end
+ function t:close() self.closed=true end
+ return t
+end
+-- Config trust boundary, canonical identity and stable future eager names.
+local settings,servers,warnings=config.parse({servers={fs={command='echo',args={'${env:ABSENT}','${project_root}'},env={X='${env:TOKEN}'},cwd='sub'},bad={command='x',url='https://x'},['bad.name']={command='x'},['bad__name']={command='x'},['tail_']={command='x'},off={enabled=false}}},{project_root='/project'},function(k) if k=='TOKEN' then return 'secret' end end)
+eq(servers.fs.args[1],'','missing env'); eq(servers.fs.args[2],'/project'); eq(servers.fs.cwd,'/project/sub'); eq(#warnings,4)
+check(not servers.off and not servers.bad and not servers.bad__name and not servers.tail_,'invalid/disabled skipped')
+check(not config.valid_name('a__b') and not config.valid_name('ends_'),'wire-ambiguous server names rejected')
+do
+ local _,remote_servers=config.parse({servers={cloud={url='https://api.example/mcp',auth='mcp.cloud',headers={['X-Tenant']='${env:TENANT}'}}}},{project_root='/project'},function(k) if k=='TENANT' then return 'tenant-a' end end)
+ eq(remote_servers.cloud.transport,'http'); eq(remote_servers.cloud.url,'https://api.example/mcp')
+ eq(remote_servers.cloud.auth,'mcp.cloud'); eq(remote_servers.cloud.headers['X-Tenant'],'tenant-a')
+ local _,safe_server,header_warnings=config.parse({servers={remote={url='https://api.example',auth='mcp',headers={
+ Host='h',Connection='c',['Content-Length']='1',['Transfer-Encoding']='chunked',Expect='100-continue',Upgrade='websocket',
+ TE='trailers',['Keep-Alive']='x',['Proxy-Connection']='x',Authorization='Bearer SECRET',
+ ['Bad Header']='x',['X-Empty']='${env:EMPTY}',['X-Good']='fine'}}}},{project_root='/project'},function() end)
+ eq(#header_warnings,12,'unsafe HTTP headers warn at parse time'); eq(safe_server.remote.headers['X-Good'],'fine')
+ for _,header in ipairs({'Host','Connection','Content-Length','Transfer-Encoding','Expect','Upgrade','TE','Keep-Alive','Proxy-Connection','Authorization','Bad Header','X-Empty'}) do
+ eq(safe_server.remote.headers[header],nil,'forbidden header omitted: '..header)
+ end
+ check(not table.concat(header_warnings,' '):find('SECRET',1,true),'header warnings do not reveal values')
+ local _,http_servers,http_warnings=config.parse({servers={
+ insecure={url='http://example.test/mcp',headers={Cookie='SECRET',['X-API-Key']='APISECRET'}},
+ secret={url='http://api.example/mcp',auth='mcp.secret'},
+ loopback={url='http://127.0.0.1:9000/mcp',auth='mcp.local',headers={Cookie='local'}}
+ }},{project_root='/project'})
+ eq(#http_warnings,3,'plain non-loopback credentials warn early'); check(not http_servers.secret,'unsafe named auth server skipped')
+ eq(next(http_servers.insecure.headers),nil,'sensitive non-loopback headers omitted')
+ eq(http_servers.loopback.headers.Cookie,'local','loopback sensitive header allowed')
+ check(not table.concat(http_warnings,' '):find('APISECRET',1,true),'credential warnings redact values')
+ local long_idle,_,warnings_idle=config.parse({idle_timeout_ms=120001,servers={}},{project_root='/project'})
+ eq(long_idle.idle_timeout_ms,120001); eq(#warnings_idle,0,'Lua-owned idle timeout has no core cap')
+end
+eq(config.hash('hello'),'4f9f2cab','FNV-1a vector')
+eq(config.canonical({b=2,a=1}),config.canonical({a=1,b=2}),'canonical order')
+check(config.fingerprint(servers.fs)~=config.fingerprint({command='changed'}),'identity changes')
+eq(cache.directory(function(k) if k=='XDG_DATA_HOME' then return '' elseif k=='HOME' then return '/h' end end),'/h/.local/share/panto-mcp')
+local _,eager_servers,eager_warnings=config.parse({servers={fast={command='echo',expose='eager'}}},{project_root='/project'})
+eq(eager_servers.fast.expose,'eager','eager setting preserved until core capability check'); eq(#eager_warnings,0,'eager does not warn before activation')
+check(config.tool_name('fs','a.b')~=config.tool_name('fs','a_b'),'sanitizer collisions')
+local sanitized_candidate=config.tool_name('fs','a.b')
+local crafted_collision=sanitized_candidate:sub(#'mcp.fs.'+1)
+check(config.tool_name('fs',crafted_collision)~=sanitized_candidate,'own-name suffix avoids crafted sanitizer collision')
+local stable_name=config.tool_name('fs','stable.tool')
+config.tool_name('fs','a new tool')
+eq(config.tool_name('fs','stable.tool'),stable_name,'adding a catalog name cannot rename an eager tool')
+for _,c in ipairs({
+ {'a.b','mcp.fs.a_b-'}, {'a__b','mcp.fs.a_b-'},
+}) do check(config.tool_name('fs',c[1]):find(c[2],1,true),'sanitized wire name '..c[1]) end
+local long_a=config.tool_name('fs',string.rep('x',300)); local long_b=config.tool_name('fs',string.rep('y',300))
+eq(#(long_a:gsub('%.','__'))<=64,true,'wire length')
+check(long_a~=long_b,'hash-suffixed truncation distinguishes long names')
+local long_server_a=config.tool_name(string.rep('s',40)..'a','tool'); local long_server_b=config.tool_name(string.rep('s',40)..'b','tool')
+check(long_server_a~=long_server_b,'long server names are disambiguated')
+eq(config.tool_name('github','create_issue'),'mcp.github.create_issue','unchanged eager name has no suffix')
+eq(config.tool_name(string.rep('s',32),'create_issue'),'mcp.'..string.rep('s',32)..'.create_issue','32-byte server leaves normal tool name intact')
+do
+ local names={'list','_x','x_','__','a.b','é','',string.rep('z',200),'a b','a/b','a__b','_','-','---___'}
+ local seed=1
+ local function random(n) seed=(seed*1664525+1013904223)&0xffffffff; return (seed%n)+1 end
+ for _=1,3000 do local out={}; for _=1,random(90) do out[#out+1]=string.char(31+random(95)) end; names[#names+1]=table.concat(out) end
+ local seen={}; local valid=true
+ for _,server in ipairs({'a','gh','a-b','x_y',string.rep('s',32),string.rep('t',33),string.rep('u_',40)..'u','s-_-'} ) do
+ for _,name in ipairs(names) do
+ local wire=config.tool_name(server,name):gsub('%.','__'); local parts={}; local cursor=1
+ while true do local at=wire:find('__',cursor,true); if not at then parts[#parts+1]=wire:sub(cursor); break end
+ parts[#parts+1]=wire:sub(cursor,at-1); cursor=at+2 end
+ local identity=server..'\0'..name
+ if #wire>64 or #parts~=3 or parts[1]~='mcp' or not wire:match('^[A-Za-z0-9_-]+$') or (seen[wire] and seen[wire]~=identity) then valid=false end
+ seen[wire]=identity
+ end
+ end
+ check(valid,'names_probe regression: 3000 random names x 8 servers decode without collisions within wire limits')
+end
+check(config.tool_enabled({enabled_tools={'read*'},disabled_tools={'*secret*'}},'read_file'),'enabled glob')
+check(not config.tool_enabled({enabled_tools={},disabled_tools={'delete_*'}},'delete_a'),'disabled glob')
+-- Validator table: false/null, deep equality, combinators, refs, prefix items,
+-- JSON-pointer paths, Unicode lengths and multiple independent diagnostics.
+for i,c in ipairs({
+ {false,{type='boolean'},true}, {json.null,{type='null'},true}, {json.null,{type='object'},false},
+ {{},{type='object'},true}, {json.array({}),{type='array'},true}, {json.array({}),{type='object'},false}, {{1,2},{type='object'},false},
+ {{a=1},{enum={{a=1}}},true}, {{a=1},{const={a=2}},false},
+ {2,{anyOf={{type='string'},{type='integer'}}},true}, {2,{oneOf={{type='number'},{type='integer'}}},true},
+ {2,{allOf={{minimum=1},{maximum=1}}},false}, {2,{['not']={const=2}},true},
+ {{x=1},{patternProperties={['^x']={type='number'}},additionalProperties=false},true},
+ {{x=3},{type='object',properties={x={['$ref']='#/$defs/n'}},['$defs']={n={minimum=4}}},false},
+ {'x',{['$ref']='#/$defs/tuple/0',['$defs']={tuple={{type='integer'}}}},false},
+ {2,{['$ref']='#/$defs/',['$defs']={['']={const=1}}},false},
+ {{'x',3},{prefixItems={{type='string'}},items={minimum=2}},true},
+ {{'x',1},{prefixItems={{type='string'}},items=false},false},
+ {1,{exclusiveMinimum=1},false}, {0.3,{multipleOf=0.1},true},
+ {'é',{maxLength=1},true}, {'x',{pattern='never',format='unknown'},true},
+ {{a=1},{additionalProperties=false},false}, {{1,1},{uniqueItems=true},false},
+ {{},{minItems=1},false}, {{},{required={'x'}},false},
+}) do local ok=validate.check(c[1],c[2]); eq(ok,c[3],'validator case ' .. i) end
+local valid,errors=validate.check({['a/b']=1,z=false},{properties={['a/b']={type='string'},z={type='integer'}}})
+check(not valid and #errors==2 and table.concat(errors,' '):find('/a~1b',1,true),'multiple pointer errors')
+-- Prompt arguments are parsed synchronously; quoted values and a single
+-- positional remainder are covered table-first rather than via the TUI.
+local one_arg={arguments={{name='text',required=true}}}
+local named_prompt={arguments={{name='person',required=true},{name='tone'}}}
+for _,case in ipairs({
+ {one_arg,'two words "quoted phrase"',{text='two words "quoted phrase"'}},
+ {one_arg,'hello world',{text='hello world'}},
+ {one_arg,"Don't",{text="Don't"}},
+ {one_arg,'text="Ada Lovelace"',{text='Ada Lovelace'}},
+ {one_arg,'other=literal',{text='other=literal'}},
+ {one_arg,'back\\slash',{text='back\\slash'}},
+ {named_prompt,'person="Ada Lovelace" tone=\'calm voice\'',{person='Ada Lovelace',tone='calm voice'}},
+ {named_prompt,'person=Ada\\ Lovelace',{person='Ada Lovelace'}},
+}) do
+ local value,why=prompts.parse_arguments(case[1],case[2]); check(value,tostring(why)..' input='..case[2])
+ for key,expected in pairs(case[3]) do eq(value[key],expected,'prompt argument '..key) end
+end
+for _,case in ipairs({
+ {named_prompt,'','missing required arguments: person'},
+ {named_prompt,'person="open','unclosed quote'},
+ {named_prompt,'other=x','unknown prompt argument: other'},
+ {named_prompt,'person=x person=y','duplicate prompt argument: person'},
+}) do local value,why=prompts.parse_arguments(case[1],case[2]); check(not value and why:find(case[3],1,true),'prompt parse error '..case[3]) end
+local prompt_messages={
+ {role='user',content={type='text',text='before'}},
+ {role='assistant',content={{type='text',text='answer'},{type='image',data='aGk=',mimeType='image/png'}}},
+ {role='user',content={type='text',text='last'}}
+}
+local mapped_prompt=assert(prompts.map_messages(prompt_messages))
+eq(mapped_prompt[1].role,'user'); eq(mapped_prompt[2].role,'assistant')
+check(mapped_prompt[2].blocks[2].text:find('Assistant media omitted',1,true),'assistant media becomes placeholder')
+local conv_log={}; local conversation={}
+function conversation:add_user_blocks(blocks) conv_log[#conv_log+1]={role='user',blocks=blocks} end
+function conversation:add_assistant_message(message) conv_log[#conv_log+1]={role='assistant',blocks=message.blocks} end
+local media_prompt=assert(prompts.map_messages({{role='user',content={{type='resource',resource={uri='file://x',blob='JVBERi0=',mimeType='application/pdf'}},{type='image',data='aGk=',mimeType='image/png'}}}}))
+eq(media_prompt[1].blocks[1].type,'text','non-image resource blob becomes a placeholder')
+eq(media_prompt[1].blocks[2].type,'media','image/* content remains media')
+local unsupported=assert(prompts.map_messages({{role='user',content={type='image',data='aGk=',mimeType='image/svg+xml'}}}))
+eq(unsupported[1].blocks[1].type,'text','unsupported image subtype becomes a placeholder')
+local submitted; local agent={}
+function agent:conversation() return conversation end
+function agent:submit(blocks) submitted=blocks end
+local invalid_prompt={{role='user',content={type='text',text='valid'}},{role='system',content={type='text',text='invalid role'}}}
+local no_append,append_error=prompts.append_to(agent,invalid_prompt)
+check(not no_append and append_error and #conv_log==0,'all prompt messages map before conversation mutation')
+if type(require('panto').conversation)=='function' then
+ local ok,why=prompts.append_to(agent,{{role='user',content={type='image',data='aGk=',mimeType='image/png'}}})
+ check(ok==nil and why=='MCP prompt image could not be decoded' and #conv_log==0,'preflight failure is clean and does not mutate conversation')
+end
+check(prompts.append_to(agent,prompt_messages),'trailing user prompt submits')
+eq(#conv_log,2,'trailing user is not duplicated')
+eq(conv_log[1].role,'user'); eq(conv_log[2].role,'assistant'); eq(submitted[1].text,'last')
+submitted=nil; conv_log={}
+check(not prompts.append_to(agent,{prompt_messages[1],prompt_messages[2]}),'assistant-tail does not submit')
+eq(#conv_log,2,'assistant-tail appends all roles'); eq(submitted,nil)
+-- Slash callbacks return synchronously; a late async result is discarded if a turn starts meanwhile.
+do
+ local waits={async.future(),async.future(),async.future()}; local request_count=0; local command_spec
+ local turn_state={busy=false}; local conversation_log={}; local sent_blocks; local emitted={}
+ local prompt_agent={}
+ function prompt_agent:conversation()
+ return {
+ add_user_blocks=function(_,blocks) conversation_log[#conversation_log+1]={role='user',blocks=blocks} end,
+ add_assistant_message=function(_,message) conversation_log[#conversation_log+1]={role='assistant',blocks=message.blocks} end,
+ }
+ end
+ function prompt_agent:submit(blocks) sent_blocks=blocks end
+ local saved_module=package.loaded.panto
+ package.loaded.panto={ext={agent=prompt_agent}}
+ local prompt_manager={}
+ function prompt_manager:prompt() request_count=request_count+1; return waits[request_count]:await() end
+ local command_set=prompts.commands({register_command=function(spec) command_spec=spec; return true end,
+ unregister_command=function() return true end,emit=function(name) emitted[#emitted+1]=name end},prompt_manager,turn_state,true)
+ command_set.reconcile('server',{catalog={prompts={{name='ask',arguments={{name='who',required=true}}}}}},true)
+ check(command_spec,'async prompt command registered')
+ turn_state.busy=true
+ check(command_spec.handler('who=busy'):find('turn is in progress',1,true),'prompt refuses an active turn')
+ eq(request_count,0,'busy prompt does not start network request')
+ turn_state.busy=false
+ check(command_spec.handler('who=first'):find('Fetching',1,true),'prompt callback returns immediately')
+ eq(request_count,1)
+ waits[1]:resolve({{role='assistant',content={type='text',text='prior'}},{role='user',content={type='text',text='question'}}})
+ eq(conversation_log[1].role,'assistant','async prompt preserves assistant role')
+ eq(sent_blocks[1].text,'question','async prompt submits trailing user blocks')
+ local before=#conversation_log; turn_state.busy=false
+ command_spec.handler('who=late'); eq(request_count,2)
+ turn_state.busy=true
+ waits[2]:resolve({{role='user',content={type='text',text='discard'}}})
+ eq(#conversation_log,before,'result arriving during a new turn is discarded')
+ eq(sent_blocks[1].text,'question','discarded prompt does not submit')
+ turn_state.busy=false
+ command_spec.handler('who=tail')
+ waits[3]:resolve({{role='assistant',content={type='text',text='assistant tail'}}})
+ eq(emitted[1],'agent_submission','assistant-tail prompt wakes TUI conversation sync')
+ eq(sent_blocks[1].text,'question','assistant-tail prompt does not submit a turn')
+ package.loaded.panto=saved_module
+end
+do
+ local callbacks={}; local busy_state={busy=false}
+ prompts.track_busy({on=function(name,fn) callbacks[name]=fn end},busy_state,{registered={['mcp:server:ask']=true}})
+ callbacks.command_start({command_name='mcp:server:ask'}); eq(busy_state.busy,false,'prompt command itself does not block its callback')
+ callbacks.command_end({command_name='mcp:server:ask'})
+ callbacks.command_start({command_name='compact'}); check(busy_state.busy,'command_start marks /compact busy')
+ callbacks.turn_start({}); callbacks.command_end({command_name='compact'})
+ check(busy_state.busy,'command_end cannot clear active turn state')
+ callbacks.turn_end({}); eq(busy_state.busy,false,'turn_end clears busy after compact')
+end
+do
+ local registrations,removed,warnings,event_hooks={}, {}, {}, {}
+ local mount_component,mount_handle
+ local ext={
+ register_command=function(spec) registrations[spec.name]=spec; return true end,
+ unregister_command=function(name) removed[#removed+1]=name; registrations[name]=nil; return true end,
+ on=function(name,fn) event_hooks[name]=fn end,
+ mount=function(component,placement)
+ eq(placement,'above_input','prompt errors mount above input')
+ mount_component=component; mount_handle={live=true}
+ function mount_handle:alive() return self.live end
+ function mount_handle:invalidate() self.invalidated=true end
+ function mount_handle:unmount() self.live=false end
+ return mount_handle
+ end,
+ }
+ local failure=async.future(); local prompt_manager={}
+ function prompt_manager:prompt() return failure:await() end
+ local commands=prompts.commands(ext,prompt_manager,{busy=false},true,warnings)
+ commands.reconcile('a',{catalog={prompts={{name='pa'}}}},true)
+ commands.reconcile('b',{catalog={prompts={{name='pb'},{name='bad/name'},{name='bad name'}}}},true)
+ commands.reconcile('a',{catalog={prompts={{name='pa'}}}},false)
+ check(registrations['mcp:a:pa'] and registrations['mcp:b:pb'],'reconciling one server preserves other-server prompt commands')
+ check(not registrations['mcp:b:bad/name'] and not registrations['mcp:b:bad name'],'core-invalid prompt command names skipped')
+ local warning_status=require('panto_mcp.tools').status({servers=function() return {} end},warnings)
+ check(warning_status:find('prompt command skipped',1,true),'invalid prompt names appear in /mcp warnings')
+ check(registrations['mcp:b:pb'].handler(''):find('Fetching',1,true),'prompt failure command returns immediately')
+ failure:resolve(nil,'server unavailable')
+ check(mount_handle and mount_handle:alive() and mount_component.render():find('server unavailable',1,true),'async prompt failure is visible above input')
+ event_hooks.command_start({command_name='next'})
+ check(not mount_handle:alive(),'prompt error mount clears at next command_start')
+ registrations['mcp:b:pb'].handler(''); event_hooks.turn_start({})
+ check(not mount_handle:alive(),'prompt error mount clears on a normal turn')
+end
+-- NDJSON chunks/CRLF and malformed/oversized lines.
+local bad_lines={}; local frames={}; local feed=stdio.framer(function(m) frames[#frames+1]=m end,nil,function(line) bad_lines[#bad_lines+1]=line end)
+check(feed('{"jsonrpc":"2.0",'),'partial frame'); check(feed('"id":1,"result":{}}\r\n\n{"id":2}\n'),'CRLF frame')
+eq(#frames,2); eq(frames[1].id,1)
+check(not stdio.framer(function() end,4)('12345'),'frame cap')
+check(feed('not json\n{"id":3}\n'),'bad stdout line does not stop transport'); eq(#bad_lines,1); eq(#frames,3)
+do
+-- OAuth policy checks use injected auth, HTTP and timers; no credentials or wall-clock sleeps.
+do
+ local OAuth=require('panto_mcp.oauth')
+ local sha256=require('panto_mcp.hash').sha256
+ for _,case in ipairs({
+ {'','e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'},
+ {'abc','ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'},
+ {'abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq','248d6a61d20638b8e5c026930c3e6039a33ce45964ff2167f6ecedd419db06c1'},
+ }) do eq(sha256(case[1]),case[2],'SHA-256 known vector') end
+ for _,case in ipairs({
+ {'Bearer scope="read write", resource_metadata="https://r.example/meta"','read write','https://r.example/meta'},
+ {'Basic realm="a,b", Bearer scope="read", error="insufficient_scope"','read',nil,'insufficient_scope'},
+ {'Digest realm="x", nonce="a\\\"b,c", Bearer resource_metadata="https://r.example/a,b", scope="r\\ead"','read','https://r.example/a,b'},
+ {'Bearer scope="first", Basic realm="x", Bearer resource_metadata="https://r.example/m", scope="second"','second','https://r.example/m'},
+ {'Bearer scope="unterminated',nil},
+ {'Bearer scope="one", scope="two"',nil},
+ {'Basic realm="private"',nil},
+ }) do
+ local c=OAuth.challenge(case[1]); eq(c.scope,case[2],'challenge scope'); eq(c.resource_metadata,case[3],'challenge PRM'); eq(c.error,case[4],'challenge error')
+ end
+ for _,case in ipairs({
+ {'https://API.example/mcp','https://api.example/.well-known/oauth-protected-resource/mcp,https://api.example/.well-known/oauth-protected-resource'},
+ {'https://api.example/','https://api.example/.well-known/oauth-protected-resource'},
+ {'https://api.example/a/b?tenant=x','https://api.example/.well-known/oauth-protected-resource/a/b,https://api.example/.well-known/oauth-protected-resource'},
+ }) do eq(table.concat(OAuth.prm_urls(case[1]),','),case[2],'PRM URL order') end
+ for _,case in ipairs({
+ {'https://as.example','https://as.example/.well-known/oauth-authorization-server,https://as.example/.well-known/openid-configuration'},
+ {'https://as.example/tenant','https://as.example/.well-known/oauth-authorization-server/tenant,https://as.example/.well-known/openid-configuration/tenant,https://as.example/tenant/.well-known/openid-configuration'},
+ }) do eq(table.concat(OAuth.metadata_urls(case[1]),','),case[2],'AS URL order') end
+ for _,url in ipairs({'http://evil.example','https://u:p@as.example','https://as.example/#x','https://as.example\\@evil.test','https://127.0.0.1:99999'}) do eq(OAuth.url(url),nil,'unsafe OAuth URL rejected') end
+ eq(OAuth.url('HTTPS://API.example:443/mcp'),'https://api.example/mcp','canonical resource')
+ eq(table.concat(OAuth.union({'read','read'},{'write','read'}),' '),'read write','scope union')
+ eq(#OAuth.scopes({'bad scope','quote"','back\\slash','read'}),1,'invalid scope tokens omitted')
+ local metadata={issuer='https://as.example/tenant',authorization_endpoint='https://as.example/authorize',token_endpoint='https://as.example/token',code_challenge_methods_supported={'plain','S256'}}
+ for _,case in ipairs({{metadata.issuer,true},{'https://as.example/tenant/',false},{'https://evil.example',false}}) do
+ eq(not not OAuth.validate_metadata(metadata,case[1]),case[2],'exact issuer')
+ end
+ metadata.code_challenge_methods_supported={'plain'}; check(not OAuth.validate_metadata(metadata,metadata.issuer),'reject missing S256')
+ metadata.code_challenge_methods_supported=nil; check(not OAuth.validate_metadata(metadata,metadata.issuer),'reject absent PKCE declaration')
+ local _,configured,config_warnings=config.parse({servers={oauth={url='https://api.example/mcp',oauth={client_id='id',issuer='https://as.example/tenant',client_secret='${env:SECRET}',scopes={'configured'}}}}},{project_root='/project'},function() return 'DO_NOT_LOG' end)
+ eq(configured.oauth.oauth.client_secret,'DO_NOT_LOG','OAuth secret expansion'); eq(#config_warnings,0)
+ local _,missing_issuer,missing_warnings=config.parse({servers={remote={url='https://api.example/mcp',oauth={client_id='id',client_secret='secret'}}}},{project_root='/project'})
+ check(not missing_issuer.remote and missing_warnings[1]:find('oauth.issuer',1,true),'H1 configured client requires an issuer binding')
+ local session=OAuth.session_name(string.rep('s',200),'https://resource.example/mcp','https://issuer.example','id')
+ check(#session<=128,'H2 bounded core session name')
+ for _,identity in ipairs({{'https://other.example/mcp','https://issuer.example','id'},{'https://resource.example/mcp','https://other.example','id'},{'https://resource.example/mcp','https://issuer.example','other'}}) do
+ check(OAuth.session_name(string.rep('s',200),table.unpack(identity))~=session,'H2 resource/issuer/client identity changes token namespace')
+ end
+ eq(session,OAuth.session_name(string.rep('s',200),'https://resource.example/mcp','https://issuer.example','id'),'H2 session name is deterministic')
+ for _,url in ipairs({'http://0127.0.0.1/x','https://127.00.0.1/x','http://127.0.0.01/x','https://127.1/x','https://2130706433/x','https://0x7f000001/x'}) do eq(OAuth.url(url),nil,'ambiguous IPv4 octets rejected') end
+ local status={state='logged_out'}; local specs={}; local logins,refreshes=0,0; local definitions=0
+ local clock=0; local status_reads=0; local refresh_failure=false; local login_failure=false
+ local dcr_count=0; local logouts={}; local prm_servers
+ local issuer='https://as.example/tenant'; local scope_challenge='read write'
+ local fake_auth={
+ define=function(name,spec) definitions=definitions+1; specs[name]=spec; return true end,
+ status=function() status_reads=status_reads+1; return status end,
+ login=function() logins=logins+1; if login_failure then login_failure=false; return nil,'AuthFlowFailed' end; status={state='pending'}; return {url='https://as.example/authorize?state=opaque'} end,
+ logout=function(name) logouts[#logouts+1]=name; return true end,
+ complete=function(_,url) if url=='bad' then return nil,'SECRET' end; status={state='pending'}; return true end,
+ refresh=function() refreshes=refreshes+1; if refresh_failure then status={state='logged_out'}; return nil,type(refresh_failure)=='string' and refresh_failure or 'AuthLoginRequired' end; status={state='pending'}; return true end,
+ }
+ local stored={}; local fake_state={get=function(k) return stored[k] end,set=function(k,v) stored[k]=v; return true end}
+ local sent={}; local protected='normal'; local refresh_once=false
+ local registration_result={client_id='dynamic-public',registration_access_token='DO_NOT_STORE'}
+ local function request_fn(opts,cb)
+ sent[#sent+1]=opts
+ local response={status=200,headers={},body=''}
+ if opts.url=='https://api.example/mcp' then
+ if not opts.auth or protected=='always401' or ((protected=='refresh' or protected=='refresh_scope') and not refresh_once) then
+ if opts.auth then refresh_once=true end
+ response.status=401; response.headers['www-authenticate']='Basic realm="x", Bearer resource_metadata="https://api.example/meta", scope="read"'
+ response.body='DO_NOT_LOG_ACCESS_TOKEN'
+ elseif protected=='bad_body' then
+ response.status=500; response.body='DO_NOT_LOG_ACCESS_TOKEN'
+ elseif protected=='bad_rpc' then
+ response.status=500; local req=json.decode(opts.body)
+ response.body=json.encode({jsonrpc='2.0',id=req.id,error={code=-32000,message='DO_NOT_LOG_ACCESS_TOKEN'}})
+ elseif (protected=='scope' or protected=='refresh_scope') and json.decode(opts.body).params.arguments and json.decode(opts.body).params.arguments.restricted then
+ response.status=403; response.headers['www-authenticate']='Bearer error="insufficient_scope", scope="'..scope_challenge..'"'
+ else
+ local req=json.decode(opts.body)
+ local result=req.method=='server/discover' and {capabilities={tools={}},resultType='complete'} or
+ req.method=='tools/list' and {tools={{name='echo',inputSchema={type='object'}}}} or {content={{type='text',text='oauth success'}}}
+ response.body=json.encode({jsonrpc='2.0',id=req.id,result=result})
+ end
+ elseif opts.url=='https://api.example/meta' then
+ check(not opts.auth and not opts.headers.Authorization,'discovery never carries credentials')
+ response.body=json.encode({resource='https://api.example/mcp',authorization_servers=prm_servers or {issuer},scopes_supported={'fallback'}})
+ elseif opts.url==OAuth.metadata_urls(issuer)[1] then
+ local origin=issuer:match('^(https://[^/]+)')
+ response.body=json.encode({issuer=issuer,authorization_endpoint=origin..'/authorize',token_endpoint=origin..'/token',
+ registration_endpoint=origin..'/register',code_challenge_methods_supported={'S256'},authorization_response_iss_parameter_supported=true})
+ elseif opts.url==issuer:match('^(https://[^/]+)')..'/register' then
+ dcr_count=dcr_count+1; registration_result.client_id='dynamic-public-'..dcr_count
+ local body=json.decode(opts.body)
+ eq(body.application_type,'native'); eq(body.redirect_uris[1],'http://127.0.0.1/callback'); eq(body.token_endpoint_auth_method,'none')
+ eq(table.concat(body.grant_types,','),'authorization_code,refresh_token')
+ response.body=json.encode(registration_result)
+ else error('unexpected fake OAuth request') end
+ cb(response); return {cancel=function() end}
+ end
+ local ts,tf=timers()
+ local _,cfgs=config.parse({servers={remote={url='https://api.example/mcp'}}},{project_root='/project'})
+ local manager=Manager.new(settings,cfgs,{cache_dir=temp..'/oauth-cache',request_fn=request_fn,auth=fake_auth,state=fake_state,timer_factory=tf,clock=function() return clock end})
+ local s=manager.states.remote; local oauth=s.oauth
+ manager:start(s)
+ eq(s.state,'failed','401 discovers then stops for user login'); check(s.error:find('/mcp-login remote',1,true),'login-required error: '..tostring(s.error))
+ eq(logins,0,'never starts login automatically'); eq(#sent,4,'401 PRM AS DCR sequence'); eq(definitions,1)
+ check(oauth:blocked(),'logged-out scoped session requires login')
+ local not_authorized=OAuth.new(cfgs.remote,{auth=fake_auth,state=fake_state,request_fn=request_fn,timer_factory=tf})
+ check(not_authorized:blocked() and not not_authorized:request_auth(),'warm definition still checks core status'); not_authorized:close()
+ eq(specs[oauth.name].resource,'https://api.example/mcp'); eq(specs[oauth.name].scopes[1],'read','challenge overrides PRM')
+ check(specs[oauth.name].require_iss,'require issuer in callback when advertised')
+ check(not json.encode(stored):find('DO_NOT_STORE',1,true),'DCR registration tokens never persisted')
+ local initial_name=oauth.name
+ local command=manager:login('remote'); eq(dcr_count,1,'first login does not repeat initial DCR'); eq(oauth.name,initial_name,'first login retains token namespace')
+ check(command:find('https://as.example/authorize',1,true),'login prints URL'); check(command:find('<callback-url>',1,true),'headless instructions')
+ local function tick() local t=ts[#ts]; check(t and not t.closed,'poll timer armed'); clock=clock+t.ms; t:fire() end
+ status={state='logged_in'}; tick()
+ eq(s.state,'ready','login completion reconnects'); eq(logins,1)
+ local output; async.run(function() output=manager:call('remote','echo',{}) end,error)
+ check(output and not output.is_error and output.text:find('oauth success',1,true),'authenticated tool success')
+ for _,mode in ipairs({'bad_body','bad_rpc'}) do
+ protected=mode; async.run(function() output=manager:call('remote','echo',{}) end,error)
+ check(output.is_error and not output.text:find('DO_NOT_LOG',1,true),'authenticated HTTP errors discard reflected credentials')
+ end
+ protected='normal'
+ local before=#sent
+ local warm=OAuth.new(cfgs.remote,{auth=fake_auth,state=fake_state,request_fn=request_fn,timer_factory=tf})
+ eq(#sent,before,'warm activation does not rediscover'); check(warm.definition,'warm definition restored')
+ protected='refresh'; output=nil
+ async.run(function() output=manager:call('remote','echo',{}) end,error)
+ eq(refreshes,1,'401 forces one refresh'); check(not output,'refresh waits asynchronously')
+ local parallel; local before_parallel=#sent
+ async.run(function() parallel=manager:call('remote','echo',{}) end,error)
+ check(not parallel,'M4 parallel calls wait for forced refresh'); eq(#sent,before_parallel,'no unauthenticated call while refresh pending')
+ eq(oauth:request_auth(),oauth.name,'M4 refresh-pending retains auth name')
+ status={state='logged_in'}; tick(); check(output and not output.is_error,'refresh retries successfully')
+ check(parallel and not parallel.is_error,'M4 parallel call succeeds after refresh')
+ protected='always401'; output=nil
+ async.run(function() output=manager:call('remote','echo',{}) end,error)
+ status={state='logged_in'}; tick()
+ check(output.is_error and output.text:find('/mcp-login remote',1,true),'second 401 requires login'); eq(refreshes,2,'never refreshes twice per request')
+ check(not output.text:find('DO_NOT_LOG',1,true),'401 body never reaches tool errors')
+ eq(manager:login('remote','bad'),'OAuth callback rejected; check the URL/state/issuer and retry','callback rejection hides core detail')
+ protected='normal'; manager:login('remote','callback'); status={state='logged_in'}; tick()
+ protected='refresh_scope'; refresh_once=false; output=nil; async.run(function() output=manager:call('remote','echo',{restricted=true}) end,error)
+ status={state='logged_in'}; tick()
+ check(output.is_error and output.text:find('/mcp-login remote',1,true),'scope step-up after refresh asks for consent')
+ eq(table.concat(oauth.spec.scopes,' '),'read write','scope step-up unions scopes')
+ check(not oauth.login_required,'M3 scope step-up does not lock out the server')
+ local stepped=OAuth.new(cfgs.remote,{auth=fake_auth,state=fake_state,request_fn=request_fn,timer_factory=tf})
+ check(not stepped:blocked() and stepped:request_auth(),'M3 warm scope upgrade preserves usable token'); stepped:close()
+ local requests_before=#sent; async.run(function() output=manager:call('remote','echo',{}) end,error)
+ check(#sent>requests_before and not output.is_error,'M3 unrelated tool still works after a scope challenge')
+ scope_challenge='read'; status={state='logged_in',scopes={'read'}}; clock=clock+1000
+ async.run(function() output=manager:call('remote','echo',{restricted=true}) end,error)
+ check(output.is_error and not oauth.login_required,'M3 already-held scope is a per-tool permission failure, not a server lockout')
+ async.run(function() output=manager:call('remote','echo',{}) end,error)
+ check(not output.is_error,'M3 unrelated tool works after already-held scope challenge')
+ local logins_before=logins
+ for i=1,5 do
+ local ok,err=oauth:recover({http_status=403,challenge={error='insufficient_scope',scope='extra'..i}})
+ check(not ok and err:find('/mcp-login',1,true),'scope upgrades require user action, not an artificial counter')
+ end
+ eq(logins,logins_before,'scope challenges never start login automatically')
+ protected='refresh'; refresh_once=false; refresh_failure='AuthFlowFailed'; status={state='logged_in'}
+ local discovery_before=#sent
+ async.run(function() output=manager:call('remote','echo',{}) end,error)
+ check(output.is_error and #sent>discovery_before+1 and oauth.definition,'M6 refresh failure rediscovered metadata and registration')
+ eq(dcr_count,1,'transient refresh failure keeps DCR registration'); eq(oauth.name,initial_name,'transient failure retains token namespace')
+ check(output.text:find('--reregister',1,true),'failed refresh explains registration escape hatch')
+ refresh_failure=false; protected='normal'; issuer='https://as2.example/tenant'; local old_name=oauth.name; login_failure=true
+ local refreshed_login=manager:login('remote')
+ check(refreshed_login:find('https://as.example/authorize',1,true),'M6 manual login starts after rediscovery')
+ eq(oauth.spec.issuer,issuer,'M6 manual login observes changed issuer'); check(oauth.name~=old_name,'H2 changed issuer selects a different token file')
+ eq(logouts[#logouts],old_name,'issuer/name change logs out previous session')
+ status={state='logged_in'}; tick(); eq(s.state,'ready','rediscovered login reconnects')
+ local count=dcr_count; local stable=oauth.name; local requests=#sent
+ manager:login('remote')
+ eq(dcr_count,count,'repeat consent login keeps DCR registration'); eq(oauth.name,stable,'repeat consent retains session name'); eq(#sent,requests,'usable definition avoids rediscovery')
+ check(not oauth:blocked() and not oauth.login_required,'consent login does not block an existing usable token')
+ async.run(function() output=manager:call('remote','echo',{}) end,error)
+ check(not output.is_error,'working tools remain usable during consent')
+ for _=1,670 do
+ local t; for i=#ts,1,-1 do if not ts[i].closed then t=ts[i]; break end end
+ assert(t,'login poll must remain active until give-up'); clock=clock+t.ms; t:fire()
+ end
+ check(not oauth.login_required and not oauth:blocked(),'abandoned consent poll clears lockout and retains usable token')
+ check(s.error:find('--reregister',1,true),'failed login poll explains escape hatch')
+ status={state='logged_in'}; clock=clock+1000
+ async.run(function() output=manager:call('remote','echo',{}) end,error); check(not output.is_error,'working tools survive abandoned consent')
+ manager:login('remote',nil,true)
+ eq(dcr_count,count+1,'explicit --reregister performs exactly one DCR'); check(oauth.name~=stable,'explicit reregistration selects new client namespace')
+ eq(logouts[#logouts],stable,'explicit reregistration logs out old namespace')
+ status={state='logged_in'}; tick()
+ manager:close(); warm:close()
+ for _,case in ipairs({{method='none',secret='IGNORE_PUBLIC_SECRET'},{method='client_secret_basic',secret='CONFIDENTIAL_DCR_SECRET'}}) do
+ local key='mcp.oauth.registration_'..config.hash(issuer); stored[key]=nil
+ registration_result={client_id='registered-'..case.method,client_secret=case.secret,token_endpoint_auth_method=case.method}
+ local instance=OAuth.new({name='client_'..case.method,url=cfgs.remote.url,fingerprint=case.method},
+ {auth=fake_auth,state=fake_state,request_fn=request_fn,timer_factory=tf})
+ local ok,why=instance:discover({resource_metadata='https://api.example/meta'})
+ check(not ok and why:find('Confidential DCR',1,true),'M5 refuse any DCR secret, including public-method responses')
+ check(not instance.spec and not stored[key],'M5 confidential DCR is never defined or persisted')
+ check(not why:find(case.secret,1,true) and not json.encode(stored):find(case.secret,1,true),'M5 secret absent from state/errors')
+ instance:close()
+ end
+ local old=OAuth.new(cfgs.remote,{auth={},state=fake_state,request_fn=request_fn,timer_factory=tf})
+ local _,old_error=old:recover({http_status=401}); check(old_error:find('newer panto',1,true),'old core OAuth clear error')
+ local override=OAuth.new({name='remote',url='https://api.example/mcp',auth='custom'},{auth=fake_auth,state=fake_state})
+ eq(override:request_auth(),'custom','explicit auth takes precedence'); check(not override.definition,'explicit auth disables automatic definition')
+ for _,auth in ipairs({{}, {define=function() return true end,status=function() return {state='logged_in'} end,login=function() return nil,'UnsupportedAuthType' end,complete=function() end,refresh=function() return nil,'UnsupportedAuthType' end}}) do
+ local explicit=OAuth.new({name='explicit',auth='api-key',url=cfgs.remote.url},{auth=auth,state=fake_state})
+ local _,err=explicit:recover({http_status=401,auth_used=true})
+ check(err:find('Configured auth session',1,true) and not err:find('newer panto',1,true) and not err:find('/mcp-login',1,true),'explicit/non-PKCE auth rejection has actionable, accurate error')
+ end
+ local _,permission_error=override:recover({http_status=403,challenge={}})
+ check(permission_error:find('permissions',1,true) and not permission_error:find('/mcp-login',1,true),'unrelated 403 is not a login instruction')
+ local cached=OAuth.new(cfgs.remote,{auth=fake_auth,state=fake_state,clock=function() return clock end})
+ local reads_before=status_reads
+ for _=1,100 do cached:status(); cached:blocked(); cached:request_auth() end
+ eq(status_reads,reads_before+1,'status reads cached across request/status paths')
+ clock=clock+999; cached:status(); eq(status_reads,reads_before+1,'status cache holds for one second')
+ clock=clock+1; cached:status(); eq(status_reads,reads_before+2,'status cache refreshes after one second'); cached:close()
+ local unsafe_requests=0
+ local remote_policy=OAuth.new({name='remote',url='https://resource.example/mcp'},{auth=fake_auth,state=fake_state,request_fn=function() unsafe_requests=unsafe_requests+1 end})
+ for _,url in ipairs({'http://127.0.0.1:6379/','http://[::1]/','https://127.0.0.1/','https://localhost/','https://localhost./','https://[0:0:0:0:0:0:0:1]/','https://[::ffff:7f00:1]/'}) do
+ local value=remote_policy:fetch(url); check(not value,'remote OAuth cannot reach loopback discovery/DCR')
+ end
+ eq(unsafe_requests,0,'unsafe loopback URLs rejected before HTTP')
+ local local_policy=OAuth.new({name='local',url='http://127.0.0.1:9000/mcp'},{auth=fake_auth,state=fake_state})
+ check(local_policy:url_allowed('http://127.0.0.1:9001/meta'),'loopback resource permits loopback OAuth')
+ registration_result={client_id='public'}; prm_servers={'https://unrelated.example',issuer}
+ local pinned=OAuth.new({name='pinned',url=cfgs.remote.url,fingerprint='pin',oauth={issuer=issuer}},
+ {auth=fake_auth,state=fake_state,request_fn=request_fn,timer_factory=tf})
+ check(pinned:discover({resource_metadata='https://api.example/meta'}),'issuer-only pin selects the advertised second issuer')
+ eq(pinned.spec.issuer,issuer,'DCR uses the configured issuer without a client ID')
+ local definitions_before=definitions
+ pinned.cfg.oauth.issuer='https://other.example'
+ check(not pinned:define(pinned.definition) and definitions==definitions_before,'warm definition enforces issuer-only pin'); pinned:close()
+ prm_servers=nil
+ -- Discovery fallbacks fail closed on a mismatched resource/issuer, not on unavailable URLs.
+ for _,case in ipairs({
+ {name='fallback',scope='prm',requests=5},
+ {name='configured',scope='configured',requests=5,no_prm_scopes=true},
+ {name='bad_resource',error='resource mismatch',requests=2},
+ {name='bad_issuer',error='issuer mismatch',requests=5},
+ {name='bad_pkce',error='S256',requests=5},
+ {name='foreign_issuer',error='oauth.issuer',requests=2},
+ }) do
+ local calls={}; local saved={}; local spec
+ local auth={define=function(_,value) spec=value; return true end,status=function() return {state='logged_out'} end,
+ login=fake_auth.login,complete=fake_auth.complete,refresh=fake_auth.refresh}
+ local state={get=function(key) return saved[key] end,set=function(key,value) saved[key]=value; return true end}
+ local cfg={name=case.name,url='https://resource.example/mcp',fingerprint=case.name,oauth={client_id='configured-id',issuer='https://issuer.example/tenant',client_secret='CONFIG_SECRET',scopes={'configured'}}}
+ local function request(options,callback)
+ calls[#calls+1]=options.url
+ local value
+ if options.url=='https://resource.example/.well-known/oauth-protected-resource' then
+ value={resource=case.name=='bad_resource' and 'https://other.example' or 'https://resource.example',authorization_servers={case.name=='foreign_issuer' and 'https://evil-as.example' or 'https://issuer.example/tenant'},
+ scopes_supported=not case.no_prm_scopes and {'prm'} or nil}
+ elseif options.url=='https://issuer.example/tenant/.well-known/openid-configuration' then
+ value={issuer=case.name=='bad_issuer' and 'https://other.example' or 'https://issuer.example/tenant',
+ authorization_endpoint='https://issuer.example/authorize',token_endpoint='https://issuer.example/token',
+ code_challenge_methods_supported=case.name=='bad_pkce' and {'plain'} or {'S256'}}
+ end
+ callback({status=value and 200 or 404,body=value and json.encode(value) or ''})
+ return {cancel=function() end}
+ end
+ local failed_clock=0
+ local o=OAuth.new(cfg,{auth=auth,state=state,request_fn=request,timer_factory=tf,clock=function() return failed_clock end})
+ local ok,err=o:recover({http_status=401,challenge={}})
+ check(not ok,'discovery never starts user login'); eq(#calls,case.requests,'fallback request count')
+ if case.error then
+ check(err:find(case.error,1,true),'discovery validation fails closed'); check(not spec,'invalid discovery never defines auth')
+ o:recover({http_status=401,challenge={}}); eq(#calls,case.requests,'failed discovery is negatively cached')
+ failed_clock=5000; o:recover({http_status=401,challenge={}})
+ eq(#calls,case.requests*2,'negative discovery cache expires via injected clock')
+ eq(o.retry_at,15000,'failed discovery backoff increases without waiting')
+ else
+ check(err:find('/mcp-login',1,true),'configured discovery requests login')
+ eq(spec.client_id,'configured-id','configured id skips DCR'); eq(spec.client_secret,'CONFIG_SECRET')
+ eq(spec.scopes[1],case.scope,'scope selection fallback')
+ check(not json.encode(saved):find('CONFIG_SECRET',1,true),'configured secrets absent from discovery state')
+ eq(calls[3],'https://issuer.example/.well-known/oauth-authorization-server/tenant','RFC8414 before OIDC')
+ eq(calls[4],'https://issuer.example/.well-known/openid-configuration/tenant','OIDC inserted before appended')
+ end
+ o:close()
+ end
+ -- Poll timeout and teardown settle parked refreshes with injected timers only.
+ local timeout_auth={define=fake_auth.define,status=function() return {state='pending'} end,login=fake_auth.login,complete=fake_auth.complete,
+ refresh=function() return true end}
+ local timeout=OAuth.new(cfgs.remote,{auth=timeout_auth,timer_factory=tf,state=fake_state})
+ local settled,refresh_error
+ async.run(function() settled,refresh_error=timeout:refresh() end,error)
+ for _=1,70 do ts[#ts]:fire() end
+ check(not settled and refresh_error:find('/mcp-login',1,true),'injected refresh deadline settles caller')
+ refresh_error=nil
+ async.run(function() settled,refresh_error=timeout:refresh() end,error)
+ timeout:close()
+ eq(refresh_error,'session ended','teardown settles refresh without blocking')
+end
+-- HTTP transport/parser checks use an injected request API. `panto lua` has
+-- an http_request function, but no usable HTTP service outside an active entry.
+local http=require('panto_mcp.http')
+for i,c in ipairs({
+ {{'data: one\n\n'},{'one'}},
+ {{'data: hel','lo\r','\n\r\n'},{'hello'}},
+ {{': ping\r\nevent: message\r\ndata: first\r\ndata: second\r\n\r\n'},{'first\nsecond'}},
+ {{'event: empty\n\n'},{}},
+ {{'event: ping\ndata: ignored\n\n'},{}},
+ {{'event: message\ndata:\n\n'},{}},
+ {{'\239','\187\191data: bom\n\n'},{'bom'}}
+}) do
+ local got={}; local parser=http.sse_parser(function(v) got[#got+1]=v end)
+ for _,chunk in ipairs(c[1]) do check(parser:feed(chunk),'SSE feed') end
+ check(parser:finish(),'SSE finish'); eq(#got,#c[2],'SSE event count '..i)
+ for j,value in ipairs(c[2]) do eq(got[j],value,'SSE value '..i) end
+end
+local eof_events={}; local eof_parser=http.sse_parser(function(v) eof_events[#eof_events+1]=v end)
+check(eof_parser:feed('data: final'),'SSE partial'); check(eof_parser:finish(),'SSE EOF'); eq(eof_events[1],'final')
+check(eof_parser:feed('data: carriage\r'),'SSE trailing CR'); check(eof_parser:finish(),'SSE CR EOF'); eq(eof_events[2],'carriage')
+local header_cfg={headers={accept='wrong',['MCP-METHOD']='wrong',Authorization='Bearer PRIVATE'}}
+local mh=http.headers(header_cfg,{era='modern',protocol_version='2026-07-28',method='tools/call',name='lookup'})
+eq(mh.Accept,'application/json, text/event-stream'); eq(mh['Content-Type'],'application/json'); eq(mh['MCP-Protocol-Version'],'2026-07-28')
+eq(mh['Mcp-Method'],'tools/call'); eq(mh['Mcp-Name'],'lookup'); eq(mh.Authorization,'Bearer PRIVATE'); eq(mh.accept,nil)
+for _,method in ipairs({'tools/call','resources/read','prompts/get'}) do
+ eq(http.headers({}, {era='modern',method=method,name='item'})['Mcp-Name'],'item','required MCP name header')
+end
+eq(http.headers({}, {era='modern',method='tools/list'})['Mcp-Name'],nil,'name omitted for other methods')
+local ih=http.headers(header_cfg,{era='legacy',initial=true,method='initialize'},'old')
+eq(ih['MCP-Protocol-Version'],nil); eq(ih['Mcp-Session-Id'],nil)
+local lh=http.headers(header_cfg,{era='legacy',protocol_version='2025-06-18'},'sid')
+eq(lh['MCP-Protocol-Version'],'2025-06-18'); eq(lh['Mcp-Session-Id'],'sid')
+do
+ local schema={type='object',properties={region={type={'string','null'},['x-mcp-header']='Region'},nested={type='object',properties={count={type='integer',['x-mcp-header']='Count'},flag={type='boolean',['x-mcp-header']='Flag'},optional={type={'string','null'},['x-mcp-header']='Optional'}}}}}
+ local annotations=assert(http.validate_param_headers(schema)); eq(#annotations,4)
+ local headers=assert(http.headers({}, {era='modern',method='tools/call',name='météo ',param_headers=annotations,
+ arguments={region='us-west1',nested={count=-7,flag=false,optional=json.null}}}))
+ eq(headers['Mcp-Name'],'=?base64?bcOpdMOpbyA=?='); eq(headers['Mcp-Param-Region'],'us-west1')
+ eq(headers['Mcp-Param-Count'],'-7'); eq(headers['Mcp-Param-Flag'],'false'); eq(headers['Mcp-Param-Optional'],nil)
+ for _,c in ipairs({
+ {'plain','plain'}, {'Hello, 世界','=?base64?SGVsbG8sIOS4lueVjA==?='},
+ {' padded ','=?base64?IHBhZGRlZCA=?='}, {'=?base64?literal?=','=?base64?PT9iYXNlNjQ/bGl0ZXJhbD89?='}
+ }) do eq(http.encode_header_value(c[1]),c[2],'MCP header value encoding') end
+ check(http.validate_param_headers({type='object',properties={id={type='string',['x-mcp-header']='Id'}},allOf={{type='object'}}}),
+ 'properties path is static despite unrelated composition')
+ check(http.validate_param_headers({type='object',properties={['x-mcp-header']={type='string'}},enum={{['x-mcp-header']='data'}}}),
+ 'instance data is not misread as schema annotation')
+ check(http.validate_param_headers({type='object',properties={enum={type='string',['x-mcp-header']='Enum'}}}),
+ 'instance-data keyword may also name a property')
+ local bad={
+ {type='string',['x-mcp-header']='Root'},
+ {type='object',properties={x={type='number',['x-mcp-header']='X'}}},
+ {type='object',properties={x={type='string',['x-mcp-header']=''}}},
+ {type='object',properties={x={type='string',['x-mcp-header']='Bad Name'}}},
+ {type='object',properties={x={type='string',['x-mcp-header']='Region'},y={type='string',['x-mcp-header']='region'}}},
+ {type='object',properties={items={type='array',items={type='object',properties={r={type='string',['x-mcp-header']='X'}}}}}},
+ {type='object',oneOf={{type='object',properties={r={type='string',['x-mcp-header']='X'}}}}},
+ {type='object',properties={items={type='array',items={{type='string',['x-mcp-header']='X'}}}}},
+ {type='object',properties={x={anyOf={{type='string',['x-mcp-header']='X'}}}}},
+ {type='object',properties={x={['$ref']='#/$defs/x',['x-mcp-header']='X'}}}
+ }
+ for i,bad_schema in ipairs(bad) do local result,why=http.validate_param_headers(bad_schema); check(not result and why,'invalid x-mcp-header schema '..i) end
+end
+for i,c in ipairs({
+ {{code=-32022,message='UnsupportedProtocolVersion',data={supported={'2025-11-25'}}},false},
+ {{code=-32020,message='HeaderMismatch'},false},
+ {{code=-32000,message='bad request',data={http_status=400,transport_fallback=true}},true},
+ {{code=-32000,message='not found',data={http_status=404,transport_fallback=true}},true},
+ {{code=-32601,message='modern method not found',data={http_status=404,transport_fallback=false}},false},
+ {{code=-32601,message='legacy discover missing',data={http_status=404,transport_fallback=true}},true},
+ {{code=-32000,message='unauthorized',data={http_status=401,auth_error=true}},false},
+ {'request timed out: server/discover',true},
+ {'remote server/discover: request timed out: server/discover',true},
+ {'connect failed',false}, {'DNS resolution failed',false}, {'TLS handshake failed',false}, {'idle timeout',true}
+}) do eq(http.should_fallback(c[1]),c[2],'era fallback '..i) end
+for _,c in ipairs({
+ {'connect failed','transport'}, {'TLS failed','transport'}, {'timeout','timeout'}, {'idle timeout','idle_timeout'},
+ {'connection closed before response','transport'}, {'connection closed mid-response','transport'},
+ {'other','transport'}, {'response too large','transport'}, {'authentication unavailable','transport'},
+ {'on_head callback failed: timeout','callback'}, {'on_data callback failed: timeout','callback'}
+}) do eq(http.failure_kind(c[1]),c[2],'core failure label') end
+check(not http.should_fallback('on_data callback failed: timeout'),'callback failure never falls back')
+check(http.methods_supported(function() return nil,'invalid HTTP request options' end),'method-capable API probe')
+local old_probe_cancelled=false
+check(not http.methods_supported(function() return {cancel=function() old_probe_cancelled=true end} end),'GET-only API rejected')
+check(old_probe_cancelled,'unsupported API probe cancelled')
+do
+ local probes=0; local capable=function() probes=probes+1; return nil,'invalid HTTP request options' end
+ check(http.methods_supported(capable),'method capability true'); check(http.methods_supported(capable),'method capability cached'); eq(probes,1)
+end
+local function http_reply(opts,cb,status,headers,body,chunks)
+ headers=headers or {}; opts.on_head({status=status,headers=headers})
+ for _,chunk in ipairs(chunks or (body and {body}) or {}) do opts.on_data(chunk) end
+ cb({status=status,headers=headers},nil)
+end
+local remote={name='remote',url='https://example.test/mcp',auth='mcp.remote',headers={['X-Tenant']='acme'}}
+local function injected(cfg,respond,settings_arg,timer_factory)
+ local calls={}
+ local function request(options,callback)
+ calls[#calls+1]=options
+ local handle={cancelled=false}; function handle:cancel() self.cancelled=true end
+ respond(options,callback,handle,#calls); return handle
+ end
+ local tr,err=http.new(cfg,settings_arg or {idle_timeout_ms=4321,call_timeout_ms=300000},
+ {request_fn=request,timer_factory=timer_factory}); assert(tr,err)
+ local messages,errors={},{}; tr:set_callbacks(function(m) messages[#messages+1]=m end,function(e) errors[#errors+1]=e end)
+ return tr,calls,messages,errors
+end
+do
+ local now,js_timers=0,{}
+ local function js_factory(ms,fn)
+ local timer={at=now+ms,closed=false,fn=fn}
+ function timer:is_closing() return self.closed end
+ function timer:close() self.closed=true end
+ function timer:fire() if not self.closed then self:close(); self.fn() end end
+ js_timers[#js_timers+1]=timer; return timer
+ end
+ local function advance(ms)
+ now=now+ms
+ for _,timer in ipairs(js_timers) do if timer.at<=now then timer:fire() end end
+ end
+ local callback,opts,handle
+ local slow=assert(http.new(remote,{idle_timeout_ms=10,call_timeout_ms=5000},{timer_factory=js_factory,request_fn=function(o,cb)
+ opts=o; callback=cb; handle={cancelled=false}; function handle:cancel() self.cancelled=true end
+ o.on_head({status=200,headers={['content-type']='application/json'}}); return handle
+ end}))
+ local rpc=Rpc.new(slow,{timeout_ms=5000,timer_factory=js_factory})
+ local future=rpc:start('tools/call',{name='hello',arguments={}},{era='modern',protocol_version='2026-07-28',method='tools/call'})
+ eq(opts.idle_timeout_ms,0,'core idle timeout disabled'); eq(#js_timers,1,'JSON has only total-call deadline')
+ eq(js_timers[1].at,5000,'JSON response total cap is call_timeout_ms')
+ advance(11); check(not future.done,'slow JSON remains pending past idle timeout')
+ opts.on_data(json.encode({jsonrpc='2.0',id=1,result={ok=true}}))
+ callback({status=200,headers={['content-type']='application/json'}},nil)
+ check(future.done and future.value.ok,'slow JSON answer survives idle threshold'); rpc:close()
+ local idle_timers,idle_factory=timers(); local idle_handle; local idle_messages={}
+ local idle_http=assert(http.new(remote,{idle_timeout_ms=25},{timer_factory=idle_factory,request_fn=function(o)
+ idle_handle={cancelled=false}; function idle_handle:cancel() self.cancelled=true end
+ o.on_head({status=200,headers={['content-type']='text/event-stream'}}); return idle_handle
+ end}))
+ idle_http:set_callbacks(function(m) idle_messages[#idle_messages+1]=m end,function() end)
+ idle_http:send({jsonrpc='2.0',id=55,method='tools/call',params={name='hello'}},{era='modern',protocol_version='2026-07-28',method='tools/call'})
+ eq(idle_timers[1].ms,25,'SSE Lua idle timer starts at response head')
+ idle_timers[1]:fire(); check(idle_handle.cancelled and idle_messages[1].error.data.transport_error=='idle_timeout','idle timeout cancels only stream')
+end
+do
+ local stream_options,stream_handle,stream_messages
+ stream_messages={}
+ local notification_stream=assert(http.new(remote,{},{request_fn=function(options)
+ if options.method=='GET' then
+ stream_options=options
+ stream_handle={cancelled=false}; function stream_handle:cancel() self.cancelled=true end
+ options.on_head({status=200,headers={['content-type']='text/event-stream'}})
+ options.on_data('data: '..json.encode({jsonrpc='2.0',method='notifications/tools/list_changed'})..'\n\n')
+ return stream_handle
+ end
+ return {cancel=function() end}
+ end}))
+ notification_stream.protocol_version='2025-11-25'; notification_stream.session_id='legacy-session'
+ notification_stream:set_callbacks(function(message) stream_messages[#stream_messages+1]=message end,function(err) error(err) end)
+ check(notification_stream:open_notification_stream(),'legacy notification GET opened')
+ eq(stream_options.method,'GET'); eq(stream_options.timeout_ms,0); eq(stream_options.idle_timeout_ms,0)
+ eq(stream_options.headers.Accept,'text/event-stream'); eq(stream_options.headers['Content-Type'],nil)
+ eq(stream_options.headers['Mcp-Session-Id'],'legacy-session'); eq(stream_options.headers['MCP-Protocol-Version'],'2025-11-25')
+ eq(stream_messages[1].method,'notifications/tools/list_changed','legacy GET delivers JSON-RPC notifications')
+ notification_stream:close(); check(stream_handle.cancelled,'legacy GET closes on teardown')
+ local unsupported_handle,unsupported_errors
+ unsupported_errors=0
+ local no_stream=assert(http.new(remote,{}, {request_fn=function(options)
+ if options.method=='GET' then
+ unsupported_handle={cancelled=false}; function unsupported_handle:cancel() self.cancelled=true end
+ options.on_head({status=405,headers={}}); return unsupported_handle
+ end
+ return {cancel=function() end}
+ end}))
+ no_stream:set_callbacks(function() end,function() unsupported_errors=unsupported_errors+1 end)
+ check(not no_stream:open_notification_stream(),'405 means no notification stream')
+ check(unsupported_handle.cancelled and unsupported_errors==0,'405 stream is benign and cancelled')
+ no_stream:close()
+end
+do
+ local retry_timers,retry_factory=timers(); local get_count,list_count,initialize_count=0,0,0
+ local get_done,get_handles,get_options={},{},{}
+ local request_fn=function(options,callback)
+ if options.method=='GET' then
+ get_count=get_count+1; get_options[get_count]=options; get_done[get_count]=callback
+ local handle={cancelled=false}; function handle:cancel() self.cancelled=true end; get_handles[get_count]=handle
+ options.on_head({status=200,headers={['content-type']='text/event-stream'}})
+ return handle
+ elseif options.method=='DELETE' then return {cancel=function() end} end
+ local request=json.decode(options.body)
+ if request.method=='initialize' then
+ initialize_count=initialize_count+1
+ http_reply(options,callback,200,{['content-type']='application/json',['mcp-session-id']='sid'..initialize_count},
+ json.encode({jsonrpc='2.0',id=request.id,result={protocolVersion='2025-11-25',capabilities={tools={listChanged=true}}}}))
+ elseif request.method=='notifications/initialized' then http_reply(options,callback,202,{})
+ elseif request.method=='tools/list' then
+ list_count=list_count+1
+ if list_count==2 then http_reply(options,callback,404,{},'expired')
+ else http_reply(options,callback,200,{['content-type']='application/json'},json.encode({jsonrpc='2.0',id=request.id,result={tools={}}})) end
+ else http_reply(options,callback,200,{['content-type']='application/json'},json.encode({jsonrpc='2.0',id=request.id,result={}})) end
+ return {cancel=function() end}
+ end
+ local eager_http={name='remote',url=remote.url,transport='http',expose='eager',auth=remote.auth,headers=remote.headers,args={},env={}}
+ local client=require('panto_mcp.client').new(eager_http,settings,{timer_factory=retry_factory,request_fn=request_fn})
+ check(client:connect({era='legacy',version='2025-11-25'}),'legacy eager client connects with notification stream')
+ eq(get_count,1)
+ get_done[1]({status=200,headers={}},nil)
+ local retry_timer
+ for _,timer in ipairs(retry_timers) do if timer.ms==1000 and not timer.closed then retry_timer=timer end end
+ check(retry_timer,'closed legacy stream schedules an injected reconnect timer')
+ retry_timer:fire(); eq(get_count,2,'closed legacy stream reopens')
+ local result,err=client:request('tools/list',{})
+ check(result and not err,'404 session re-init retries the original list request')
+ eq(initialize_count,2); eq(get_count,3,'404 re-init opens a new notification stream')
+ check(get_handles[2].cancelled,'old session stream closes before re-init')
+ eq(get_options[3].headers['Mcp-Session-Id'],'sid2','reopened stream uses replacement session')
+ client:close(); check(get_handles[3].cancelled,'replacement stream closes on teardown')
+ local gets=0
+ local proxy=require('panto_mcp.client').new({name='proxy',url=remote.url,transport='http',expose='eager'},settings,{timer_factory=retry_factory,request_fn=function(options,callback)
+ if options.method=='GET' then
+ gets=gets+1
+ local status=gets>=9 and 401 or 200
+ options.on_head({status=status,headers={['content-type']='text/event-stream'}})
+ callback({status=status,headers={}})
+ elseif options.method=='POST' then
+ local req=json.decode(options.body)
+ local result=req.method=='initialize' and {protocolVersion='2025-11-25',capabilities={tools={listChanged=true}}} or {tools={}}
+ if req.id then http_reply(options,callback,200,{['content-type']='application/json'},json.encode({jsonrpc='2.0',id=req.id,result=result}))
+ else http_reply(options,callback,202,{}) end
+ end
+ return {cancel=function() end}
+ end})
+ check(proxy:connect({era='legacy',version='2025-11-25'}),'proxy notification test connects')
+ for _,delay in ipairs({1000,2000,4000,8000,16000,32000,60000,60000}) do
+ local t=assert(proxy.notification_retry_timer); eq(t.ms,delay,'stream retry exponential delay/cap'); t:fire()
+ end
+ check(proxy.notification_retry_stopped and not proxy.notification_retry_timer,'401 stops notification reconnects')
+ local warning_manager=Manager.new(settings,{})
+ warning_manager.states.proxy={cfg=proxy.cfg,state='ready',client=proxy}
+ check(require('panto_mcp.tools').status(warning_manager,{}):find('Notification stream rejected (HTTP 401)',1,true),'401 notification warning is visible in /mcp')
+ warning_manager:close()
+end
+local active_http=require('panto').ext.http_request
+if not http.methods_supported(active_http) then
+ local missing,why=http.new(remote,{})
+ check(not missing and why:find('require a newer panto',1,true),'missing HTTP POST API reports upgrade requirement')
+end
+local jt,jcalls,jm=injected(remote,function(o,cb)
+ eq(o.method,'POST'); eq(o.auth,'mcp.remote'); eq(o.timeout_ms,0); eq(o.idle_timeout_ms,0)
+ eq(o.headers['Mcp-Method'],'server/discover'); eq(o.headers['MCP-Protocol-Version'],'2026-07-28')
+ http_reply(o,cb,200,{['content-type']='application/json'},json.encode({jsonrpc='2.0',id=1,result={ok=true}}))
+end)
+jt:send({jsonrpc='2.0',id=1,method='server/discover',params={}},{era='modern',protocol_version='2026-07-28',method='server/discover'})
+eq(jm[1].result.ok,true); eq(jcalls[1].headers['X-Tenant'],'acme')
+local sm={}; local st=injected(remote,function(o,cb)
+ local n='event: message\r\ndata: {"jsonrpc":"2.0","method":"notifications/tools/list_changed"}\r\n\r\n'
+ local r='event: message\r\ndata: {"jsonrpc":"2.0","id":2,"result":{"ok":true}}\r\n\r\n'
+ http_reply(o,cb,200,{['content-type']='text/event-stream'},nil,{n:sub(1,31),n:sub(32)..r:sub(1,25),r:sub(26)})
+end)
+st:set_callbacks(function(m) sm[#sm+1]=m end,function() end)
+st:send({jsonrpc='2.0',id=2,method='tools/list',params={}},{era='modern',protocol_version='2026-07-28',method='tools/list'})
+eq(#sm,2); eq(sm[1].method,'notifications/tools/list_changed'); eq(sm[2].result.ok,true)
+do
+ local posted=0; local transport=assert(http.new(remote,{idle_timeout_ms=100},{request_fn=function(o,cb)
+ posted=posted+1
+ local events={
+ 'data: {"jsonrpc":"2.0","method":"notifications/progress"}\n\n',
+ 'data: {"jsonrpc":"2.0","id":1,"method":"ping"}\n\n',
+ 'data: {"jsonrpc":"2.0","id":1,"result":{"ok":true}}\n\n'
+ }
+ http_reply(o,cb,200,{['content-type']='text/event-stream'},nil,events)
+ return {cancel=function() end}
+ end}))
+ local rpc=Rpc.new(transport,{timer_factory=function() return {close=function() end,is_closing=function() return false end} end})
+ local future=rpc:start('tools/list',{}, {era='modern',protocol_version='2026-07-28'})
+ check(future.done and future.value.ok,'server request with colliding id does not settle call')
+ eq(posted,1,'modern response to server request is dropped, not posted')
+ rpc:close()
+end
+do
+ local count=0; local transport=assert(http.new(remote,{}, {request_fn=function(o,cb)
+ count=count+1; local id=json.decode(o.body).id
+ local handle={cancelled=false}; function handle:cancel() self.cancelled=true end
+ if count==1 then http_reply(o,cb,200,{['content-type']='application/json'},json.encode({jsonrpc='2.0',id=id}))
+ else o.on_head({status=200,headers={['content-type']='application/json'}}) end
+ return handle
+ end}))
+ local rpc=Rpc.new(transport,{timeout_ms=5000,timer_factory=function() return {close=function() end,is_closing=function() return false end} end})
+ local malformed=rpc:start('tools/list',{}, {era='modern',protocol_version='2026-07-28'})
+ local other=rpc:start('tools/call',{name='hello'},{era='modern',protocol_version='2026-07-28'})
+ check(malformed.done and malformed.err.code==-32000 and malformed.err.message:find('malformed JSON-RPC response',1,true),'malformed matching response is request-scoped')
+ check(not rpc.closed and not other.done,'malformed response leaves other RPCs alive')
+ other:cancel(); rpc:close()
+end
+local step=0; local lt,lc= injected({name='legacy',url='http://127.0.0.1:1234',headers={}},function(o,cb)
+ if o.method=='DELETE' then return end
+ local req=json.decode(o.body); step=step+1
+ if req.method=='initialize' then
+ http_reply(o,cb,200,{['content-type']='application/json',['mcp-session-id']='old-session'},json.encode({jsonrpc='2.0',id=req.id,result={protocolVersion='2025-11-25',capabilities={}}}))
+ elseif req.method=='notifications/initialized' then http_reply(o,cb,202,{})
+ else http_reply(o,cb,404,{},'expired') end
+end)
+local legacy_received={}; lt:set_callbacks(function(m) legacy_received[#legacy_received+1]=m end,function(e) error(e) end)
+lt:send({jsonrpc='2.0',id=10,method='initialize',params={protocolVersion='2025-11-25'}},{era='legacy',protocol_version='2025-11-25',method='initialize'})
+lt:send({jsonrpc='2.0',method='notifications/initialized',params={}},{era='legacy',protocol_version='2025-11-25',method='notifications/initialized'})
+lt:send({jsonrpc='2.0',id=11,method='tools/list',params={}},{era='legacy',protocol_version='2025-11-25',method='tools/list'})
+eq(#lc,3,'expired session signals re-handshake without DELETE'); eq(legacy_received[#legacy_received].id,11)
+check(legacy_received[#legacy_received].error.data.session_expired,'404 signals client re-handshake'); eq(lt.session_id,nil)
+eq(lc[1].headers['MCP-Protocol-Version'],nil); eq(lc[2].headers['MCP-Protocol-Version'],'2025-11-25')
+eq(lc[3].headers['Mcp-Session-Id'],'old-session')
+lt:close()
+do
+ local calls={}; local tr=assert(http.new({name='reply',url='https://example.test',headers={}}, {call_timeout_ms=5000},
+ {request_fn=function(o,cb)
+ calls[#calls+1]=o
+ local req=json.decode(o.body)
+ local h={cancelled=false}; function h:cancel() self.cancelled=true end
+ if req.method=='tools/list' then o.on_head({status=200,headers={['content-type']='application/json'}})
+ elseif req.method=='notifications/cancelled' then http_reply(o,cb,404,{},'stale session')
+ elseif req.method==nil and req.error then http_reply(o,cb,400,{['content-type']='application/json'},json.encode({jsonrpc='2.0',id=req.id,error=req.error}))
+ else http_reply(o,cb,202,{}) end
+ return h
+ end}))
+ tr.era='legacy'; tr.protocol_version='2025-06-18'; tr.session_id='sid'
+ local delivered,transport_errors={},{}
+ tr:set_callbacks(function(m) delivered[#delivered+1]=m end,function(e) transport_errors[#transport_errors+1]=e end)
+ local request_state=tr:send({jsonrpc='2.0',id=1,method='tools/list',params={}},{era='legacy',protocol_version='2025-06-18',method='tools/list'})
+ tr:send({jsonrpc='2.0',id=1,result={}},{method='ping'})
+ check(tr.active['id:1']==request_state,'server reply ID does not collide with client request')
+ tr:send({jsonrpc='2.0',id=1,error={code=-32601,message='reply failed'}},{method='elicitation/create'})
+ check(tr.active['id:1']==request_state and #delivered==0 and #transport_errors==0,'failed reply is logged but isolated')
+ eq(calls[2].headers['MCP-Protocol-Version'],'2025-06-18'); eq(calls[2].headers['Mcp-Session-Id'],'sid')
+ tr:cancel(1,request_state)
+ local cancelled=json.decode(calls[4].body); eq(cancelled.method,'notifications/cancelled')
+ eq(calls[4].headers['MCP-Protocol-Version'],'2025-06-18'); eq(calls[4].headers['Mcp-Session-Id'],'sid')
+ check(not tr.closed and #delivered==0 and #transport_errors==0,'failed cancellation POST is non-fatal')
+end
+do
+ local calls={}; local tr=assert(http.new({name='sessionless',url='http://127.0.0.1:1234',headers={}}, {},
+ {request_fn=function(o,cb)
+ calls[#calls+1]=o; local h={cancel=function() end}
+ if json.decode(o.body).method=='notifications/cancelled' then http_reply(o,cb,202,{})
+ else o.on_head({status=200,headers={['content-type']='application/json'}}) end
+ return h
+ end}))
+ local req=tr:send({jsonrpc='2.0',id=8,method='tools/call',params={name='x'}},{era='legacy',protocol_version='2024-11-05',method='tools/call'})
+ tr:cancel(8,req); eq(#calls,2,'sessionless legacy sends cancellation')
+ eq(json.decode(calls[2].body).method,'notifications/cancelled'); eq(calls[2].headers['MCP-Protocol-Version'],'2024-11-05')
+ eq(calls[2].headers['Mcp-Session-Id'],nil,'sessionless cancellation omits id')
+ tr:close()
+end
+do
+ local modern_posts=0
+ local modern=assert(http.new({name='modern',url='https://example.test',headers={}}, {}, {request_fn=function() modern_posts=modern_posts+1; return {} end}))
+ modern.era='modern'; modern.protocol_version='2026-07-28'
+ modern:send({jsonrpc='2.0',id='peer',result={}},{method='ping'})
+ eq(modern_posts,0,'modern era drops forbidden server-request replies')
+end
+do
+ local errors={}
+ local tr=assert(http.new({name='handshake',url='https://example.test',headers={}}, {}, {request_fn=function(o,cb)
+ http_reply(o,cb,500,{['content-type']='text/plain'},'initialized rejected')
+ return {cancel=function() end}
+ end}))
+ tr:set_callbacks(function() error('fire-and-forget reached RPC') end,function(e) errors[#errors+1]=e end)
+ local handle=tr:send({jsonrpc='2.0',method='notifications/initialized',params={}},{era='legacy',protocol_version='2025-11-25',method='notifications/initialized'})
+ local accepted,why=handle:await()
+ check(not accepted and why:find('notifications/initialized',1,true),'initialized failure reaches handshake waiter')
+ check(not tr.closed and #errors==0,'initialized failure is not promoted to transport/RPC failure')
+end
+do
+ local fire_timers,fire_factory=timers(); local messages,errors={},{}
+ local tr=assert(http.new({name='notify',url='https://example.test',headers={}}, {call_timeout_ms=999999},
+ {timer_factory=fire_factory,request_fn=function() return {cancel=function() end} end}))
+ tr:set_callbacks(function(m) messages[#messages+1]=m end,function(e) errors[#errors+1]=e end)
+ tr:send({jsonrpc='2.0',method='notifications/cancelled',params={requestId=1}},
+ {era='legacy',protocol_version='2025-11-25',method='notifications/cancelled'})
+ eq(fire_timers[1].ms,10000,'fire-and-forget timeout is fixed')
+ fire_timers[1]:fire(); check(not tr.closed and #messages==0 and #errors==0,'failed notification is diagnostic-only')
+end
+do
+ local calls=0; local tr=assert(http.new({name='init',url='https://example.test',headers={}}, {},
+ {request_fn=function() calls=calls+1; return {cancel=function() end} end}))
+ local init=tr:send({jsonrpc='2.0',id=7,method='initialize',params={}},{era='legacy',protocol_version='2024-11-05',method='initialize'})
+ tr:cancel(7,init); eq(calls,1,'initialize cancellation never POSTs notifications/cancelled')
+end
+local at,_,am=injected({name='github',url='https://example.test',headers={Authorization='Bearer NEVER-SURFACE'}},function(o,cb)
+ http_reply(o,cb,401,{['content-type']='text/event-stream'},'Bearer NEVER-SURFACE')
+end)
+at:send({jsonrpc='2.0',id=12,method='server/discover',params={}},{era='modern',protocol_version='2026-07-28',method='server/discover'})
+local auth_text=am[1].error.message
+check(auth_text:find('github',1,true) and auth_text:find('auth = "<session>"',1,true),'401 guidance')
+check(not auth_text:find('NEVER-SURFACE',1,true),'headers are not surfaced')
+local body_error_t,_,body_error_m=injected({name='redact',url='https://example.test',headers={['X-Key']='SECRET'}},function(o,cb)
+ http_reply(o,cb,500,{['content-type']='text/plain'},'SECRET '..string.rep('x',1200))
+end)
+body_error_t:send({jsonrpc='2.0',id=15,method='server/discover',params={}},{era='modern',protocol_version='2026-07-28',method='server/discover'})
+check(body_error_m[1].error.message:find('500',1,true) and not body_error_m[1].error.message:find('SECRET',1,true),'HTTP status body is bounded and redacted')
+do
+ local token_t,_,token_messages=injected({name='redact',url='https://example.test',headers={Authorization='Bearer ACCESS_TOKEN'}},function(o,cb)
+ http_reply(o,cb,500,{['content-type']='text/plain'},string.rep('x',1020)..'ACCESS_TOKEN-tail')
+ end)
+ token_t:send({jsonrpc='2.0',id=16,method='tools/list',params={}},{era='modern',protocol_version='2026-07-28',method='tools/list'})
+ check(not token_messages[1].error.message:find('ACCESS_TOKEN',1,true) and not token_messages[1].error.message:find('ACCESS',1,true),'redaction precedes truncation and removes auth token part')
+end
+local json_error_t,_,json_error_m=injected({name='redact',url='https://example.test',headers={['X-Key']='SECRET'},},function(o,cb)
+ http_reply(o,cb,400,{['content-type']='application/json'},json.encode({jsonrpc='2.0',id=18,error={code=-32600,message='SECRET bad header'}}))
+end)
+json_error_t:send({jsonrpc='2.0',id=18,method='server/discover',params={}},{era='modern',protocol_version='2026-07-28',method='server/discover'})
+check(json_error_m[1].error.message:find('bad header',1,true) and not json_error_m[1].error.message:find('SECRET',1,true) and json_error_m[1].error.data.http_status==400,'HTTP JSON-RPC errors preserve message, context, status, and redaction')
+do
+ local null_transport,_,null_messages=injected(remote,function(o,cb)
+ http_reply(o,cb,400,{['content-type']='application/json'},json.encode({jsonrpc='2.0',id=json.null,error={code=-32022,message='unsupported',data={supported={'2024-11-05'}}}}))
+ end)
+ null_transport:send({jsonrpc='2.0',id=19,method='server/discover',params={}},{era='modern',protocol_version='2026-07-28',method='server/discover'})
+ local error_response=null_messages[1].error
+ eq(error_response.code,-32022); eq(error_response.data.supported[1],'2024-11-05')
+ check(not http.should_fallback(error_response),'null-id modern negotiation is not downgraded')
+end
+do
+ local ok_transport,_,ok_messages=injected({name='redact',url='https://example.test',headers={['X-Key']='SECRET'}},function(o,cb)
+ http_reply(o,cb,200,{['content-type']='application/json'},json.encode({jsonrpc='2.0',id=20,error={code=-32022,message='SECRET UnsupportedProtocolVersion',data={supported={'2025-11-25'}}}}))
+ end)
+ ok_transport:send({jsonrpc='2.0',id=20,method='server/discover',params={}},{era='modern',protocol_version='2026-07-28',method='server/discover'})
+ check(not ok_messages[1].error.message:find('SECRET',1,true),'successful HTTP JSON-RPC errors redact static headers')
+end
+local et,_,em=injected(remote,function(o,cb)
+ http_reply(o,cb,200,{['content-type']='text/event-stream'},nil,{'data: {"jsonrpc":"2.0","method":"notifications/progress"}\n\n'})
+end)
+et:send({jsonrpc='2.0',id=13,method='tools/call',params={name='hello'}},{era='modern',protocol_version='2026-07-28',method='tools/call',name='hello'})
+eq(em[#em].id,13); check(em[#em].error.message:find('without a response',1,true),'SSE EOF is request-scoped')
+do
+ local stream,_,stream_messages=injected(remote,function(o,cb)
+ http_reply(o,cb,200,{['content-type']='text/event-stream'},nil,{'data: {"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"server rejected"}}\n\n'})
+ end)
+ stream:send({jsonrpc='2.0',id=23,method='tools/list',params={}},{era='modern',protocol_version='2026-07-28',method='tools/list'})
+ eq(stream_messages[1].id,23); check(stream_messages[1].error.message:find('server rejected',1,true),'null-id SSE error is correlated to its request')
+ check(not stream_messages[1].error.message:find('without a response',1,true),'null-id SSE error is preserved')
+end
+local pending_handle; local ct=assert(http.new(remote,{}, {request_fn=function() pending_handle={cancelled=false}; function pending_handle:cancel() self.cancelled=true end; return pending_handle end}))
+local pending=ct:send({jsonrpc='2.0',id=14,method='tools/list',params={}},{era='modern',protocol_version='2026-07-28',method='tools/list'})
+ct:cancel(14,pending); check(pending_handle.cancelled,'HTTP cancellation')
+do
+ local handles={}
+ local closing_http=assert(http.new(remote,{}, {request_fn=function()
+ local h={cancelled=false}; function h:cancel() self.cancelled=true end; handles[#handles+1]=h; return h
+ end}))
+ closing_http:send({jsonrpc='2.0',id=21,method='tools/list',params={}},{era='modern',protocol_version='2026-07-28',method='tools/list'})
+ closing_http:send({jsonrpc='2.0',id=22,method='tools/list',params={}},{era='modern',protocol_version='2026-07-28',method='tools/list'})
+ closing_http:close(); check(handles[1].cancelled and handles[2].cancelled,'session close cancels every HTTP request')
+end
+end
+
+-- JSON-RPC: injected deadlines, cancellation, late responses, server requests.
+local ts,tf=timers(); local t=fake_transport(); local rpc=Rpc.new(t,{timer_factory=tf,timeout_ms=99})
+local a=rpc:start('one',{}); local b=rpc:start('two',{})
+t.message({jsonrpc='2.0',id=2,result={v=2}}); check(b.done and not a.done,'id routing')
+ts[1]:fire(); check(a.done and a.err:find('timed out',1,true),'injected timeout'); eq(t.cancels[1],1)
+t.message({jsonrpc='2.0',id=1,result={late=true}}); check(a.err~=nil,'late response ignored')
+local c=rpc:start('three',{}); c:cancel(); check(c.done,'cancel settles')
+t.message({jsonrpc='2.0',id='server-ping',method='ping'}); check(t.sent[#t.sent].msg.result~=nil,'ping response')
+t.message({jsonrpc='2.0',id='other',method='sampling/createMessage'}); eq(t.sent[#t.sent].msg.error.code,-32601)
+local d=rpc:start('four',{}); rpc:close(); check(d.done and t.closed,'close settles pending')
+local it,ift=timers(); local itx=fake_transport(); local irpc=Rpc.new(itx,{timer_factory=ift,timeout_ms=9})
+local initialize=irpc:start('initialize',{}, {cancel_protocol=false}); it[1]:fire()
+check(initialize.done and #itx.cancels==0,'initialize timeout sends no cancellation notification'); irpc:close()
+
+-- Mapped results and capped/unsupported data.
+eq(results.decode64('aGVsbG8='),'hello'); eq(results.decode64('JQ=='),'%','percent replacement'); eq(results.decode64('AAAA'),'\0\0\0','zero-byte decode'); eq(results.decode64('+/8='),'\xfb\xff','high-byte decode'); check(not results.decode64('bad!'),'invalid base64')
+local large_image=assert(results.decode64(string.rep('QUJD',1747626)))
+eq(#large_image,5242878,'multi-megabyte base64 length'); eq(large_image:sub(1,3),'ABC'); eq(large_image:sub(-3),'ABC')
+local r=results.map('srv',{content={{type='text',text='{"a":1}'},{type='image',data='aGk=',mimeType='image/png'},
+ {type='audio',data='aGk=',mimeType='audio/wav'},{type='resource_link',uri='docs://a',name='A'},
+ {type='resource',resource={uri='docs://b',text='embedded'}}},structuredContent={a=1}})
+eq(r.attachments[1].data,'hi'); check(r.text:find('server="srv"',1,true),'resource guidance')
+local _,n=r.text:gsub('"a":1',''); eq(n,1,'structured dedup')
+check(results.map('srv',{resultType='input_required'}).is_error,'input_required')
+check(results.map('srv',{isError=true,content={{type='text',text='oops'}}}).is_error,'tool error')
+check(results.map('srv',nil,{message='oops',code=-1}).text:find('(-1)',1,true),'rpc error')
+check(results.cap(string.rep('x',results.MAX_OUTPUT+1)):find('truncated',1,true),'output cap')
+-- Disk metadata: warm/cold/fingerprint/corrupt. No servers spawn on warm load.
+local cfg=servers.fs
+local meta={era='modern',version='2026-07-28',catalog={tools={{name='read_file',description='Read file contents',inputSchema={type='object',properties={path={type='string'}}}}},prompts={},resources={{name='guide',uri='docs://guide'}},templates={}},instructions=string.rep('x',5000)}
+local cleaned=cache.normalize_catalog({tools={{name='ok',title=json.null,annotations=json.null,inputSchema={}},{name='drop',description=7,inputSchema={}}},prompts={},resources={},templates={}})
+eq(#cleaned.tools,1,'malformed catalog entry dropped'); eq(cleaned.tools[1].title,nil,'null catalog field absent'); eq(cleaned.tools[1].annotations,nil,'all null catalog fields absent')
+check(cache.save(cfg,meta,temp),'cache write'); check(cache.load(cfg,temp),'cache warm')
+write(temp..'/fs-extra-12345678.json','keep other server cache')
+check(read(cache.path(cfg,temp)):find('"prompts":%[%]'),'empty cache lists encode as arrays')
+local warm=Manager.new(settings,{fs=cfg},{cache_dir=temp,transport_factory=function() error('warm activation spawned') end})
+eq(warm.states.fs.state,'idle'); warm:start_cold(); eq(warm.states.fs.state,'idle','warm starts nothing')
+local hits=assert(warm:search('file',{server='fs'})); eq(hits.hits[1].name,'read_file'); check(hits.hits[1].inputSchema,'schema returned'); check(hits.instructions:find('truncated',1,true),'instructions cap')
+eq(assert(warm:search('guide',{})).hits[1].kind,'resources')
+local other_cfg={name=cfg.name,fingerprint=config.hash('other')}
+check(cache.save(other_cfg,meta,temp),'cache save changed fingerprint')
+check(not read(cache.path(cfg,temp)),'old fingerprint pruned')
+eq(read(temp..'/fs-extra-12345678.json'),'keep other server cache','shared-prefix server cache preserved')
+write(cache.path(cfg,temp),'corrupt'); check(not cache.load(cfg,temp),'corrupt is cold')
+local cfg2={name=cfg.name,fingerprint='different'}; check(not cache.load(cfg2,temp),'fingerprint cold')
+warm:close()
+-- Startup deadlines/retry are injected, not tested by sleeping.
+local timers2,factory2=timers(); local count=0
+local stalled=Manager.new(settings,{fs=cfg},{cache_dir=temp,timer_factory=factory2,transport_factory=function() count=count+1; return fake_transport() end})
+local pending=stalled:start(stalled.states.fs); timers2[1]:fire()
+check(pending.done and stalled.states.fs.state=='failed','startup deadline')
+check(count==1,'deadline must not restart closed client')
+stalled:start(stalled.states.fs); check(count==2,'failed retried lazily'); stalled:close()
+local closing_ts,closing_tf=timers()
+local closing=Manager.new(settings,{fs=cfg},{cache_dir=temp,timer_factory=closing_tf,transport_factory=function() return fake_transport() end})
+local closing_ready=closing:start(closing.states.fs); local resumed=false
+local waiter=coroutine.create(function() closing_ready:await(); resumed=true end)
+assert(coroutine.resume(waiter)); eq(coroutine.status(waiter),'suspended')
+closing:close()
+check(not resumed and coroutine.status(waiter)=='suspended','session_end abandons waiters without resuming them'); check(closing_ready.done,'abandoned startup future settled')
+
+-- Era selection and silent-probe fallback with scripted transports/injected
+-- timers. No elapsed-time sleeps are used to manufacture timeout behavior.
+local Client=require('panto_mcp.client')
+local function scripted(respond)
+ local tr=fake_transport()
+ local send=tr.send
+ function tr:send(msg,opts)
+ local h=send(self,msg,opts)
+ if msg.id then
+ local value,err=respond(msg,opts)
+ if value~=nil or err~=nil then self.message({jsonrpc='2.0',id=msg.id,result=value,error=err}) end
+ end
+ return h
+ end
+ return tr
+end
+do
+ local t,tf=timers(); local tr=fake_transport(); local send=tr.send
+ local initializes,tool_calls=0,0; local initialized=false
+ function tr:send(msg,opts)
+ local h=send(self,msg,opts)
+ if msg.method=='initialize' then initializes=initializes+1
+ elseif msg.method=='notifications/initialized' then initialized=true
+ elseif msg.method=='tools/call' then
+ tool_calls=tool_calls+1
+ if initialized then self.message({jsonrpc='2.0',id=msg.id,result={ok=true}}) end
+ end
+ return h
+ end
+ local client=Client.new({name='remote',url='https://example.test',transport='http'},settings,
+ {timer_factory=tf,transport_factory=function() return tr end})
+ assert(client:open()); client.era='legacy'; client.version='2025-11-25'; tr.era='legacy'; tr.protocol_version='2025-11-25'; tr.session_generation=1
+ local r1,e1,r2,e2
+ async.run(function() r1,e1=client:request('tools/call',{name='hello',arguments={}}) end,function(err) error(err) end)
+ async.run(function() r2,e2=client:request('tools/call',{name='hello',arguments={}}) end,function(err) error(err) end)
+ eq(tool_calls,2,'parallel stale requests in flight')
+ tr.message({jsonrpc='2.0',id=1,error={code=-32000,message='session expired',data={session_expired=true,session_generation=1}}})
+ tr.message({jsonrpc='2.0',id=2,error={code=-32000,message='session expired',data={session_expired=true,session_generation=1}}})
+ eq(initializes,1,'parallel session expiry shares one re-init')
+ tr.message({jsonrpc='2.0',id=3,result={protocolVersion='2024-11-05',capabilities={}}})
+ check(r1 and r1.ok and r2 and r2.ok and not e1 and not e2,'both expired calls retry once')
+ eq(initializes,1); eq(tool_calls,4,'one retry per original request'); eq(tr.protocol_version,'2024-11-05')
+ local initialized_version
+ for _,entry in ipairs(tr.sent) do if entry.msg.method=='notifications/initialized' then initialized_version=entry.opts.protocol_version end end
+ eq(initialized_version,'2024-11-05','2024 counter-offer retained during re-init'); client:close()
+end
+local remote_http={name='http',url='https://example.test/mcp',transport='http',headers={},args={},env={}}
+do
+ local function stream_client(expose,era)
+ local streams=0
+ local client=Client.new({name='http',url='https://example.test/mcp',transport='http',expose=expose,headers={},args={},env={}},settings,
+ {transport_factory=function()
+ local transport=scripted(function(message)
+ if message.method=='initialize' then return {protocolVersion='2025-11-25',capabilities={tools={listChanged=true}}} end
+ if message.method=='server/discover' then return {capabilities={tools={listChanged=true}}} end
+ if message.method=='tools/list' then return {tools={}} end
+ end)
+ function transport:open_notification_stream() streams=streams+1; return true end
+ return transport
+ end})
+ local cached=era=='legacy' and {era='legacy',version='2025-11-25'} or {era='modern',version='2026-07-28'}
+ check(client:connect(cached),'cached client connects for notification-stream gate')
+ client:close()
+ return streams
+ end
+ eq(stream_client('eager','legacy'),1,'only eager 2025-11-25 HTTP clients open GET stream')
+ eq(stream_client('search','legacy'),0,'search HTTP client does not open GET stream')
+ eq(stream_client('eager','modern'),0,'modern HTTP client does not open legacy GET stream')
+end
+do
+ local calls,reported={},nil; local timer_list,timer_factory=timers()
+ local client=Client.new(remote_http,settings,{timer_factory=timer_factory,on_error=function(err) reported=err end,
+ transport_factory=function(cfg,client_settings)
+ return assert(require('panto_mcp.http').new(cfg,client_settings,{timer_factory=timer_factory,request_fn=function(o,cb)
+ calls[#calls+1]=o
+ local handle={cancel=function() end}
+ if o.method=='DELETE' then return handle end
+ local req=json.decode(o.body); local status=req.method=='initialize' and 200 or 500
+ local headers=req.method=='initialize' and {['content-type']='application/json',['mcp-session-id']='half-session'} or {['content-type']='text/plain'}
+ local body=req.method=='initialize' and json.encode({jsonrpc='2.0',id=req.id,result={protocolVersion='2025-11-25',capabilities={}}}) or 'initialized failed'
+ o.on_head({status=status,headers=headers}); o.on_data(body); cb({status=status,headers=headers},nil)
+ return handle
+ end}))
+ end})
+ assert(client:open()); client.era='legacy'; client.version='2025-11-25'
+ local ready,why
+ async.run(function() ready,why=client:reinitialize_legacy() end,function(err) error(err) end)
+ check(not ready and why and client.rpc.closed and reported,'failed re-init fails RPC/client for next-use reconnect')
+ eq(calls[3].method,'DELETE'); eq(calls[3].headers['Mcp-Session-Id'],'half-session','half-initialized session is deleted')
+ client:close()
+end
+do
+ local annotated_transport; local list_calls,call_calls,call_headers=0,0,{}
+ local annotated=Client.new(remote_http,settings,{transport_factory=function()
+ annotated_transport=scripted(function(msg,opts)
+ if msg.method=='server/discover' then return {capabilities={tools={}}} end
+ if msg.method=='tools/list' then
+ list_calls=list_calls+1
+ local header_name=list_calls==1 and 'Region' or 'Locale'
+ return {tools={
+ {name='hello',inputSchema={type='object',properties={nested={type='object',properties={region={type='string',['x-mcp-header']=header_name}}}}}},
+ {name='bad',inputSchema={type='object',properties={x={type='number',['x-mcp-header']='Bad'}}}}
+ }}
+ end
+ if msg.method=='tools/call' then
+ call_calls=call_calls+1; call_headers[call_calls]=opts.param_headers[1].name
+ if call_calls==1 then return nil,{code=-32020,message='HeaderMismatch'} end
+ return {content={}}
+ end
+ end)
+ return annotated_transport
+ end})
+ check(annotated:connect(),'HTTP catalog with annotations connects')
+ eq(#annotated.catalog.tools,1,'invalid annotated tool excluded'); eq(annotated.catalog.tools[1].name,'hello')
+ annotated:call('hello',{nested={region='us-west1'}})
+ eq(list_calls,2,'HeaderMismatch re-lists tool schemas once'); eq(call_calls,2,'HeaderMismatch retries once')
+ eq(call_headers[1],'Region'); eq(call_headers[2],'Locale','retry uses updated Mcp-Param annotation')
+ annotated:close()
+end
+do
+ for _,scenario in ipairs({'removed','new-schema'}) do
+ local call_count,list_count=0,0
+ local client=Client.new(remote_http,settings,{transport_factory=function()
+ return scripted(function(msg)
+ if msg.method=='server/discover' then return {capabilities={tools={}}} end
+ if msg.method=='tools/list' then
+ list_count=list_count+1
+ if list_count==2 and scenario=='removed' then return {tools={}} end
+ local kind=list_count==2 and scenario=='new-schema' and 'integer' or 'string'
+ return {tools={{name='hello',inputSchema={type='object',properties={region={type=kind,['x-mcp-header']='Region'}},required={'region'}}}}}
+ end
+ if msg.method=='tools/call' then
+ call_count=call_count+1
+ return nil,{code=call_count==1 and -32020 or -32602,message='HeaderMismatch'}
+ end
+ end)
+ end})
+ check(client:connect(),'HeaderMismatch retry precondition')
+ local _,err=client:call('hello',{region='us-west1'})
+ if scenario=='removed' then eq(err.code,-32020,'removed tool returns original HeaderMismatch')
+ else eq(err.code,-32602,'updated schema revalidates old input') end
+ eq(call_count,1,'removed or incompatible tool is not retried')
+ client:close()
+ end
+end
+do
+ local transport
+ local refresh_client=Client.new(remote_http,settings,{transport_factory=function()
+ transport=scripted(function(msg)
+ if msg.method=='tools/list' then return {tools={{name='new',inputSchema={type='object',properties={x={type='string',['x-mcp-header']='X'}}}}}} end
+ if msg.method=='prompts/list' then return nil,{code=-32000,message='list failed'} end
+ end)
+ return transport
+ end})
+ assert(refresh_client:open()); refresh_client.era='modern'; refresh_client.version='2026-07-28'
+ refresh_client.capabilities={tools={},prompts={}}
+ local old_catalog=json.array({{name='old'}}); local old_headers={old={{name='Old',path={'old'},type='string'}}}
+ refresh_client.catalog.tools=old_catalog; refresh_client.tool_headers=old_headers
+ local refreshed=refresh_client:refresh()
+ check(not refreshed and refresh_client.catalog.tools==old_catalog and refresh_client.tool_headers==old_headers,
+ 'failed catalog refresh retains catalog and MCP parameter headers atomically')
+ refresh_client:close()
+end
+local probe_methods={}
+local fallback_http=Client.new(remote_http,settings,{transport_factory=function()
+ return scripted(function(msg)
+ probe_methods[#probe_methods+1]=msg.method
+ if msg.method=='server/discover' then return nil,{code=-32000,message='empty HTTP 400',data={http_status=400,transport_fallback=true}} end
+ if msg.method=='initialize' then return {protocolVersion='2025-11-25',capabilities={}} end
+ if msg.method=='tools/list' then return {tools={}} end
+ end)
+end})
+check(fallback_http:connect(),'HTTP empty 400 falls back to legacy'); eq(fallback_http.era,'legacy'); eq(probe_methods[1],'server/discover'); eq(probe_methods[2],'initialize'); fallback_http:close()
+local mismatch_methods={}
+local mismatch_http=Client.new(remote_http,settings,{transport_factory=function()
+ return scripted(function(msg)
+ mismatch_methods[#mismatch_methods+1]=msg.method
+ if msg.method=='server/discover' then return nil,{code=-32020,message='HeaderMismatch'} end
+ end)
+end})
+local mismatch_ok,mismatch_error=mismatch_http:connect()
+check(not mismatch_ok and mismatch_error:find('HeaderMismatch',1,true),'HTTP modern JSON-RPC error is not downgraded')
+eq(#mismatch_methods,1,'recognized modern error stops fallback'); mismatch_http:close()
+local connection_opens,connection_methods=0,{}
+local connection_client=Client.new(remote_http,settings,{transport_factory=function()
+ connection_opens=connection_opens+1
+ return scripted(function(msg)
+ connection_methods[#connection_methods+1]=msg.method
+ return nil,{code=-32000,message='connect failed',data={transport_error='connection'}}
+ end)
+end})
+local connection_ok=connection_client:connect()
+check(not connection_ok,'connection failures stay errors'); eq(connection_opens,1); eq(#connection_methods,1,'connection failure does not probe legacy')
+connection_client:close()
+do
+ local timeout_timers,timeout_factory=timers(); local timeout_client=Client.new(remote_http,settings,
+ {timer_factory=timeout_factory,transport_factory=function() return fake_transport() end})
+ assert(timeout_client:open()); timeout_client.era='modern'; timeout_client.version='2026-07-28'
+ local timeout_error
+ async.run(function() local _,err=timeout_client:request('tools/call',{name='hello',arguments={}}); timeout_error=err end)
+ timeout_timers[1]:fire()
+ check(timeout_error and timeout_error:find('http tools/call: request timed out',1,true),'HTTP RPC timeout names server and method')
+ timeout_client:close()
+end
+local cached_opens=0
+local cached_connection=Client.new(remote_http,settings,{transport_factory=function()
+ cached_opens=cached_opens+1
+ return scripted(function() return nil,{code=-32000,message='TLS handshake failed',data={transport_error='connection'}} end)
+end})
+local cached_ok=cached_connection:connect({era='modern',version='2026-07-28'})
+check(not cached_ok,'cached connection failure stays an error'); eq(cached_opens,1,'cached connection failure is not re-probed')
+cached_connection:close()
+local retry_opens=0
+local retried=Manager.new(settings,{fs=cfg},{cache_dir=temp,transport_factory=function()
+ retry_opens=retry_opens+1
+ return scripted(function(msg)
+ if msg.method=='server/discover' then return {capabilities={tools={}}} end
+ if msg.method=='tools/list' then return {tools={}} end
+ end)
+end})
+retried.states.fs.metadata=meta; retried.states.fs.state='failed'
+local retried_search=assert(retried:search(nil,{server='fs'}))
+eq(retry_opens,1,'search lazily retries failed servers'); eq(retried.states.fs.state,'ready')
+check(retried_search.servers[1].stderr==nil,'search status strips stderr'); retried:close()
+local chosen
+local selection=Client.new(remote_http,settings,{transport_factory=function()
+ return scripted(function(msg,opts)
+ if msg.method=='server/discover' then
+ eq(opts.protocol_version,'2026-07-28','transport version seam')
+ return nil,{code=-32022,message='unsupported',data={supported={'2024-11-05'}}}
+ end
+ if msg.method=='initialize' then chosen=msg.params.protocolVersion; return {protocolVersion=chosen,capabilities={}} end
+ end)
+end})
+check(selection:connect(),'unsupported-version selection'); eq(chosen,'2024-11-05'); selection:close()
+local counteroffer_calls={}
+local counteroffer_failure=Client.new(remote_http,settings,{transport_factory=function()
+ return scripted(function(msg)
+ counteroffer_calls[#counteroffer_calls+1]=msg.method
+ if msg.method=='server/discover' then return nil,{code=-32022,message='unsupported',data={supported={'2025-11-25'}}} end
+ if msg.method=='initialize' then return nil,{code=-32600,message='legacy initialize rejected'} end
+ end)
+end})
+local counteroffer_ok,counteroffer_error=counteroffer_failure:connect()
+check(not counteroffer_ok and counteroffer_error:find('legacy initialize rejected',1,true),'counter-offer failure reports legacy error')
+eq(table.concat(counteroffer_calls,','),'server/discover,initialize','counter-offer is tried once'); counteroffer_failure:close()
+local opens=0
+local reprobe=Client.new(cfg,settings,{transport_factory=function()
+ opens=opens+1
+ return scripted(function(msg)
+ if msg.method=='initialize' then return nil,{code=-32601,message='modern only'} end
+ return {capabilities={}}
+ end)
+end})
+check(reprobe:connect({era='legacy',version='2025-11-25'}),'cached era re-probed'); eq(opens,2); eq(reprobe.era,'modern'); reprobe:close()
+local delayed_ts,delayed_tf=timers(); local delayed_opens,initialize_count,offered=0,0,nil; local delayed_done
+local delayed=Client.new(cfg,settings,{timer_factory=delayed_tf,transport_factory=function()
+ delayed_opens=delayed_opens+1
+ local tr=fake_transport(); local send=tr.send
+ function tr:send(msg,opts)
+ local h=send(self,msg,opts)
+ if msg.method=='initialize' then
+ initialize_count=initialize_count+1; offered=msg.params.protocolVersion
+ delayed_tf(2000,function() self.message({jsonrpc='2.0',id=msg.id,result={protocolVersion='2025-11-25',capabilities={}}}) end)
+ end
+ return h
+ end
+ return tr
+end})
+async.run(function() delayed_done=assert(delayed:connect({era='legacy',version='2025-03-26'})) end,function(err) error(err) end)
+eq(delayed_ts[1].ms,settings.startup_timeout_ms,'cached handshake gets full startup budget')
+eq(delayed_ts[2].ms,2000,'injectable slow legacy server start')
+eq(offered,'2025-11-25','cached legacy upgrades its offered version')
+delayed_ts[2]:fire()
+check(delayed_done and delayed_opens==1 and initialize_count==1,'slow cached legacy starts one process and initializes once'); delayed:close()
+local changed_lists,change_transport=0,nil
+local changed_client=Client.new(cfg,settings,{transport_factory=function()
+ change_transport=scripted(function(msg)
+ if msg.method=='server/discover' then return {capabilities={tools={}}} end
+ if msg.method=='tools/list' then
+ changed_lists=changed_lists+1
+ if changed_lists==1 then change_transport.message({jsonrpc='2.0',method='notifications/tools/list_changed'}) end
+ return {tools={}}
+ end
+ end)
+ return change_transport
+end})
+check(changed_client:connect(),'connect survives list_changed during initial refresh')
+eq(changed_lists,2,'connect replays list_changed'); changed_client:close()
+local silent_ts,silent_tf=timers(); local silent_opens=0; local silent_done
+local silent=Client.new(cfg,settings,{timer_factory=silent_tf,transport_factory=function()
+ silent_opens=silent_opens+1
+ return scripted(function(msg)
+ if msg.method=='initialize' then return {protocolVersion='2025-11-25',capabilities={}} end
+ end)
+end})
+async.run(function() silent_done=assert(silent:connect()) end,function(err) error(err) end)
+eq(silent_ts[1].ms,1500,'short modern probe'); silent_ts[1]:fire()
+check(silent_done and silent.era=='legacy' and silent_opens==2,'silent legacy probe falls back fresh'); silent:close()
+local slow_ts,slow_tf=timers(); local slow_opens=0; local slow_done
+local slow_modern=Client.new(cfg,settings,{timer_factory=slow_tf,transport_factory=function()
+ slow_opens=slow_opens+1
+ local attempt=slow_opens
+ return scripted(function(msg)
+ if attempt==1 then return nil end
+ if msg.method=='initialize' then return nil,{code=-32601,message='modern only'} end
+ return {capabilities={}}
+ end)
+end})
+async.run(function() slow_done=assert(slow_modern:connect()) end,function(err) error(err) end)
+slow_ts[1]:fire()
+check(slow_done and slow_modern.era=='modern' and slow_opens==2,'slow modern-only startup recovers after legacy rejection')
+slow_modern:close()
+
+-- Activation from a warm cache: checkout entry/namespace registration, stable
+-- config-only guidance, zero process starts, and nonblocking command output.
+local saved_panto=package.loaded.panto; local saved_std=package.loaded._std
+local old_directory=cache.directory; cache.directory=function() return temp end
+local activation_raw={servers={fs={command='echo',expose='eager'},alpha={command='echo'},off={enabled=false}}}
+local _,activation_servers=config.parse(activation_raw,{project_root=here})
+local activation_meta={era='modern',version='2026-07-28',capabilities={tools={},prompts={},resources={}},catalog={
+ tools=meta.catalog.tools,prompts={{name='greet',title='Greet',arguments={{name='name',required=true}}}},
+ resources=meta.catalog.resources,templates=meta.catalog.templates}}
+check(cache.save(activation_servers.fs,activation_meta,temp),'activation warm cache')
+check(cache.save(activation_servers.alpha,activation_meta,temp),'second activation warm cache')
+local registered,events,commands,namespaces={},{},{},{}
+local guidance
+package.loaded.panto={ext={json=json,config={mcp=activation_raw},dirs={project_root=here},
+ register_tool=function(tool) registered[#registered+1]=tool end,
+ register_command=function(command) commands[command.name]=command end,
+ on=function(name,fn) events[name]=fn end,
+ style=function() return {dim='<dim>',reset='</dim>'} end,
+ agent={add_system_message=function(_,text) guidance=text end}}}
+package.loaded._std={lua_namespace=function(name,factory) namespaces[name]=factory end}
+dofile(here .. '/init.lua').activate()
+eq(#registered,3,'older-core eager fallback exposes search tools'); check(namespaces.mcp,'namespace installed')
+check(commands['mcp:fs:greet'],'warm prompt command registered on older core')
+check(commands['mcp:fs:greet'].handler(''):find('missing required arguments: name',1,true),'warm prompt validates args without starting server')
+check(commands.mcp.handler(''):find('idle',1,true),'warm activation stays idle')
+do
+ local header={render=function(_,width) eq(width,80,'inner header width'); return {'panto',' skills: example',''} end}
+ events.render_header({get_component=function() return header end,set_component=function(_,component) header=component end})
+ eq(table.concat(header:render(80),'\n'),'panto\n skills: example\n<dim> mcp: alpha, fs</dim>\n',
+ 'header adds sorted enabled server names before trailing blank')
+end
+events.session_ready(); check(guidance:find('fs: stdio, search',1,true),'stable config guidance after old-core fallback')
+check(commands.mcp.handler(''):find('eager not yet supported',1,true),'old-core eager fallback warning')
+events.session_end()
+package.loaded.panto=saved_panto; package.loaded._std=saved_std; cache.directory=old_directory
+-- The live core path exposes warm eager tools and prompts from cache without a process start.
+do
+ cache.directory=function() return temp end
+ local raw={servers={fast={command='echo',expose='eager'}}}
+ local _,ss=config.parse(raw,{project_root=here})
+ local warm_meta={era='modern',version='2026-07-28',capabilities={tools={listChanged=true},prompts={},resources={}},catalog={
+ tools={{name='read_file',description='Read cached',inputSchema={type='object',properties={path={type='string'}}}}},
+ prompts={{name='greet',title='Greet',arguments={{name='name',required=true}}}},
+ resources={{name='guide',uri='docs://guide'}},templates={}}}
+ check(cache.save(ss.fast,warm_meta,temp),'eager cache write')
+ local tools_now,commands_now,events_now={},{},{}
+ local ext={json=json,config={mcp=raw},dirs={project_root=here},
+ register_tool=function(spec) tools_now[spec.name]=spec; return true end,
+ unregister_tool=function(name) tools_now[name]=nil; return true end,
+ register_command=function(spec) commands_now[spec.name]=spec; return true end,
+ unregister_command=function(name) commands_now[name]=nil; return true end,
+ on=function(name,fn) events_now[name]=fn end,
+ agent={add_system_message=function() end}}
+ package.loaded.panto={ext=ext}; package.loaded._std={lua_namespace=function() end}
+ dofile(here .. '/init.lua').activate()
+ check(tools_now[config.tool_name('fast','read_file')],'warm eager tool registered at activation')
+ check(tools_now['mcp.read_resource'],'eager resource tool registered from warm capability')
+ eq(tools_now['mcp.search'],nil,'eager-only mode omits search tools')
+ check(commands_now['mcp:fast:greet'],'warm prompt command registered')
+ check(commands_now.mcp~=nil,'status command remains available')
+ check(commands_now['mcp:fast:greet'].description:find('name',1,true),'prompt description includes argument names')
+ check(commands_now.mcp.handler(''):find('idle',1,true),'warm eager activation spawns nothing')
+ events_now.session_end()
+ package.loaded.panto=saved_panto; package.loaded._std=saved_std; cache.directory=old_directory
+end
+-- Reconcile connect snapshots: new/removed/changed eager tools and prompt commands.
+do
+ local _,ss=config.parse({servers={fast={command='echo',expose='eager',enabled_tools={'*'},disabled_tools={'disabled*'}}}},{project_root=here})
+ local calls,tool_specs,command_specs,removed_tools,removed_commands={},{},{},{},{}
+ local fake_manager={states={fast={cfg=ss.fast}}}
+ function fake_manager:call(server,name,input)
+ calls[#calls+1]={server=server,name=name,input=input}
+ return {is_error=false,text='called '..name,attachments={}}
+ end
+ local fake_ext={
+ register_tool=function(spec) tool_specs[spec.name]=spec; return true end,
+ unregister_tool=function(name) removed_tools[#removed_tools+1]=name; tool_specs[name]=nil; return true end,
+ register_command=function(spec) command_specs[spec.name]=spec; return true end,
+ unregister_command=function(name) removed_commands[#removed_commands+1]=name; command_specs[name]=nil; return true end,
+ }
+ local eager=require('panto_mcp.eager').new(fake_ext,fake_manager)
+ local command_set=prompts.commands(fake_ext,fake_manager,{busy=false},true)
+ local function def(name,description,kind)
+ return {name=name,description=description,inputSchema={type='object',properties={value={type=kind or 'string'}}}}
+ end
+ local initial={catalog={tools={def('a.b','old'),def('a_b','collision'),def('remove_me','remove'),def('change_me','change'),def('disabled_tool','disabled')},
+ prompts={{name='first',description='First',arguments={{name='q',required=true}}}},resources={},templates={}}}
+ fake_manager.states.fast.metadata=initial
+ eager:reconcile(); command_set.reconcile('fast',initial,true)
+ local dotted=config.tool_name('fast','a.b'); local underscored=config.tool_name('fast','a_b')
+ check(dotted~=underscored,'eager sanitizer collision disambiguated')
+ check(tool_specs[dotted] and tool_specs[underscored],'initial eager catalog registered')
+ eq(tool_specs[config.tool_name('fast','disabled_tool')],nil,'disabled eager tool excluded')
+ eq(tool_specs[dotted].handler({value='x'}).text,'called a.b','eager handler maps sanitized name back to MCP name')
+ eq(calls[1].server,'fast'); eq(calls[1].name,'a.b')
+ local changed={catalog={tools={def('a.b','updated','integer'),def('brand_new','new')},
+ prompts={{name='second',title='Second',arguments={{name='text',required=true}}}},resources={},templates={}}}
+ fake_manager.states.fast.metadata=changed
+ eager:reconcile(); command_set.reconcile('fast',changed,false)
+ check(tool_specs[dotted] and tool_specs[dotted].description=='updated','changed eager definition re-registered')
+ eq(tool_specs[dotted].schema.properties.value.type,'integer','changed eager schema replaced')
+ check(tool_specs[config.tool_name('fast','brand_new')],'new eager tool registered')
+ eq(tool_specs[underscored],nil,'removed eager tool unregistered')
+ check(#removed_tools>=4,'removed and changed eager registrations unregistered')
+ eq(command_specs['mcp:fast:first'],nil,'removed prompt command unregistered')
+ check(command_specs['mcp:fast:second'],'new prompt command registered')
+ check(#removed_commands==1,'removed prompt registration reconciled')
+end
+do
+ local warning_command,render_header
+ package.loaded.panto={ext={json=json,config={mcp={servers={bad={url='file://invalid'}}}},dirs={},
+ register_command=function(c) warning_command=c end,
+ on=function(name,fn) if name=='render_header' then render_header=fn end end,
+ style=function() return {dim='',reset=''} end}}
+ dofile(here .. '/init.lua').activate()
+ check(warning_command and warning_command.handler(''):find('Config warning',1,true),'invalid-only config still exposes TUI warnings')
+ local header={render=function() return {'panto'} end}
+ render_header({get_component=function() return header end,set_component=function(_,component) header=component end})
+ eq(table.concat(header:render(80),'\n'),'panto\n mcp: (none)','header excludes invalid servers')
+ package.loaded.panto=saved_panto
+end
+local gate=async.future(); local command
+require('panto_mcp.tools').register({register_tool=function() end,register_command=function(c) command=c end,
+ mount=function() error('refresh must not mount a component') end}, {servers=function() return {} end,refresh=function() return gate:await() end})
+check(command.handler('refresh'):find('started',1,true),'refresh returns started while async work is parked')
+gate:resolve(true)
+local warning_only
+require('panto_mcp.tools').register_status({register_command=function(c) warning_only=c end},{servers=function() return {} end},{'bad server'})
+check(warning_only.handler(''):find('Config warning: bad server',1,true),'status displays config warnings')
+do
+ local tools=require('panto_mcp.tools')
+ local status=tools.status({servers=function() return {{name='remote',state='idle',transport='http',tools=0,prompts=0,resources=0,templates=0,stderr=''}} end},{})
+ check(status:find('HTTP URL',1,true),'status identifies URL transport')
+ local ready,system_hint
+ tools.hint({on=function(name,fn) ready=fn end,agent={add_system_message=function(_,text) system_hint=text end}},
+ {remote={transport='http',expose='search',url='https://secret.example'}})
+ ready(); check(system_hint:find('remote: HTTP URL, search',1,true),'config-only URL hint')
+ check(not system_hint:find('secret.example',1,true),'system hint omits remote URL')
+end
+
+-- Real subprocess integration. A bounded watchdog protects the harness; no
+-- timeout behavior is inferred from elapsed sleeps.
+local integration_error
+local done=false
+local managers={}
+local watchdog=uv.new_timer(); watchdog:start(30000,0,function()
+ integration_error='integration watchdog expired'; for _,m in ipairs(managers) do m:close() end
+ close(watchdog)
+end)
+async.run(function()
+ for _,mode in ipairs({'modern','banner','legacy','legacy-close','tools-only','missing-templates','env-check'}) do
+ local child_env=mode=='env-check' and {PANTO_MCP_TEST_CHILD_ENV='child'} or nil
+ local _,ss=config.parse({servers={fake={command=uv.exepath(),args={'lua',here .. '/_selfcheck.lua','--fake',mode},env=child_env}}},{project_root=here})
+ local m=Manager.new(settings,ss,{cache_dir=temp}); managers[#managers+1]=m
+ local api=namespace.factory(m,{})
+ local one,two=api.start('fake','echo',{message='first'}),api.start('fake','echo',{message='second'})
+ local first=assert(one:await())
+ check(not first.is_error,first.text .. '\n' .. (m.states.fake.client.transport.stderr_tail or ''))
+ eq(first.text,'first',mode .. ' first call'); eq(assert(two:await()).text,'second',mode .. ' concurrent call')
+ eq(m.states.fake.state,'ready'); eq(#m.states.fake.metadata.catalog.tools,2,'pagination')
+ local searched=assert(m:search(nil,{server='fake'}))
+ check(searched.servers[1].stderr==nil,'search omits stderr'); check(m:servers()[1].stderr~=nil,'servers retains stderr')
+ eq(m.states.fake.metadata.era,(mode=='modern' or mode=='banner' or mode=='env-check') and 'modern' or 'legacy','era')
+ check(m:call('fake','echo',{}).is_error,'live schema validation')
+ check(m:call('fake','ecoh',{message='x'}).text:find('echo',1,true),'closest exact name')
+ if mode~='tools-only' then
+ check(m:read_resource('fake','docs://guide').text:find('resource body',1,true),'resource read')
+ eq(#assert(api.prompts('fake')),1); eq(assert(api.prompt('fake','greet',{name='A'}))[1].role,'user')
+ else eq(#m.states.fake.metadata.catalog.resources,0,'unadvertised list skipped') end
+ if mode=='missing-templates' then eq(#m.states.fake.metadata.catalog.templates,0,'unimplemented list is empty') end
+ if mode=='modern' then
+ local changed=async.future()
+ m.opts.on_catalog=function(_,data) if #data.catalog.tools==3 then changed:resolve(true) end end
+ eq(m:call('fake','echo',{message='change'}).text,'change')
+ check(changed:await(),'list_changed relisted')
+ eq(#assert(cache.load(ss.fake,temp)).catalog.tools,3,'list_changed rewrote cache')
+ local _,eager_servers=config.parse({servers={fake={command=uv.exepath(),args={'lua',here .. '/_selfcheck.lua','--fake','modern'},expose='eager'}}},{project_root=here})
+ local dynamic_tools,dynamic_commands={},{}
+ local registration_ext={
+ register_tool=function(spec) dynamic_tools[spec.name]=spec; return true end,
+ unregister_tool=function(name) dynamic_tools[name]=nil; return true end,
+ register_command=function(spec) dynamic_commands[spec.name]=spec; return true end,
+ unregister_command=function(name) dynamic_commands[name]=nil; return true end,
+ }
+ local eager_manager
+ local eager_registration
+ local prompt_registration
+ local catalog_changed=async.future(); local catalog_removed=async.future()
+ eager_manager=Manager.new(settings,eager_servers,{cache_dir=temp,on_catalog=function(server,data)
+ eager_registration:reconcile()
+ prompt_registration.reconcile(server,data,false)
+ if dynamic_tools[config.tool_name('fake','new_tool')] and dynamic_commands['mcp:fake:wave'] then catalog_changed:resolve(true) end
+ if next(dynamic_tools)==nil and dynamic_commands['mcp:fake:wave']==nil then catalog_removed:resolve(true) end
+ end})
+ eager_registration=require('panto_mcp.eager').new(registration_ext,eager_manager)
+ prompt_registration=prompts.commands(registration_ext,eager_manager,{busy=false},true)
+ eq(eager_manager:call('fake','echo',{message='change'}).text,'change','eager manager starts cold server lazily')
+ check(catalog_changed:await(),'connect/list_changed adds eager tool and reconciles prompt')
+ check(dynamic_tools[config.tool_name('fake','echo')] and dynamic_tools[config.tool_name('fake','new_tool')],'new eager catalog registered')
+ eq(dynamic_commands['mcp:fake:greet'],nil,'removed prompt command reconciled on connect')
+ check(dynamic_commands['mcp:fake:wave'],'new prompt command reconciled on connect')
+ eager_manager:call('fake','echo',{message='remove'})
+ check(catalog_removed:await(),'second list_changed removes live eager registrations')
+ eager_manager:close()
+ end
+ m:close()
+ end
+ local _,noisy_config=config.parse({servers={noisy={command=uv.exepath(),args={'lua',here .. '/_selfcheck.lua','--fake','noisy-exit'}}}},{project_root=here})
+ local noisy=Manager.new(settings,noisy_config,{cache_dir=temp}); managers[#managers+1]=noisy
+ local noisy_result=noisy:call('noisy','echo',{})
+ check(noisy_result.is_error and noisy_result.text:find('diagnostic-tail-from-child',1,true),'transport errors include bounded stderr tail')
+ done=true; close(watchdog)
+end,function(err) integration_error=err; for _,m in ipairs(managers) do m:close() end; close(watchdog) end)
+uv.run()
+assert(not integration_error,integration_error); check(done,'integration finished')
+
+-- A server that ignores stdin EOF must still reach TERM/KILL escalation on
+-- ordinary nonblocking transport.close(), not just on parent death.
+local ignored=assert(stdio.new({command=uv.exepath(),args={'lua',here .. '/_selfcheck.lua','--fake','ignore'},env={}}))
+local ignore_poll,ignore_bound=uv.new_timer(),uv.new_timer()
+local ignore_pid,ignore_gone,ignore_error
+ignore_poll:start(0,20,function()
+ if ignored.server_pid and not ignore_pid then ignore_pid=ignored.server_pid; ignored:close() end
+ if ignore_pid and not uv.kill(-ignore_pid,0) then ignore_gone=true; close(ignore_poll); close(ignore_bound) end
+end)
+ignore_bound:start(8000,0,function()
+ ignore_error='EOF-ignoring server exceeded bounded exit wait'
+ if ignore_pid then uv.kill(-ignore_pid,'sigkill') end
+ ignored:close(); close(ignore_poll); close(ignore_bound)
+end)
+uv.run(); assert(not ignore_error,ignore_error); check(ignore_gone,'EOF-ignoring server reaped after close')
+local orphaned=assert(stdio.new({command=uv.exepath(),args={'lua',here .. '/_selfcheck.lua','--fake','ignore'},env={}}))
+local orphan_poll,orphan_bound=uv.new_timer(),uv.new_timer()
+local orphan_pid,supervisor_killed,orphan_gone,orphan_error,supervisor_reason=nil,false,false,nil,nil
+orphaned:set_callbacks(function() end,function(err) supervisor_reason=err end)
+orphan_poll:start(0,20,function()
+ if orphaned.server_pid and not supervisor_killed then
+ orphan_pid=orphaned.server_pid; supervisor_killed=true; orphaned.proc:kill('sigkill')
+ end
+ if orphan_pid and not uv.kill(-orphan_pid,0) then orphan_gone=true; close(orphan_poll); close(orphan_bound) end
+end)
+orphan_bound:start(8000,0,function()
+ orphan_error='orphan survived supervisor death'
+ if orphan_pid then uv.kill(-orphan_pid,'sigkill') end
+ close(orphan_poll); close(orphan_bound)
+end)
+uv.run(); assert(not orphan_error,orphan_error); check(orphan_gone and supervisor_reason and supervisor_reason:find('supervisor exited',1,true),'parent TERM/KILL fallback reaps group after supervisor death')
+local eof=assert(stdio.new({command=uv.exepath(),args={'lua',here .. '/_selfcheck.lua','--fake','exit-on-eof'},env={}}))
+local eof_done,eof_alive,eof_closed,eof_error,eof_reason=false,false,false,nil,nil
+local eof_poll,eof_bound=uv.new_timer(),uv.new_timer()
+eof:set_callbacks(function() end,function(err) eof_reason=err; eof_alive=uv.kill(eof.supervisor_pid,0)~=nil; eof_done=true end)
+eof_poll:start(0,10,function()
+ if eof.server_pid and not eof_closed then eof_closed=true; async.close(eof.stdin) end
+ if eof_done then close(eof_poll); close(eof_bound) end
+end)
+eof_bound:start(5000,0,function() eof_error='server stdout EOF delayed until supervisor exit'; close(eof_poll); close(eof_bound); eof:close() end)
+uv.run(); assert(not eof_error,eof_error); check(eof_done and eof_alive and eof_reason:find('stdout closed',1,true),'supervisor drops fd 0/1 before grace period')
+
+-- S1: parent SIGKILL must close the fourth-fd lifeline and reap the whole
+-- TERM-resistant group, including a grandchild shell/sleep tree.
+local parent_out=uv.new_pipe(false); local parent_err=uv.new_pipe(false)
+local parent,server_pid,orphan_error,parent_exited,group_gone
+local poll=uv.new_timer(); local bound=uv.new_timer()
+local function cleanup()
+ close(poll); close(bound); close(parent_out); close(parent_err); close(parent)
+end
+parent=assert(uv.spawn(uv.exepath(),{args={'lua',here .. '/_selfcheck.lua','--parent'},stdio={nil,parent_out,parent_err},detached=true},function() parent_exited=true; close(parent) end))
+local output=''
+parent_out:read_start(function(e,data)
+ if e then orphan_error=e; cleanup(); return end
+ if data then
+ output=output .. data
+ local pid=tonumber(output:match('SERVER=(%d+)\n'))
+ if pid and not server_pid then server_pid=pid; assert(parent:kill('sigkill')) end
+ end
+end)
+parent_err:read_start(function(e,data) if e then orphan_error=e end; if data then output=output .. data end end)
+poll:start(0,25,function()
+ if server_pid and not uv.kill(-server_pid,0) then group_gone=true; cleanup() end
+end)
+bound:start(8000,0,function()
+ orphan_error='orphan check exceeded bounded exit wait'
+ if server_pid then uv.kill(-server_pid,'sigkill') end
+ pcall(parent.kill,parent,'sigkill'); cleanup()
+end)
+uv.run()
+assert(not orphan_error,orphan_error); check(server_pid and parent_exited and group_gone,'SIGKILL parent tears down server group')
+-- panto lua has no active HTTP service. A scripted provider keeps this token-free.
+-- Set PANTO_MCP_HTTP_E2E=1; PANTO_MCP_PANTO selects the nested test binary.
+local function http_e2e(mode)
+local http_panto=uv.fs_realpath(os.getenv('PANTO_MCP_PANTO') or '/tmp/panto-mcp-work/panto-full')
+assert(http_panto,'HTTP E2E requires /tmp/panto-mcp-work/panto-full (or PANTO_MCP_PANTO)')
+if http_panto then
+ local rig=temp..'/http-rig-'..mode; local extdir=rig..'/fixture'; local data_home=temp..'/http-data-'..mode
+ assert(uv.fs_mkdir(rig,448)); assert(uv.fs_mkdir(extdir,448)); assert(uv.fs_mkdir(data_home,448))
+ local provider=[[local panto=require('panto')
+local json=panto.ext.json
+local function last_results(request)
+ local out={}
+ for _,m in ipairs(request.messages) do
+ for _,b in ipairs(m.blocks or {}) do
+ if b.type=='tool_result' then out[#out+1]=type(b.content)=='string' and b.content or json.encode(b.content) end
+ end
+ end
+ return table.concat(out,'\\n')
+end
+return {name='mcp-http-selfcheck-provider',activate=function()
+ panto.ext.register_protocol{name='mcp-http-selfcheck',open=function(request)
+ local rounds=0
+ for _,m in ipairs(request.messages) do if m.role=='assistant' then rounds=rounds+1 end end
+ local event
+ if rounds==0 then event={type='tool_call',id='http-search',name='mcp.search',input_json=json.encode({server='remote',query='hello'})}
+ elseif rounds==1 then
+ assert(last_results(request):find('hello',1,true),'HTTP tool search did not return hello')
+ event={type='tool_call',id='http-call',name='mcp.call',input_json=json.encode({server='remote',tool='hello'})}
+ else
+ assert(last_results(request):find('HTTP_E2E_TOOL_OK',1,true),'HTTP MCP call did not return expected content')
+ event={type='text_delta',text='HTTP_MCP_E2E_OK'}
+ end
+ local sent=false
+ return {next=function() if sent then return {type='done'} end; sent=true; return event end}
+ end}
+end}]]
+ if mode=='oauth' then
+ provider=[[local panto=require('panto')
+local async=require('panto_mcp.async')
+local json=panto.ext.json
+return {name='mcp-oauth-selfcheck-provider',activate=function()
+ local settings,servers=require('panto_mcp.config').parse(panto.ext.config.mcp,panto.ext.dirs)
+ local manager=require('panto_mcp.manager').new(settings,servers)
+ local commands={}
+ require('panto_mcp.tools').register_status({register_command=function(spec) commands[spec.name]=spec; return true end},manager,{})
+ local function get(url)
+ local future=async.future()
+ assert(panto.ext.http_request({url=url},function(response,err) future:resolve(response,err) end))
+ local response,err=future:await(); assert(response,err); return response
+ end
+ local function ready()
+ local future=async.future(); local attempts=0
+ local function poll()
+ attempts=attempts+1
+ if manager.states.remote.state=='ready' and not manager.states.remote.oauth.login_required and not manager.states.remote.oauth.login_url then future:resolve(true)
+ elseif attempts>=500 then future:resolve(nil,'OAuth reconnect did not finish')
+ else async.timer(20,poll) end
+ end
+ poll(); local ok,err=future:await(); assert(ok,err)
+ end
+ local function authorize(pasted)
+ local future=async.future(); local attempts=0
+ local function login_url()
+ attempts=attempts+1
+ local output=commands['mcp-login'].handler('remote')
+ local url=output:match('\n(http[^%s]+)')
+ if url then future:resolve(url)
+ elseif attempts>=20 then future:resolve(nil,'login URL missing: '..output)
+ else async.timer(1000,login_url) end
+ end
+ login_url(); local url,err=future:await(); assert(url,err)
+ local response=get(url); assert(response.status==302,'authorize did not redirect')
+ local callback=assert(response.headers.location,'missing authorization Location')
+ if pasted then
+ local accepted=commands['mcp-login'].handler('remote '..callback)
+ assert(accepted:find('accepted',1,true),'headless callback not accepted')
+ else assert(get(callback).status==200,'loopback callback failed') end
+ ready()
+ end
+ panto.ext.register_tool{name='oauth-check',description='Exercise real-core MCP OAuth',schema={type='object'},handler=function()
+ local client,err=manager:ensure('remote')
+ assert(not client and err:find('/mcp-login remote',1,true),'initial 401 did not request login')
+ authorize(false)
+ local result=manager:call('remote','hello',{})
+ assert(not result.is_error and result.text:find('HTTP_E2E_TOOL_OK',1,true),'refresh-on-401 failed')
+ result=manager:call('remote','hello',{stepup=true})
+ assert(result.is_error and result.text:find('/mcp-login remote',1,true),'missing scope consent request')
+ authorize(true)
+ result=manager:call('remote','hello',{stepup=true})
+ assert(not result.is_error,'step-up reauthorization failed: '..result.text)
+ manager:close()
+ manager=require('panto_mcp.manager').new(settings,servers)
+ assert(manager.states.remote.oauth.definition,'warm discovery missing')
+ result=manager:call('remote','hello',{})
+ assert(not result.is_error,'warm core session failed')
+ manager:close()
+ return 'HTTP_E2E_TOOL_OK'
+ end}
+ panto.ext.register_protocol{name='mcp-http-selfcheck',open=function(request)
+ local done=false; local completed=false
+ for _,m in ipairs(request.messages) do for _,b in ipairs(m.blocks or {}) do
+ if b.type=='tool_result' then
+ local text=type(b.content)=='string' and b.content or json.encode(b.content)
+ assert(text:find('HTTP_E2E_TOOL_OK',1,true),'OAuth fixture tool failed: '..text); completed=true
+ end
+ end end
+ return {next=function()
+ if done then return {type='done'} end; done=true
+ if completed then return {type='text_delta',text='HTTP_MCP_E2E_OK'} end
+ return {type='tool_call',id='oauth-flow',name='oauth-check',input_json='{}'}
+ end}
+ end}
+end}]]
+ provider='package.path='..string.format('%q',here..'/?.lua;'..here..'/?/init.lua;')..'..package.path\n'..provider
+ end
+ write(extdir..'/provider.lua',provider)
+ local function q(s) return '"'..s:gsub('\\','\\\\'):gsub('"','\\"')..'"' end
+ local served={}; local server_error; local clients={}; local server_timers={}; local handle_client
+ local oauth_seen={prm=0,metadata=0,registration=0,authorize=0,tokens=0,refresh=0,stepup=0}
+ local authorized_scope='read'; local forced_refresh=false
+ local function form(text)
+ local out={}
+ local function decode(v) return (v:gsub('+',' '):gsub('%%(%x%x)',function(hex) return string.char(tonumber(hex,16)) end)) end
+ for key,value in text:gmatch('([^&=?]+)=([^&]*)') do out[decode(key)]=decode(value) end
+ return out
+ end
+ local function escape(text) return (text:gsub('[^A-Za-z0-9_.~-]',function(c) return string.format('%%%02X',c:byte()) end)) end
+ local listener=assert(uv.new_tcp()); assert(listener:bind('127.0.0.1',0)==0)
+ local port=assert(listener:getsockname()).port
+ assert(listener:listen(32,function(accept_err)
+ if accept_err then server_error=tostring(accept_err); return end
+ local client=assert(uv.new_tcp()); local accepted,why=listener:accept(client)
+ if accepted~=0 then server_error=tostring(why or accepted); close(client); return end
+ handle_client(client)
+ end))
+ local config_text=(mode=='slow' and '[mcp]\nidle_timeout_ms = 20\ncall_timeout_ms = 5000\n\n' or '')..
+ '[extensions]\npaths = ['..(mode=='oauth' and '' or q(here)..', ')..q(extdir)..']\n\n'..
+ '[providers.fixture]\nprotocol = "mcp-http-selfcheck"\n\n[defaults]\nmodel = "fixture:dummy"\n\n'..
+ '[mcp.servers.remote]\nurl = '..q('http://127.0.0.1:'..port..'/mcp')..'\n'
+ write(rig..'/config.toml',config_text)
+ local function respond(client,status,body,content_type,session_id,delay_ms,extra_headers)
+ local text=status==200 and 'OK' or status==202 and 'Accepted' or 'Bad Request'
+ local fields='Content-Length: '..#body..'\r\nConnection: close\r\n'
+ if content_type then fields='Content-Type: '..content_type..'\r\n'..fields end
+ if session_id then fields=fields..'Mcp-Session-Id: '..session_id..'\r\n' end
+ for name,value in pairs(extra_headers or {}) do fields=fields..name..': '..value..'\r\n' end
+ local head='HTTP/1.1 '..status..' '..text..'\r\n'..fields..'\r\n'
+ if delay_ms then
+ client:write(head,function(err)
+ if err then server_error=tostring(err); close(client); return end
+ local timer=uv.new_timer(); server_timers[#server_timers+1]=timer
+ timer:start(delay_ms,0,function() close(timer); client:write(body,function() close(client) end) end)
+ end)
+ else client:write(head..body,function() close(client) end) end
+ end
+ handle_client=function(client)
+ clients[#clients+1]=client
+ local raw=''; local answered=false
+ client:read_start(function(read_err,chunk)
+ if answered then return end
+ if read_err then server_error=tostring(read_err); close(client); return end
+ if not chunk then close(client); return end
+ raw=raw..chunk
+ local boundary=raw:find('\r\n\r\n',1,true); if not boundary then return end
+ local head=raw:sub(1,boundary-1); local headers={}
+ local request_method=head:match('^(%S+)')
+ local target=head:match('^%S+ (%S+)')
+ for line in (head..'\r\n'):gmatch('(.-)\r\n') do
+ local name,value=line:match('^([^:]+):%s*(.*)$'); if name then headers[name:lower()]=value end
+ end
+ local body
+ if (headers['transfer-encoding'] or ''):lower():find('chunked',1,true) then
+ local chunks={}; local cursor=boundary+4
+ while true do
+ local line_end=raw:find('\r\n',cursor,true); if not line_end then return end
+ local size=tonumber(raw:sub(cursor,line_end-1),16); if not size then server_error='invalid chunk size'; respond(client,400,'bad request'); return end
+ cursor=line_end+2
+ if size==0 then
+ local trailer_end=raw:find('\r\n\r\n',cursor,true)
+ if trailer_end then cursor=trailer_end+4
+ elseif raw:sub(cursor,cursor+1)=='\r\n' then cursor=cursor+2
+ else return end
+ body=table.concat(chunks); break
+ end
+ if #raw<cursor+size+1 then return end
+ chunks[#chunks+1]=raw:sub(cursor,cursor+size-1); cursor=cursor+size
+ if raw:sub(cursor,cursor+1)~='\r\n' then server_error='invalid chunk framing'; respond(client,400,'bad request'); return end
+ cursor=cursor+2
+ end
+ else
+ local length=tonumber(headers['content-length']) or 0
+ if #raw-boundary-3<length then return end
+ body=raw:sub(boundary+4,boundary+3+length)
+ end
+ answered=true; client:read_stop()
+ if request_method=='DELETE' then respond(client,200,''); return end
+ if mode=='oauth' and target~='/mcp' then
+ local origin='http://127.0.0.1:'..port
+ local function send(value) respond(client,200,json.encode(value),'application/json') end
+ if target=='/meta' then
+ oauth_seen.prm=oauth_seen.prm+1
+ if headers.authorization then server_error='OAuth discovery leaked credentials' end
+ send({resource=origin..'/mcp',authorization_servers={origin..'/tenant'},scopes_supported={'fallback'}})
+ elseif target=='/.well-known/oauth-authorization-server/tenant' then
+ oauth_seen.metadata=oauth_seen.metadata+1
+ send({issuer=origin..'/tenant',authorization_endpoint=origin..'/authorize',token_endpoint=origin..'/token',registration_endpoint=origin..'/register',
+ code_challenge_methods_supported={'S256'},authorization_response_iss_parameter_supported=true})
+ elseif target=='/register' then
+ oauth_seen.registration=oauth_seen.registration+1
+ local registration=json.decode(body)
+ if registration.application_type~='native' or registration.redirect_uris[1]~='http://127.0.0.1/callback' or registration.token_endpoint_auth_method~='none' then server_error='bad DCR metadata' end
+ send({client_id='native-e2e',registration_access_token='DO_NOT_PERSIST_REGISTRATION_TOKEN'})
+ elseif target:match('^/authorize%?') then
+ oauth_seen.authorize=oauth_seen.authorize+1
+ local params=form(target:match('%?(.*)'))
+ if params.client_id~='native-e2e' or params.code_challenge_method~='S256' or not params.code_challenge or #params.code_challenge~=43 or params.resource~=origin..'/mcp' then server_error='bad PKCE/resource authorize params' end
+ if not params.redirect_uri:match('^http://127%.0%.0%.1:%d+/callback$') then server_error='bad loopback redirect URI' end
+ authorized_scope=params.scope
+ respond(client,302,'',nil,nil,nil,{Location=params.redirect_uri..'?code=e2e-code&state='..escape(params.state)..'&iss='..escape(origin..'/tenant')})
+ elseif target=='/token' then
+ oauth_seen.tokens=oauth_seen.tokens+1
+ local params=form(body)
+ if params.resource~=origin..'/mcp' then server_error='missing token resource indicator' end
+ if params.grant_type=='refresh_token' then
+ oauth_seen.refresh=oauth_seen.refresh+1
+ if not params.refresh_token then server_error='missing refresh token' end
+ elseif params.grant_type~='authorization_code' or params.code~='e2e-code' or not params.code_verifier then server_error='bad code exchange' end
+ send({access_token='e2e-access-'..oauth_seen.tokens,refresh_token='e2e-refresh-'..oauth_seen.tokens,token_type='Bearer',expires_in=3600,scope=authorized_scope})
+ else server_error='unexpected OAuth endpoint'; respond(client,404,'') end
+ return
+ end
+ local ok,request=pcall(json.decode,body)
+ if not ok or type(request)~='table' then server_error='invalid JSON request'; respond(client,400,'bad request'); return end
+ served[#served+1]=request.method
+ if mode=='oauth' then
+ if not headers.authorization or (request.method=='tools/call' and not forced_refresh) then
+ if headers.authorization then forced_refresh=true end
+ respond(client,401,'DO_NOT_LOG_ACCESS_TOKEN',nil,nil,nil,{['WWW-Authenticate']='Bearer resource_metadata="http://127.0.0.1:'..port..'/meta", scope="read"'})
+ return
+ end
+ if headers.authorization~='Bearer e2e-access-'..oauth_seen.tokens then server_error='wrong core-injected Bearer' end
+ if request.method=='tools/call' and request.params.arguments.stepup and not authorized_scope:find('write',1,true) then
+ oauth_seen.stepup=oauth_seen.stepup+1
+ respond(client,403,'DO_NOT_LOG_ACCESS_TOKEN',nil,nil,nil,{['WWW-Authenticate']='Bearer error="insufficient_scope", scope="write"'})
+ return
+ end
+ end
+ local result
+ if mode=='legacy' and request.method=='server/discover' then
+ if headers['mcp-protocol-version']~='2026-07-28' or headers['mcp-method']~='server/discover' then server_error='bad modern probe headers' end
+ respond(client,400,'legacy endpoint'); return
+ elseif mode=='legacy' and request.method=='initialize' then
+ if headers['mcp-protocol-version'] or headers['mcp-session-id'] then server_error='legacy initialize carried session metadata' end
+ result={protocolVersion='2024-11-05',capabilities={tools={}}}
+ elseif mode=='legacy' and request.method=='notifications/initialized' then
+ if headers['mcp-protocol-version']~='2024-11-05' or headers['mcp-session-id']~='e2e-session' then server_error='legacy notification missing negotiated headers' end
+ respond(client,202,''); return
+ elseif mode=='legacy' then
+ if headers['mcp-protocol-version']~='2024-11-05' or headers['mcp-session-id']~='e2e-session' or headers['mcp-method'] then server_error='legacy request headers mismatch' end
+ if request.method=='tools/list' then result={tools={{name='hello',description='Say hello',inputSchema={type='object'}}}}
+ elseif request.method=='tools/call' then result={content={{type='text',text='HTTP_E2E_TOOL_OK'}}}
+ else server_error=server_error or ('unexpected legacy method '..tostring(request.method)); result={} end
+ else
+ if headers['mcp-protocol-version']~='2026-07-28' or headers['mcp-method']~=request.method then server_error='missing modern HTTP headers for '..tostring(request.method) end
+ if request.method=='tools/call' and headers['mcp-name']~='hello' then server_error='missing Mcp-Name' end
+ if request.method=='server/discover' then result={resultType='complete',supportedVersions={'2026-07-28'},capabilities={tools={}}}
+ elseif request.method=='tools/list' then result={tools={{name='hello',description='Say hello',inputSchema={type='object'}}}}
+ elseif request.method=='tools/call' then result={content={{type='text',text='HTTP_E2E_TOOL_OK'}}}
+ else server_error=server_error or ('unexpected method '..tostring(request.method)); result={} end
+ end
+ if server_error then respond(client,400,'bad headers'); return end
+ local payload=json.encode({jsonrpc='2.0',id=request.id,result=result})
+ if mode=='sse' then
+ local notification=json.encode({jsonrpc='2.0',method='notifications/progress',params={progress=1}})
+ payload='event: message\r\ndata: '..notification..'\r\n\r\nevent: message\r\ndata: '..payload..'\r\n\r\n'
+ respond(client,200,payload,'text/event-stream')
+ else respond(client,200,payload,'application/json',mode=='legacy' and request.method=='initialize' and 'e2e-session' or nil,
+ mode=='slow' and request.method=='tools/call' and 120 or nil) end
+ end)
+ end
+ local child_out,child_err=uv.new_pipe(false),uv.new_pipe(false)
+ local envmap=uv.os_environ(); envmap.XDG_DATA_HOME=data_home; envmap.XDG_CONFIG_HOME=data_home..'/config'; envmap.PANTO_SESSION_DIR=temp..'/http-sessions'
+ local env={}; for k,v in pairs(envmap) do env[#env+1]=k..'='..v end
+ table.sort(env)
+ local command=assert(uv.new_timer()); local child,child_pid
+ local stdout,stderr='',''; local out_eof,err_eof,exited=false,false,false; local code,signal
+ local future=async.future()
+ local function maybe_done()
+ if exited and out_eof and err_eof then future:resolve({code=code,signal=signal,stdout=stdout,stderr=stderr}) end
+ end
+ child,child_pid=uv.spawn(http_panto,{args={'--print','--incognito','--rig',rig,'--model','fixture:dummy','--','test remote MCP'},cwd=rig,env=env,stdio={nil,child_out,child_err}},function(c,s)
+ exited=true; code=c; signal=s; close(child); maybe_done()
+ end)
+ assert(child,'could not start HTTP print-mode panto: '..tostring(child_pid))
+ child_out:read_start(function(e,d) if e then server_error=tostring(e) end; if d then stdout=stdout..d else out_eof=true; close(child_out); maybe_done() end end)
+ child_err:read_start(function(e,d) if e then server_error=tostring(e) end; if d then stderr=stderr..d else err_eof=true; close(child_err); maybe_done() end end)
+ command:start(30000,0,function()
+ if not exited then server_error='print-mode HTTP integration watchdog expired'; pcall(child.kill,child,'sigkill') end
+ end)
+ async.run(function()
+ local result=future:await(); close(command); close(listener)
+ for _,client in ipairs(clients) do close(client) end
+ for _,timer in ipairs(server_timers) do close(timer) end
+ check(not server_error,'HTTP fake server: '..tostring(server_error))
+ check(result.code==0,'HTTP print-mode exit '..tostring(result.code)..': '..result.stdout..result.stderr)
+ check(result.stdout:find('HTTP_MCP_E2E_OK',1,true),'print-mode MCP tools completed: '..result.stdout..result.stderr)
+ local expected=mode=='legacy' and 'server/discover,initialize,notifications/initialized,tools/list,tools/call' or 'server/discover,tools/list,tools/call'
+ if mode=='oauth' then
+ eq(oauth_seen.prm,1,'OAuth E2E warm/consent login reuse discovery'); eq(oauth_seen.metadata,1,'OAuth E2E AS discovery')
+ eq(oauth_seen.registration,1,'OAuth E2E reuses one public DCR client across consent logins'); eq(oauth_seen.authorize,2,'OAuth E2E consent and scope step-up')
+ eq(oauth_seen.tokens,3,'OAuth E2E code/refresh/code exchanges'); eq(oauth_seen.refresh,1,'OAuth E2E forced refresh exactly once')
+ eq(oauth_seen.stepup,1,'OAuth E2E insufficient scope challenge')
+ check(not (result.stdout..result.stderr):find('e2e%-access%-') and not (result.stdout..result.stderr):find('DO_NOT_LOG',1,true),'OAuth secrets absent from transcript/stderr')
+ local remembered=assert(read(data_home..'/panto/state.toml'),'OAuth state file missing')
+ check(remembered:find('native-e2e',1,true) and not remembered:find('e2e%-access%-') and not remembered:find('DO_NOT_PERSIST',1,true),'OAuth state stores registration, never tokens')
+ local cache_scan=assert(uv.fs_scandir(data_home..'/panto-mcp'))
+ while true do
+ local name=uv.fs_scandir_next(cache_scan); if not name then break end
+ local text=assert(read(data_home..'/panto-mcp/'..name))
+ check(not text:find('e2e%-access%-') and not text:find('e2e%-refresh%-') and not text:find('Authorization',1,true),'OAuth catalog cache contains no credentials')
+ end
+ else check(table.concat(served,',')==expected,mode..' HTTP request sequence') end
+ for _,path in ipairs({rig..'/config.toml',extdir..'/provider.lua'}) do uv.fs_unlink(path) end
+ uv.fs_rmdir(extdir); uv.fs_rmdir(rig)
+ local function remove_tree(path)
+ local scan=uv.fs_scandir(path); if not scan then return end
+ while true do
+ local name=uv.fs_scandir_next(scan); if not name then break end
+ local child_path=path..'/'..name; local stat=uv.fs_lstat(child_path)
+ if stat and stat.type=='directory' then remove_tree(child_path) else uv.fs_unlink(child_path) end
+ end
+ uv.fs_rmdir(path)
+ end
+ remove_tree(data_home); remove_tree(temp..'/http-sessions')
+ end,function(err)
+ server_error=err; close(command); close(listener); if child and not exited then pcall(child.kill,child,'sigkill') end
+ for _,client in ipairs(clients) do close(client) end
+ for _,timer in ipairs(server_timers) do close(timer) end
+ end)
+ uv.run()
+ assert(not server_error,server_error)
+end
+end
+local function eager_print_e2e()
+ local binary=uv.fs_realpath(os.getenv('PANTO_MCP_PANTO') or '/tmp/panto-mcp-work/panto-full')
+ assert(binary,'new-core panto binary missing; set PANTO_MCP_PANTO')
+ local rig=temp..'/eager-print-rig'; local extdir=rig..'/fixture'; local data_home=temp..'/eager-print-data'
+ assert(uv.fs_mkdir(rig,448)); assert(uv.fs_mkdir(extdir,448)); assert(uv.fs_mkdir(data_home,448))
+ local function q(s) return '"'..s:gsub('\\','\\\\'):gsub('"','\\"')..'"' end
+ local provider=[[local panto=require('panto')
+local json=panto.ext.json
+local function tool_result_text(request)
+ local out={}
+ for _,m in ipairs(request.messages) do
+ for _,b in ipairs(m.blocks or {}) do
+ if b.type=='tool_result' then out[#out+1]=type(b.content)=='string' and b.content or json.encode(b.content) end
+ end
+ end
+ return table.concat(out,'\n')
+end
+return {name='mcp-eager-print-provider',activate=function()
+ panto.ext.register_protocol{name='mcp-eager-print',open=function(request)
+ local rounds=0
+ for _,message in ipairs(request.messages) do if message.role=='assistant' then rounds=rounds+1 end end
+ local event
+ if rounds==0 then
+ event={type='tool_call',id='discover-eager',name='mcp.search',input_json=json.encode({server='eager',query='echo'})}
+ elseif rounds==1 then
+ assert(tool_result_text(request):find('echo',1,true),'MCP search did not return eager catalog')
+ local found=false
+ for _,tool in ipairs(request.tools or {}) do if tool.name=='EAGER_TOOL_NAME' then found=true end end
+ assert(found,'post-activation eager tool absent from next provider request')
+ event={type='tool_call',id='call-eager',name='EAGER_TOOL_NAME',input_json=json.encode({message='EAGER_E2E_OK'})}
+ else
+ assert(tool_result_text(request):find('EAGER_E2E_OK',1,true),'eager MCP tool result missing')
+ event={type='text_delta',text='MCP_EAGER_E2E_OK'}
+ end
+ local sent=false
+ return {next=function() if sent then return {type='done'} end; sent=true; return event end}
+ end}
+end}]]
+ write(extdir..'/provider.lua',provider:gsub('EAGER_TOOL_NAME',config.tool_name('eager','echo')))
+ local fake=here..'/_selfcheck.lua'
+ local helper_raw={servers={helper={command='echo',expose='search'}}}
+ local _,helper_servers=config.parse(helper_raw,{project_root=rig})
+ local helper_meta={era='modern',version='2026-07-28',capabilities={tools={}},catalog={tools={},prompts={},resources={},templates={}}}
+ check(cache.save(helper_servers.helper,helper_meta,data_home..'/panto-mcp'),'seed helper cache for print integration')
+ local config_text='[extensions]\npaths = ['..q(here)..', '..q(extdir)..']\n\n'..
+ '[providers.fixture]\nprotocol = "mcp-eager-print"\n\n[defaults]\nmodel = "fixture:dummy"\n\n'..
+ '[mcp.servers.helper]\ncommand = "echo"\nexpose = "search"\n\n'..
+ '[mcp.servers.eager]\ncommand = '..q(uv.exepath())..'\nargs = ["lua", '..q(fake)..', "--fake", "modern"]\nexpose = "eager"\n'
+ write(rig..'/config.toml',config_text)
+ local envmap=uv.os_environ(); envmap.XDG_DATA_HOME=data_home; envmap.XDG_CONFIG_HOME=data_home..'/config'; envmap.PANTO_SESSION_DIR=temp..'/eager-print-sessions'
+ local env={}; for k,v in pairs(envmap) do env[#env+1]=k..'='..v end; table.sort(env)
+ local out_pipe,err_pipe=uv.new_pipe(false),uv.new_pipe(false)
+ local child,child_pid; local stdout,stderr='',''; local exited,out_eof,err_eof=false,false,false; local code
+ local watchdog=uv.new_timer(); local future=async.future()
+ local function finish_if_ready() if exited and out_eof and err_eof then future:resolve({code=code,stdout=stdout,stderr=stderr}) end end
+ child,child_pid=uv.spawn(binary,{args={'--print','--incognito','--rig',rig,'--model','fixture:dummy','--','run eager MCP'},cwd=rig,env=env,stdio={nil,out_pipe,err_pipe}},function(status)
+ exited=true; code=status; close(child); finish_if_ready()
+ end)
+ assert(child,'could not launch new-core panto: '..tostring(child_pid))
+ out_pipe:read_start(function(err,data) if err then stderr=stderr..tostring(err) end; if data then stdout=stdout..data else out_eof=true; close(out_pipe); finish_if_ready() end end)
+ err_pipe:read_start(function(_,data) if data then stderr=stderr..data else err_eof=true; close(err_pipe); finish_if_ready() end end)
+ watchdog:start(30000,0,function() if not exited then stderr=stderr..'print-mode eager integration watchdog expired'; pcall(child.kill,child,'sigkill') end end)
+ local result; local integration_failure
+ async.run(function() result=future:await() end,function(err) integration_failure=err end)
+ uv.run()
+ close(watchdog)
+ assert(not integration_failure,integration_failure)
+ check(result.code==0,'new-core eager print-mode exit '..tostring(result.code)..': '..result.stderr)
+ check(result.stdout:find('MCP_EAGER_E2E_OK',1,true),'post-activation eager tool was visible and callable: '..result.stdout..result.stderr)
+ local function remove_tree(path)
+ local scan=uv.fs_scandir(path); if not scan then return end
+ while true do local name=uv.fs_scandir_next(scan); if not name then break end
+ local child_path=path..'/'..name; local stat=uv.fs_lstat(child_path)
+ if stat and stat.type=='directory' then remove_tree(child_path) else uv.fs_unlink(child_path) end
+ end
+ uv.fs_rmdir(path)
+ end
+ remove_tree(rig); remove_tree(data_home); remove_tree(temp..'/eager-print-sessions')
+end
+if os.getenv('PANTO_MCP_PRINT_E2E')=='1' then eager_print_e2e() end
+if os.getenv('PANTO_MCP_HTTP_E2E')=='1' then
+ local only=os.getenv('PANTO_MCP_HTTP_E2E_MODE')
+ http_e2e('oauth') -- Always exercise the new core, including when this harness uses old panto.
+ for _,mode in ipairs(only and {only} or {'json','sse','legacy','slow'}) do if mode~='oauth' then http_e2e(mode) end end
+end
+print('panto-mcp selfcheck: OK (' .. checks .. ' assertions; HTTP/stdio eras, cache, RPC, eager/prompt reconciliation, validation, resources, namespace, orphan tree)')
+-- Remove only test-owned fixtures, including nested OAuth cache directories.
+local function remove_test_tree(path)
+ local scan=uv.fs_scandir(path); if not scan then return end
+ while true do
+ local name=uv.fs_scandir_next(scan); if not name then break end
+ local child_path=path..'/'..name; local stat=uv.fs_lstat(child_path)
+ if stat and stat.type=='directory' then remove_test_tree(child_path) else uv.fs_unlink(child_path) end
+ end
+ uv.fs_rmdir(path)
+end
+remove_test_tree(temp)
diff --git a/init.lua b/init.lua
new file mode 100644
index 0000000..53c06ef
--- /dev/null
+++ b/init.lua
@@ -0,0 +1,76 @@
+local function install_header(ext,servers)
+ local names={}
+ for name in pairs(servers) do names[#names+1]=name end
+ table.sort(names)
+ local value=#names==0 and '(none)' or table.concat(names,', ')
+ ext.on('render_header',function(ev)
+ local inner=ev:get_component()
+ ev:set_component({render=function(_,width)
+ local colors=ext.style()
+ local lines=inner:render(width)
+ local at=lines[#lines]=='' and #lines or #lines+1
+ table.insert(lines,at,colors.dim .. ' mcp: ' .. value .. colors.reset)
+ return lines
+ end})
+ end)
+end
+
+return {name='mcp',activate=function()
+ local ext=require('panto').ext
+ local config=require('panto_mcp.config')
+ local raw_mcp=ext.config and ext.config.mcp
+ local settings,servers,warnings=config.parse(raw_mcp,ext.dirs)
+ install_header(ext,servers)
+ for _,warning in ipairs(warnings) do io.stderr:write('panto-mcp: ',warning,'\n') end
+ local tools=require('panto_mcp.tools')
+ local prompts=require('panto_mcp.prompts')
+ if not next(servers) then
+ if type(raw_mcp)=='table' then tools.register_status(ext,require('panto_mcp.manager').new(settings,{}),warnings) end
+ return
+ end
+
+ local dynamic_tools=type(ext.unregister_tool)=='function' and type(ext.register_tool)=='function'
+ local dynamic_commands=type(ext.unregister_command)=='function' and type(ext.register_command)=='function'
+ if not dynamic_tools then
+ for _,server in pairs(servers) do
+ if server.expose=='eager' then
+ warnings[#warnings+1]=server.name..': eager not yet supported on this panto build; using search mode'
+ server.expose='search'
+ end
+ end
+ end
+ local search_enabled=false
+ for _,server in pairs(servers) do search_enabled=search_enabled or server.expose=='search' end
+
+ local eager
+ local prompt_commands
+ local turn={busy=false}
+ local resource_registered=search_enabled
+ local manager
+ local function maybe_register_resource(name,metadata)
+ local state=manager.states[name]
+ if not resource_registered and state and state.cfg.expose=='eager'
+ and type(metadata.capabilities)=='table' and type(metadata.capabilities.resources)=='table' then
+ resource_registered=tools.register_resource(ext,manager) or resource_registered
+ end
+ end
+ local function reconcile_catalog(name,metadata,warm)
+ if eager then eager:reconcile() end
+ if prompt_commands then prompt_commands.reconcile(name,metadata,warm) end
+ maybe_register_resource(name,metadata)
+ end
+ manager=require('panto_mcp.manager').new(settings,servers,{on_catalog=function(name,metadata)
+ reconcile_catalog(name,metadata,false)
+ end})
+ eager=require('panto_mcp.eager').new(ext,manager)
+ prompt_commands=prompts.commands(ext,manager,turn,dynamic_commands,warnings)
+ require('panto_mcp.namespace').install(manager)
+ tools.register(ext,manager,warnings,search_enabled,search_enabled)
+ for name,state in pairs(manager.states) do
+ if state.metadata then reconcile_catalog(name,state.metadata,true) end
+ end
+ prompts.track_busy(ext,turn,prompt_commands)
+ tools.hint(ext,servers)
+ ext.on('session_end',function() manager:close() end)
+ manager:start_cold()
+end}
diff --git a/mise.toml b/mise.toml
new file mode 100644
index 0000000..65e47b8
--- /dev/null
+++ b/mise.toml
@@ -0,0 +1,53 @@
+[tasks.check]
+description = "Run the self-check inside panto's interpreter"
+dir = "{{config_root}}"
+run = "panto lua _selfcheck.lua"
+
+[tasks.version]
+description = "Rewrite the rockspec for a new version (then commit it)"
+dir = "{{config_root}}"
+run = """
+set -eu
+NEW="{{arg(name='version')}}"
+set -- ./*.rockspec
+[ "$#" -eq 1 ] || { echo "expected exactly one rockspec, found $#" >&2; exit 1; }
+SPEC="$1"
+PKG="$(sed -n 's/^package = \"\\(.*\\)\"/\\1/p' "$SPEC")"
+NEWSPEC="./$PKG-$NEW-1.rockspec"
+TMP="$(mktemp)"
+sed -e "s/^version = \".*\"/version = \"$NEW-1\"/" \\
+ -e "s/^\\( *\\)tag = \"v[^\"]*\"/\\1tag = \"v$NEW\"/" "$SPEC" > "$TMP"
+mv "$TMP" "$NEWSPEC"
+[ "$SPEC" = "$NEWSPEC" ] || rm -f "$SPEC"
+luarocks lint "$NEWSPEC"
+echo "wrote $NEWSPEC -- commit it, then: mise run release"
+"""
+
+[tasks.release]
+description = "Tag the committed version, push the tag, upload to luarocks.org"
+depends = ["check"]
+dir = "{{config_root}}"
+run = """
+set -eu
+set -- ./*.rockspec
+[ "$#" -eq 1 ] || { echo "expected exactly one rockspec, found $#" >&2; exit 1; }
+SPEC="$1"
+VER="$(sed -n 's/^version = \"\\(.*\\)-[0-9]*\"/\\1/p' "$SPEC")"
+[ -n "$VER" ] || { echo "could not read version from $SPEC" >&2; exit 1; }
+TAG="v$VER"
+REV="${REV:-@-}"
+if ! jj file show -r "$REV" "$SPEC" 2>/dev/null | diff -q - "$SPEC" >/dev/null 2>&1; then
+ echo "$SPEC at $REV differs from the working copy -- commit it first" >&2
+ exit 1
+fi
+if jj tag list | grep -q "^$TAG:"; then
+ echo "tag $TAG already exists -- bump the version first" >&2
+ exit 1
+fi
+jj tag set "$TAG" -r "$REV"
+jj tag list | grep "^$TAG:"
+for remote in $(git remote); do
+ git push "$remote" "$TAG"
+done
+luarocks upload "$SPEC"
+"""
diff --git a/panto-mcp-0.1.0-1.rockspec b/panto-mcp-0.1.0-1.rockspec
new file mode 100644
index 0000000..4d38a4f
--- /dev/null
+++ b/panto-mcp-0.1.0-1.rockspec
@@ -0,0 +1,49 @@
+rockspec_format = "3.0"
+package = "panto-mcp"
+version = "0.1.0-1"
+
+source = {
+ url = "git+https://code.tjp.lol/public/panto-mcp.git",
+ tag = "v0.1.0",
+}
+
+description = {
+ summary = "MCP server tools for panto, over stdio and Streamable HTTP",
+ detailed = [[
+Connect panto to local stdio and remote HTTP Model Context Protocol servers.
+Provides deferred search/call tools, resource reads, prompts and a std.lua namespace.
+]],
+ homepage = "https://code.tjp.lol/public/panto-mcp",
+ license = "MIT",
+ labels = { "ai", "llm", "agent", "panto", "pantograph", "extension", "mcp" },
+}
+
+dependencies = {
+ "lua >= 5.4, < 5.5",
+}
+
+build = {
+ type = "builtin",
+ modules = {
+ ["panto-mcp"] = "init.lua",
+ ["panto_mcp.async"] = "panto_mcp/async.lua",
+ ["panto_mcp.cache"] = "panto_mcp/cache.lua",
+ ["panto_mcp.client"] = "panto_mcp/client.lua",
+ ["panto_mcp.config"] = "panto_mcp/config.lua",
+ ["panto_mcp.docs"] = "panto_mcp/docs.lua",
+ ["panto_mcp.eager"] = "panto_mcp/eager.lua",
+ ["panto_mcp.http"] = "panto_mcp/http.lua",
+ ["panto_mcp.hash"] = "panto_mcp/hash.lua",
+ ["panto_mcp.jsonrpc"] = "panto_mcp/jsonrpc.lua",
+ ["panto_mcp.manager"] = "panto_mcp/manager.lua",
+ ["panto_mcp.namespace"] = "panto_mcp/namespace.lua",
+ ["panto_mcp.oauth"] = "panto_mcp/oauth.lua",
+ ["panto_mcp.prompts"] = "panto_mcp/prompts.lua",
+ ["panto_mcp.results"] = "panto_mcp/results.lua",
+ ["panto_mcp.search"] = "panto_mcp/search.lua",
+ ["panto_mcp.stdio"] = "panto_mcp/stdio.lua",
+ ["panto_mcp.supervisor"] = "panto_mcp/supervisor.lua",
+ ["panto_mcp.tools"] = "panto_mcp/tools.lua",
+ ["panto_mcp.validate"] = "panto_mcp/validate.lua",
+ },
+}
diff --git a/panto_mcp/async.lua b/panto_mcp/async.lua
new file mode 100644
index 0000000..173e6d0
--- /dev/null
+++ b/panto_mcp/async.lua
@@ -0,0 +1,59 @@
+local uv = require('luv')
+local M = {}
+function M.close(h) if h and not h:is_closing() then h:close() end end
+function M.timer(ms, fn)
+ local t = uv.new_timer()
+ t:start(ms, 0, function() M.close(t); fn() end)
+ return t
+end
+function M.resume(co)
+ if coroutine.status(co) ~= 'suspended' then return end
+ local ok, err = coroutine.resume(co)
+ if not ok then io.stderr:write('panto-mcp: ', tostring(err), '\n') end
+end
+-- Futures have many awaiters; awaiting must occur in a yieldable coroutine.
+-- A close guard optionally cancels outstanding work on host interruption.
+function M.future(cancel)
+ local f = { done = false, waiters = {} }
+ function f:resolve(value, err)
+ if self.done then return end
+ self.done, self.value, self.err = true, value, err
+ local waiters = self.waiters; self.waiters = {}
+ for co in pairs(waiters) do M.resume(co) end
+ end
+ function f:abandon(value,err)
+ if self.done then return end
+ self.done,self.value,self.err=true,value,err
+ self.waiters={}
+ end
+ function f:cancel() if not self.done and cancel then cancel() end end
+ function f:await()
+ if not self.done then
+ assert(coroutine.isyieldable(), 'MCP await requires a coroutine')
+ local co = coroutine.running()
+ local guard <close> = setmetatable({}, {__close = function()
+ self.waiters[co] = nil
+ if not self.done then self:cancel() end
+ end})
+ self.waiters[co] = true
+ while not self.done do
+ -- std.lua budgets only active instructions, not parked time.
+ local hook,mask,count=debug.gethook(co)
+ if hook then debug.sethook(co) end
+ coroutine.yield()
+ if hook then debug.sethook(co,hook,mask,count) end
+ end
+ end
+ return self.value, self.err
+ end
+ return f
+end
+function M.run(fn, on_error)
+ local co = coroutine.create(function()
+ local ok, err = xpcall(fn, debug.traceback)
+ if not ok then (on_error or function(e) io.stderr:write(tostring(e), '\n') end)(err) end
+ end)
+ M.resume(co)
+ return co
+end
+return M
diff --git a/panto_mcp/cache.lua b/panto_mcp/cache.lua
new file mode 100644
index 0000000..fb14faa
--- /dev/null
+++ b/panto_mcp/cache.lua
@@ -0,0 +1,95 @@
+local uv = require('luv')
+local json = require('panto').ext.json
+local M = {}
+function M.directory(getenv)
+ getenv = getenv or os.getenv
+ local xdg = getenv('XDG_DATA_HOME')
+ return ((xdg and xdg~='') and xdg or ((getenv('HOME') or '.') .. '/.local/share')) .. '/panto-mcp'
+end
+local function mkdir(path)
+ if uv.fs_stat(path) then return true end
+ local parent = path:match('^(.*)/[^/]+$')
+ if parent and parent~='' then
+ local ok,err=mkdir(parent); if not ok then return nil,err end
+ end
+ local ok,err=uv.fs_mkdir(path, 448)
+ if ok then return true end
+ local stat=uv.fs_stat(path)
+ if stat and stat.type=='directory' then return true end
+ return nil,err
+end
+function M.path(cfg, dir) return (dir or M.directory()) .. '/' .. cfg.name .. '-' .. cfg.fingerprint .. '.json' end
+function M.normalize_catalog(catalog)
+ if type(catalog)~='table' then return nil end
+ local out={}
+ for _,kind in ipairs({'tools','prompts','resources','templates'}) do
+ local items=catalog[kind]
+ if type(items)~='table' then return nil end
+ local clean=json.array({})
+ for _,item in ipairs(items) do
+ if type(item)=='table' then
+ local valid=true
+ for field,value in pairs(item) do if value==json.null then item[field]=nil end end
+ for _,field in ipairs({'name','title','description','uri','uriTemplate','mimeType'}) do
+ if item[field]~=nil and type(item[field])~='string' then valid=false end
+ end
+ if (kind=='tools' or kind=='prompts') and (not item.name or item.name=='') then valid=false end
+ if kind=='tools' and type(item.inputSchema)~='table' then valid=false end
+ if kind=='resources' and not item.uri then valid=false end
+ if kind=='templates' and not item.uriTemplate then valid=false end
+ if valid then clean[#clean+1]=item end
+ end
+ end
+ out[kind]=clean
+ end
+ return out
+end
+function M.load(cfg, dir)
+ local f = io.open(M.path(cfg,dir), 'rb'); if not f then return nil end
+ local text = f:read(16*1024*1024 + 1); f:close()
+ if not text or #text>16*1024*1024 then return nil end
+ local ok, data = pcall(json.decode,text)
+ if not ok or type(data)~='table' or data.fingerprint~=cfg.fingerprint or type(data.catalog)~='table' then return nil end
+ local catalog=M.normalize_catalog(data.catalog)
+ if not catalog then return nil end
+ data.catalog=catalog
+ if data.era~='modern' and data.era~='legacy' then return nil end
+ return data
+end
+local serial = 0
+function M.save(cfg, data, dir)
+ dir = dir or M.directory()
+ local ok,err = mkdir(dir); if not ok then return nil,err end
+ local catalog=M.normalize_catalog(data.catalog)
+ if not catalog then return nil,'invalid cache catalog' end
+ serial=serial+1
+ local path = M.path(cfg,dir)
+ local temp = path .. '.' .. uv.os_getpid() .. '-' .. serial .. '.tmp'
+ local fd; fd,err=uv.fs_open(temp,'wx',384); if not fd then return nil,err end
+ local encoded_ok,text=pcall(json.encode,{fingerprint=cfg.fingerprint, era=data.era,
+ version=data.version, info=data.info, instructions=data.instructions,
+ capabilities=data.capabilities, catalog=catalog})
+ if not encoded_ok then uv.fs_close(fd); uv.fs_unlink(temp); return nil,text end
+ local offset=0
+ while offset<#text do
+ local written; written,err=uv.fs_write(fd,text:sub(offset+1),offset)
+ if not written or written==0 then uv.fs_close(fd); uv.fs_unlink(temp); return nil,err or 'short cache write' end
+ offset=offset+written
+ end
+ uv.fs_close(fd)
+ ok,err=uv.fs_rename(temp,path)
+ if not ok then uv.fs_unlink(temp); return nil,err end
+ local scan=uv.fs_scandir(dir)
+ if scan then
+ while true do
+ local name=uv.fs_scandir_next(scan)
+ if not name then break end
+ local server,fingerprint=name:match('^(.*)%-([0-9a-f]+)%.json$')
+ if server==cfg.name and fingerprint and #fingerprint==8 and name~=path:match('([^/]+)$') then
+ uv.fs_unlink(dir .. '/' .. name)
+ end
+ end
+ end
+ return true
+end
+return M
diff --git a/panto_mcp/client.lua b/panto_mcp/client.lua
new file mode 100644
index 0000000..9d139e1
--- /dev/null
+++ b/panto_mcp/client.lua
@@ -0,0 +1,334 @@
+local rpc = require('panto_mcp.jsonrpc')
+local async = require('panto_mcp.async')
+local json = require('panto').ext.json
+local M = {}; M.__index=M
+M.MODERN='2026-07-28'; M.LEGACY='2025-11-25'; M.VERSION='0.1.0'
+local supported={['2025-11-25']=true,['2025-06-18']=true,['2025-03-26']=true,['2024-11-05']=true}
+local info={name='panto-mcp',version=M.VERSION}
+local function failure(err)
+ if type(err)=='table' then return tostring(err.message or 'RPC error') .. ' (' .. tostring(err.code) .. ')' end
+ return tostring(err)
+end
+local function context(self,method,text)
+ if self.cfg.transport=='http' then return self.cfg.name..' '..method..': '..tostring(text) end
+ return text
+end
+M.error_text=failure
+function M.new(cfg,settings,opts)
+ opts=opts or {}
+ return setmetatable({cfg=cfg,settings=settings,opts=opts,catalog={tools=json.array({}),prompts=json.array({}),resources=json.array({}),templates=json.array({})}},M)
+end
+local function filter_http_tools(self,items)
+ if self.cfg.transport=='http' then return require('panto_mcp.http').filter_tools(items,self.cfg.name) end
+ return items,{}
+end
+function M:open()
+ if self.closed then return nil,'connection closed' end
+ async.close(self.notification_retry_timer); self.notification_retry_timer=nil
+ if self.rpc then self.replacing=true; self.rpc:close(); self.replacing=false end
+ local factory=self.opts.transport_factory or function(cfg,settings)
+ if cfg.transport=='stdio' then return require('panto_mcp.stdio').new(cfg) end
+ if cfg.transport=='http' then
+ local transport,why
+ transport,why=require('panto_mcp.http').new(cfg,settings,{timer_factory=self.opts.timer_factory,
+ oauth=self.opts.oauth,request_fn=self.opts.request_fn,on_notification_stream_end=function(status)
+ if self.transport==transport then self:schedule_notification_stream_retry(status) end
+ end})
+ return transport,why
+ end
+ return nil,'unknown MCP transport'
+ end
+ local transport,err=factory(self.cfg,self.settings)
+ if not transport then
+ if self.cfg.transport=='http' then return nil,self.cfg.name..' connect: '..tostring(err) end
+ return nil,err
+ end
+ self.transport=transport
+ self.rpc=rpc.new(transport,{timeout_ms=self.settings.call_timeout_ms,timer_factory=self.opts.timer_factory,
+ on_notification=function(method) self:notification(method) end,
+ on_error=function(e) if not self.replacing and self.opts.on_error then self.opts.on_error(e) end end})
+ return true
+end
+function M:request(method,params,timeout_ms)
+ params=params or {}
+ local oauth=self.opts.oauth
+ if oauth then
+ local ok,err=oauth:before_request(); if not ok then return nil,err end
+ end
+ if self.era=='legacy' and self.transport and self.transport.protocol_version then self.version=self.transport.protocol_version end
+ if self.legacy_reinit and method~='initialize' then
+ local ok,err=self.legacy_reinit:await(); if not ok then return nil,err end
+ end
+ if self.era=='modern' then
+ params._meta=params._meta or {}
+ params._meta['io.modelcontextprotocol/protocolVersion']=self.version
+ params._meta['io.modelcontextprotocol/clientCapabilities']={}
+ params._meta['io.modelcontextprotocol/clientInfo']=info
+ end
+ local opts={era=self.era,protocol_version=self.version,method=method,
+ name=params.name or params.uri,timeout_ms=timeout_ms,cancel_protocol=method~='initialize'}
+ if method=='tools/call' and self.tool_headers then opts.param_headers=self.tool_headers[params.name] end
+ local function request_once()
+ local value,request_error=self.rpc:request(method,params,opts)
+ if type(request_error)=='string' and request_error:match('^request timed out:') then request_error=context(self,method,request_error) end
+ return value,request_error
+ end
+ local result,err=request_once()
+ local data=type(err)=='table' and type(err.data)=='table' and err.data or nil
+ if oauth and data and data.auth_error then
+ local retry,why=oauth:recover(data)
+ if not retry then return nil,why end
+ result,err=request_once()
+ data=type(err)=='table' and type(err.data)=='table' and err.data or nil
+ if data and data.auth_error then
+ if data.http_status==403 then
+ local _,why=oauth:recover(data)
+ return nil,why
+ end
+ oauth.login_required=not oauth:usable() or nil
+ return nil,oauth.cfg.auth and oauth:configured_error() or oauth:login_error()
+ end
+ end
+ if self.cfg.transport=='http' and self.era=='legacy' and method~='initialize' and data and data.session_expired then
+ if data.session_generation~=nil and self.transport and self.transport.session_generation~=data.session_generation then
+ if self.legacy_reinit then local ok,why=self.legacy_reinit:await(); if not ok then return nil,why end end
+ opts.protocol_version=self.transport.protocol_version or self.version
+ return request_once()
+ end
+ local ok,why=self:reinitialize_legacy(); if not ok then return nil,why end
+ opts.protocol_version=self.version
+ return request_once()
+ end
+ if self.cfg.transport=='http' and self.era=='modern' and method=='tools/call' and type(err)=='table' and err.code==-32020 then
+ local original_error=err
+ local catalog,refresh_err=self:refresh()
+ if not catalog then return nil,refresh_err end
+ local definition
+ for _,tool in ipairs(catalog.tools) do if tool.name==params.name then definition=tool; break end end
+ if not definition then return nil,original_error end
+ local input=params.arguments or {}
+ local valid,validation_errors=require('panto_mcp.validate').check(input,definition.inputSchema)
+ if not valid then
+ return nil,{code=-32602,message=context(self,'tools/call','input validation failed after schema refresh: '..table.concat(validation_errors,'; ')),
+ data={validation_errors=validation_errors,schema=definition.inputSchema}}
+ end
+ opts.param_headers=self.tool_headers[params.name]
+ return request_once()
+ end
+ return result,err
+end
+function M:reinitialize_legacy()
+ local future=self.legacy_reinit
+ if not future then
+ future=async.future(); self.legacy_reinit=future
+ local function failed(err)
+ local why=failure(err)
+ if self.rpc and not self.rpc.closed then self.rpc:fail(why) end
+ future:resolve(nil,why)
+ if self.legacy_reinit==future then self.legacy_reinit=nil end
+ end
+ async.run(function()
+ local result,err=self:handshake('legacy',self.version or M.LEGACY,self.settings.startup_timeout_ms)
+ if result then
+ future:resolve(true); if self.legacy_reinit==future then self.legacy_reinit=nil end
+ else failed(err) end
+ end,function(err) failed(err) end)
+ end
+ return future:await()
+end
+function M:schedule_notification_stream_retry(status)
+ if status==401 then
+ self.notification_retry_stopped=true
+ self.notification_warning='Notification stream rejected (HTTP 401); '..(self.cfg.auth and 'check configured auth' or ('run /mcp-login '..self.cfg.name))
+ async.close(self.notification_retry_timer); self.notification_retry_timer=nil
+ return
+ end
+ if self.notification_retry_stopped then return end
+ if self.closed or self.cfg.expose~='eager' or self.cfg.transport~='http' or self.era~='legacy'
+ or self.version~=M.LEGACY or type(self.capabilities)~='table'
+ or type(self.capabilities.tools)~='table' or self.capabilities.tools.listChanged~=true then return end
+ async.close(self.notification_retry_timer)
+ local timer_factory=self.opts.timer_factory or async.timer
+ self.notification_retry_delay=math.min((self.notification_retry_delay or 500)*2,60000)
+ self.notification_retry_timer=timer_factory(self.notification_retry_delay,function()
+ self.notification_retry_timer=nil
+ if not self.closed and self.transport and self.transport.open_notification_stream then
+ self.transport:open_notification_stream()
+ end
+ end)
+end
+function M:handshake(era,version,timeout)
+ if era=='legacy' and self.cfg.transport=='http' and self.transport and self.transport.close_notification_stream then
+ self.transport:close_notification_stream()
+ self.notification_retry_stopped=nil; self.notification_warning=nil; self.notification_retry_delay=nil
+ async.close(self.notification_retry_timer); self.notification_retry_timer=nil
+ end
+ self.era=era; self.version=version or (era=='modern' and M.MODERN or M.LEGACY)
+ local result,err
+ if era=='modern' then result,err=self:request('server/discover',{},timeout)
+ else
+ result,err=self:request('initialize',{protocolVersion=self.version,capabilities={},clientInfo=info},timeout)
+ if result then
+ if not supported[result.protocolVersion] then return nil,context(self,'initialize','unsupported initialize version: '..tostring(result.protocolVersion)) end
+ self.version=result.protocolVersion
+ local sent,why=self.rpc:notify('notifications/initialized',{}, {era='legacy',protocol_version=self.version})
+ if not sent then return nil,why end
+ if type(sent)=='table' and type(sent.await)=='function' then
+ local accepted,notify_err=sent:await(); if not accepted then return nil,notify_err end
+ end
+ end
+ end
+ if not result then return nil,err end
+ if type(result)~='table' then return nil,context(self,era=='modern' and 'server/discover' or 'initialize','invalid discovery response') end
+ if result.resultType=='input_required' then return nil,context(self,era=='modern' and 'server/discover' or 'initialize','discovery requested unsupported user input') end
+ if era=='legacy' and self.transport and self.transport.protocol_version then self.transport.protocol_version=self.version end
+ self.capabilities=type(result.capabilities)=='table' and result.capabilities or {}
+ self.info=result.serverInfo or (type(result._meta)=='table' and result._meta['io.modelcontextprotocol/serverInfo']) or {}
+ self.instructions=result.instructions
+ if self.cfg.expose=='eager' and self.cfg.transport=='http' and era=='legacy'
+ and self.version==M.LEGACY and type(self.capabilities.tools)=='table'
+ and self.capabilities.tools.listChanged==true and self.transport.open_notification_stream then
+ self.transport:open_notification_stream()
+ end
+ return result
+end
+function M:refresh_stable()
+ local catalog,err
+ repeat
+ self.dirty=false
+ catalog,err=self:refresh()
+ if not catalog then return nil,err end
+ until not self.dirty or self.closed
+ return catalog
+end
+local function real_rejection(err)
+ return type(err)=='table' or (type(err)=='string' and err:find('unsupported initialize version',1,true)~=nil)
+end
+function M:connect(cached)
+ self.closed=false; self.connecting=true
+ local ok,err=self:open(); if not ok then return nil,err end
+ local result
+ if cached then
+ local version=cached.era=='legacy' and M.LEGACY or cached.version
+ result,err=self:handshake(cached.era,version,self.settings.startup_timeout_ms)
+ if result then
+ local catalog; catalog,err=self:refresh_stable()
+ if catalog then self.connecting=false; return true end
+ return nil,err
+ end
+ if self.cfg.transport=='http' then
+ if not require('panto_mcp.http').should_fallback(err) and not (type(err)=='table' and err.code==-32022) then return nil,failure(err) end
+ elseif not real_rejection(err) then return nil,failure(err) end
+ ok,err=self:open(); if not ok then return nil,err end
+ end
+ result,err=self:handshake('modern',M.MODERN,math.min(1500,self.settings.startup_timeout_ms))
+ local modern_probe_error=err
+ if not result and type(err)=='table' and err.code==-32022 then
+ local versions=(type(err.data)=='table' and err.data.supported) or err.supported or {}
+ if type(versions)~='table' then versions={} end
+ local choice
+ for _,v in ipairs(versions) do
+ if v==M.MODERN or supported[v] then choice=v; break end
+ end
+ if choice and choice~=M.MODERN then
+ result,err=self:handshake('legacy',choice,self.settings.startup_timeout_ms)
+ if not result then return nil,failure(err) end
+ elseif self.cfg.transport=='http' then
+ return nil,failure(err)
+ end
+ end
+ if not result and self.cfg.transport=='http' and self.transport and not require('panto_mcp.http').should_fallback(modern_probe_error) then
+ return nil,failure(modern_probe_error)
+ end
+ if not result then
+ -- Some legacy stdio implementations close on a pre-initialize probe.
+ -- Always give initialize a fresh process, with no probe history.
+ ok,err=self:open(); if not ok then return nil,err end
+ result,err=self:handshake('legacy',M.LEGACY,self.settings.startup_timeout_ms)
+ if not result and not self.closed then
+ local initialize_error=err
+ if self.cfg.transport=='stdio' then
+ if self.rpc.closed then ok,err=self:open(); if not ok then return nil,err end end
+ result,err=self:handshake('modern',M.MODERN,self.settings.startup_timeout_ms)
+ if not result then err=initialize_error end
+ end
+ end
+ end
+ if not result then return nil,failure(err) end
+ local catalog; catalog,err=self:refresh_stable()
+ if not catalog then return nil,err end
+ self.connecting=false
+ return true
+end
+function M:list(method,key)
+ local items,cursor,seen=json.array({}),nil,{}
+ local pages=0
+ repeat
+ pages=pages+1
+ if pages>1000 then return nil,context(self,method,'pagination exceeds 1000 pages') end
+ local result,err=self:request(method,{cursor=cursor})
+ if not result then
+ if type(err)=='table' and err.code==-32601 then return items end
+ return nil,failure(err)
+ end
+ if type(result)~='table' or type(result[key])~='table' then return nil,context(self,method,'invalid '..method..' result') end
+ for _,item in ipairs(result[key]) do items[#items+1]=item end
+ if #items>100000 then return nil,context(self,method,'catalog exceeds 100000 entries') end
+ cursor=result.nextCursor
+ if cursor==json.null then cursor=nil end
+ if cursor~=nil then
+ if type(cursor)~='string' or seen[cursor] then return nil,context(self,method,'invalid/repeated pagination cursor') end
+ seen[cursor]=true
+ end
+ until not cursor
+ return items
+end
+function M:refresh()
+ local catalog={tools=json.array({}),prompts=json.array({}),resources=json.array({}),templates=json.array({})}
+ local tool_headers={}
+ for _,entry in ipairs({{'tools','tools/list','tools','tools'}, {'prompts','prompts/list','prompts','prompts'},
+ {'resources','resources/list','resources','resources'}, {'resources','resources/templates/list','resourceTemplates','templates'}}) do
+ if type(self.capabilities[entry[1]])=='table' then
+ local items,err=self:list(entry[2],entry[3]); if not items then return nil,err end
+ if entry[4]=='tools' then items,tool_headers=filter_http_tools(self,items) end
+ catalog[entry[4]]=items
+ end
+ end
+ catalog=require('panto_mcp.cache').normalize_catalog(catalog)
+ if not catalog then return nil,context(self,'catalog','invalid catalog metadata') end
+ self.catalog=catalog
+ self.tool_headers=tool_headers
+ if self.opts.on_catalog then self.opts.on_catalog(self) end
+ return catalog
+end
+function M:notification(method)
+ self.notification_retry_delay=nil
+ if not method:match('^notifications/[a-z]+/list_changed$') then return end
+ if self.closed then return end
+ self.dirty=true
+ if self.connecting or self.refreshing then return end
+ self.refreshing=true
+ async.run(function()
+ repeat
+ self.dirty=false
+ local _,err=self:refresh()
+ if err and self.opts.on_error then self.opts.on_error(err); break end
+ until not self.dirty or self.closed
+ self.refreshing=false
+ end,function(err) self.refreshing=false; if self.opts.on_error then self.opts.on_error(err) end end)
+end
+function M:call(name,input) return self:request('tools/call',{name=name,arguments=input or {}}) end
+function M:read_resource(uri) return self:request('resources/read',{uri=uri}) end
+function M:prompt(name,args) return self:request('prompts/get',{name=name,arguments=args or {}}) end
+function M:metadata()
+ return {era=self.era,version=self.version,info=self.info,instructions=self.instructions,
+ capabilities=self.capabilities,catalog=self.catalog}
+end
+function M:close(abandon)
+ self.closed=true
+ async.close(self.notification_retry_timer); self.notification_retry_timer=nil
+ self.replacing=true
+ if self.rpc then self.rpc:close(abandon) end
+ self.replacing=false
+end
+return M
diff --git a/panto_mcp/config.lua b/panto_mcp/config.lua
new file mode 100644
index 0000000..2a88c9c
--- /dev/null
+++ b/panto_mcp/config.lua
@@ -0,0 +1,176 @@
+local json = require('panto').ext.json
+local M = {}
+local function string_ok(v) return type(v) == 'string' and not v:find('%z') end
+function M.expand(s, root, getenv)
+ return (s:gsub('%${env:([%w_]+)}', function(k) return (getenv or os.getenv)(k) or '' end)
+ :gsub('%${project_root}', function() return root end))
+end
+function M.canonical(v) return json.encode(v) end
+function M.hash(s)
+ local h = 2166136261
+ for i = 1, #s do h = ((h ~ s:byte(i)) * 16777619) & 0xffffffff end
+ return string.format('%08x', h)
+end
+function M.fingerprint(s)
+ return M.hash(M.canonical({url=s.url, command=s.command, args=s.args, env=s.env,
+ cwd=s.cwd, headers=s.headers, auth=s.auth, oauth=s.oauth}))
+end
+local function tool_hash(name) return M.hash(name)..M.hash(name:reverse()) end
+function M.valid_name(s)
+ return type(s)=='string' and s:match('^[A-Za-z0-9_-]+$')~=nil
+ and not s:find('__',1,true) and s:sub(-1)~='_'
+end
+function M.tool_name(server,name)
+ local server_part=server
+ if #server_part>32 then server_part=server_part:sub(1,15)..'-'..tool_hash(server_part) end
+ local prefix='mcp.'..server_part..'.'
+ local stem=name:gsub('[^A-Za-z0-9_-]','_'):gsub('__+','_')
+ local available=64-(#prefix+2)
+ -- Reserve encoded-looking suffixes so a literal name cannot impersonate a sanitized one.
+ if stem:match('%-'..string.rep('%x',16)..'$') then stem=stem..'_' end
+ if stem==name and #stem<=available then return prefix..stem end
+ local suffix='-'..tool_hash(name)
+ stem=stem:sub(1,math.max(1,available-#suffix))
+ return prefix..stem..suffix
+end
+local function list(v, field)
+ if v == nil then return {} end
+ assert(type(v)=='table', field .. ' must be an array')
+ local count = 0
+ for k,x in pairs(v) do
+ assert(type(k)=='number' and k>=1 and k%1==0 and string_ok(x), field .. ' must contain strings')
+ count = count+1
+ end
+ assert(count == #v, field .. ' must be dense')
+ return v
+end
+local function map(v, field)
+ if v == nil then return {} end
+ assert(type(v)=='table', field .. ' must be a table')
+ for k,x in pairs(v) do assert(string_ok(k) and string_ok(x), field .. ' must map strings to strings') end
+ return v
+end
+local forbidden_headers={host=true,connection=true,['content-length']=true,['transfer-encoding']=true,
+ expect=true,upgrade=true,te=true,['keep-alive']=true,['proxy-connection']=true}
+local sensitive_headers={authorization=true,['proxy-authorization']=true,cookie=true,['x-api-key']=true,
+ ['api-key']=true,['x-auth-token']=true,['x-access-token']=true}
+local function loopback_url(url)
+ local authority=url:match('^[Hh][Tt][Tt][Pp]://([^/?#]+)')
+ if not authority then return false end
+ authority=authority:match('@(.+)$') or authority
+ local host
+ if authority:sub(1,1)=='[' then host=authority:match('^(%b[])')
+ else host=authority:match('^([^:]+)') end
+ if not host then return false end
+ local lower=host:lower()
+ if lower=='localhost' or lower=='[::1]' or lower=='::1' then return true end
+ local a,b,c,d=lower:match('^(%d+)%.(%d+)%.(%d+)%.(%d+)$')
+ if not a then return false end
+ for _,octet in ipairs({a,b,c,d}) do if #octet>1 and octet:sub(1,1)=='0' then return false end end
+ a,b,c,d=tonumber(a),tonumber(b),tonumber(c),tonumber(d)
+ return a==127 and b<256 and c<256 and d<256
+end
+local function header_token(s)
+ if type(s)~='string' or s=='' then return false end
+ for i=1,#s do
+ local c=s:sub(i,i)
+ if not c:match('^[A-Za-z0-9]$') and not ("!#$%&'*+-.^_`|~"):find(c,1,true) then return false end
+ end
+ return true
+end
+local function empty_env_expansion(value,getenv)
+ for key in value:gmatch('%${env:([%w_]+)}') do
+ local expanded=(getenv or os.getenv)(key)
+ if expanded==nil or expanded=='' then return true end
+ end
+ return false
+end
+local function glob(pattern, s)
+ local p = pattern:gsub('([%^%$%(%)%%%.%[%]%+%-])', '%%%1'):gsub('%*', '.*'):gsub('%?', '.')
+ return s:match('^' .. p .. '$') ~= nil
+end
+function M.tool_enabled(cfg, name)
+ local enabled = #cfg.enabled_tools == 0
+ for _,p in ipairs(cfg.enabled_tools) do if glob(p,name) then enabled = true end end
+ for _,p in ipairs(cfg.disabled_tools) do if glob(p,name) then return false end end
+ return enabled
+end
+function M.parse(raw, dirs, getenv)
+ local warnings, servers = {}, {}
+ if raw~=nil and type(raw)~='table' then warnings[#warnings+1]='mcp must be a table' end
+ raw = type(raw)=='table' and raw or {}
+ local settings = {}
+ for k,default in pairs({startup_timeout_ms=30000, call_timeout_ms=300000, idle_timeout_ms=60000}) do
+ local v = raw[k] or default
+ if type(v)~='number' or v<1 or v%1~=0 then warnings[#warnings+1]=k .. ': using default'; v=default end
+ settings[k]=v
+ end
+ local root = (dirs and dirs.project_root) or require('luv').cwd()
+ local function expand(v) return M.expand(v, root, getenv) end
+ if raw.servers ~= nil and type(raw.servers)~='table' then warnings[#warnings+1]='servers must be a table'; return settings,servers,warnings end
+ for name, raw_server in pairs(raw.servers or {}) do
+ local ok, s = pcall(function()
+ assert(M.valid_name(name), 'invalid server name')
+ assert(type(raw_server)=='table', 'server must be a table')
+ local r = raw_server
+ assert(r.enabled == nil or type(r.enabled)=='boolean', 'enabled must be boolean')
+ if r.enabled == false then return nil end
+ assert((r.url~=nil) ~= (r.command~=nil), 'configure exactly one of url / command')
+ local c = {name=name, expose=r.expose or 'search', enabled=true}
+ assert(c.expose=='search' or c.expose=='eager', 'expose must be search or eager')
+ for _,k in ipairs({'url','command','cwd','auth'}) do
+ if r[k]~=nil then assert(string_ok(r[k]) and r[k]~='', k .. ' must be a nonempty string'); c[k]=expand(r[k]) end
+ end
+ if c.command then assert(c.command~='', 'command expanded to empty') end
+ if c.url then assert(c.url:match('^https?://'), 'url must use http(s)') end
+ if c.url and c.url:match('^http://') and c.auth and not loopback_url(c.url) then
+ warnings[#warnings+1]=name .. ': named auth on non-loopback HTTP is forbidden; server ignored'
+ return nil
+ end
+ if r.oauth~=nil then
+ assert(c.url and type(r.oauth)=='table', 'oauth requires an HTTP server and a table')
+ c.oauth={scopes=list(r.oauth.scopes,'oauth.scopes')}
+ for _,key in ipairs({'client_id','client_secret','issuer'}) do
+ if r.oauth[key]~=nil then
+ assert(string_ok(r.oauth[key]) and r.oauth[key]~='', 'oauth.'..key..' must be a nonempty string')
+ c.oauth[key]=expand(r.oauth[key])
+ assert(c.oauth[key]~='', 'oauth.'..key..' expanded to empty')
+ end
+ end
+ assert(not c.oauth.client_secret or c.oauth.client_id, 'oauth.client_secret requires client_id')
+ assert(not c.oauth.client_id or c.oauth.issuer, 'oauth.client_id requires oauth.issuer')
+ end
+ c.args={}; for _,v in ipairs(list(r.args,'args')) do c.args[#c.args+1]=expand(v) end
+ c.env={}; for k,v in pairs(map(r.env,'env')) do
+ assert(k~='' and not k:find('=',1,true), 'invalid environment name'); c.env[k]=expand(v)
+ end
+ c.headers={}
+ for k,v in pairs(map(r.headers,'headers')) do
+ local lower=k:lower()
+ if not header_token(k) then warnings[#warnings+1]=name .. ': invalid HTTP header name ignored'
+ elseif forbidden_headers[lower] or (lower=='authorization' and c.auth~=nil) then warnings[#warnings+1]=name .. ': core-forbidden HTTP header ignored'
+ elseif c.url and c.url:match('^http://') and not loopback_url(c.url) and sensitive_headers[lower] then
+ warnings[#warnings+1]=name .. ': sensitive header on non-loopback HTTP ignored'
+ elseif empty_env_expansion(v,getenv) then warnings[#warnings+1]=name .. ': header has an empty env expansion and was ignored'
+ else
+ local value=expand(v)
+ if (k..value):find('[\r\n]') then warnings[#warnings+1]=name .. ': unsafe HTTP header ignored'
+ else c.headers[k]=value end
+ end
+ end
+ c.enabled_tools=list(r.enabled_tools,'enabled_tools'); c.disabled_tools=list(r.disabled_tools,'disabled_tools')
+ c.cwd=c.cwd or root
+ if c.cwd:sub(1,1)~='/' then c.cwd=root .. '/' .. c.cwd end
+ c.transport=c.url and 'http' or 'stdio'
+ c.fingerprint=M.fingerprint(c)
+ return c
+ end)
+ if not ok then warnings[#warnings+1]=tostring(name) .. ': ' .. tostring(s)
+ elseif s then
+ servers[name]=s
+
+ end
+ end
+ return settings, servers, warnings
+end
+return M
diff --git a/panto_mcp/docs.lua b/panto_mcp/docs.lua
new file mode 100644
index 0000000..af726d3
--- /dev/null
+++ b/panto_mcp/docs.lua
@@ -0,0 +1,43 @@
+return {
+ discovery = [[MCP code mode (also available to child agents)
+mcp.servers() -> array {name,transport,mode,era,version,state,auth?,error,notification_warning?,tools,prompts,resources,templates,stderr}
+Transport is stdio or an HTTP URL. HTTP uses modern 2026-07-28 POST with JSON/SSE, falling back to supported legacy session revisions (2025-11-25, 2025-06-18, or 2025-03-26); it requires panto's POST/streaming http_request API. Configure url, optional static headers, and auth = "<session>" on the server. Valid HTTP tool schemas may annotate primitive parameters with x-mcp-header; matching values are mirrored as safe Mcp-Param-* headers, and tools with invalid annotations are excluded. Secrets should use named auth; headers are never shown by status.
+mcp.search(query?, {server?,limit?}) -> {hits,total,instructions?,servers}, or nil,error.
+Search warm metadata without starting servers. Cold catalogs wait for bounded startup.
+Hits are tools/resources/templates, with server, name, description and full inputSchema.
+Search is the default exposure mode; `expose = "eager"` opts in to cached
+`mcp.<server>.<tool>` tools at activation and cold-catalog reconciliation.
+Eager tool names are sanitized, stable per MCP name, and capped at 64 provider-wire bytes. Older panto
+builds without dynamic tool registration fall back to search mode.
+Use exact server/tool names from search; calls never execute fuzzy matches.
+return mcp.search("read file", {server="fs",limit=5})]],
+ auth = [[HTTP OAuth: /mcp-login <server> [callback-url | --reregister]; /mcp shows status. Preparation is async; explicit auth wins.
+Optional oauth.issuer pins discovery; client_id requires it. Public DCR registrations survive failures; --reregister explicitly replaces one. Sessions use SHA-256 identity hashes.
+401 refreshes once (parallel calls wait); scope consent keeps working tokens usable. See README for storage, recovery and provider limits.]],
+ calls = [[mcp.call(server,tool,input?) -> {text,attachments,structured?,is_error}.
+Validates against LIVE inputSchema after lazy connection; failed servers retry next use.
+Validation failures include validation_errors and schema. Attachments contain raw data bytes
+and media_type. Output text is capped at 100 KiB with a truncation marker; images are
+capped at 5 MiB each / 10 MiB total. RPC/tool/input_required failures set is_error=true.
+local h1=mcp.start("fs","read_text_file",{path="/allowed/a"})
+local h2=mcp.start("fs","read_text_file",{path="/allowed/b"})
+return {h1:await(), h2:await()}
+A start handle also supports :cancel(); :await() returns nil,error on cancellation.
+Await only from the std.lua script coroutine, never from a non-yielding TUI callback.
+No polling or sleeps. Calls time out at the configured deadline; progress never extends it.]],
+ resources = [[mcp.read_resource(server,uri) -> same mapped result as mcp.call.
+A resource_link names its originating server: read there, not with web.fetch.
+Fill resource template variables to form a concrete URI before reading.
+return mcp.read_resource("catalog", "docs://guide")
+No subscriptions; resources/list and resources/templates/list are cached/searchable.]],
+ prompts = [[mcp.prompts(server) -> prompt definitions, or nil,error.
+mcp.prompt(server,name,args?) -> messages [{role,content}], or nil,error.
+Args must be string-valued. These namespace methods return data only.
+Each prompt is also registered as `/mcp:<server>:<prompt>`; pass `name=value`
+tokens with shell-style quoting, or a single raw trimmed remainder when no
+matching `name=` token appears. Prompts with slash/whitespace names are skipped
+and shown in `/mcp` warnings. Commands return immediately; asynchronous failures
+show above the input until the next command or turn. A trailing user message is submitted;
+an assistant tail is appended and wakes idle conversation sync without a turn.
+Messages retain user/assistant roles, and media is text for assistant or unsupported image/non-image content.]],
+}
diff --git a/panto_mcp/eager.lua b/panto_mcp/eager.lua
new file mode 100644
index 0000000..30dd400
--- /dev/null
+++ b/panto_mcp/eager.lua
@@ -0,0 +1,60 @@
+local json = require('panto').ext.json
+local config = require('panto_mcp.config')
+
+local M = {}
+local function log(err)
+ io.stderr:write('panto-mcp: registration: ', tostring(err), '\n')
+end
+local function invoke(ext, method, name)
+ local ok, value, err = pcall(ext[method], name)
+ if not ok then log(value); return false end
+ if not value then log(err or (method .. ' failed for ' .. name)); return false end
+ return true
+end
+local function tool_spec(manager, server, tool, wire_name)
+ return {
+ name = wire_name,
+ description = tool.description or tool.title or ('MCP tool ' .. tool.name .. ' on ' .. server),
+ schema = tool.inputSchema,
+ handler = function(input)
+ local result = manager:call(server, tool.name, input)
+ if result.is_error then error(result.text, 0) end
+ return {text=result.text, attachments=result.attachments}
+ end,
+ }
+end
+function M.new(ext, manager)
+ local self = {ext=ext, manager=manager, tools={}}
+ function self:reconcile()
+ if type(ext.unregister_tool) ~= 'function' then return end
+ local wanted = {}
+ for server, state in pairs(manager.states) do
+ if state.cfg.expose == 'eager' then
+ for _,tool in ipairs((state.metadata and state.metadata.catalog and state.metadata.catalog.tools) or {}) do
+ if config.tool_enabled(state.cfg,tool.name) then
+ local wire=config.tool_name(server,tool.name)
+ local fingerprint=json.encode({description=tool.description,title=tool.title,schema=tool.inputSchema})
+ wanted[wire]={server=server,name=tool.name,tool=tool,fingerprint=fingerprint}
+ end
+ end
+ end
+ end
+ for wire, old in pairs(self.tools) do
+ local current = wanted[wire]
+ if not current or current.fingerprint ~= old.fingerprint or current.server ~= old.server or current.name ~= old.name then
+ if invoke(ext, 'unregister_tool', wire) then self.tools[wire] = nil end
+ end
+ end
+ for wire, current in pairs(wanted) do
+ if not self.tools[wire] then
+ local spec = tool_spec(manager, current.server, current.tool, wire)
+ local ok, value, err = pcall(ext.register_tool, spec)
+ if ok and value then
+ self.tools[wire] = current
+ else log(ok and (err or ('register_tool failed for ' .. wire)) or value) end
+ end
+ end
+ end
+ return self
+end
+return M
diff --git a/panto_mcp/hash.lua b/panto_mcp/hash.lua
new file mode 100644
index 0000000..7ba2438
--- /dev/null
+++ b/panto_mcp/hash.lua
@@ -0,0 +1,41 @@
+-- SHA-256 over bytes, returning lowercase hexadecimal (Lua 5.4 integers).
+local M = {}
+local K={
+ 0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,
+ 0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,
+ 0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,
+ 0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,
+ 0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,
+ 0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,
+ 0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,
+ 0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2,
+}
+local function rotate(x,n) return ((x>>n)|(x<<(32-n))) & 0xffffffff end
+function M.sha256(bytes)
+ local size=#bytes
+ bytes=bytes..'\128'..string.rep('\0',(55-size)%64)..string.pack('>I8',size*8)
+ local h={0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19}
+ for offset=1,#bytes,64 do
+ local w={}
+ for i=1,16 do w[i]=string.unpack('>I4',bytes,offset+(i-1)*4) end
+ for i=17,64 do
+ local x,y=w[i-15],w[i-2]
+ local s0=rotate(x,7) ~ rotate(x,18) ~ (x>>3)
+ local s1=rotate(y,17) ~ rotate(y,19) ~ (y>>10)
+ w[i]=(w[i-16]+s0+w[i-7]+s1)&0xffffffff
+ end
+ local a,b,c,d,e,f,g,z=table.unpack(h)
+ for i=1,64 do
+ local s1=rotate(e,6) ~ rotate(e,11) ~ rotate(e,25)
+ local choice=(e&f) ~ ((~e)&g)
+ local t1=(z+s1+choice+K[i]+w[i])&0xffffffff
+ local s0=rotate(a,2) ~ rotate(a,13) ~ rotate(a,22)
+ local majority=(a&b) ~ (a&c) ~ (b&c)
+ z,g,f,e,d,c,b,a=g,f,e,(d+t1)&0xffffffff,c,b,a,(t1+s0+majority)&0xffffffff
+ end
+ for i,v in ipairs({a,b,c,d,e,f,g,z}) do h[i]=(h[i]+v)&0xffffffff end
+ end
+ local out={}; for i,v in ipairs(h) do out[i]=string.format('%08x',v) end
+ return table.concat(out)
+end
+return M
diff --git a/panto_mcp/http.lua b/panto_mcp/http.lua
new file mode 100644
index 0000000..206e2d5
--- /dev/null
+++ b/panto_mcp/http.lua
@@ -0,0 +1,680 @@
+local json = require('panto').ext.json
+local async = require('panto_mcp.async')
+local M = {}
+local Transport = {}; Transport.__index = Transport
+local MAX_BODY,MAX_ERROR_BODY,FIRE_TIMEOUT_MS=16*1024*1024,1024,10000
+local method_support=setmetatable({}, {__mode='k'})
+
+local function cancel_handle(handle)
+ if handle and type(handle.cancel)=='function' then pcall(handle.cancel,handle) end
+end
+local function newer_error()
+ return 'URL MCP servers require a newer panto with HTTP POST and streaming support'
+end
+M.newer_error=newer_error
+function M.methods_supported(request_fn)
+ if type(request_fn)~='function' then return false end
+ local cached=method_support[request_fn]
+ if cached~=nil then return cached end
+ -- A supported API rejects OPTIONS during parsing, before opening a socket.
+ local ok,handle,err=pcall(request_fn,{url='http://127.0.0.1:1/',method='OPTIONS',timeout_ms=1},function() end)
+ local supported=ok and not handle and type(err)=='string' and err:find('invalid HTTP request options',1,true)~=nil
+ if handle then cancel_handle(handle) end
+ method_support[request_fn]=not not supported
+ return not not supported
+end
+
+local function header_value(headers,name)
+ local value=headers and headers[name:lower()]
+ if type(value)=='table' then return value[1] end
+ return value
+end
+local function set_header(out,lower,name,value)
+ local key=name:lower()
+ if lower[key] then out[lower[key]]=nil end
+ lower[key]=name; out[name]=value
+end
+local function remove_header(out,lower,name)
+ local key=name:lower()
+ if lower[key] then out[lower[key]]=nil; lower[key]=nil end
+end
+local function b64(value)
+ local alphabet='ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+ local out={}
+ for i=1,#value,3 do
+ local a,b,c=value:byte(i,i+2); b=b or 0; c=c or 0
+ local n=(a<<16)|(b<<8)|c
+ out[#out+1]=alphabet:sub(((n>>18)&63)+1,((n>>18)&63)+1)
+ out[#out+1]=alphabet:sub(((n>>12)&63)+1,((n>>12)&63)+1)
+ out[#out+1]=i+1<=#value and alphabet:sub(((n>>6)&63)+1,((n>>6)&63)+1) or '='
+ out[#out+1]=i+2<=#value and alphabet:sub((n&63)+1,(n&63)+1) or '='
+ end
+ return table.concat(out)
+end
+local function encode_value(value)
+ local safe=not (value:match('^[ \t]') or value:match('[ \t]$') or
+ (value:sub(1,9)=='=?base64?' and value:sub(-2)=='?='))
+ if safe then
+ for i=1,#value do local b=value:byte(i); if not (b==9 or b==32 or (b>=33 and b<=126)) then safe=false; break end end
+ end
+ if safe then return value end
+ return '=?base64?'..b64(value)..'?='
+end
+M.encode_header_value=encode_value
+
+local tchar={}
+for c in ('!#$%&\'*+-.^_`|~'):gmatch('.') do tchar[c]=true end
+local function valid_token(value)
+ if type(value)~='string' or value=='' then return false end
+ for i=1,#value do
+ local b=value:byte(i)
+ if not ((b>=48 and b<=57) or (b>=65 and b<=90) or (b>=97 and b<=122) or tchar[value:sub(i,i)]) then return false end
+ end
+ return true
+end
+function M.validate_param_headers(schema)
+ local found,seen,reason={}, {}, nil
+ local total,reachable=0,0
+ local instance_data={enum=true,const=true,default=true,examples=true}
+ local function reject(text) reason=reason or text end
+ local function count(value)
+ if type(value)~='table' then return end
+ if value['x-mcp-header']~=nil then total=total+1 end
+ for key,child in pairs(value) do
+ if key=='properties' or key=='patternProperties' or key=='dependentSchemas' or key=='dependencies' or key=='$defs' or key=='definitions' then
+ if type(child)=='table' then for _,nested in pairs(child) do count(nested) end end
+ elseif not instance_data[key] then count(child) end
+ end
+ end
+ local function get_type(value)
+ local types={}
+ if type(value)=='string' then types[1]=value
+ elseif type(value)=='table' then
+ local n=0
+ for k,t in pairs(value) do
+ if type(k)~='number' or k<1 or k%1~=0 or type(t)~='string' then return nil end
+ n=n+1; types[#types+1]=t
+ end
+ if n~=#value then return nil end
+ else return nil end
+ local base
+ for _,t in ipairs(types) do
+ if t~='null' then
+ if base then return nil end
+ base=t
+ end
+ end
+ if base=='string' or base=='integer' or base=='boolean' then return base end
+ return nil
+ end
+ local function walk(node,path,reachable_path)
+ if type(node)~='table' then return end
+ local name=node['x-mcp-header']
+ if name~=nil and reachable_path then
+ reachable=reachable+1
+ local primitive=get_type(node.type)
+ if #path==0 then reject('x-mcp-header must annotate a parameter property')
+ elseif not valid_token(name) then reject('x-mcp-header must be an HTTP token')
+ elseif not primitive then reject('x-mcp-header requires string, integer, or boolean')
+ else
+ local key=name:lower()
+ if seen[key] then reject('x-mcp-header names must be case-insensitively unique')
+ else seen[key]=true; found[#found+1]={name=name,path=path,type=primitive} end
+ end
+ end
+ local properties=node.properties
+ if type(properties)=='table' then
+ for property,child in pairs(properties) do
+ if type(property)=='string' and type(child)=='table' then
+ local nested={}; for i,v in ipairs(path) do nested[i]=v end; nested[#nested+1]=property
+ walk(child,nested,reachable_path)
+ elseif type(child)=='table' then walk(child,path,false) end
+ end
+ end
+ end
+ count(schema); walk(schema,{},true)
+ if total~=reachable then reject('x-mcp-header is not statically reachable through properties') end
+ if reason then return nil,reason end
+ return found
+end
+function M.filter_tools(tools,server,quiet)
+ local filtered,headers=json.array({}),{}
+ for _,tool in ipairs(tools or {}) do
+ local annotations,why=M.validate_param_headers(type(tool)=='table' and tool.inputSchema or nil)
+ if annotations then
+ filtered[#filtered+1]=tool
+ if #annotations>0 and type(tool)=='table' and type(tool.name)=='string' then headers[tool.name]=annotations end
+ else
+ local name=type(tool)=='table' and tostring(tool.name or '?') or '?'
+ name=name:gsub('[%z\1-\31\127]','?'):sub(1,100)
+ if not quiet then io.stderr:write('panto-mcp: ',tostring(server),': excluded tool ',name,': invalid x-mcp-header (',why,')\n') end
+ end
+ end
+ return filtered,headers
+end
+local function param_value(spec,arguments)
+ local value=arguments
+ for _,key in ipairs(spec.path) do if type(value)~='table' then return nil end; value=value[key] end
+ if value==nil or value==json.null then return nil end
+ if spec.type=='string' then
+ if type(value)~='string' then return nil,'must be a string' end
+ elseif spec.type=='boolean' then
+ if type(value)~='boolean' then return nil,'must be a boolean' end
+ value=value and 'true' or 'false'
+ elseif spec.type=='integer' then
+ if type(value)~='number' or value%1~=0 or math.abs(value)>9007199254740991 then return nil,'must be a safe integer' end
+ value=string.format('%.0f',value)
+ else return nil,'has an unsupported annotated type' end
+ return encode_value(value)
+end
+M.parameter_value=param_value
+function M.headers(cfg,opts,session_id)
+ opts=opts or {}
+ local out,lower={},{}
+ for name,value in pairs(cfg.headers or {}) do set_header(out,lower,name,value) end
+ set_header(out,lower,'Accept','application/json, text/event-stream')
+ set_header(out,lower,'Content-Type','application/json')
+ if opts.era=='modern' then
+ remove_header(out,lower,'Mcp-Session-Id')
+ set_header(out,lower,'MCP-Protocol-Version',opts.protocol_version or '2026-07-28')
+ set_header(out,lower,'Mcp-Method',opts.method or '')
+ remove_header(out,lower,'Mcp-Name')
+ if opts.method=='tools/call' or opts.method=='resources/read' or opts.method=='prompts/get' then
+ if type(opts.name)~='string' then return nil,'Mcp-Name requires a string value' end
+ set_header(out,lower,'Mcp-Name',encode_value(opts.name))
+ end
+ if opts.method=='tools/call' then
+ for _,spec in ipairs(opts.param_headers or {}) do
+ local value,err=param_value(spec,opts.arguments)
+ if err then return nil,'annotated parameter '..table.concat(spec.path,'.')..' '..err end
+ if value~=nil then set_header(out,lower,'Mcp-Param-'..spec.name,value) end
+ end
+ end
+ elseif opts.initial then
+ remove_header(out,lower,'MCP-Protocol-Version'); remove_header(out,lower,'Mcp-Session-Id')
+ remove_header(out,lower,'Mcp-Method'); remove_header(out,lower,'Mcp-Name')
+ else
+ remove_header(out,lower,'Mcp-Method'); remove_header(out,lower,'Mcp-Name')
+ set_header(out,lower,'MCP-Protocol-Version',opts.protocol_version or '2025-11-25')
+ if session_id then set_header(out,lower,'Mcp-Session-Id',session_id) end
+ end
+ return out
+end
+
+-- Processes each input byte once; only the current line and event are retained.
+function M.sse_parser(on_event,max_bytes)
+ local line_parts,data_lines,line_bytes,event_bytes= {},{},0,0
+ local event_type,skip_lf,bom_started,bom_pending=nil,false,false,''
+ max_bytes=max_bytes or MAX_BODY
+ local function append_line(part)
+ if part~='' then line_parts[#line_parts+1]=part; line_bytes=line_bytes+#part end
+ if line_bytes>max_bytes then error('SSE line exceeds size limit',0) end
+ end
+ local function dispatch_event()
+ if #data_lines>0 then
+ local data=table.concat(data_lines,'\n')
+ if data~='' and (event_type==nil or event_type=='' or event_type=='message') then on_event(data,event_type) end
+ end
+ data_lines={}; event_type=nil; event_bytes=0
+ end
+ local function process_line()
+ local value=table.concat(line_parts); line_parts={}; line_bytes=0
+ if value=='' then dispatch_event(); return end
+ if value:sub(1,1)==':' then return end
+ local colon=value:find(':',1,true); local field,content
+ if colon then field,content=value:sub(1,colon-1),value:sub(colon+1); if content:sub(1,1)==' ' then content=content:sub(2) end
+ else field,content=value,'' end
+ if field=='data' then
+ event_bytes=event_bytes+#content+1
+ if event_bytes>max_bytes then error('SSE event exceeds size limit',0) end
+ data_lines[#data_lines+1]=content
+ elseif field=='event' then event_type=content end
+ end
+ local function process(chunk)
+ local i=1
+ if skip_lf then
+ if chunk=='' then return end
+ if chunk:sub(1,1)=='\n' then i=2 end
+ skip_lf=false
+ end
+ while i<=#chunk do
+ local at=chunk:find('[\r\n]',i)
+ if not at then append_line(chunk:sub(i)); break end
+ append_line(chunk:sub(i,at-1))
+ local is_cr=chunk:sub(at,at)=='\r'
+ if is_cr and chunk:sub(at+1,at+1)=='\n' then i=at+2
+ else i=at+1; if is_cr and i>#chunk then skip_lf=true end end
+ process_line()
+ end
+ end
+ local parser={}
+ function parser:feed(chunk)
+ if type(chunk)~='string' then return nil,'invalid SSE chunk' end
+ if not bom_started then
+ bom_pending=bom_pending..chunk
+ if #bom_pending<3 then return true end
+ if bom_pending:sub(1,3)=='\239\187\191' then bom_pending=bom_pending:sub(4) end
+ chunk=bom_pending; bom_pending=''; bom_started=true
+ end
+ local ok,err=pcall(process,chunk); if not ok then return nil,err end
+ return true
+ end
+ function parser:finish()
+ if not bom_started then
+ local chunk=bom_pending; bom_pending=''; bom_started=true
+ if chunk:sub(1,3)=='\239\187\191' then chunk=chunk:sub(4) end
+ local ok,err=pcall(process,chunk); if not ok then return nil,err end
+ end
+ if #line_parts>0 then local ok,err=pcall(process_line); if not ok then return nil,err end end
+ local ok,err=pcall(dispatch_event); if not ok then return nil,err end
+ return true
+ end
+ return parser
+end
+
+local function decode_message(body)
+ if not body or body=='' then return nil end
+ local ok,msg=pcall(json.decode,body)
+ if ok and type(msg)=='table' then return msg end
+ return nil
+end
+local function is_sse(headers)
+ local value=header_value(headers,'content-type')
+ return type(value)=='string' and value:lower():match('^%s*text/event%-stream')~=nil
+end
+local function escaped_pattern(value) return value:gsub('([^%w])','%%%1') end
+local function redact(text,headers)
+ text=text or ''
+ for name,value in pairs(headers or {}) do
+ if type(value)=='string' and value~='' then
+ text=text:gsub(escaped_pattern(value),'[redacted]')
+ if name:lower()=='authorization' then
+ local token=value:match('^%s*%S+%s+(%S+)%s*$')
+ if token and token~='' then text=text:gsub(escaped_pattern(token),'[redacted]') end
+ end
+ end
+ end
+ return text:sub(1,MAX_ERROR_BODY)
+end
+local function prefix_error(server,method,text)
+ return tostring(server)..' '..tostring(method or 'HTTP')..': '..tostring(text)
+end
+local function failure_kind(err)
+ local text=tostring(err or '')
+ if text:match('^on_head callback failed:') or text:match('^on_data callback failed:') then return 'callback' end
+ if text=='timeout' then return 'timeout' end
+ if text=='idle timeout' then return 'idle_timeout' end
+ return 'transport'
+end
+M.failure_kind=failure_kind
+function M.should_fallback(err)
+ if type(err)=='table' then
+ local data=type(err.data)=='table' and err.data or {}
+ if data.session_expired or data.auth_error or data.http_status==401 or data.http_status==403 then return false end
+ if err.code==-32020 or err.code==-32021 or err.code==-32022 or data.supported then return false end
+ if data.http_status then return data.transport_fallback==true end
+ if data.transport_error=='timeout' or data.transport_error=='idle_timeout' then return true end
+ return false
+ end
+ local kind=failure_kind(err)
+ return kind=='timeout' or kind=='idle_timeout' or (type(err)=='string' and
+ (err:match('^request timed out:')~=nil or err:match('^[^%s]+ [^:]+: request timed out:')~=nil))
+end
+function M.new(cfg,settings,opts)
+ opts=opts or {}; settings=settings or {}
+ local request_fn=opts.request_fn
+ if not request_fn then
+ local ext=require('panto').ext
+ request_fn=ext and ext.http_request
+ if type(request_fn)~='function' or not M.methods_supported(request_fn) then return nil,newer_error() end
+ end
+ return setmetatable({cfg=cfg,settings=settings,request_fn=request_fn,
+ timer_factory=opts.timer_factory or async.timer,active={},sequence=0,closed=false,
+ session_id=nil,protocol_version=nil,era=nil,session_generation=0,initialize_params=nil,
+ on_message=nil,on_error=nil,oauth=opts.oauth,
+ on_notification_stream_end=opts.on_notification_stream_end},Transport)
+end
+function Transport:set_callbacks(message,err) self.on_message=message; self.on_error=err end
+function Transport:auth_name()
+ if self.oauth then return self.oauth:request_auth() end
+ return self.cfg.auth
+end
+
+function Transport:_clear_state(state)
+ if state.done then return end
+ state.done=true; self.active[state.key]=nil
+ local op=state.op
+ if op then async.close(op.idle_timer); async.close(op.fire_timer) end
+end
+function Transport:_log_failure(text)
+ self.stderr_tail=((self.stderr_tail or '')..text..'\n'):sub(-8192)
+ io.stderr:write('panto-mcp: ',text,'\n')
+end
+function Transport:_finish_handshake(state,ok,err)
+ if state.handshake_future and not state.handshake_future.done then state.handshake_future:resolve(ok,err) end
+end
+function Transport:_emit_error(state,message,text,data)
+ if state.done or state.cancelled then return end
+ local method=(message and message.method) or state.opts.method
+ text=redact(prefix_error(self.cfg.name,method,text),self.cfg.headers)
+ self:_clear_state(state)
+ if state.fire_and_forget then
+ if state.handshake_notification then self:_finish_handshake(state,nil,text) else self:_log_failure(text) end
+ elseif message and message.id~=nil then
+ if self.on_message then self.on_message({jsonrpc='2.0',id=message.id,error={code=-32000,message=text,data=data}}) end
+ else self:_log_failure(text) end
+end
+function Transport:_deliver(state,message)
+ if type(message)~='table' or message.jsonrpc~='2.0' then
+ self:_emit_error(state,state.message,'invalid JSON-RPC message'); return
+ end
+ if type(message.error)=='table' and type(message.error.message)=='string' then
+ message.error.message=redact(message.error.message,self.cfg.headers)
+ if not state.fire_and_forget then message.error.message=prefix_error(self.cfg.name,state.opts.method,message.error.message) end
+ end
+ if state.fire_and_forget then
+ if message.error then self:_emit_error(state,state.message,message.error.message or 'JSON-RPC error on fire-and-forget POST') end
+ return
+ end
+ if message.method==nil and message.error~=nil and (message.id==nil or message.id==json.null) and state.message.id~=nil then
+ message.id=state.message.id
+ end
+ local is_response=message.method==nil and message.id~=nil and message.id==state.message.id
+ if is_response and message.result==nil and message.error==nil then
+ self:_emit_error(state,state.message,'malformed JSON-RPC response'); return
+ end
+ if is_response then state.got_response=true end
+ if self.on_message then self.on_message(message) end
+ if state.got_response then
+ local handle=state.op and state.op.handle
+ self:_clear_state(state); cancel_handle(handle)
+ end
+end
+function Transport:_delete_session(session_id)
+ if not session_id then return end
+ local headers=M.headers(self.cfg,{era='legacy',protocol_version=self.protocol_version or '2025-11-25'},session_id)
+ pcall(self.request_fn,{url=self.cfg.url,method='DELETE',auth=self:auth_name(),headers=headers,timeout_ms=1000,max_bytes=1024},function() end)
+end
+function Transport:_session_expired(state,message,session_id,generation)
+ if self.session_id==session_id then self.session_id=nil end
+ self:_emit_error(state,message,'session expired',{session_expired=true,http_status=404,session_generation=generation})
+end
+function Transport:_start_http(state,message,opts,on_done)
+ if state.cancelled or state.done or self.closed then return end
+ local initial=opts.era=='legacy' and message.method=='initialize'
+ local session_id=initial and nil or self.session_id
+ local headers,header_err=M.headers(self.cfg,{era=opts.era,protocol_version=opts.protocol_version,
+ method=message.method or opts.method,name=(message.params and (message.params.name or message.params.uri)) or opts.name,
+ param_headers=opts.param_headers,arguments=message.params and message.params.arguments,initial=initial},session_id)
+ if not headers then self:_emit_error(state,message,header_err); return end
+ local op={body_parts={},body_len=0,sse=false,parser=nil,handle=nil,headers={},status=0,
+ session_id=session_id,session_generation=self.session_generation or 0,idle_timer=nil,fire_timer=nil}
+ state.op=op
+ local request_options={url=self.cfg.url,method='POST',body=json.encode(message),auth=self:auth_name(),headers=headers,
+ timeout_ms=0,idle_timeout_ms=0,max_bytes=MAX_BODY}
+ op.auth_used=request_options.auth~=nil
+ local function reset_idle()
+ async.close(op.idle_timer); op.idle_timer=nil
+ local idle=self.settings.idle_timeout_ms or 60000
+ if idle>0 and op.sse and op.status>=200 and op.status<300 and not state.done and not state.cancelled then
+ op.idle_timer=self.timer_factory(idle,function()
+ cancel_handle(op.handle)
+ self:_emit_error(state,message,'idle timeout',{transport_error='idle_timeout',idle_timeout=true})
+ end)
+ end
+ end
+ request_options.on_head=function(head)
+ if state.cancelled or state.done or self.closed then cancel_handle(op.handle); return end
+ op.status=head.status or 0; op.headers=head.headers or {}; op.sse=is_sse(op.headers)
+ if opts.era=='legacy' and message.method=='initialize' then
+ self.session_id=header_value(op.headers,'mcp-session-id')
+ self.protocol_version=opts.protocol_version
+ self.session_generation=(self.session_generation or 0)+1
+ end
+ if op.sse then
+ op.parser=M.sse_parser(function(data)
+ local msg=decode_message(data)
+ if not msg then self:_emit_error(state,message,'invalid JSON in SSE event'); return end
+ self:_deliver(state,msg)
+ end,MAX_BODY)
+ reset_idle()
+ end
+ end
+ request_options.on_data=function(chunk)
+ if state.done or state.cancelled or self.closed then return end
+ if op.sse and op.parser and op.status>=200 and op.status<300 then
+ reset_idle()
+ local ok,err=op.parser:feed(chunk)
+ if not ok then self:_emit_error(state,message,err); cancel_handle(op.handle) end
+ else
+ if op.body_len+#chunk>MAX_BODY then
+ if op.status>=400 then self:_http_failure(state,message,op.status,table.concat(op.body_parts),nil,opts)
+ else self:_emit_error(state,message,'HTTP response exceeds size limit') end
+ cancel_handle(op.handle); return
+ end
+ op.body_parts[#op.body_parts+1]=chunk; op.body_len=op.body_len+#chunk
+ end
+ end
+ local function complete(response,request_error)
+ if state.done or state.cancelled or state.op~=op then return end
+ async.close(op.idle_timer); op.idle_timer=nil; async.close(op.fire_timer); op.fire_timer=nil
+ if request_error then on_done(nil,nil,tostring(request_error),op); return end
+ if response then
+ op.status=response.status or op.status; op.headers=response.headers or op.headers
+ if response.body and response.body~='' then op.body_parts[#op.body_parts+1]=response.body; op.body_len=op.body_len+#response.body end
+ end
+ if op.sse and op.parser then
+ local ok,err=op.parser:finish()
+ if not ok then op.parse_error=err end
+ end
+ local body=table.concat(op.body_parts)
+ local msg
+ if not op.sse or op.status<200 or op.status>=300 then msg=decode_message(body) end
+ if msg and not state.fire_and_forget and op.status>=200 and op.status<300 and msg.id==message.id then self:_deliver(state,msg) end
+ on_done({status=op.status,headers=op.headers,body=body},msg,op.parse_error,op)
+ end
+ local ok,handle,err=pcall(self.request_fn,request_options,complete)
+ if not ok then complete(nil,handle); return end
+ if not handle then complete(nil,err or 'HTTP request could not start'); return end
+ op.handle=handle
+ if state.op==op and not state.done and not state.cancelled then
+ if state.fire_and_forget then
+ op.fire_timer=self.timer_factory(FIRE_TIMEOUT_MS,function()
+ cancel_handle(op.handle); self:_emit_error(state,message,'request timed out',{transport_error='timeout'})
+ end)
+ end
+ else cancel_handle(handle) end
+end
+function Transport:_http_failure(state,message,status,body,jsonrpc_error,opts)
+ if status==401 or status==403 then
+ if self.oauth then
+ local op=state.op or {}
+ local text=status==403 and 'Forbidden (HTTP 403); check server permissions' or
+ (self.cfg.auth and self.oauth:configured_error() or self.oauth:login_error())
+ self:_emit_error(state,message,text,{http_status=status,auth_error=true,
+ challenge=require('panto_mcp.oauth').challenge(header_value(op.headers,'www-authenticate')),auth_used=op.auth_used})
+ return
+ end
+ local text=status==403 and 'Forbidden (HTTP 403); check server permissions' or
+ string.format('requires authentication (HTTP 401); configure auth = "<session>" in [mcp.servers.%s]',self.cfg.name)
+ self:_emit_error(state,message,text,{http_status=status,auth_error=true}); return
+ end
+ if status==404 and opts and opts.era=='legacy' and not state.fire_and_forget and message.method and state.op and state.op.session_id then
+ self:_session_expired(state,message,state.op.session_id,state.op.session_generation); return
+ end
+ if jsonrpc_error then
+ local error_text=state.op and state.op.auth_used and ('HTTP '..status..' JSON-RPC error') or jsonrpc_error.message
+ if state.fire_and_forget then self:_emit_error(state,message,error_text or 'HTTP JSON-RPC error',{http_status=status}); return end
+ local data=type(jsonrpc_error.data)=='table' and jsonrpc_error.data or {}
+ data.http_status=status
+ data.transport_fallback=(status==400 or status==404 or status==405) and
+ jsonrpc_error.code~=-32020 and jsonrpc_error.code~=-32021 and jsonrpc_error.code~=-32022 and
+ not (status==404 and jsonrpc_error.code==-32601 and message.method~='server/discover')
+ local text=redact(error_text or 'HTTP JSON-RPC error',self.cfg.headers)
+ self:_clear_state(state)
+ if self.on_message then self.on_message({jsonrpc='2.0',id=message.id,error={code=jsonrpc_error.code,message=prefix_error(self.cfg.name,message.method or state.opts.method,text),data=data}}) end
+ return
+ end
+ local body_text=state.op and state.op.auth_used and '' or redact(body,self.cfg.headers)
+ local text=string.format('HTTP %d%s',status,body_text~='' and ': '..body_text or '')
+ self:_emit_error(state,message,text,{http_status=status,transport_fallback=status==400 or status==404 or status==405})
+end
+function Transport:_main_complete(state,message,opts,response,msg,err,op)
+ if state.done or state.cancelled then return end
+ local status=response and response.status or (op and op.status) or 0
+ if err then
+ if status==404 and opts.era=='legacy' and not state.fire_and_forget and message.method and op and op.session_id then
+ self:_session_expired(state,message,op.session_id,op.session_generation); return
+ end
+ if status>=400 then self:_http_failure(state,message,status,op and table.concat(op.body_parts),nil,opts)
+ else
+ local kind=failure_kind(err)
+ self:_emit_error(state,message,err,{transport_error=kind,timeout=kind=='timeout',idle_timeout=kind=='idle_timeout'})
+ end
+ return
+ end
+ if status==404 and opts.era=='legacy' and not state.fire_and_forget and message.method and op and op.session_id then
+ self:_session_expired(state,message,op.session_id,op.session_generation); return
+ end
+ if status<200 or status>=300 then
+ local null_id=msg and (msg.id==nil or msg.id==json.null)
+ if msg and msg.error and (msg.id==message.id or null_id) then self:_http_failure(state,message,status,response.body,msg.error,opts)
+ else self:_http_failure(state,message,status,response and response.body,nil,opts) end
+ return
+ end
+ if state.fire_and_forget then
+ if msg and msg.error then
+ self:_emit_error(state,message,msg.error.message or 'JSON-RPC error on fire-and-forget POST')
+ else
+ self:_clear_state(state)
+ if state.handshake_notification then self:_finish_handshake(state,true) end
+ end
+ return
+ end
+ if op.sse then
+ if message.id~=nil and not state.got_response then self:_emit_error(state,message,'HTTP SSE stream ended without a response for this request',{http_status=status})
+ elseif not state.done then self:_clear_state(state) end
+ return
+ end
+ if message.id~=nil and not state.got_response then
+ self:_emit_error(state,message,'HTTP response did not contain this request\'s JSON-RPC response',{http_status=status})
+ elseif not state.done then self:_clear_state(state) end
+end
+function Transport:send(message,opts)
+ if self.closed then return nil,'HTTP transport closed' end
+ opts=opts or {}
+ local current_era=opts.era or self.era
+ if message.method==nil and current_era=='modern' then return {} end
+ self.sequence=self.sequence+1
+ local fire=message.method==nil or message.id==nil
+ local key=fire and ('fire:'..self.sequence) or ('id:'..tostring(message.id))
+ local effective={era=opts.era or self.era,protocol_version=opts.protocol_version or self.protocol_version,
+ method=opts.method or message.method,name=opts.name,param_headers=opts.param_headers,arguments=opts.arguments}
+ if opts.era then self.era=opts.era end
+ if opts.protocol_version then self.protocol_version=opts.protocol_version end
+ local handshake_notification=effective.era=='legacy' and message.method=='notifications/initialized'
+ local state={key=key,message=message,opts=effective,fire_and_forget=fire,handshake_notification=handshake_notification,cancelled=false,done=false,got_response=false}
+ if handshake_notification then
+ state.handshake_future=async.future()
+ function state:await() return self.handshake_future:await() end
+ end
+ self.active[key]=state
+ if effective.era=='legacy' and message.method=='initialize' then self.initialize_params=message.params or {} end
+ self:_start_http(state,message,effective,function(response,result,err,op)
+ self:_main_complete(state,message,effective,response,result,err,op)
+ end)
+ return state
+end
+local function cancel_state(self,id,handle,notify)
+ local state=self.active['id:'..tostring(id)] or handle
+ if not state then return end
+ local was_legacy=state.opts.era=='legacy'
+ local method=state.message and state.message.method
+ local version=state.opts.protocol_version or self.protocol_version
+ state.cancelled=true; self.active[state.key]=nil
+ local op=state.op; if op then async.close(op.idle_timer); async.close(op.fire_timer); cancel_handle(op.handle) end
+ if notify and was_legacy and state.op and state.op.session_generation==self.session_generation and
+ method and method~='initialize' and method~='notifications/cancelled' and not self.closed then
+ self:send({jsonrpc='2.0',method='notifications/cancelled',params={requestId=id,reason='request cancelled'}},
+ {era='legacy',protocol_version=version,method='notifications/cancelled'})
+ end
+end
+function Transport:open_notification_stream()
+ if self.closed or self.notification_stream then return false end
+ local headers=M.headers(self.cfg,{era='legacy',protocol_version=self.protocol_version or '2025-11-25'},self.session_id)
+ headers.Accept='text/event-stream'
+ headers['Content-Type']=nil
+ local stream={status=0,ignore=false,handle=nil,parser=nil}
+ self.notification_stream=stream
+ local function finish()
+ if self.notification_stream~=stream then return end
+ self.notification_stream=nil
+ if stream.status~=405 and not self.closed and self.on_notification_stream_end then
+ pcall(self.on_notification_stream_end,stream.status)
+ end
+ end
+ local options={url=self.cfg.url,method='GET',auth=self:auth_name(),headers=headers,
+ timeout_ms=0,idle_timeout_ms=0}
+ options.on_head=function(head)
+ if self.closed or self.notification_stream~=stream then return end
+ stream.status=head.status or 0
+ if stream.status<200 or stream.status>=300 then
+ stream.ignore=true
+ cancel_handle(stream.handle)
+ finish()
+ return
+ end
+ stream.opened=true
+ stream.parser=M.sse_parser(function(data)
+ local message=decode_message(data)
+ if message and self.on_message and not self.closed then self.on_message(message) end
+ end,MAX_BODY)
+ end
+ options.on_data=function(chunk)
+ if self.closed or stream.ignore or self.notification_stream~=stream or not stream.parser then return end
+ local ok=stream.parser:feed(chunk)
+ if not ok then stream.ignore=true; cancel_handle(stream.handle); finish() end
+ end
+ local ok,handle=pcall(self.request_fn,options,function()
+ if self.notification_stream~=stream then return end
+ if stream.parser and not stream.ignore then pcall(stream.parser.finish,stream.parser) end
+ finish()
+ end)
+ if not ok or not handle then finish(); return false end
+ stream.handle=handle
+ if self.closed or self.notification_stream~=stream or stream.ignore then cancel_handle(handle); return false end
+ return true
+end
+function Transport:close_notification_stream()
+ local stream=self.notification_stream
+ if not stream then return end
+ self.notification_stream=nil; stream.ignore=true
+ cancel_handle(stream.handle)
+end
+function Transport:cancel_request(id,handle) cancel_state(self,id,handle,false) end
+function Transport:cancel(id,handle) cancel_state(self,id,handle,true) end
+function Transport:fail(err)
+ if self.closed then return end
+ self.closed=true
+ if self.notification_stream then self:close_notification_stream() end
+ for _,state in pairs(self.active) do
+ state.cancelled=true
+ if state.handshake_future then self:_finish_handshake(state,nil,'HTTP transport closed') end
+ if state.op then async.close(state.op.idle_timer); async.close(state.op.fire_timer); cancel_handle(state.op.handle) end
+ end
+ self.active={}; if self.on_error then self.on_error(err) end
+end
+function Transport:close()
+ if self.did_close then return end
+ self.did_close=true
+ if self.notification_stream then self:close_notification_stream() end
+ local session=self.session_id
+ for _,state in pairs(self.active) do
+ state.cancelled=true
+ if state.handshake_future then self:_finish_handshake(state,nil,'HTTP transport closed') end
+ if state.op then async.close(state.op.idle_timer); async.close(state.op.fire_timer); cancel_handle(state.op.handle) end
+ end
+ self.active={}; self.closed=true
+ self:_delete_session(session)
+end
+return M
diff --git a/panto_mcp/jsonrpc.lua b/panto_mcp/jsonrpc.lua
new file mode 100644
index 0000000..714c137
--- /dev/null
+++ b/panto_mcp/jsonrpc.lua
@@ -0,0 +1,75 @@
+-- Transport contract (shared with future HTTP):
+-- t:set_callbacks(on_message, on_error); t:send(message, opts) -> handle|nil, err
+-- t:cancel(id, handle); t:close() (nonblocking).
+-- cancel_request cancels a transport handle without sending an MCP-level notice.
+-- `cancel` additionally permits a transport-specific cancellation notification.
+-- opts = {era, protocol_version, method, name, param_headers?};
+-- on_error means the whole transport failed, not a request-level RPC error.
+local async = require('panto_mcp.async')
+local json = require('panto').ext.json
+local M = {}; M.__index = M
+function M.new(transport, opts)
+ opts=opts or {}
+ local self=setmetatable({transport=transport, next_id=0, pending={},
+ timeout_ms=opts.timeout_ms or 300000, timer_factory=opts.timer_factory or async.timer,
+ on_notification=opts.on_notification, on_error=opts.on_error},M)
+ transport:set_callbacks(function(msg) self:receive(msg) end, function(err) self:fail(err) end)
+ return self
+end
+function M:finish(id, value, err)
+ local p=self.pending[id]; if not p then return end
+ self.pending[id]=nil
+ async.close(p.timer)
+ p.future:resolve(value,err)
+end
+function M:receive(msg)
+ if self.closed then return end
+ if type(msg)~='table' or msg.jsonrpc~='2.0' then self:fail('malformed JSON-RPC message'); return end
+ if type(msg.method)=='string' then
+ if msg.id~=nil then
+ local reply={jsonrpc='2.0',id=msg.id}
+ if msg.method=='ping' then reply.result={} else reply.error={code=-32601,message='Method not found'} end
+ self.transport:send(reply,{method=msg.method})
+ elseif self.on_notification then self.on_notification(msg.method,msg.params) end
+ elseif msg.id~=nil and (msg.result~=nil or msg.error~=nil) then
+ self:finish(msg.id,msg.result,msg.error)
+ else self:fail('malformed JSON-RPC response') end
+end
+function M:start(method, params, opts)
+ opts=opts or {}; opts.method=method
+ if self.closed then local f=async.future(); f:resolve(nil,self.error or 'connection closed'); return f end
+ self.next_id=self.next_id+1
+ local id=self.next_id
+ local future=async.future(function() self:cancel(id,'request cancelled') end)
+ local p={future=future,cancel_protocol=opts.cancel_protocol}; self.pending[id]=p
+ p.timer=self.timer_factory(opts.timeout_ms or self.timeout_ms,function() self:cancel(id,'request timed out: ' .. method) end)
+ local ok,h,err=pcall(self.transport.send,self.transport,{jsonrpc='2.0',id=id,method=method,params=params or {}},opts)
+ if not ok or not h then self:finish(id,nil,not ok and h or err or 'send failed') else p.handle=h end
+ return future
+end
+function M:request(method,params,opts) return self:start(method,params,opts):await() end
+function M:notify(method,params,opts)
+ if self.closed then return nil,self.error end
+ opts=opts or {}; opts.method=method
+ return self.transport:send({jsonrpc='2.0',method=method,params=params or {}},opts)
+end
+function M:cancel(id,reason)
+ local p=self.pending[id]; if not p then return end
+ self.pending[id]=nil; async.close(p.timer)
+ if p.cancel_protocol~=false then pcall(self.transport.cancel,self.transport,id,p.handle)
+ elseif type(self.transport.cancel_request)=='function' then pcall(self.transport.cancel_request,self.transport,id,p.handle) end
+ p.future:resolve(nil,reason or 'request cancelled')
+end
+function M:fail(err,abandon)
+ if self.closed then return end
+ self.closed=true; self.error=err or 'connection closed'
+ local pending=self.pending; self.pending={}
+ for _,p in pairs(pending) do
+ async.close(p.timer)
+ if abandon then p.future:abandon(nil,self.error) else p.future:resolve(nil,self.error) end
+ end
+ self.transport:close()
+ if self.on_error then self.on_error(self.error) end
+end
+function M:close(abandon) self:fail('connection closed',abandon) end
+return M
diff --git a/panto_mcp/manager.lua b/panto_mcp/manager.lua
new file mode 100644
index 0000000..a76e7bf
--- /dev/null
+++ b/panto_mcp/manager.lua
@@ -0,0 +1,229 @@
+local async = require('panto_mcp.async')
+local Client = require('panto_mcp.client')
+local cache = require('panto_mcp.cache')
+local search = require('panto_mcp.search')
+local config = require('panto_mcp.config')
+local results = require('panto_mcp.results')
+local validate = require('panto_mcp.validate')
+local json = require('panto').ext.json
+local M = {}; M.__index=M
+function M.new(settings,servers,opts)
+ opts=opts or {}
+ local self=setmetatable({settings=settings,states={},opts=opts},M)
+ for name,cfg in pairs(servers) do
+ local metadata=cache.load(cfg,opts.cache_dir)
+ if metadata and cfg.transport=='http' and metadata.catalog then
+ metadata.catalog.tools=require('panto_mcp.http').filter_tools(metadata.catalog.tools,cfg.name,true)
+ end
+ self.states[name]={cfg=cfg,state='idle',metadata=metadata,
+ oauth=cfg.transport=='http' and require('panto_mcp.oauth').new(cfg,opts) or nil}
+ end
+ return self
+end
+function M:lookup(name)
+ if type(name)~='string' then return nil,'server must be an exact name' end
+ local state=self.states[name]; if state then return state end
+ local names={}; for n in pairs(self.states) do names[#names+1]=n end
+ return nil,'unknown server ' .. name .. '; closest: ' .. search.closest(name,names)
+end
+function M:start(state)
+ if self.closed then local f=async.future(); f:resolve(nil,'session ended'); return f end
+ if state.state=='connecting' then return state.ready end
+ if state.state=='ready' then local f=async.future(); f:resolve(state.client); return f end
+ state.state='connecting'; state.error=nil
+ local ready=async.future(); state.ready=ready
+ local timer_factory=self.opts.timer_factory or async.timer
+ local timer
+ local function fail(err)
+ if ready.done then return end
+ state.state='failed'; state.error=Client.error_text(err)
+ async.close(timer)
+ -- Resolve the shared startup first: closing RPC resumes the connector.
+ local failed_client=state.client
+ ready:resolve(nil,state.error)
+ if failed_client then failed_client:close() end
+ end
+ local c
+ c=Client.new(state.cfg,self.settings,{
+ transport_factory=self.opts.transport_factory,timer_factory=self.opts.timer_factory,oauth=state.oauth,request_fn=self.opts.request_fn,
+ on_error=function(err)
+ if state.state=='ready' and state.client==c then
+ state.state='failed'; state.error=Client.error_text(err); c:close()
+ end
+ end,
+ on_catalog=function(client)
+ if self.closed or client.closed then return end
+ state.metadata=client:metadata()
+ local _,err=cache.save(state.cfg,state.metadata,self.opts.cache_dir)
+ state.cache_error=err
+ -- E5/E6 hook: reconcile eager tools/prompt commands from this snapshot.
+ if self.opts.on_catalog then self.opts.on_catalog(state.cfg.name,state.metadata) end
+ end,
+ })
+ state.client=c
+ timer=timer_factory(self.settings.startup_timeout_ms,function()
+ fail(state.cfg.transport=='http' and state.cfg.name .. ' server/discover: startup timed out' or 'startup timed out')
+ end)
+ state.timer=timer
+ async.run(function()
+ local ok,err=c:connect(state.metadata)
+ if ready.done or self.closed then c:close(); return end
+ if not ok then fail(err); return end
+ async.close(timer)
+ state.state='ready'; state.error=nil
+ ready:resolve(c)
+ end,fail)
+ return ready
+end
+function M:ensure(name)
+ local state,err=self:lookup(name); if not state then return nil,err end
+ return self:start(state):await()
+end
+function M:start_cold()
+ for _,s in pairs(self.states) do if not s.metadata then self:start(s) end end
+end
+function M:servers()
+ local out=json.array({})
+ for name,s in pairs(self.states) do
+ local meta=s.metadata or {}; local catalog=meta.catalog or {}
+ out[#out+1]={name=name,transport=s.cfg.transport,mode=s.cfg.expose,state=s.state,
+ era=meta.era,version=meta.version,error=s.error,cache_error=s.cache_error,auth=s.oauth and s.oauth:status(),
+ notification_warning=s.client and s.client.notification_warning,
+ tools=#(catalog.tools or {}),prompts=#(catalog.prompts or {}),resources=#(catalog.resources or {}),
+ templates=#(catalog.templates or {}),stderr=s.client and s.client.transport and s.client.transport.stderr_tail or ''}
+ end
+ table.sort(out,function(a,b) return a.name<b.name end)
+ return out
+end
+function M:search(query,opts)
+ opts=opts or {}
+ if query~=nil and type(query)~='string' then return nil,'query must be a string' end
+ if opts.limit~=nil and (type(opts.limit)~='number' or opts.limit%1~=0 or opts.limit<1 or opts.limit>100) then return nil,'limit must be an integer from 1 to 100' end
+ if opts.server then local s,err=self:lookup(opts.server); if not s then return nil,err end end
+ -- Warm search never starts processes; cold activation is already connecting.
+ for name,s in pairs(self.states) do
+ if not opts.server or name==opts.server then
+ if s.state=='failed' or (not s.metadata and s.state=='idle') then self:start(s) end
+ if s.state=='connecting' then s.ready:await() end
+ end
+ end
+ local out=search.search(self.states,query,opts)
+ out.servers=self:servers()
+ for _,server in ipairs(out.servers) do server.stderr=nil end
+ return out
+end
+function M:call(server,tool,input)
+ if type(tool)~='string' or tool=='' then return results.map(tostring(server),nil,'tool must be an exact nonempty name') end
+ local c,err=self:ensure(server)
+ if not c then return results.map(tostring(server),nil,err) end
+ local definition,names=nil,{}
+ for _,t in ipairs(c.catalog.tools) do
+ if config.tool_enabled(c.cfg,t.name or '') then
+ names[#names+1]=t.name
+ if t.name==tool then definition=t end
+ end
+ end
+ if not definition then return results.map(server,nil,'unknown or disabled tool ' .. tool .. '; closest: ' .. search.closest(tool,names)) end
+ if input==nil then input={} end
+ local valid,errors=validate.check(input,definition.inputSchema)
+ if not valid then
+ local out=results.map(server,nil,'input validation failed:\n' .. table.concat(errors,'\n') .. '\nSchema: ' .. json.encode(definition.inputSchema))
+ out.validation_errors=errors; out.schema=definition.inputSchema
+ return out
+ end
+ local result; result,err=c:call(tool,input)
+ return results.map(server,result,err)
+end
+function M:read_resource(server,uri)
+ if type(uri)~='string' or uri=='' then return results.map(tostring(server),nil,'uri must be a nonempty string') end
+ local c,err=self:ensure(server); if not c then return results.map(tostring(server),nil,err) end
+ local result; result,err=c:read_resource(uri)
+ return results.map(server,result,err)
+end
+function M:prompts(server)
+ local c,err=self:ensure(server); if not c then return nil,err end
+ return c.catalog.prompts
+end
+function M:prompt(server,name,args)
+ if type(name)~='string' or name=='' then return nil,'prompt name must be nonempty' end
+ if args~=nil then
+ if type(args)~='table' then return nil,'prompt arguments must be an object of strings' end
+ for k,v in pairs(args) do if type(k)~='string' or type(v)~='string' then return nil,'prompt arguments must be an object of strings' end end
+ end
+ local c,err=self:ensure(server); if not c then return nil,err end
+ local result; result,err=c:prompt(name,args)
+ if not result then return nil,Client.error_text(err) end
+ if result.resultType=='input_required' then return nil,'server requested unsupported user input' end
+ return result.messages
+end
+function M:refresh(name)
+ local names={}
+ if name then local s,err=self:lookup(name); if not s then return nil,err end; names={name}
+ else for n in pairs(self.states) do names[#names+1]=n end; table.sort(names) end
+ local failures={}
+ for _,n in ipairs(names) do
+ local s=self.states[n]
+ if s.state=='ready' then
+ local _,err=s.client:refresh()
+ if err then s.state='failed'; s.error=err; s.client:close(); failures[#failures+1]=n .. ': ' .. err end
+ else local _,err=self:ensure(n); if err then failures[#failures+1]=n .. ': ' .. err end end
+ end
+ if #failures>0 then return nil,table.concat(failures,'\n') end
+ return true
+end
+function M:login(name,callback_url,reregister)
+ local state,err=self:lookup(name); if not state then return err end
+ local oauth=state.oauth
+ if not oauth then return 'OAuth is only available for HTTP servers' end
+ local function reconnect()
+ if self.closed then return end
+ if state.client then state.client:close() end
+ state.state='idle'; state.error=nil
+ self:start(state)
+ end
+ local function present(url)
+ if url==true then return 'OAuth callback accepted; /mcp shows login/reconnect status.' end
+ return 'Open this URL to log in:\n'..url..'\nFor SSH/headless, paste the full callback URL: /mcp-login '..name..' <callback-url>'
+ end
+ if state.login_preparing then return 'OAuth discovery/login preparation started; retry /mcp-login '..name..' to get the URL.' end
+ if oauth.refreshing then return 'OAuth refresh is in progress; retry /mcp-login '..name..' when it finishes.' end
+ local function failed(why) state.error=why end
+ local url,why
+ if reregister and (state.cfg.auth or (state.cfg.oauth and state.cfg.oauth.client_id)) then
+ return '--reregister is only available for automatic public DCR clients.'
+ end
+ if not reregister and (oauth.definition or state.cfg.auth or callback_url) then
+ url,why=oauth:login(callback_url,reconnect,failed)
+ if url or callback_url or state.cfg.auth or not oauth:available() then return url and present(url) or why end
+ end
+ if not oauth:available() then local _,err=oauth:login(nil,reconnect,failed); return err end
+ -- Only missing/failed definitions or an explicit registration reset need discovery.
+ if state.ready and not state.ready.done then state.ready:resolve(nil,'OAuth rediscovery requested') end
+ async.close(state.timer)
+ if state.client then state.client:close() end
+ oauth:invalidate(reregister); state.state='idle'; state.login_preparing=true
+ async.run(function()
+ local _,connect_error=self:start(state):await()
+ if self.closed then return end
+ if oauth.definition then url,why=oauth:login(nil,reconnect,failed)
+ else why=oauth:recovery_error(connect_error or 'OAuth discovery failed') end
+ state.login_preparing=nil
+ if not url then state.error=why end
+ end,function()
+ state.login_preparing=nil; state.error=oauth:recovery_error('OAuth discovery/login preparation failed')
+ end)
+ if url then return present(url) end
+ return why or ('OAuth discovery/login preparation started; retry /mcp-login '..name..' to get the URL.')
+end
+function M:close()
+ if self.closed then return end
+ self.closed=true
+ for _,s in pairs(self.states) do
+ s.state='failed'; s.error='session ended'
+ async.close(s.timer)
+ if s.oauth then s.oauth:close() end
+ if s.ready and not s.ready.done then s.ready:abandon(nil,'session ended') end
+ if s.client then s.client:close(true) end
+ end
+end
+return M
diff --git a/panto_mcp/namespace.lua b/panto_mcp/namespace.lua
new file mode 100644
index 0000000..47e99ed
--- /dev/null
+++ b/panto_mcp/namespace.lua
@@ -0,0 +1,31 @@
+local async = require('panto_mcp.async')
+local M = {}
+function M.factory(manager, _context)
+ -- Unlike delegation, MCP is also available in child agent lanes.
+ local api={}
+ function api.servers() return manager:servers() end
+ function api.search(query,opts) return manager:search(query,opts) end
+ function api.call(server,tool,input) return manager:call(server,tool,input) end
+ function api.start(server,tool,input)
+ local co
+ local future
+ future=async.future(function()
+ if co and coroutine.status(co)~='dead' then coroutine.close(co) end
+ future:resolve(nil,'request cancelled')
+ end)
+ co=async.run(function() future:resolve(manager:call(server,tool,input)) end,
+ function(err) future:resolve(nil,tostring(err)) end)
+ return future
+ end
+ function api.read_resource(server,uri) return manager:read_resource(server,uri) end
+ function api.prompts(server) return manager:prompts(server) end
+ function api.prompt(server,name,args) return manager:prompt(server,name,args) end
+ return api
+end
+function M.install(manager)
+ local ok,std=pcall(require,'_std')
+ if not ok or type(std.lua_namespace)~='function' then return false end
+ std.lua_namespace('mcp',function(context) return M.factory(manager,context) end)
+ return true
+end
+return M
diff --git a/panto_mcp/oauth.lua b/panto_mcp/oauth.lua
new file mode 100644
index 0000000..b97c1a7
--- /dev/null
+++ b/panto_mcp/oauth.lua
@@ -0,0 +1,458 @@
+local ext = require('panto').ext
+local json = ext.json
+local async = require('panto_mcp.async')
+local config = require('panto_mcp.config')
+local M = {}; M.__index=M
+local function nonempty(v) return type(v)=='string' and v~='' and not v:find('[%z\1-\32\127]') end
+-- Credentials, fragments and ambiguous authorities are never accepted.
+function M.url(value)
+ if type(value)~='string' or value:find('[%z\1-\32\127\\#]') then return nil end
+ local scheme,authority,tail=value:match('^([A-Za-z]+)://([^/?]+)(.*)$')
+ if not scheme then return nil end
+ scheme=scheme:lower(); if scheme~='https' and scheme~='http' then return nil end
+ local host,port
+ if authority:sub(1,1)=='[' then host,port=authority:match('^(%[[%x:]+%])(:?%d*)$')
+ else host,port=authority:match('^([A-Za-z0-9.-]+)(:?%d*)$') end
+ if not host or port==':' then return nil end
+ if port~='' and (not tonumber(port:sub(2)) or tonumber(port:sub(2))<1 or tonumber(port:sub(2))>65535) then return nil end
+ host=host:lower()
+ local literal_loopback=host=='[::1]'
+ local mapped_loopback=false
+ if host:sub(1,1)=='[' then
+ local address=host:sub(2,-2); local left,right=address:match('^(.-)::(.-)$')
+ local groups={}
+ for group in (left or address):gmatch('[^:]+') do groups[#groups+1]=tonumber(group,16) end
+ if left then
+ local suffix={}; for group in right:gmatch('[^:]+') do suffix[#suffix+1]=tonumber(group,16) end
+ while #groups+#suffix<8 do groups[#groups+1]=0 end
+ for _,group in ipairs(suffix) do groups[#groups+1]=group end
+ end
+ if #groups==8 then
+ local zeros=true; for i=1,5 do if groups[i]~=0 then zeros=false end end
+ literal_loopback=zeros and groups[6]==0 and groups[7]==0 and groups[8]==1
+ mapped_loopback=zeros and groups[6]==0xffff and groups[7]>=0x7f00 and groups[7]<=0x7fff
+ end
+ end
+ local a,b,c,d=host:match('^(%d+)%.(%d+)%.(%d+)%.(%d+)$')
+ if a then
+ for _,octet in ipairs({a,b,c,d}) do
+ if (#octet>1 and octet:sub(1,1)=='0') or tonumber(octet)>255 then return nil end
+ end
+ literal_loopback=a=='127'
+ elseif host:match('^[%d.]+$') then return nil end
+ for octet in host:gmatch('[^.]+') do if octet:match('^0x%x+$') then return nil end end
+ if scheme=='http' and not literal_loopback then return nil end
+ if (scheme=='https' and port==':443') or (scheme=='http' and port==':80') then port='' end
+ local origin=scheme..'://'..host..port
+ if tail=='/' then tail='' end
+ return origin..tail,origin,tail:match('^[^?]*'),literal_loopback or mapped_loopback or host=='localhost' or host=='localhost.' or host:match('%.localhost%.?$')~=nil
+end
+function M.prm_urls(resource)
+ local _,origin,path=M.url(resource); if not origin then return {} end
+ local root=origin..'/.well-known/oauth-protected-resource'
+ return path~='' and {root..path,root} or {root}
+end
+function M.metadata_urls(issuer)
+ local _,origin,path=M.url(issuer)
+ if not origin or issuer:find('?',1,true) then return {} end
+ path=path:gsub('/$','')
+ local urls={origin..'/.well-known/oauth-authorization-server'..path,origin..'/.well-known/openid-configuration'..path}
+ if path~='' then urls[#urls+1]=origin..path..'/.well-known/openid-configuration' end
+ return urls
+end
+function M.scopes(value)
+ local out,seen={},{}
+ if type(value)=='string' then
+ local parts={}; for part in value:gmatch('%S+') do parts[#parts+1]=part end; value=parts
+ end
+ if type(value)~='table' then return out end
+ for _,v in ipairs(value) do
+ local valid=type(v)=='string' and v~=''
+ if valid then
+ for i=1,#v do
+ local byte=v:byte(i)
+ if byte<33 or byte>126 or byte==34 or byte==92 then valid=false; break end
+ end
+ end
+ if valid and not seen[v] then seen[v]=true; out[#out+1]=v end
+ end
+ return out
+end
+function M.union(a,b)
+ local out=M.scopes(a); local seen={}; for _,v in ipairs(out) do seen[v]=true end
+ for _,v in ipairs(M.scopes(b)) do if not seen[v] then seen[v]=true; out[#out+1]=v end end
+ return out
+end
+-- Commas inside quoted strings are not challenge separators; quoted-pairs are unescaped.
+function M.challenge(header)
+ if type(header)~='string' or #header>16384 or header:find('[\r\n%z]') then return {} end
+ local chunks,begin,quoted,escaped={},1,false,false
+ for i=1,#header do
+ local c=header:sub(i,i)
+ if escaped then escaped=false
+ elseif quoted and c=='\\' then escaped=true
+ elseif c=='"' then quoted=not quoted
+ elseif c==',' and not quoted then chunks[#chunks+1]=header:sub(begin,i-1); begin=i+1 end
+ end
+ if quoted or escaped then return {} end
+ chunks[#chunks+1]=header:sub(begin)
+ local candidates,current={},nil
+ for _,chunk in ipairs(chunks) do
+ chunk=chunk:match('^%s*(.-)%s*$')
+ local scheme,rest=chunk:match('^([%w!#$%%&\'*+.^_`|~-]+)%s+(.+)$')
+ if scheme and not rest:match('^=') then
+ current={scheme=scheme:lower()}; candidates[#candidates+1]=current; chunk=rest
+ elseif chunk:match('^[%w_-]+$') then
+ current={scheme=chunk:lower()}; candidates[#candidates+1]=current; chunk=''
+ end
+ if current and chunk~='' then
+ local key,value=chunk:match('^([%w!#$%%&\'*+.^_`|~-]+)%s*=%s*(.-)%s*$')
+ if key then
+ key=key:lower()
+ if value:sub(1,1)=='"' and value:sub(-1)=='"' then
+ value=value:sub(2,-2):gsub('\\(.)','%1')
+ elseif not value:match('^[%w!#$%%&\'*+.^_`|~-]+$') then current.invalid=true end
+ if current[key]~=nil then current.invalid=true end
+ current[key]=value
+ else current.invalid=true end
+ end
+ end
+ local first
+ for _,c in ipairs(candidates) do
+ if c.scheme=='bearer' and not c.invalid then
+ local safe={resource_metadata=c.resource_metadata,scope=c.scope,error=c.error}
+ if c.resource_metadata then return safe end
+ first=first or safe
+ end
+ end
+ return first or {}
+end
+function M.validate_metadata(metadata,issuer)
+ if type(metadata)~='table' or metadata.issuer~=issuer then return nil,'OAuth metadata issuer mismatch' end
+ if not M.url(metadata.authorization_endpoint) or not M.url(metadata.token_endpoint) then return nil,'OAuth metadata has unsafe endpoints' end
+ local s256=false
+ for _,method in ipairs(type(metadata.code_challenge_methods_supported)=='table' and metadata.code_challenge_methods_supported or {}) do
+ if method=='S256' then s256=true end
+ end
+ if not s256 then return nil,'OAuth server must advertise PKCE S256' end
+ if metadata.authorization_response_iss_parameter_supported~=nil and type(metadata.authorization_response_iss_parameter_supported)~='boolean' then
+ return nil,'Invalid OAuth issuer-response metadata'
+ end
+ return true
+end
+function M.session_name(server,resource,issuer,client_id)
+ local identity=json.encode({resource=resource,issuer=issuer,client_id=client_id})
+ return 'mcp.'..server:sub(1,91)..'.'..require('panto_mcp.hash').sha256(identity):sub(1,32)
+end
+function M.new(cfg,opts)
+ opts=opts or {}
+ local resource,origin,_,loopback=M.url(cfg.url)
+ local self=setmetatable({cfg=cfg,name=cfg.auth,auth=opts.auth or ext.auth,
+ state=opts.state or ext.state,request_fn=opts.request_fn or ext.http_request,
+ timer_factory=opts.timer_factory or async.timer,clock=opts.clock or require('luv').now,
+ timers={},resource=resource,origin=origin,loopback=loopback},M)
+ self.key='mcp.oauth.server_'..cfg.name
+ if not cfg.auth and self.state then
+ local stored=self.state.get(self.key)
+ if type(stored)=='table' and stored.version==2 and stored.fingerprint==cfg.fingerprint and stored.resource==resource and self:available() then
+ self.name=stored.name
+ self:define(stored)
+ end
+ end
+ return self
+end
+function M:available()
+ return type(self.auth)=='table' and type(self.auth.define)=='function' and type(self.auth.status)=='function'
+ and type(self.auth.login)=='function' and type(self.auth.refresh)=='function' and type(self.auth.complete)=='function'
+end
+function M:login_error() return 'Authentication required; run /mcp-login '..self.cfg.name end
+function M:recovery_error(text)
+ if self.cfg.auth then return text..'; check configured auth with panto auth login/status' end
+ local hint=(self.cfg.oauth and self.cfg.oauth.client_id) and 'check the configured OAuth client/issuer' or
+ ('try /mcp-login '..self.cfg.name..' --reregister to replace a stale DCR client')
+ return text..'; '..hint
+end
+function M:usable()
+ local state=self:auth_status().state
+ return state=='logged_in' or (state=='pending' and self.login_usable==true)
+end
+function M:configured_error()
+ return 'Configured auth session rejected (HTTP 401); check its credentials/type with panto auth login/status'
+end
+function M:auth_status()
+ if not self.name or not self:available() then return {state='logged_out'} end
+ local now=self.clock()
+ if not self.cached_status or now>=(self.status_at or 0)+1000 then
+ self.cached_status=self.auth.status(self.name) or {state='logged_out'}; self.status_at=now
+ end
+ return self.cached_status
+end
+function M:status()
+ if not self:available() then return 'unavailable' end
+ if not self.cfg.auth and not self.definition then return 'undiscovered' end
+ local state=self:auth_status().state
+ if self.login_required and state~='pending' then return 'login_required' end
+ return state
+end
+function M:request_auth()
+ if self.cfg.auth then return self.cfg.auth end
+ if self.definition and (self.refreshing or (not self.login_required and self:usable())) then return self.name end
+end
+function M:blocked()
+ if self.refreshing then return false end
+ return not self.cfg.auth and self.definition and (self.login_required or not self:usable())
+end
+function M:before_request()
+ if self.refreshing then
+ local ok,err=self.refreshing:await(); if not ok then return nil,err end
+ end
+ if self:blocked() then return nil,self:login_error() end
+ if not self.definition and self.discovery_error and self.clock()<self.retry_at then return nil,self.discovery_error end
+ return true
+end
+function M:url_allowed(url)
+ local canonical,_,_,loopback=M.url(url)
+ return canonical and (not loopback or self.loopback)
+end
+function M:define(stored)
+ if not self:available() then return nil,'MCP OAuth requires a newer panto with panto.ext.auth' end
+ if not self.resource then return nil,'MCP OAuth requires HTTPS (or literal loopback HTTP)' end
+ local configured=self.cfg.oauth
+ if configured and ((configured.issuer and configured.issuer~=stored.issuer) or
+ (configured.client_id and (not configured.issuer or configured.client_id~=stored.client_id))) then
+ return nil,'Configured oauth.issuer does not match the discovered authorization server/client'
+ end
+ if not self:url_allowed(stored.issuer) or #M.metadata_urls(stored.issuer)==0 then return nil,'Unsafe OAuth issuer for this resource' end
+ local ok,err=M.validate_metadata(stored.metadata,stored.issuer); if not ok then return nil,err end
+ if not self:url_allowed(stored.metadata.authorization_endpoint) or not self:url_allowed(stored.metadata.token_endpoint) then return nil,'Unsafe OAuth endpoint for this resource' end
+ if not nonempty(stored.client_id) or stored.client_secret~=nil then return nil,'Invalid/public-only OAuth client registration; configure oauth.client_id and oauth.issuer' end
+ local name=M.session_name(self.cfg.name,self.resource,stored.issuer,stored.client_id)
+ local spec={type='oauth_pkce',authorization_url=stored.metadata.authorization_endpoint,token_url=stored.metadata.token_endpoint,
+ client_id=stored.client_id,client_secret=configured and configured.client_secret,
+ scopes=M.scopes(stored.scopes),resource=self.resource,issuer=stored.issuer,
+ require_iss=stored.metadata.authorization_response_iss_parameter_supported==true}
+ if not self.auth.define(name,spec) then return nil,'Cannot define MCP OAuth session (check session name/config collision)' end
+ if self.name and self.name~=name then
+ -- Runtime definitions are process-local; a stored old name may need restoring for logout.
+ if not self.auth.define(self.name,self.spec or spec) then return nil,'Cannot restore the previous OAuth session for logout' end
+ local ok=self.auth.logout and self.auth.logout(self.name)
+ if not ok then return nil,'Cannot retire the previous OAuth session' end
+ end
+ if self.name~=name then self.cached_status=nil; self.login_usable=nil end
+ self.name=name; self.definition=stored; self.spec=spec
+ return true
+end
+function M:save()
+ if self.state and self.definition then
+ local d=self.definition
+ return self.state.set(self.key,{version=2,name=self.name,fingerprint=self.cfg.fingerprint,resource=self.resource,issuer=d.issuer,
+ metadata=d.metadata,client_id=d.client_id,scopes=d.scopes})
+ end
+ return true
+end
+function M:invalidate(reregister)
+ if self.cfg.auth then return end
+ if self.definition then
+ self.previous_issuer=self.definition.issuer; self.requested_scopes=self.spec.scopes
+ end
+ if reregister and self.state and self.previous_issuer then
+ self.state.set('mcp.oauth.registration_'..config.hash(self.previous_issuer),nil)
+ end
+ if self.state then self.state.set(self.key,nil) end
+ self.login_poll=(self.login_poll or 0)+1
+ self.definition=nil; self.spec=nil; self.cached_status=nil; self.login_required=nil; self.login_url=nil
+ self.discovery_error=nil; self.retry_at=nil; self.backoff=nil
+end
+function M:fetch(url,body)
+ if self.closed then return nil,'session ended' end
+ if not self:url_allowed(url) then return nil,'Unsafe OAuth discovery URL for this resource' end
+ local future=async.future()
+ local opts={url=url,method=body and 'POST' or 'GET',timeout_ms=10000,max_bytes=1024*1024,headers={Accept='application/json'}}
+ if body then opts.body=json.encode(body); opts.headers['Content-Type']='application/json' end
+ local ok,handle=pcall(self.request_fn,opts,function(response)
+ if self.closed then future:resolve(nil,'session ended'); return end
+ if not response or response.status<200 or response.status>=300 then future:resolve(nil,'OAuth discovery/registration request failed'); return end
+ local decoded,value=pcall(json.decode,response.body or '')
+ if not decoded or type(value)~='table' then future:resolve(nil,'Invalid OAuth metadata JSON'); return end
+ future:resolve(value)
+ end)
+ if not ok or not handle then return nil,'OAuth HTTP request could not start' end
+ self.requests=self.requests or {}; self.requests[handle]=future
+ local value,err=future:await(); self.requests[handle]=nil
+ return value,err
+end
+function M:discover(challenge)
+ if self.cfg.auth then return nil,self:configured_error() end
+ challenge=challenge or {}
+ if self.definition then return true end
+ if self.discovering then return self.discovering:await() end
+ if self.discovery_error and self.clock()<self.retry_at then return nil,self.discovery_error end
+ if not self:available() then return nil,'MCP OAuth requires a newer panto with panto.ext.auth and HTTP POST support' end
+ if not self.resource then return nil,'MCP OAuth requires HTTPS (or literal loopback HTTP)' end
+ local future=async.future(); self.discovering=future
+ local function work()
+ local urls=challenge.resource_metadata and {challenge.resource_metadata} or M.prm_urls(self.resource)
+ local prm,expected_resource
+ for i,url in ipairs(urls) do
+ local value=self:fetch(url)
+ if value then
+ prm=value; expected_resource=(not challenge.resource_metadata and i==2) and self.origin or self.resource
+ break
+ end
+ end
+ if not prm then return nil,'Cannot discover OAuth protected-resource metadata' end
+ if M.url(prm.resource)~=expected_resource then return nil,'OAuth protected-resource metadata resource mismatch' end
+ local servers=type(prm.authorization_servers)=='table' and prm.authorization_servers or {}
+ local issuer=servers[1]
+ local pinned=self.cfg.oauth and self.cfg.oauth.issuer
+ if pinned then
+ issuer=nil
+ for _,candidate in ipairs(servers) do if candidate==pinned then issuer=candidate; break end end
+ if not issuer then return nil,'Configured oauth.issuer is not advertised by the resource' end
+ end
+ if not issuer or #M.metadata_urls(issuer)==0 or not self:url_allowed(issuer) then return nil,'OAuth resource has no safe authorization server' end
+ local metadata
+ for _,url in ipairs(M.metadata_urls(issuer)) do
+ local value=self:fetch(url)
+ if value then
+ local valid,why=M.validate_metadata(value,issuer); if not valid then return nil,why end
+ metadata={issuer=issuer,authorization_endpoint=value.authorization_endpoint,token_endpoint=value.token_endpoint,
+ code_challenge_methods_supported={'S256'},registration_endpoint=value.registration_endpoint,
+ authorization_response_iss_parameter_supported=value.authorization_response_iss_parameter_supported}
+ break
+ end
+ end
+ if not metadata then return nil,'Cannot discover OAuth authorization-server metadata' end
+ if not self:url_allowed(metadata.authorization_endpoint) or not self:url_allowed(metadata.token_endpoint) then return nil,'Unsafe OAuth endpoint for this resource' end
+ local registration=self.cfg.oauth
+ local registration_key='mcp.oauth.registration_'..config.hash(issuer)
+ if not registration or not registration.client_id then
+ registration=self.state and self.state.get(registration_key)
+ if type(registration)=='table' and registration.client_secret~=nil then
+ return nil,self:recovery_error('Confidential DCR is unsupported')
+ end
+ if type(registration)~='table' or registration.issuer~=issuer or not nonempty(registration.client_id) then
+ if not self:url_allowed(metadata.registration_endpoint) then return nil,'OAuth server needs configured oauth.client_id and oauth.issuer (no safe DCR endpoint)' end
+ local value,why=self:fetch(metadata.registration_endpoint,{client_name='panto-mcp',application_type='native',
+ redirect_uris={'http://127.0.0.1/callback'},token_endpoint_auth_method='none',
+ grant_types={'authorization_code','refresh_token'},response_types={'code'}})
+ if not value then return nil,why end
+ if value.client_secret~=nil or (value.token_endpoint_auth_method~=nil and value.token_endpoint_auth_method~='none') then
+ return nil,'Confidential DCR is unsupported; configure oauth.client_id, oauth.issuer and optional oauth.client_secret'
+ end
+ if not nonempty(value.client_id) then return nil,'Invalid OAuth registration response' end
+ registration={issuer=issuer,client_id=value.client_id}
+ if self.state and not self.state.set(registration_key,registration) then return nil,'Cannot persist OAuth registration' end
+ end
+ end
+ local scopes=challenge.scope
+ if scopes==nil then scopes=prm.scopes_supported end
+ if scopes==nil then scopes=self.cfg.oauth and self.cfg.oauth.scopes end
+ if self.previous_issuer==issuer then scopes=M.union(scopes,self.requested_scopes) end
+ local ok,why=self:define({issuer=issuer,metadata=metadata,client_id=registration.client_id,scopes=M.scopes(scopes)})
+ if not ok then return nil,why end
+ if not self:save() then return nil,'Cannot persist OAuth discovery' end
+ if self.previous_issuer and self.previous_issuer~=issuer and self.state then
+ self.state.set('mcp.oauth.registration_'..config.hash(self.previous_issuer),nil)
+ end
+ return true
+ end
+ local ok,value,err=pcall(work)
+ if not ok then value=nil; err='OAuth discovery failed' end
+ if not value then
+ self.backoff=math.min((self.backoff or 2500)*2,60000); self.retry_at=self.clock()+self.backoff; self.discovery_error=err
+ else self.backoff=nil; self.discovery_error=nil; self.retry_at=nil end
+ self.discovering=nil; future:resolve(value,err)
+ return value,err
+end
+function M:poll(callback,remaining,active)
+ if self.closed then return end
+ local t
+ t=self.timer_factory(1000,function()
+ self.timers[t]=nil
+ if self.closed or (active and not active()) then return end
+ local status=self:auth_status()
+ if status.state~='pending' then callback(status); return end
+ if remaining<=1000 then callback(nil); return end
+ self:poll(callback,remaining-1000,active)
+ end)
+ self.timers[t]=true
+end
+function M:refresh()
+ if self.refreshing then return self.refreshing:await() end
+ local future=async.future(); self.refreshing=future
+ local ok=self.auth.refresh(self.name)
+ if not ok then self.refreshing=nil; return nil,self.cfg.auth and self:configured_error() or self:recovery_error(self:login_error()) end
+ self.cached_status={state='pending'}; self.status_at=self.clock()
+ self:poll(function(status)
+ self.refreshing=nil
+ if status and status.state=='logged_in' and not status.error then future:resolve(true)
+ else future:resolve(nil,self.cfg.auth and self:configured_error() or self:recovery_error(self:login_error())) end
+ end,70000)
+ return future:await()
+end
+function M:recover(data)
+ local challenge=data.challenge or {}
+ if data.http_status==403 then
+ if challenge.error~='insufficient_scope' then return nil,'Forbidden (HTTP 403); check server permissions' end
+ if self.cfg.auth then return nil,'Configured auth session needs additional scopes; update its scopes and use panto auth login' end
+ if not self.definition then return nil,'Insufficient scope (HTTP 403); no OAuth definition is available' end
+ local scopes=M.union(M.union(self.spec.scopes,self:auth_status().scopes),challenge.scope)
+ self.definition.scopes=scopes
+ local ok,err=self:define(self.definition); if not ok then return nil,err end
+ self:save()
+ return nil,'Additional permission required; run /mcp-login '..self.cfg.name
+ end
+ if not self:available() then
+ return nil,self.cfg.auth and self:configured_error() or 'MCP OAuth requires a newer panto with panto.ext.auth and HTTP POST support'
+ end
+ if data.auth_used then
+ local ok,err=self:refresh()
+ if ok or self.cfg.auth then return ok,err end
+ self:invalidate()
+ local discovered,why=self:discover(challenge)
+ self.login_required=not self:usable() or nil
+ return nil,discovered and err or self:recovery_error(why)
+ end
+ local ok,err=self:discover(challenge)
+ if not ok then return nil,err end
+ if self:request_auth() then return true end
+ return nil,self:login_error()
+end
+function M:login(callback_url,on_success,on_error)
+ if not self:available() then return nil,self.cfg.auth and 'Configured auth login requires a newer panto and an oauth_pkce session; use panto auth login instead' or 'MCP OAuth requires a newer panto with panto.ext.auth' end
+ if not self.cfg.auth and not self.definition then return nil,'OAuth discovery is not ready; retry /mcp-login '..self.cfg.name..' after checking /mcp' end
+ local usable=self:usable()
+ local result
+ if callback_url then
+ if not self.auth.complete(self.name,callback_url) then return nil,'OAuth callback rejected; check the URL/state/issuer and retry' end
+ elseif self.login_url and self:auth_status().state=='pending' then result={url=self.login_url}
+ else
+ result=self.auth.login(self.name)
+ if not result then
+ local text='Cannot start OAuth login; check that the configured auth session is oauth_pkce'
+ return nil,self.cfg.auth and text or self:recovery_error(text)
+ end
+ self.login_url=result.url
+ end
+ self.login_usable=usable; self.login_required=not usable or nil
+ self.cached_status={state='pending'}; self.status_at=self.clock()
+ self.login_poll=(self.login_poll or 0)+1
+ local generation=self.login_poll
+ self:poll(function(status)
+ self.login_required=nil; self.login_url=nil
+ if status and status.state=='logged_in' and not status.error then
+ self.login_usable=nil; on_success()
+ elseif on_error then
+ on_error(self:recovery_error('OAuth login failed or timed out'))
+ end
+ end,670000,function() return generation==self.login_poll end)
+ return result and result.url or true
+end
+function M:close()
+ self.closed=true
+ for t in pairs(self.timers) do async.close(t) end; self.timers={}
+ for handle,future in pairs(self.requests or {}) do handle:cancel(); future:resolve(nil,'session ended') end
+ if self.refreshing then self.refreshing:resolve(nil,'session ended') end
+end
+return M
diff --git a/panto_mcp/prompts.lua b/panto_mcp/prompts.lua
new file mode 100644
index 0000000..6d84509
--- /dev/null
+++ b/panto_mcp/prompts.lua
@@ -0,0 +1,267 @@
+local async = require('panto_mcp.async')
+local json = require('panto').ext.json
+local results = require('panto_mcp.results')
+
+local M = {}
+local function shell_words(text)
+ local words, i = {}, 1
+ while i <= #text do
+ while text:sub(i,i):match('%s') do i=i+1 end
+ if i > #text then break end
+ local out, quote, started = {}, nil, false
+ while i <= #text do
+ local ch=text:sub(i,i)
+ if quote == "'" then
+ if ch == "'" then quote=nil else out[#out+1]=ch end
+ started=true; i=i+1
+ elseif quote == '"' then
+ if ch == '"' then quote=nil; i=i+1
+ elseif ch == '\\' then
+ if i == #text then return nil,'trailing escape' end
+ out[#out+1]=text:sub(i+1,i+1); i=i+2
+ else out[#out+1]=ch; i=i+1 end
+ started=true
+ elseif ch:match('%s') then break
+ elseif ch == "'" or ch == '"' then quote=ch; started=true; i=i+1
+ elseif ch == '\\' then
+ if i == #text then return nil,'trailing escape' end
+ out[#out+1]=text:sub(i+1,i+1); started=true; i=i+2
+ else out[#out+1]=ch; started=true; i=i+1 end
+ end
+ if quote then return nil,'unclosed quote' end
+ if started then words[#words+1]=table.concat(out) end
+ end
+ return words
+end
+M.shell_words = shell_words
+
+local function has_named_token(text,name)
+ local needle=name..'='
+ local cursor=1
+ while true do
+ local start=text:find(needle,cursor,true)
+ if not start then return false end
+ if start==1 or text:sub(start-1,start-1):match('%s') then return true end
+ cursor=start+1
+ end
+end
+function M.parse_arguments(prompt, text)
+ if type(text) ~= 'string' then return nil,'arguments must be text' end
+ local args, definitions = {}, {}
+ for _, argument in ipairs(prompt.arguments or {}) do
+ if type(argument.name) ~= 'string' or argument.name == '' then return nil,'invalid prompt argument metadata' end
+ definitions[argument.name]=argument
+ end
+ local words,err={},nil
+ if #(prompt.arguments or {})==1 then
+ local only=prompt.arguments[1].name
+ local remainder=text:match('^%s*(.-)%s*$') or ''
+ if not has_named_token(remainder,only) then
+ if remainder~='' then args[only]=remainder end
+ else words,err=shell_words(text) end
+ else words,err=shell_words(text) end
+ if not words then return nil,err end
+ for _,word in ipairs(words) do
+ local equals=word:find('=',1,true)
+ if not equals or equals == 1 then return nil,'expected name=value argument' end
+ local name,value=word:sub(1,equals-1),word:sub(equals+1)
+ if not definitions[name] then return nil,'unknown prompt argument: '..name end
+ if args[name] ~= nil then return nil,'duplicate prompt argument: '..name end
+ args[name]=value
+ end
+ local missing={}
+ for _,argument in ipairs(prompt.arguments or {}) do
+ if argument.required and args[argument.name] == nil then missing[#missing+1]=argument.name end
+ end
+ if #missing > 0 then return nil,'missing required arguments: '..table.concat(missing,', ') end
+ return args
+end
+
+local function text_block(text) return {type='text',text=text} end
+local function content_blocks(content, role)
+ if type(content)=='string' then return {text_block(content)} end
+ local entries
+ if type(content)~='table' then return {text_block('[Unsupported MCP prompt content]')} end
+ if type(content.type)=='string' then entries={content} else entries=content end
+ local out={}
+ local function add_image(data,mime)
+ mime=type(mime)=='string' and mime or nil
+ local supported={['image/png']=true,['image/jpeg']=true,['image/webp']=true,['image/bmp']=true,['image/gif']=true}
+ local is_image=mime and supported[mime:lower()]
+ local decoded=is_image and type(data)=='string' and results.decode64(data)
+ if role=='assistant' then out[#out+1]=text_block('[Assistant media omitted: '..tostring(mime or 'image')..']')
+ elseif not is_image then out[#out+1]=text_block('[MCP unsupported attachment omitted: '..tostring(mime or 'unknown MIME type')..']')
+ elseif decoded then out[#out+1]={type='media',data=decoded,media_type=mime}
+ else out[#out+1]=text_block('[Invalid MCP image omitted]') end
+ end
+ for _,block in ipairs(entries) do
+ if type(block)~='table' then out[#out+1]=text_block('[Unsupported MCP prompt content]')
+ elseif block.type=='text' then out[#out+1]=text_block(block.text or '')
+ elseif block.type=='image' then add_image(block.data,block.mimeType)
+ elseif block.type=='audio' then out[#out+1]=text_block('[MCP audio omitted: '..tostring(block.mimeType or 'unknown MIME type')..']')
+ elseif block.type=='resource' and type(block.resource)=='table' then
+ local resource=block.resource
+ if type(resource.text)=='string' then out[#out+1]=text_block((type(resource.uri)=='string' and '['..resource.uri..']\n' or '')..resource.text)
+ elseif resource.blob then add_image(resource.blob,resource.mimeType)
+ else out[#out+1]=text_block('[MCP resource omitted: '..tostring(resource.uri or 'unknown URI')..']') end
+ else out[#out+1]=text_block('[Unsupported MCP prompt content: '..tostring(block.type or 'unknown')..']') end
+ end
+ return out
+end
+function M.map_messages(messages)
+ if type(messages)~='table' then return nil,'invalid prompt messages' end
+ local mapped={}
+ for _,message in ipairs(messages) do
+ if type(message)~='table' or (message.role~='user' and message.role~='assistant') then
+ return nil,'invalid prompt message role'
+ end
+ mapped[#mapped+1]={role=message.role,blocks=content_blocks(message.content,message.role)}
+ end
+ return mapped
+end
+local function preflight(mapped)
+ local has_media=false
+ for _,message in ipairs(mapped) do
+ for _,block in ipairs(message.blocks) do if block.type=='media' then has_media=true end end
+ end
+ if not has_media then return end
+ local probe=require('panto').conversation()
+ for _,message in ipairs(mapped) do
+ if message.role=='user' then probe:add_user_blocks(message.blocks)
+ else probe:add_assistant_message({blocks=message.blocks}) end
+ end
+end
+function M.append_to(agent, messages)
+ local mapped,err=M.map_messages(messages)
+ if not mapped then return nil,err end
+ local ok=pcall(preflight,mapped)
+ if not ok then return nil,'MCP prompt image could not be decoded' end
+ local trailing_user=mapped[#mapped] and mapped[#mapped].role=='user'
+ local conv=agent:conversation()
+ local stop=trailing_user and #mapped-1 or #mapped
+ for i=1,stop do
+ local message=mapped[i]
+ if message.role=='user' then conv:add_user_blocks(message.blocks)
+ else conv:add_assistant_message({blocks=message.blocks}) end
+ end
+ if trailing_user then agent:submit(mapped[#mapped].blocks); return true end
+ return false
+end
+
+local function log(err) io.stderr:write('panto-mcp: prompt command: ',tostring(err),'\n') end
+local function unregister(ext,name)
+ local ok,value,err=pcall(ext.unregister_command,name)
+ if not ok or not value then log(ok and (err or ('cannot unregister '..name)) or value); return false end
+ return true
+end
+local function prompt_description(prompt)
+ local parts={}
+ if type(prompt.title)=='string' and prompt.title~='' then parts[#parts+1]=prompt.title end
+ if type(prompt.description)=='string' and prompt.description~='' then parts[#parts+1]=prompt.description end
+ local names={}
+ for _,argument in ipairs(prompt.arguments or {}) do names[#names+1]=argument.name end
+ if #names>0 then parts[#parts+1]='Arguments: '..table.concat(names,', ') end
+ return #parts>0 and table.concat(parts,' — ') or ('MCP prompt '..prompt.name)
+end
+function M.commands(ext, manager, turn, dynamic, warnings)
+ local registered, warned={},{}
+ local error_mount,error_text
+ local function clear_error()
+ if error_mount then
+ pcall(function() if error_mount:alive() then error_mount:unmount() end end)
+ error_mount=nil; error_text=nil
+ end
+ end
+ local function show_error(err)
+ error_text='MCP prompt failed: '..tostring(err):gsub('[%z\1-\8\11\12\14-\31\127]','?'):sub(1,800)
+ if error_mount then
+ local ok=pcall(error_mount.invalidate,error_mount)
+ if ok then return end
+ error_mount=nil
+ end
+ if type(ext.mount)=='function' then
+ local ok,handle=pcall(ext.mount,{render=function() return error_text end},'above_input')
+ if ok then error_mount=handle; return end
+ end
+ log(error_text)
+ end
+ if type(ext.on)=='function' then
+ ext.on('command_start',clear_error); ext.on('turn_start',clear_error)
+ end
+ local function warning(key,text)
+ if warned[key] then return end
+ warned[key]=true
+ local message='prompt '..text
+ if warnings then warnings[#warnings+1]=message end
+ log(message)
+ end
+ local function reconcile(server, metadata, warm)
+ local wanted={}
+ for _,prompt in ipairs((metadata and metadata.catalog and metadata.catalog.prompts) or {}) do
+ if type(prompt.name)=='string' and not prompt.name:find('[/%s]') then
+ local name='mcp:'..server..':'..prompt.name
+ local description=prompt_description(prompt)
+ wanted[name]={server=server,prompt=prompt,signature=json.encode({description=description,arguments=prompt.arguments})}
+ else warning(server..':'..tostring(prompt.name),'command skipped because its name contains slash or whitespace: '..tostring(prompt.name)) end
+ end
+ if dynamic then
+ for name,old in pairs(registered) do
+ if old.server==server then
+ local next_prompt=wanted[name]
+ if not next_prompt or next_prompt.signature~=old.signature then
+ if unregister(ext,name) then registered[name]=nil end
+ end
+ end
+ end
+ end
+ for name,current in pairs(wanted) do
+ if not registered[name] and (dynamic or warm) then
+ local handler=function(text)
+ if turn.busy then return 'Cannot run an MCP prompt while a turn is in progress.' end
+ local args,why=M.parse_arguments(current.prompt,text or '')
+ if not args then return 'MCP prompt arguments: '..why end
+ async.run(function()
+ local messages,err=manager:prompt(current.server,current.prompt.name,args)
+ if not messages then show_error(err); return end
+ if turn.busy then show_error('result discarded because a turn started while the prompt was loading'); return end
+ local submitted,append_err=M.append_to(require('panto').ext.agent,messages)
+ if submitted==nil then show_error(append_err)
+ elseif not submitted and type(ext.emit)=='function' then
+ local emitted,emit_err=pcall(ext.emit,'agent_submission')
+ if not emitted then show_error(emit_err) end
+ end
+ end,show_error)
+ return 'Fetching MCP prompt…'
+ end
+ local ok,value,err=pcall(ext.register_command,{name=name,description=prompt_description(current.prompt),handler=handler})
+ if ok and (value or (not dynamic and err==nil)) then registered[name]=current
+ else
+ local reason=ok and (err or ('register_command failed for '..name)) or value
+ warning(name..':registration','command registration failed for '..name..': '..tostring(reason))
+ end
+ end
+ end
+ end
+ return {reconcile=reconcile,registered=registered}
+end
+function M.track_busy(ext,turn,prompt_commands)
+ local in_turn,commands,prompt_dispatch=false,0,false
+ local function update() turn.busy=in_turn or commands>0 end
+ local function event_name(event)
+ return type(event)=='table' and type(event.command_name)=='string' and event.command_name or '<unknown command>'
+ end
+ ext.on('turn_start',function() in_turn=true; update() end)
+ ext.on('turn_end',function() in_turn=false; update() end)
+ ext.on('command_start',function(event)
+ local name=event_name(event)
+ prompt_dispatch=prompt_commands.registered[name]~=nil
+ if not prompt_dispatch then commands=commands+1 end
+ update()
+ end)
+ ext.on('command_end',function(event)
+ if not prompt_dispatch then commands=math.max(0,commands-1) end
+ prompt_dispatch=false
+ update()
+ end)
+end
+return M
diff --git a/panto_mcp/results.lua b/panto_mcp/results.lua
new file mode 100644
index 0000000..b7da16b
--- /dev/null
+++ b/panto_mcp/results.lua
@@ -0,0 +1,89 @@
+local json = require('panto').ext.json
+local M = {MAX_OUTPUT=100*1024, MAX_IMAGE=5*1024*1024, MAX_ATTACHMENTS=10*1024*1024}
+local alphabet='ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+local tokens,bytes={},{}
+for i=1,#alphabet do
+ local c=alphabet:sub(i,i); local v=i-1
+ tokens[c]=string.char((v>>4)&3,(v>>2)&3,v&3)
+end
+for a=0,3 do for b=0,3 do for c=0,3 do for d=0,3 do
+ local key=string.char(a,b,c,d)
+ local value=string.char((a<<6)|(b<<4)|(c<<2)|d)
+ bytes[key]=value=='%' and '%%' or value
+end end end end
+function M.decode64(s,cap)
+ if type(s)~='string' then return nil,'invalid base64' end
+ cap=cap or M.MAX_IMAGE
+ if #s>math.ceil(cap/3)*4 then return nil,'attachment exceeds size cap' end
+ if #s%4~=0 or s:find('[^A-Za-z0-9+/=]') or not s:match('^[A-Za-z0-9+/]*=?=?$') then return nil,'invalid base64' end
+ local symbols=s:gsub('=+$','')
+ local padding=#s-#symbols
+ if padding>2 or (#symbols%4~=0 and #symbols%4~=2 and #symbols%4~=3) or
+ (padding==1 and #symbols%4~=3) or (padding==2 and #symbols%4~=2) then return nil,'invalid base64 padding' end
+ local size=math.floor(#symbols*3/4)
+ if size>cap then return nil,'attachment exceeds size cap' end
+ if #symbols==0 then return '' end
+ -- Table replacements keep both full-string passes in gsub's C loop. Each
+ -- sextet expands to three 2-bit tokens; groups of four tokens form a byte.
+ local bits=symbols:gsub('.',tokens)
+ local rem=#bits%4
+ if rem~=0 then bits=bits .. string.rep('\0',4-rem) end
+ local decoded=bits:gsub('....',bytes)
+ return decoded:sub(1,size)
+end
+function M.cap(text,limit)
+ limit=limit or M.MAX_OUTPUT
+ if #text<=limit then return text end
+ local at=limit
+ while at>0 and text:byte(at+1) and text:byte(at+1)>=128 and text:byte(at+1)<192 do at=at-1 end
+ return text:sub(1,at) .. '\n[truncated at ' .. limit .. ' bytes]'
+end
+function M.map(server,result,err)
+ if err then
+ local message=type(err)=='table' and (tostring(err.message) .. ' (' .. tostring(err.code) .. ')') or tostring(err)
+ return {text=M.cap(server .. ': ' .. message),is_error=true,attachments=json.array({})}
+ end
+ if type(result)~='table' then return {text=server .. ': invalid MCP result',is_error=true,attachments=json.array({})} end
+ if result.resultType=='input_required' then return {text=server .. ': server requested user input; panto does not support it yet',is_error=true,attachments=json.array({})} end
+ local texts,attachments={},json.array({}); local total=0
+ local function text(s) texts[#texts+1]=tostring(s or '') end
+ local function image(data,mime)
+ local bytes,why=M.decode64(data,math.min(M.MAX_IMAGE,M.MAX_ATTACHMENTS-total))
+ if not bytes then text('[' .. why .. ']'); return end
+ total=total+#bytes
+ attachments[#attachments+1]={data=bytes,media_type=mime or 'image/png'}
+ end
+ local content
+ content=function(block)
+ if type(block)~='table' then return end
+ if block.type=='text' then text(block.text)
+ elseif block.type=='image' then image(block.data,block.mimeType)
+ elseif block.type=='audio' then text('[audio ' .. tostring(block.mimeType or 'unknown') .. ', base64 bytes ' .. (type(block.data)=='string' and #block.data or 0) .. ']')
+ elseif block.type=='resource_link' then
+ text(tostring(block.name or '') .. ' ' .. tostring(block.uri or '') .. ' ' .. tostring(block.description or '') ..
+ '\nRead with mcp.read_resource{server=' .. json.encode(server) .. ', uri=' .. json.encode(block.uri or '') .. '}')
+ elseif block.type=='resource' then
+ local r=type(block.resource)=='table' and block.resource or {}; text('Resource: ' .. tostring(r.uri or ''))
+ if r.text then text(r.text)
+ elseif r.blob and type(r.mimeType)=='string' and r.mimeType:match('^image/') then image(r.blob,r.mimeType)
+ else text('[embedded resource ' .. tostring(r.mimeType or 'unknown') .. ', base64 bytes ' .. (type(r.blob)=='string' and #r.blob or 0) .. ']') end
+ else text('[unsupported MCP content: ' .. tostring(block.type) .. ']') end
+ end
+ for _,block in ipairs(type(result.content)=='table' and result.content or {}) do content(block) end
+ for _,resource in ipairs(type(result.contents)=='table' and result.contents or {}) do content({type='resource',resource=resource}) end
+ local structured=result.structuredContent
+ if structured~=nil then
+ local encoded=json.encode(structured)
+ local duplicate=false
+ for _,s in ipairs(texts) do
+ if s==encoded then duplicate=true; break end
+ local ok,decoded=pcall(json.decode,s)
+ if ok and json.encode(decoded)==encoded then duplicate=true; break end
+ end
+ if not duplicate then text(encoded) end
+ if #encoded>M.MAX_OUTPUT then structured=nil end
+ end
+ return {text=M.cap(table.concat(texts,'\n')),attachments=attachments,
+ structured=structured,is_error=result.isError==true}
+end
+return M
diff --git a/panto_mcp/search.lua b/panto_mcp/search.lua
new file mode 100644
index 0000000..a36e48c
--- /dev/null
+++ b/panto_mcp/search.lua
@@ -0,0 +1,83 @@
+local config = require('panto_mcp.config')
+local json = require('panto').ext.json
+local M = {}
+local function terms(s)
+ local out={}; for t in tostring(s or ''):lower():gmatch('[%w]+') do out[#out+1]=t end; return out
+end
+local function fields(item)
+ local out={item.name or '',item.name or '',item.name or '',item.title or '',item.title or '',item.uri or '',item.uriTemplate or '',item.description or ''}
+ local function props(schema,depth)
+ if type(schema)~='table' or depth>8 then return end
+ for name,p in pairs(type(schema.properties)=='table' and schema.properties or {}) do
+ out[#out+1]=tostring(name)
+ if type(p)=='table' then out[#out+1]=type(p.description)=='string' and p.description or ''; props(p,depth+1) end
+ end
+ end
+ props(item.inputSchema,0)
+ return table.concat(out,' ')
+end
+function M.search(states,query,opts)
+ opts=opts or {}; local docs,df={},{}
+ for server,state in pairs(states) do
+ if not opts.server or opts.server==server then
+ local catalog=(state.metadata and state.metadata.catalog) or {}
+ for _,kind in ipairs({'tools','resources','templates'}) do
+ for _,item in ipairs(catalog[kind] or {}) do
+ if kind~='tools' or config.tool_enabled(state.cfg,item.name or '') then
+ local tf,n={},0
+ for _,t in ipairs(terms(fields(item))) do tf[t]=(tf[t] or 0)+1; n=n+1 end
+ for t in pairs(tf) do df[t]=(df[t] or 0)+1 end
+ docs[#docs+1]={server=server,item=item,kind=kind,tf=tf,n=n}
+ end
+ end
+ end
+ end
+ end
+ local total=0; for _,d in ipairs(docs) do total=total+d.n end
+ local avg=math.max(1,total/math.max(1,#docs)); local q=terms(query)
+ local ranked={}
+ for _,d in ipairs(docs) do
+ local score=0
+ for _,t in ipairs(q) do
+ local f=d.tf[t] or 0
+ if f>0 then score=score+math.log(1+(#docs-(df[t] or 0)+0.5)/((df[t] or 0)+0.5))*f*2.2/(f+1.2*(0.25+0.75*d.n/avg)) end
+ end
+ if #q==0 or score>0 then d.score=score; ranked[#ranked+1]=d end
+ end
+ table.sort(ranked,function(a,b)
+ if a.score~=b.score then return a.score>b.score end
+ return (a.server .. ':' .. a.kind .. ':' .. tostring(a.item.name or a.item.uri or a.item.uriTemplate)) <
+ (b.server .. ':' .. b.kind .. ':' .. tostring(b.item.name or b.item.uri or b.item.uriTemplate))
+ end)
+ local hits=json.array({})
+ for i=1,math.min(#ranked,opts.limit or 10) do
+ local d=ranked[i]; local v=d.item
+ hits[#hits+1]={server=d.server,kind=d.kind,name=v.name or v.uri or v.uriTemplate,
+ title=v.title or (type(v.annotations)=='table' and v.annotations.title),description=v.description,
+ inputSchema=v.inputSchema,uri=v.uri,uriTemplate=v.uriTemplate,mimeType=v.mimeType,score=d.score}
+ end
+ local out={hits=hits,total=#ranked}
+ if opts.server and states[opts.server] then
+ local meta=states[opts.server].metadata
+ if meta and type(meta.instructions)=='string' then out.instructions=require('panto_mcp.results').cap(meta.instructions,4096) end
+ end
+ return out
+end
+local function distance(a,b)
+ a=a:sub(1,256):lower(); b=b:sub(1,256):lower()
+ local prev={}; for j=0,#b do prev[j]=j end
+ for i=1,#a do
+ local row={[0]=i}
+ for j=1,#b do row[j]=math.min(row[j-1]+1,prev[j]+1,prev[j-1]+(a:byte(i)==b:byte(j) and 0 or 1)) end
+ prev=row
+ end
+ return prev[#b]
+end
+function M.closest(name,names)
+ local ranked={}
+ for _,n in ipairs(names) do ranked[#ranked+1]={name=n,d=distance(name,n)} end
+ table.sort(ranked,function(a,b) return a.d==b.d and a.name<b.name or a.d<b.d end)
+ local out={}; for i=1,math.min(3,#ranked) do out[#out+1]=ranked[i].name end
+ return table.concat(out,', ')
+end
+return M
diff --git a/panto_mcp/stdio.lua b/panto_mcp/stdio.lua
new file mode 100644
index 0000000..1a9d996
--- /dev/null
+++ b/panto_mcp/stdio.lua
@@ -0,0 +1,108 @@
+local uv = require('luv')
+local json = require('panto').ext.json
+local async = require('panto_mcp.async')
+local M = {}; M.__index=M
+-- Exported small framer for deterministic checks. Protocol-sized bound prevents
+-- an untrusted/noisy server from accumulating an unbounded partial line.
+function M.framer(emit, max_bytes, on_bad_line)
+ local buf=''; max_bytes=max_bytes or 16*1024*1024
+ return function(chunk)
+ buf=buf .. chunk
+ while true do
+ local at=buf:find('\n',1,true)
+ if not at then if #buf>max_bytes then return nil,'stdio frame exceeds size limit' end; return true end
+ if at>max_bytes then return nil,'stdio frame exceeds size limit' end
+ local line=buf:sub(1,at-1):gsub('\r$',''); buf=buf:sub(at+1)
+ if line:match('%S') then
+ local ok,msg=pcall(json.decode,line)
+ if not ok then
+ if on_bad_line then on_bad_line(line) end
+ elseif type(msg)~='table' then return nil,'malformed JSON on MCP stdout'
+ else emit(msg) end
+ end
+ end
+ end
+end
+function M.new(cfg)
+ local path,err=package.searchpath('panto_mcp.supervisor',package.path)
+ if not path then return nil,err end
+ local self=setmetatable({stderr_tail='',cfg=cfg},M)
+ self.stdin=uv.new_pipe(false); self.stdout=uv.new_pipe(false)
+ self.stderr=uv.new_pipe(false); self.lifeline=uv.new_pipe(false)
+ local function stop_orphan()
+ local server_pid=self.server_pid
+ if not server_pid then return end
+ pcall(uv.kill,-server_pid,'sigterm')
+ local escalation=uv.new_timer()
+ escalation:start(2000,0,function()
+ if uv.kill(-server_pid,0) then pcall(uv.kill,-server_pid,'sigkill') end
+ async.close(escalation)
+ end)
+ end
+ local proc,pid=uv.spawn(uv.exepath(),{
+ args={'lua',path,json.encode({command=cfg.command,args=json.array(cfg.args or {}),env=cfg.env or {}})},
+ cwd=cfg.cwd,detached=true,
+ stdio={self.stdin,self.stdout,self.stderr,self.lifeline},
+ },function(code,signal)
+ async.close(self.proc)
+ if not self.closed then
+ stop_orphan()
+ self:fail('supervisor exited (' .. code .. ', signal ' .. signal .. ')')
+ end
+ end)
+ if not proc then self:close(); return nil,pid end
+ self.proc=proc; self.supervisor_pid=pid
+ local function append_tail(data)
+ self.stderr_tail=(self.stderr_tail .. data):sub(-8192)
+ end
+ local feed=M.framer(function(msg) if self.on_message then self.on_message(msg) end end,nil,function(line)
+ append_tail(line .. '\n')
+ end)
+ self.stdout:read_start(function(e,data)
+ if self.closed then return end
+ if e or not data then self:fail(e or 'MCP stdout closed'); return end
+ local ok,why=feed(data); if not ok then self:fail(why) end
+ end)
+ local stderr_buf=''
+ self.stderr:read_start(function(_,data)
+ if not data then return end
+ stderr_buf=stderr_buf .. data
+ -- Marker can straddle chunks. Keep only a bounded diagnostic tail.
+ self.server_pid=tonumber(stderr_buf:match('PANTO_MCP_PID=(%d+)\n')) or self.server_pid
+ stderr_buf=stderr_buf:sub(-8192)
+ append_tail(data:gsub('PANTO_MCP_PID=%d+\r?\n',''))
+ end)
+ -- Pending request/startup timers keep the loop alive only while needed.
+ for _,h in ipairs({proc,self.stdin,self.stdout,self.stderr,self.lifeline}) do h:unref() end
+ return self
+end
+function M:set_callbacks(message,err) self.on_message=message; self.on_error=err end
+function M:fail(err)
+ if self.closed then return end
+ local tail=self.stderr_tail:sub(-500):gsub('[%z\1-\8\11\12\14-\31\127]',' ')
+ if tail~='' then err=tostring(err) .. ' (stderr: ' .. tail .. ')' end
+ self:close()
+ if self.on_error then self.on_error(tostring(err)) end
+end
+function M:send(msg, _opts)
+ if self.closed then return nil,'stdio transport closed' end
+ local ok,payload=pcall(json.encode,msg); if not ok then return nil,payload end
+ local wrote,handle,err=pcall(self.stdin.write,self.stdin,payload .. '\n',function(e)
+ if e then self:fail(e) end
+ end)
+ if not wrote then self:fail(handle); return nil,handle end
+ if not handle then self:fail(err); return nil,err end
+ return handle
+end
+function M:cancel(id)
+ self:send({jsonrpc='2.0',method='notifications/cancelled',params={requestId=id,reason='client cancelled'}})
+end
+function M:close()
+ if self.closed then return end
+ self.closed=true
+ -- Never signal/wait here: the detached supervisor owns escalation, even
+ -- after this runtime disappears. Closing stdin precedes lifeline EOF.
+ async.close(self.stdin); async.close(self.lifeline)
+ async.close(self.stdout); async.close(self.stderr)
+end
+return M
diff --git a/panto_mcp/supervisor.lua b/panto_mcp/supervisor.lua
new file mode 100644
index 0000000..48649aa
--- /dev/null
+++ b/panto_mcp/supervisor.lua
@@ -0,0 +1,65 @@
+-- Standalone: panto lua <this file> <JSON {command,args}>. Never require in host.
+-- fds 0/1/2 are inherited by the detached server; fd 3 is the host lifeline.
+local uv = require('luv')
+local json = require('panto').ext.json
+local cfg = assert(json.decode(assert(arg[1], 'missing supervisor configuration')))
+local timers, signals = {}, {}
+local child, pid, stopping, exited
+local function close(h) if h and not h:is_closing() then h:close() end end
+local life = uv.new_pipe(false)
+assert(life:open(3))
+local function alive()
+ return pid and uv.kill(-pid, 0) ~= nil
+end
+local function finish()
+ close(life)
+ for _, h in ipairs(timers) do close(h) end
+ for _, h in ipairs(signals) do close(h) end
+ if exited then close(child) end
+end
+local function timer(ms, repeat_ms, fn)
+ local t = uv.new_timer(); timers[#timers + 1] = t
+ t:start(ms, repeat_ms, fn)
+ return t
+end
+local function shutdown()
+ if stopping then return end
+ stopping = true
+ close(life)
+ -- The host has already closed stdin. Even if the group leader exited,
+ -- descendants still receive the escalation (npx/shell wrappers).
+ timer(2000, 0, function()
+ if alive() then uv.kill(-pid, 'sigterm') end
+ timer(2000, 0, function()
+ if alive() then uv.kill(-pid, 'sigkill') end
+ end)
+ end)
+ timer(0, 50, function() if not alive() then finish() end end)
+end
+local child_env = uv.os_environ()
+for k, v in pairs(cfg.env or {}) do child_env[k] = v end
+local env = {}
+for k, v in pairs(child_env) do env[#env + 1] = k .. '=' .. v end
+child, pid = uv.spawn(cfg.command, {
+ args = cfg.args or {}, stdio = {0, 1, 2}, env = env, detached = true,
+}, function()
+ exited = true
+ close(child)
+ shutdown()
+end)
+if not child then
+ io.stderr:write('panto-mcp supervisor spawn failed: ', tostring(pid), '\n'); io.stderr:flush()
+ close(life)
+else
+ io.stderr:write('PANTO_MCP_PID=', tostring(pid), '\n'); io.stderr:flush()
+ -- The server inherited these descriptors; retaining supervisor copies
+ -- would delay stdout EOF until after the grace period.
+ assert(uv.fs_close(0))
+ assert(uv.fs_close(1))
+ life:read_start(function(_, data) if not data then shutdown() end end)
+ for _, name in ipairs({'sigint', 'sigterm', 'sighup'}) do
+ local s = uv.new_signal(); signals[#signals + 1] = s
+ s:start(name, shutdown)
+ end
+end
+uv.run()
diff --git a/panto_mcp/tools.lua b/panto_mcp/tools.lua
new file mode 100644
index 0000000..4651ea6
--- /dev/null
+++ b/panto_mcp/tools.lua
@@ -0,0 +1,97 @@
+local async = require('panto_mcp.async')
+local results = require('panto_mcp.results')
+local validate = require('panto_mcp.validate')
+local json = require('panto').ext.json
+local M = {}
+function M.status(manager,warnings)
+ local lines={}
+ for _,warning in ipairs(warnings or {}) do lines[#lines+1]='Config warning: ' .. warning end
+ for _,s in ipairs(manager:servers()) do
+ lines[#lines+1]=string.format('%s: %s · %s · %s · tools=%d prompts=%d resources=%d templates=%d',
+ s.name,s.state,s.era or 'unknown era',s.transport=='http' and 'HTTP URL' or s.transport,s.tools,s.prompts,s.resources,s.templates)
+ if s.auth then lines[#lines+1]=' auth: '..s.auth end
+ if s.notification_warning then lines[#lines+1]=' warning: '..s.notification_warning end
+ if s.error then lines[#lines+1]=' error: ' .. s.error end
+ if s.cache_error then lines[#lines+1]=' cache: ' .. tostring(s.cache_error) end
+ if s.stderr~='' then lines[#lines+1]=' stderr: '..s.stderr:sub(-2048):gsub('[%z\1-\8\11\12\14-\31\127]','?') end
+ end
+ return #lines>0 and table.concat(lines,'\n') or 'No enabled MCP servers.'
+end
+local function checked(input,schema)
+ local ok,errors=validate.check(input,schema)
+ if not ok then error(table.concat(errors,'\n'),0) end
+end
+local function mapped(result)
+ if result.is_error then error(result.text,0) end
+ return {text=result.text,attachments=result.attachments}
+end
+local base={server={type='string'},tool={type='string'},input={},uri={type='string'},
+ query={type='string'},limit={type='integer',minimum=1,maximum=100}}
+function M.register_resource(ext,manager)
+ local schema={type='object',properties={server=base.server,uri=base.uri},required={'server','uri'}}
+ local ok,err=ext.register_tool({name='mcp.read_resource',
+ description='Read an MCP resource URI on its originating server (including resource_link results). Does not fetch arbitrary web URLs.',
+ schema=schema,handler=function(input) checked(input,schema); return mapped(manager:read_resource(input.server,input.uri)) end})
+ if not ok and err then io.stderr:write('panto-mcp: cannot register mcp.read_resource: ',tostring(err),'\n') end
+ return ok
+end
+function M.register(ext,manager,warnings,include_search,include_resource)
+ if include_search ~= false then
+ for _,spec in ipairs({
+ {name='mcp.search',description='Search MCP tools/resources/templates. Omit query to browse. Returns exact names and full tool input schemas; warm metadata search starts no servers.',
+ schema={type='object',properties={query=base.query,server=base.server,limit=base.limit}},
+ handler=function(input)
+ local value,err=manager:search(input.query,{server=input.server,limit=input.limit})
+ if not value then error(err,0) end
+ return results.cap(json.encode(value))
+ end},
+ {name='mcp.call',description='Call one MCP tool by exact server/tool names, with input matching the live inputSchema returned by mcp.search. No fuzzy execution.',
+ schema={type='object',properties={server=base.server,tool=base.tool,input=base.input},required={'server','tool'}},
+ handler=function(input) return mapped(manager:call(input.server,input.tool,input.input)) end},
+ }) do
+ local handler=spec.handler
+ spec.handler=function(input) checked(input,spec.schema); return handler(input) end
+ ext.register_tool(spec)
+ end
+ end
+ if include_resource then M.register_resource(ext,manager) end
+ M.register_status(ext,manager,warnings)
+end
+function M.register_status(ext,manager,warnings)
+ ext.register_command({name='mcp-login',description='Log in to an HTTP MCP server: /mcp-login <server> [callback-url | --reregister]',handler=function(args)
+ local name,callback_url=(args or ''):match('^%s*(%S+)%s*(.-)%s*$')
+ if not name or callback_url:find('%s') then return 'Usage: /mcp-login <server> [callback-url | --reregister]' end
+ return manager:login(name,callback_url~='' and callback_url~='--reregister' and callback_url or nil,callback_url=='--reregister')
+ end})
+ ext.register_command({name='mcp',description='MCP status; /mcp refresh [server] starts a metadata refresh.',handler=function(args)
+ args=args or ''
+ if args=='' then return M.status(manager,warnings) end
+ local cmd,name=args:match('^(%S+)%s*(.-)%s*$')
+ if cmd~='refresh' or name:find('%s') then return 'Usage: /mcp [refresh [server]]' end
+ if name=='' then name=nil end
+ if name then local s,err=manager:lookup(name); if not s then return err end end
+ async.run(function() manager:refresh(name) end)
+ return 'MCP refresh started; /mcp shows current status.'
+ end})
+end
+function M.hint(ext,servers)
+ local names={}; local search_enabled=false
+ for n,c in pairs(servers) do names[#names+1]=n; search_enabled=search_enabled or c.expose=='search' end
+ table.sort(names)
+ local lines={'## MCP'}
+ if search_enabled then
+ lines[#lines+1]='Find tools/resources with mcp.search; call exact names with mcp.call. '
+ ..'std.lua reference: require("panto_mcp.docs").discovery (also .calls, .resources, .prompts).'
+ else
+ lines[#lines+1]='Eager MCP tools are registered as mcp.<server>.<tool>; '
+ ..'std.lua reference: require("panto_mcp.docs").discovery (also .calls, .resources, .prompts).'
+ end
+ for _,n in ipairs(names) do
+ local c=servers[n]; lines[#lines+1]=n .. ': ' .. (c.transport=='http' and 'HTTP URL' or 'stdio') .. ', ' .. c.expose
+ end
+ ext.on('session_ready',function()
+ local agent=ext.agent
+ if agent and type(agent.add_system_message)=='function' then agent:add_system_message(table.concat(lines,'\n')) end
+ end)
+end
+return M
diff --git a/panto_mcp/validate.lua b/panto_mcp/validate.lua
new file mode 100644
index 0000000..4719b54
--- /dev/null
+++ b/panto_mcp/validate.lua
@@ -0,0 +1,134 @@
+-- Cheap JSON Schema 2020-12 checks, not a full dialect implementation.
+-- Unknown keywords (notably pattern/format) are intentionally ignored.
+local json = require('panto').ext.json
+local array_mt=getmetatable(json.array({}))
+local M = {}
+local function array(v)
+ if type(v)~='table' then return false end
+ local n=0
+ for k in pairs(v) do if type(k)~='number' or k<1 or k%1~=0 then return false end; n=n+1 end
+ return n==#v
+end
+local function matches(v,t)
+ if t=='null' then return v==json.null end
+ if v==json.null then return false end
+ if t=='array' then return array(v) end
+ if t=='object' then return type(v)=='table' and getmetatable(v)~=array_mt and (not array(v) or next(v)==nil) end
+ if t=='integer' then return type(v)=='number' and v%1==0 end
+ if t=='number' or t=='string' or t=='boolean' then return type(v)==t end
+ return true
+end
+local function equal(a,b)
+ if type(a)~=type(b) then return false end
+ if type(a)~='table' then return a==b end
+ for k,v in pairs(a) do if not equal(v,b[k]) then return false end end
+ for k in pairs(b) do if a[k]==nil then return false end end
+ -- Empty arrays and objects decoded by the host have distinct encodings.
+ if next(a)==nil and next(b)==nil then return json.encode(a)==json.encode(b) end
+ return true
+end
+M.equal=equal
+local function pointer(path,k) return path .. '/' .. tostring(k):gsub('~','~0'):gsub('/','~1') end
+local function ref(root,s)
+ if s=='#' then return root end
+ if s:sub(1,2)~='#/' then return nil end
+ local v,rest=root,s:sub(3)
+ while true do
+ local at=rest:find('/',1,true)
+ local part=at and rest:sub(1,at-1) or rest
+ part=part:gsub('~1','/'):gsub('~0','~')
+ if type(v)~='table' then return nil end
+ local key=part
+ if array(v) and (next(v)~=nil or getmetatable(v)==array_mt) then
+ if not part:match('^%d+$') then return nil end
+ key=tonumber(part)+1 -- JSON pointers use zero-based array indices.
+ end
+ v=v[key]
+ if not at then return v end
+ rest=rest:sub(at+1)
+ end
+end
+local check
+check=function(v,s,path,errors,root,depth)
+ if #errors>=100 then return end
+ local function add(message) errors[#errors+1]=(path=='' and '/' or path) .. ': ' .. message end
+ if s==false then add('value is forbidden'); return end
+ if type(s)~='table' then return end
+ if depth>64 then return end -- recursive schemas must not exhaust the Lua stack
+ if type(s['$ref'])=='string' then
+ local target=ref(root,s['$ref'])
+ if target~=nil then check(v,target,path,errors,root,depth+1) end
+ end
+ if s.type then
+ local ok=false
+ if type(s.type)=='string' then ok=matches(v,s.type)
+ elseif type(s.type)=='table' then for _,t in ipairs(s.type) do if matches(v,t) then ok=true end end end
+ if not ok then add('expected ' .. json.encode(s.type)); return end
+ end
+ if s.const~=nil and not equal(v,s.const) then add('does not equal const') end
+ if type(s.enum)=='table' then
+ local found=false; for _,x in ipairs(s.enum) do if equal(v,x) then found=true; break end end
+ if not found then add('not in enum') end
+ end
+ for _,kind in ipairs({'anyOf','oneOf','allOf'}) do
+ if type(s[kind])=='table' then
+ local passed=0
+ for _,sub in ipairs(s[kind]) do
+ local e={}; check(v,sub,path,e,root,depth+1)
+ if #e==0 then passed=passed+1 end
+ if kind=='allOf' then for _,message in ipairs(e) do errors[#errors+1]=message end end
+ end
+ if (kind=='anyOf' or kind=='oneOf') and passed==0 then add('no ' .. kind .. ' branch matched') end
+ end
+ end
+ -- `not` and patternProperties are intentionally ignored: this partial
+ -- validator must not reject inputs valid under unsupported constraints.
+ if type(v)=='string' then
+ local n=utf8.len(v) or #v
+ if type(s.minLength)=='number' and n<s.minLength then add('shorter than minLength') end
+ if type(s.maxLength)=='number' and n>s.maxLength then add('longer than maxLength') end
+ elseif type(v)=='number' then
+ for _,b in ipairs({{'minimum',function(a,b) return a<b end},{'maximum',function(a,b) return a>b end},
+ {'exclusiveMinimum',function(a,b) return a<=b end},{'exclusiveMaximum',function(a,b) return a>=b end}}) do
+ if type(s[b[1]])=='number' and b[2](v,s[b[1]]) then add('outside ' .. b[1] .. ' ' .. s[b[1]]) end
+ end
+ if type(s.multipleOf)=='number' and s.multipleOf>0 then
+ local q=v/s.multipleOf
+ if math.abs(q-math.floor(q+0.5))>1e-9*math.max(1,math.abs(q)) then add('not a multipleOf ' .. s.multipleOf) end
+ end
+ elseif type(v)=='table' then
+ local isarray=array(v)
+ -- An unmarked empty Lua table can stand for either shape. Apply the
+ -- relevant keywords rather than inventing a type the host did not keep.
+ if not isarray or next(v)==nil then
+ local props=type(s.properties)=='table' and s.properties or {}
+ for _,k in ipairs(type(s.required)=='table' and s.required or {}) do
+ if v[k]==nil then errors[#errors+1]=pointer(path,k) .. ': required property missing' end
+ end
+ local n=0
+ for k,x in pairs(v) do
+ n=n+1
+ if props[k]~=nil then check(x,props[k],pointer(path,k),errors,root,depth+1)
+ elseif s.additionalProperties~=nil and s.patternProperties==nil then check(x,s.additionalProperties,pointer(path,k),errors,root,depth+1) end
+ end
+ if type(s.minProperties)=='number' and n<s.minProperties then add('fewer than minProperties') end
+ if type(s.maxProperties)=='number' and n>s.maxProperties then add('more than maxProperties') end
+ end
+ if isarray then
+ if type(s.minItems)=='number' and #v<s.minItems then add('fewer than minItems') end
+ if type(s.maxItems)=='number' and #v>s.maxItems then add('more than maxItems') end
+ local prefix=type(s.prefixItems)=='table' and s.prefixItems or {}
+ for i,x in ipairs(v) do
+ local sub=prefix[i]
+ if sub==nil then sub=s.items end
+ if sub~=nil then check(x,sub,pointer(path,i-1),errors,root,depth+1) end
+ if s.uniqueItems then for j=1,i-1 do if equal(x,v[j]) then errors[#errors+1]=pointer(path,i-1) .. ': duplicate array item'; break end end end
+ end
+ end
+ end
+end
+function M.check(value,schema)
+ local errors={}; check(value,schema,'',errors,schema,0)
+ return #errors==0, errors
+end
+return M