From 413d9a4b241a0f4111e39fdc0059ac15069d034f Mon Sep 17 00:00:00 2001 From: t Date: Tue, 17 Nov 2026 00:53:11 -0700 Subject: Establish panto-mcp baseline --- README.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 README.md (limited to 'README.md') 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..` tools. Server prompts are commands of the form +`/mcp::`; `/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 `; open the +URL shown, or paste the full callback URL using `/mcp-login +` 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 --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. -- cgit v1.3