diff options
| -rw-r--r-- | LICENSE | 18 | ||||
| -rw-r--r-- | PLAN.md | 556 | ||||
| -rw-r--r-- | README.md | 110 | ||||
| -rw-r--r-- | TODOs.md | 13 | ||||
| -rw-r--r-- | _selfcheck.lua | 2247 | ||||
| -rw-r--r-- | init.lua | 76 | ||||
| -rw-r--r-- | mise.toml | 53 | ||||
| -rw-r--r-- | panto-mcp-0.1.0-1.rockspec | 49 | ||||
| -rw-r--r-- | panto_mcp/async.lua | 59 | ||||
| -rw-r--r-- | panto_mcp/cache.lua | 95 | ||||
| -rw-r--r-- | panto_mcp/client.lua | 334 | ||||
| -rw-r--r-- | panto_mcp/config.lua | 176 | ||||
| -rw-r--r-- | panto_mcp/docs.lua | 43 | ||||
| -rw-r--r-- | panto_mcp/eager.lua | 60 | ||||
| -rw-r--r-- | panto_mcp/hash.lua | 41 | ||||
| -rw-r--r-- | panto_mcp/http.lua | 680 | ||||
| -rw-r--r-- | panto_mcp/jsonrpc.lua | 75 | ||||
| -rw-r--r-- | panto_mcp/manager.lua | 229 | ||||
| -rw-r--r-- | panto_mcp/namespace.lua | 31 | ||||
| -rw-r--r-- | panto_mcp/oauth.lua | 458 | ||||
| -rw-r--r-- | panto_mcp/prompts.lua | 267 | ||||
| -rw-r--r-- | panto_mcp/results.lua | 89 | ||||
| -rw-r--r-- | panto_mcp/search.lua | 83 | ||||
| -rw-r--r-- | panto_mcp/stdio.lua | 108 | ||||
| -rw-r--r-- | panto_mcp/supervisor.lua | 65 | ||||
| -rw-r--r-- | panto_mcp/tools.lua | 97 | ||||
| -rw-r--r-- | panto_mcp/validate.lua | 134 |
27 files changed, 6246 insertions, 0 deletions
@@ -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. @@ -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.<server>.<tool>"] + C["commands: /mcp:<server>:<prompt>"] + 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 |
