summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authort <t@tjp.lol>2026-11-17 00:53:11 -0700
committert <t@tjp.lol>2026-11-17 15:42:02 -0700
commit413d9a4b241a0f4111e39fdc0059ac15069d034f (patch)
tree55f416467d7d1f1c6a36e875c3dd60e14874a1b0 /README.md
Establish panto-mcp baselineHEADv0.1.0main
Diffstat (limited to 'README.md')
-rw-r--r--README.md110
1 files changed, 110 insertions, 0 deletions
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.