From a607ede199fa72a5583f712afebb2be4a9b8f5ca Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Fri, 16 Oct 2026 23:56:36 +0000 Subject: [PATCH 1/2] feat(extensions): add MCP servers by form or pasted config, with sealed tokens and per-tool switches MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Admins add an MCP server on Extensions with a short form (an address and headers, or a command with args and env) or by pasting a config from Claude or VS Code; Test lists its tools before saving. Header and env values that carry credentials are sealed with the server key, bound to the extension and where they go, and shown as "••••"; an upgrade step seals the ones saved before. Each tool gets a switch and "asks first", kept in the server's spec as off and ask. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01HXPWXcSCQb9hWPr7xkZu7B --- CHANGELOG.md | 6 + docs/assistant.md | 36 +- docs/database.md | 10 + docs/mcp.md | 5 +- .../app/api/v1/routes/extensions.py | 35 +- fastapi_backend/app/domain/extensions.py | 112 +++- fastapi_backend/app/domain/marketplace.py | 25 +- fastapi_backend/app/domain/mcp_servers.py | 281 ++++++++++ fastapi_backend/app/domain/migrations.py | 4 +- fastapi_backend/app/schemas/extensions.py | 36 ++ fastapi_backend/tests/api/test_mcp_servers.py | 189 ++++++- .../tests/domain/test_migrations.py | 14 +- .../__tests__/mcp-server-ui.test.tsx | 176 +++++++ .../app/(app)/extensions/new/mcp/page.tsx | 10 + nextjs-frontend/app/openapi-client/index.ts | 22 + nextjs-frontend/app/openapi-client/sdk.gen.ts | 65 +++ .../app/openapi-client/types.gen.ts | 212 ++++++++ .../extensions/extension-editor.tsx | 86 +++- .../components/extensions/extensions-page.tsx | 12 +- .../components/extensions/mcp-server-form.tsx | 483 ++++++++++++++++++ nextjs-frontend/openapi.json | 321 ++++++++++++ threat-model.json | 12 +- threat-model.md | 5 +- threat-model.yaml | 16 +- 24 files changed, 2108 insertions(+), 65 deletions(-) create mode 100644 fastapi_backend/app/domain/mcp_servers.py create mode 100644 nextjs-frontend/__tests__/mcp-server-ui.test.tsx create mode 100644 nextjs-frontend/app/(app)/extensions/new/mcp/page.tsx create mode 100644 nextjs-frontend/components/extensions/mcp-server-form.tsx diff --git a/CHANGELOG.md b/CHANGELOG.md index 08bbfb731..340e27842 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,12 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version `automation_actions`, `save_automation`, `test_automation` and `run_automation`, with problems in plain words. The assistant saves them switched off and asks before switching one on or running it ([Agents](docs/automations.md#agents)). +- **Add an MCP server with a form, or paste its config.** Extensions → Add MCP server (admins) takes an address and + its headers, or a command with its arguments and environment, or reads a config pasted from Claude (`.mcp.json`) or + VS Code, one server or many; Test lists its tools before it's saved. Tokens and keys in headers and env are now + sealed and never shown again (manifests say `••••`), and an upgrade step seals the ones saved before. Each server's + tools have a switch and "Asks first", kept in its manifest + ([Adding an MCP server](docs/assistant.md#adding-an-mcp-server)). - **Describe an automation in words.** `POST /api/v1/automations/draft` asks the model once to turn a sentence into a draft automation to try and save, and says what didn't fit and what it couldn't express ([Describe it in words](docs/automations.md#describe-it-in-words)). diff --git a/docs/assistant.md b/docs/assistant.md index bacf0168f..d8428377e 100644 --- a/docs/assistant.md +++ b/docs/assistant.md @@ -239,9 +239,10 @@ shared with namespaces (admins can share with everyone), and switched on or off - **MCP server** (admins add them): a server that speaks the Model Context Protocol over Streamable HTTP, at the address an admin gives (this machine and the local network included, as for the model's address), with the headers it needs (a token). Lens lists its tools when it's saved, and the assistant calls them as `__`: one the - server marks read-only answers at once, the others ask for approval. A server that runs as a program (stdio: - `command`, `args` and `env` instead of an address, as in Claude's `.mcp.json`, usually `npx` or `uvx`) runs in the - MCP runner, below. + server marks read-only answers at once, the others ask for approval, and an admin switches each on or off and says + which ask first ([Adding an MCP server](#adding-an-mcp-server)). A server that runs as a program (stdio: `command`, + `args` and `env` instead of an address, as in Claude's `.mcp.json`, usually `npx` or `uvx`) runs in the MCP runner, + below. - **Plugin**: a bundle of tools, skills, hooks and MCP servers, shared and switched off as one. Make one however suits you: @@ -291,6 +292,35 @@ the network (`.mcp.json`) come along when an admin installs it, and those that r runner is on (ones that run a program shipped inside the plugin are left out). Repositories are read from GitHub or GitLab (or the archive link) through the same guard as web tools: public addresses only. +### Adding an MCP server + +On **Extensions**, **Add MCP server** (admins) takes a name and either the server's address with the headers it needs, +or the command it runs as with its arguments and environment. **Paste a config** reads the JSON other apps keep their +servers in, one server or many: Claude's `.mcp.json` (or `mcpServers` in its settings), VS Code's `mcp.json` +(`servers`), or a server on its own as its README gives it. A server without a name is named after its package or its +address (`@modelcontextprotocol/server-github` is `github`), and values written as `${NAME}`, which those apps fill in +from their own settings, are pointed out to fill in. Servers on the older SSE transport are left out with a note. +**Test** asks the server for its tools before anything is saved, and Enter adds it. Over the API: +`POST /api/v1/extensions/mcp/read` reads a config (nothing is reached), `POST /api/v1/extensions/mcp/test` lists a +server's tools without saving it, and `POST /api/v1/extensions` saves it as an extension of kind `mcp`. + +Header and environment values whose names say they carry a credential (Authorization, API keys, tokens, secrets, +passwords, cookies, sessions) are sealed when the server is saved, with the server's key (as notification targets and +sources are, since an MCP server belongs to the whole install rather than a namespace), bound to the extension, the +value's name and where it goes: the address's scheme, host and port, or the command with its arguments. They're opened +only to reach the server and never shown again: the page, the API and the manifest give the name and `••••`. Saving a +manifest with `••••` keeps the value saved before, unless the server now goes somewhere else (another host, or another +command or package), when it asks for the value again, and a sealed value copied into another extension doesn't open. +Other headers (`X-Team: blue`) stay as they are, and so does a secret written into the address or the arguments, so +put tokens in headers or the environment. + +Each server's page lists its tools with a switch and **Asks first**. A tool the server marks read-only runs at once and +the others ask, unless an admin says otherwise; the choices are kept in its manifest (`off`, the tools switched off, +and `ask`, `{tool: true or false}` where it differs from the server's hint), stay when its tools are listed again, and +each change is a new version (`PATCH /api/v1/extensions/{id}/tools` with `{tool, on, ask}`). Whatever the switch says, +an MCP tool still asks first after the conversation read outside text, as every tool that sends to another host does +([Third-party content and prompt injection](#third-party-content-and-prompt-injection)). + ### The MCP runner MCP servers that run as a program run in a container of their own, the MCP runner diff --git a/docs/database.md b/docs/database.md index 7473ad304..77c818a1d 100644 --- a/docs/database.md +++ b/docs/database.md @@ -102,6 +102,16 @@ tables, or changing or removing an index that already exists, is a named step in * `lens migrations` lists every step (done, pending, failed, or unknown when a newer Lens ran it) without running anything, so it works while an upgrade is failing; `lens migrations --run` runs the pending ones. +The steps so far: + +| Step | What it does | +|---|---| +| `access-levels` | IIIF-only access levels (public, transcript, signed-in, private) become the access setting | +| `collection-homes` | every namespace gets its default collection and every recording a home | +| `tour-seen` | people who signed in before the welcome tour existed don't get it | +| `document-read-step` | documents and images queued to be transcribed are read instead, and failed ones run again | +| `mcp-sealed-secrets` | the tokens and keys MCP servers kept in plain text in their headers and env are sealed, in every version ([Adding an MCP server](assistant.md#adding-an-mcp-server)); sealed ones are left as they are | + To add a step: 1. Write a function `fn(db)` next to the code it serves. It must be safe to run twice, since a start that stops half diff --git a/docs/mcp.md b/docs/mcp.md index ebf3c82f1..a92688f1b 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -6,8 +6,9 @@ and sees exactly what that person sees: their namespaces, the collections they w those open. Its tools read, except the few listed under [Tools](#tools) that suggest or write, which need a write-scope token and editor access. -It works the other way too: Lens's own assistant calls the tools of MCP servers an admin adds, as extensions -([Extending the assistant](assistant.md#extending-the-assistant-tools-skills-hooks-and-plugins)). +It works the other way too: Lens's own assistant calls the tools of MCP servers an admin adds, as extensions, by a +short form or a config pasted from another app, with their tokens sealed +([Adding an MCP server](assistant.md#adding-an-mcp-server)). ## Connecting diff --git a/fastapi_backend/app/api/v1/routes/extensions.py b/fastapi_backend/app/api/v1/routes/extensions.py index 59a34b29e..eb9b8d5ea 100644 --- a/fastapi_backend/app/api/v1/routes/extensions.py +++ b/fastapi_backend/app/api/v1/routes/extensions.py @@ -9,7 +9,7 @@ from fastapi import APIRouter, HTTPException, Request from app.api.deps import Acl, Cfg, CurrentUser, Db, Principal, Writer, domain_errors -from app.domain import ai_tools, auth, extensions, marketplace +from app.domain import ai_tools, auth, extensions, marketplace, mcp_servers from app.schemas.common import Created, Ok from app.schemas.extensions import ( Extension, @@ -26,6 +26,11 @@ Kind, ManifestCheck, ManifestChecked, + McpConfig, + McpConfigText, + McpServerTools, + McpServerTry, + McpToolSwitch, ) from app.schemas.templates import VersionSaved @@ -93,6 +98,22 @@ def import_archive(body: ExtensionImportArchive, user: Writer, db: Db) -> Extens return ExtensionImportPreview(**out) if body.preview else ExtensionImported(**out) +@router.post("/mcp/read") +def read_mcp_config(body: McpConfigText, user: CurrentUser) -> McpConfig: + """The MCP servers in a config pasted from another app (Claude's .mcp.json, VS Code's mcp.json), ready to add: each + as an MCP extension keeps it, and what was left out and why. Nothing is reached or saved.""" + with _errors(): + return McpConfig(**mcp_servers.read(body.text)) + + +@router.post("/mcp/test") +def test_mcp_server(body: McpServerTry, user: Writer, db: Db) -> McpServerTools: + """Ask an MCP server for its tools without saving it (admins). With `extension`, values sent as •••• are that + server's saved ones.""" + with _errors(): + return McpServerTools(tools=extensions.try_mcp(db, me(user), body.spec, body.extension)) + + @router.get("/{eid}") def get_extension(eid: int, user: CurrentUser, db: Db, version: int | None = None) -> ExtensionDetail: """One version (default: the current one), as a manifest too, and the list of versions.""" @@ -108,6 +129,15 @@ def create_extension_version(eid: int, body: ExtensionVersionCreate, user: Write return VersionSaved(version=n) +@router.patch("/{eid}/tools") +def switch_mcp_tool(eid: int, body: McpToolSwitch, user: Writer, db: Db) -> VersionSaved: + """Switch one of an MCP server's tools on or off, or say whether it asks first (admins): a new version.""" + with _errors(): + n = extensions.switch_tool(db, me(user), eid, body.tool, on=body.on, ask=body.ask) + auth.audit(db, user.as_audit(), "extension.save", f"extension:{eid}", {"version": n, **body.model_dump(exclude_none=True)}) + return VersionSaved(version=n) + + @router.patch("/{eid}") def update_extension(eid: int, body: ExtensionUpdate, user: Writer, db: Db) -> Ok: """Its title, description, who sees it, and whether it's switched on.""" @@ -131,7 +161,8 @@ def test_extension(eid: int, body: ExtensionTest, user: Writer, acl: Acl, db: Db """Try one of its tools with these arguments, switched on or not. A tool that changes something really runs, so it needs `confirm`.""" with _errors(): - g = extensions.visible_one(db, me(user), eid) + extensions.visible_one(db, me(user), eid) + g = extensions.get(db, eid) # as saved: what's shown hides an MCP server's secrets name = body.tool or (g["name"] if g["kind"] == "tool" else None) t = next((it for it in extensions.tool_items(g) if it["name"] == name), None) if not t: diff --git a/fastapi_backend/app/domain/extensions.py b/fastapi_backend/app/domain/extensions.py index eb0079509..37c21bab9 100644 --- a/fastapi_backend/app/domain/extensions.py +++ b/fastapi_backend/app/domain/extensions.py @@ -32,7 +32,7 @@ import yaml -from . import activity, auth, store +from . import activity, auth, mcp_servers, store R = store.R KINDS = ("tool", "skill", "hook", "plugin", "mcp") @@ -265,9 +265,12 @@ def _check_hook(spec, me, db=None): def _check_mcp(spec, me, db=None): """An MCP server: its address and the headers it needs (a token), or the program it runs as (command, args, env: - run in the MCP runner's sandbox), and its tools as it listed them (mcp_client.py).""" - if set(spec) - {"url", "headers", "command", "args", "env", "tools"}: - raise ValueError("an MCP server is {url, headers, tools}, or {command, args, env, tools} for one that runs as a program") + run in the MCP runner's sandbox), its tools as it listed them (mcp_client.py), the tools switched off (`off`) and + which ask first where that isn't the server's own read-only hint (`ask`: {tool: true or false}).""" + if set(spec) - {"url", "headers", "command", "args", "env", "tools", "off", "ask"}: + raise ValueError( + "an MCP server is {url, headers, tools, off, ask}, or {command, args, env, tools, off, ask} for one that runs as a program" + ) if not me["admin"]: raise ValueError("only admins add MCP servers") @@ -289,11 +292,18 @@ def words(v, what): if not re.match(r"^https?://[^/?#\s]+", url): raise ValueError("an MCP server's address starts with http:// or https://") server = {"url": url, "headers": words(spec.get("headers") or {}, "headers") or None} + off, ask = spec.get("off") or [], spec.get("ask") or {} + if not isinstance(off, list) or len(off) > 100 or not all(isinstance(t, str) for t in off): + raise ValueError("an MCP server's off is a list of its tools' names") + if not isinstance(ask, dict) or len(ask) > 100 or not all(isinstance(k, str) and isinstance(v, bool) for k, v in ask.items()): + raise ValueError("an MCP server's ask is {tool: true or false}: whether each asks first") tools = spec.get("tools") - if tools is None: # asked of the server: what it offers now + # asked of the server: what it offers now (not while a secret is "••••": saving fills that in, then lists them) + if tools is None and not mcp_servers.hidden({"kind": "mcp", "spec": server}): from . import mcp_client tools = mcp_client.discover(store.clean(server)) + server.update({"off": sorted(set(off)) or None, "ask": ask or None}) if tools is not None: if not isinstance(tools, list) or len(tools) > 100: raise ValueError("an MCP server's tools are a list of at most 100") @@ -314,18 +324,23 @@ def words(v, what): return store.clean({**server, "tools": tools}) -def mcp_tools(item): - """An MCP server's tools as the assistant calls them, `__`: [{name, description, spec}]. Its own - readOnlyHint is the only thing that lets one answer without asking.""" +def mcp_tools(item, ext=None): + """An MCP server's tools as the assistant calls them, `__`: [{name, description, spec}], less those + switched off. One answers without asking when the server says it only reads (its readOnlyHint) and no admin said it + asks first, or when an admin said it needn't ask. `ext` is the extension it's in, which its sealed values are bound + to.""" s, out = item["spec"], [] + off, ask = set(s.get("off") or []), s.get("ask") or {} for t in s.get("tools") or []: + if t["name"] in off: + continue name = re.sub(r"[^A-Za-z0-9_-]", "_", f"{item['name']}__{t['name']}")[:64] where = {k: s.get(k) for k in ("url", "headers", "command", "args", "env")} - run = store.clean({"type": "mcp", **where, "tool": t["name"]}) + run = store.clean({"type": "mcp", **where, "tool": t["name"], "ext": ext, "server": item["name"]}) spec = { "params": [], "schema": t.get("schema") or {"type": "object"}, - "effect": "read" if t.get("read_only") else "change", + "effect": "change" if ask.get(t["name"], not t.get("read_only")) else "read", "run": run, } out.append({"kind": "tool", "name": name, "description": t.get("description"), "spec": spec}) @@ -339,7 +354,7 @@ def tool_items(g): if it["kind"] == "tool": out.append(it) elif it["kind"] == "mcp": - out += mcp_tools(it) + out += mcp_tools(it, g.get("id")) return out @@ -445,7 +460,7 @@ class _Dumper(yaml.SafeDumper): def to_manifest(ext): """An extension as a manifest people can read, change and import again: Markdown with frontmatter for skills and prompt tools, YAML for the rest.""" - spec = json.loads(json.dumps(ext["spec"])) + spec = mcp_servers.masked(ext["name"], ext["kind"], ext["spec"]) # secrets: their names and "••••" head = store.clean({"name": ext["name"], "kind": ext["kind"], "title": ext.get("title"), "description": ext.get("description")}) body = None if ext["kind"] == "skill": @@ -518,7 +533,7 @@ def _check_share(db, me, visibility, namespaces): def create(db, me, manifest, enabled=True, origin="code", source=None): """A new extension from a manifest; its id. `origin` says how it was made: code, canvas or chat (or import, from a marketplace or a link, when `source` says where from: marketplace.py).""" - m = check_manifest(manifest, me, db) + m = check_manifest(mcp_servers.opened(db, manifest), me, db) _check_names(db, m["kind"], m["name"], m["spec"]) vis, sids = _check_share(db, me, m.get("visibility"), m.get("namespaces")) eid, t = db.next_id("extension"), store.now() @@ -543,7 +558,7 @@ def create(db, me, manifest, enabled=True, origin="code", source=None): } ), ) - _save(db, me, eid, 1, m["spec"], None, origin) + _save(db, me, eid, 1, mcp_servers.seal(db, eid, m["name"], m["kind"], m["spec"]), None, origin) return eid @@ -604,17 +619,71 @@ def _mine(db, me, eid): def save_version(db, me, eid, manifest, notes=None, origin="code"): - """A new version from a manifest (its name and kind stay); the version's number.""" + """A new version from a manifest (its name and kind stay); the version's number. An MCP server's secrets given as + "••••" keep the values saved before.""" d = _mine(db, me, eid) - m = check_manifest({**manifest, "name": d["name"], "kind": d["kind"]}, me, db) + m = mcp_servers.opened(db, {**manifest, "name": d["name"], "kind": d["kind"]}, d["id"], get(db, d["id"])) + m = check_manifest(m, me, db) _check_names(db, d["kind"], d["name"], m["spec"], skip=d["id"]) + spec = mcp_servers.seal(db, d["id"], d["name"], d["kind"], m["spec"]) + return _new_version(db, me, d, spec, notes, origin, {k: m[k] for k in ("title", "description") if k in m}) + + +def _new_version(db, me, d, spec, notes, origin, meta=None): n = max(db.values("SELECT VALUE version FROM extension_version WHERE extension = $e", e=d["id"]) or [0]) + 1 - _save(db, me, d["id"], n, m["spec"], _text(notes, "the notes", 500), origin) - meta = {k: m[k] for k in ("title", "description") if k in m} - db.q("UPDATE $r MERGE $d", r=R("extension", d["id"]), d={**meta, "current": n, "updated_at": store.now()}) + _save(db, me, d["id"], n, spec, _text(notes, "the notes", 500), origin) + db.q("UPDATE $r MERGE $d", r=R("extension", d["id"]), d={**(meta or {}), "current": n, "updated_at": store.now()}) return n +def switch_tool(db, me, eid, tool, on=None, ask=None): + """One of an MCP server's tools switched on or off (`on`), or set to ask first or not (`ask`): a new version, which + conversations use at once. Asking as the server's read-only hint says is the default, and isn't written down.""" + d = _mine(db, me, eid) + g = get(db, d["id"]) + if g["kind"] != "mcp": + raise ValueError("only an MCP server's tools are switched one by one: change a plugin's in its manifest") + if not me["admin"]: + raise ValueError("only admins change MCP servers") + spec = json.loads(json.dumps(g["spec"])) + t = next((t for t in spec.get("tools") or [] if t["name"] == tool), None) + if not t: + raise ValueError(f"{g['name']} has no tool {tool}") + said = [] + if on is not None: + off = (set(spec.get("off") or []) - {tool}) | (set() if on else {tool}) + spec["off"] = sorted(off) or None + said.append(f"{tool} {'on' if on else 'off'}") + if ask is not None: + asks = {k: v for k, v in (spec.get("ask") or {}).items() if k != tool} + if bool(ask) != (not t.get("read_only")): + asks[tool] = bool(ask) + spec["ask"] = asks or None + said.append(f"{tool} {'asks first' if ask else 'runs without asking'}") + if not said: + raise ValueError("say whether the tool is on, or whether it asks first") + return _new_version(db, me, d, store.clean(spec), ", ".join(said), "code") + + +def try_mcp(db, me, spec, eid=None): + """The tools an MCP server ({url, headers}, or {command, args, env}) offers now, asked of it without saving it. + Values given as "••••" are the ones `eid`, an MCP server extension, has saved.""" + if not me["admin"]: + raise ValueError("only admins add MCP servers") + if not isinstance(spec, dict): + raise ValueError("an MCP server is {url, headers}, or {command, args, env} for one that runs as a program") + name, before = "server", None + if eid is not None: + d = _mine(db, me, eid) + before = get(db, d["id"]) + if before["kind"] != "mcp": + raise ValueError("that extension isn't an MCP server") + name = d["name"] + m = mcp_servers.opened(db, {"name": name, "kind": "mcp", "spec": spec}, eid, before) + server = {k: v for k, v in m["spec"].items() if k in ("url", "headers", "command", "args", "env")} + return check_spec("mcp", server, me, db).get("tools") or [] + + def update(db, me, eid, **meta): """Its title, description, who sees it, and whether it's on.""" d = _mine(db, me, eid) @@ -661,6 +730,7 @@ def _shown(db, g, me, names=None): names = names if names is not None else store.space_names(db) g["namespaces"] = [names.get(s) for s in g.get("namespaces") or [] if names.get(s)] g["editable"] = can_edit(g, me) and not g.get("deleted_at") + g["spec"] = mcp_servers.masked(g["name"], g["kind"], g["spec"]) # an MCP server's secrets are never shown return g @@ -703,7 +773,7 @@ def __init__(self, db, me): trusted = g.get("owner") == me["id"] or _owner_admin(db, g) items = g["spec"]["items"] if g["kind"] == "plugin" else [g] if _owner_admin(db, g): # MCP servers are reached while an admin owns them - items = [x for it in items for x in (mcp_tools(it) if it["kind"] == "mcp" else [it])] + items = [x for it in items for x in (mcp_tools(it, g["id"]) if it["kind"] == "mcp" else [it])] for it in items: if it["kind"] == "mcp": continue @@ -854,7 +924,7 @@ def run_tool(db, cfg, spec, args, model=None, toolbox=None): if run["type"] == "mcp": from . import mcp_client - return mcp_client.call(run, args) + return mcp_client.call(mcp_servers.open_run(db, run), args) if run["type"] == "python": from . import code_tools diff --git a/fastapi_backend/app/domain/marketplace.py b/fastapi_backend/app/domain/marketplace.py index f5b854500..a5ee26a8b 100644 --- a/fastapi_backend/app/domain/marketplace.py +++ b/fastapi_backend/app/domain/marketplace.py @@ -424,19 +424,17 @@ def _mcp(found, meta, admin, report): {"kind": "mcp", "name": ", ".join(conf)[:200], "why": "only admins add MCP servers: an admin installing it brings them"} ) return [] - from . import mcp_client + from . import mcp_client, mcp_servers out = [] for name, c in list(conf.items())[:20]: - c = c if isinstance(c, dict) else {} - kind = c.get("type") or ("stdio" if c.get("command") else "http") - if kind == "stdio" or c.get("command"): - args = [str(x) for x in c.get("args") or [] if isinstance(x, (str, int, float))] - env = {k: str(v) for k, v in (c.get("env") or {}).items() if isinstance(k, str) and isinstance(v, (str, int, float))} - if not isinstance(c.get("command"), str): - report.append({"kind": "mcp", "name": name, "why": "it says it runs a program but not which"}) - continue - if any("CLAUDE_PLUGIN_ROOT" in x for x in [c["command"], *args, *env.values()]): + server, why = mcp_servers.entry(c) + if server is None: + report.append({"kind": "mcp", "name": name, "why": why}) + continue + if server.get("command"): + words = [server["command"], *(server.get("args") or []), *(server.get("env") or {}).values()] + if any("CLAUDE_PLUGIN_ROOT" in x for x in words): report.append( {"kind": "mcp", "name": name, "why": "it runs a program from the plugin's own folder, which Lens doesn't run"} ) @@ -444,13 +442,6 @@ def _mcp(found, meta, admin, report): if not mcp_client.runner(): report.append({"kind": "mcp", "name": name, "why": mcp_client.NO_RUNNER}) continue - server = store.clean({"command": c["command"], "args": args or None, "env": env or None}) - elif kind not in ("http", "streamable-http") or not isinstance(c.get("url"), str): - report.append({"kind": "mcp", "name": name, "why": f"Lens speaks MCP over HTTP; this one uses {kind}"}) - continue - else: - headers = {k: v for k, v in (c.get("headers") or {}).items() if isinstance(k, str) and isinstance(v, str)} - server = {"url": c["url"], "headers": headers or None} try: tools = mcp_client.discover(server) except ValueError as e: diff --git a/fastapi_backend/app/domain/mcp_servers.py b/fastapi_backend/app/domain/mcp_servers.py new file mode 100644 index 000000000..085504bbd --- /dev/null +++ b/fastapi_backend/app/domain/mcp_servers.py @@ -0,0 +1,281 @@ +"""MCP servers' settings (docs/assistant.md, MCP servers): configs pasted from other apps, sealed secrets, and a switch +for each tool. The servers themselves are extensions of kind `mcp` (extensions.py), reached by mcp_client.py. + +- `read` takes the JSON other apps keep their MCP servers in (Claude's `.mcp.json` and `mcpServers`, VS Code's + `servers`, a list of them, or one server on its own) and gives back each server as an MCP extension keeps it, with + what it left out and why. Nothing is reached or run until an admin tests or saves one. +- Header and env values whose names carry credentials (Authorization, API keys, tokens, cookies: actions_web.secret) + are sealed when an extension is saved (`seal`), bound to the extension, the server's name in it, the value's name and + where it goes (the address's scheme, host and port, or the command it runs with its arguments), so a sealed value + can't be moved to another extension or sent to another host or program. MCP servers belong to the whole install, not + a namespace (only admins add them), so they're sealed with the server's key (settings.seal), as notification targets + and sources are. They're opened only to reach the server (`open_run`) and never shown: the API and manifests give + the name and "••••", and saving "••••" again keeps the value saved before, as long as the server still goes to the + same place (`opened`). +- `off` (the tools switched off) and `ask` ({tool: whether it asks first}, where that differs from the server's own + read-only hint) sit in the server's spec, so they survive its tools being listed again and travel with its manifest. +""" + +from __future__ import annotations + +import hashlib +import json +import re +import urllib.parse + +import yaml + +from . import settings, store + +HIDDEN = "••••" +SEALED = "lens-sealed:" +MAX_SERVERS = 20 +FIELDS = (("headers", "header"), ("env", "env")) +PLACEHOLDER_RX = re.compile(r"\$\{(?:input:|env:)?([A-Za-z_][A-Za-z0-9_.-]*)(?::-[^}]*)?\}") +EXAMPLE = '{"mcpServers": {"github": {"type": "http", "url": "https://api.githubcopilot.com/mcp/"}}}' + + +def secret(name): + """Whether a value's name says it carries a credential, as automations' web requests decide it.""" + from .actions_web import secret as named # loaded here: the automation actions load the assistant's tools + + return named(name) + + +def is_sealed(value): + return isinstance(value, str) and value.startswith(SEALED) + + +def where(server): + """Where a server's values go: its address's scheme, host and port, or the program it runs as (its command and + arguments, so a token given to one package isn't handed to another).""" + if server.get("url"): + u = urllib.parse.urlsplit(str(server["url"])) + try: + port = u.port + except ValueError: + port = None + return f"{u.scheme}://{(u.hostname or '').lower()}:{port or (443 if u.scheme == 'https' else 80)}" + run = json.dumps([server.get("command") or "", *(server.get("args") or [])]) + return "command:" + hashlib.sha256(run.encode()).hexdigest()[:32] + + +def _key(db): + """What settings.seal needs to find the server's key: its data folder (or ARCHIVE_SECRET_KEY).""" + return {"data_dir": db.data_dir} + + +def _context(eid, item, field, name, server): + return f"extension:{eid}.mcp:{item}.{field}:{name.lower() if field == 'header' else name}@{where(server)}" + + +def servers_in(m): + """The MCP servers in a manifest or a saved extension, each with the name its tools go by: [(name, server)]. The + server dicts are the manifest's own, so changing one changes it.""" + if not isinstance(m, dict): + return [] + body = m["spec"] if isinstance(m.get("spec"), dict) else m + if m.get("kind") == "mcp": + return [(str(m.get("name") or ""), body)] + if m.get("kind") != "plugin" or not isinstance(body.get("items"), list): + return [] + return [ + (str(it.get("name") or ""), it["spec"] if isinstance(it.get("spec"), dict) else it) + for it in body["items"] + if isinstance(it, dict) and it.get("kind") == "mcp" + ] + + +def _open(db, eid, item, field, name, server, value): + if not is_sealed(value): + return value + if eid is None: + raise ValueError(f"enter the {name} value of {item} again: it was sealed for another extension") + try: + return settings.unseal(_key(db), value[len(SEALED) :], _context(eid, item, field, name, server)) + except Exception: # noqa: BLE001 - sealed for another extension or address, or with another server key + raise ValueError(f"enter the {name} value of {item} again: it was sealed for another extension or address") from None + + +def opened(db, manifest, eid=None, before=None): + """A manifest about to be checked and saved, with its secrets as they're sent: "••••" becomes the value `before` + (the extension's current version) had, when the server still goes to the same place, and sealed values are opened. + ValueError names a value to enter again.""" + m = json.loads(json.dumps(manifest)) + old = dict(servers_in(before)) if before else {} + for item, server in servers_in(m): + for field, label in FIELDS: + values = server.get(field) + if not isinstance(values, dict): + continue + for k, v in list(values.items()): + if v == HIDDEN: + prev = old.get(item) + pv = ((prev or {}).get(field) or {}).get(k) + if pv is None: + raise ValueError(f"enter the {k} value of {item}: “{HIDDEN}” keeps one saved before, and there is none") + if where(prev) != where(server): + raise ValueError(f"enter the {k} value of {item} again: the server goes somewhere else now") + values[k] = _open(db, eid, item, label, k, prev, pv) + elif is_sealed(v): + values[k] = _open(db, eid, item, label, k, server, v) + return m + + +def seal(db, eid, name, kind, spec): + """A checked spec as it's kept: the values whose names carry credentials sealed. Sealed ones are kept as they are.""" + spec = json.loads(json.dumps(spec)) + for item, server in servers_in({"name": name, "kind": kind, "spec": spec}): + for field, label in FIELDS: + for k, v in (server.get(field) or {}).items(): + if v and isinstance(v, str) and secret(k) and not is_sealed(v): + server[field][k] = SEALED + settings.seal(_key(db), v, _context(eid, item, label, k, server)) + return spec + + +def masked(name, kind, spec): + """A spec as it's shown: values with credentials, sealed or not, as "••••".""" + spec = json.loads(json.dumps(spec)) + for _, server in servers_in({"name": name, "kind": kind, "spec": spec}): + for field, _ in FIELDS: + for k, v in (server.get(field) or {}).items(): + if is_sealed(v) or (v and secret(k)): + server[field][k] = HIDDEN + return spec + + +def hidden(manifest): + """Whether a manifest has values it can't send as they are ("••••" or sealed), so its tools can't be listed now.""" + return any( + v == HIDDEN or is_sealed(v) + for _, server in servers_in(manifest) + for field, _ in FIELDS + for v in (server.get(field) or {}).values() + if isinstance(server.get(field), dict) + ) + + +def open_run(db, run): + """An MCP tool's run (extensions.mcp_tools) with its sealed values opened, just before the server is reached.""" + run = dict(run) + for field, label in FIELDS: + if run.get(field): + run[field] = {k: _open(db, run.get("ext"), run.get("server"), label, k, run, v) for k, v in run[field].items()} + return run + + +# ---------- configs pasted from other apps ---------- +def entry(c): + """One server of a config, as an MCP extension keeps it: (spec, None), or (None, why it's left out).""" + if not isinstance(c, dict): + return None, "it isn't an object with a command or an address" + kind = str(c.get("type") or c.get("transport") or "").lower().replace("_", "-") + if c.get("command") is not None or kind == "stdio": + if not isinstance(c.get("command"), str) or not c["command"].strip(): + return None, "it says it runs a program but not which" + args = [str(x) for x in c.get("args") or [] if isinstance(x, (str, int, float))] + env = {k: str(v) for k, v in (c.get("env") or {}).items() if isinstance(k, str) and isinstance(v, (str, int, float))} + return store.clean({"command": c["command"].strip(), "args": args or None, "env": env or None}), None + if kind == "sse": + return None, "it uses the older SSE transport; Lens speaks MCP over Streamable HTTP (many servers have both: try its /mcp address)" + if kind and kind not in ("http", "streamable-http", "streamablehttp"): + return None, f"Lens speaks MCP over HTTP; this one uses {kind}" + url = c.get("url") or c.get("serverUrl") or c.get("httpUrl") + if not isinstance(url, str) or not url.strip(): + return None, "it has neither a command nor an address" + headers = {k: str(v) for k, v in (c.get("headers") or {}).items() if isinstance(k, str) and isinstance(v, (str, int, float))} + return store.clean({"url": url.strip(), "headers": headers or None}), None + + +def guess_name(server): + """A name for a server given without one: its package (`@modelcontextprotocol/server-github`: github), or the + site its address is on.""" + if server.get("url"): + labels = [x for x in (urllib.parse.urlsplit(server["url"]).hostname or "").split(".") if x] + word = labels[-2] if len(labels) > 1 else labels[0] if labels else "" + else: + args = [a for a in server.get("args") or [] if not a.startswith("-")] + word = next((a for a in args if re.search(r"mcp|server", a, re.I)), args[0] if args else server.get("command") or "") + word = re.sub(r"@[^/@]*$", "", word.rstrip("/")) # a version: @latest + parts = word.rsplit("/", 1) + word = parts[-1] + if word.lower() in ("mcp", "server", "mcp-server") and len(parts) > 1: # @playwright/mcp: playwright + word = parts[0].lstrip("@").rsplit("/", 1)[-1] + word = re.sub(r"^(mcp[-_])?(server[-_])?|([-_]mcp)?([-_]server)?$", "", word, flags=re.I) or word + return word + + +def _fill(server): + found = [] + for v in [server.get("url"), server.get("command"), *(server.get("args") or [])]: + found += PLACEHOLDER_RX.findall(str(v or "")) + for field, _ in FIELDS: + for v in (server.get(field) or {}).values(): + found += PLACEHOLDER_RX.findall(str(v)) + return list(dict.fromkeys(found)) + + +def _servers(conf): + """[(the name it was given, its settings)] from a config, whichever app's shape it has.""" + if isinstance(conf, dict): + vscode = conf.get("mcp") if isinstance(conf.get("mcp"), dict) else {} + for got in (conf.get("mcpServers"), conf.get("servers"), vscode.get("servers")): + if isinstance(got, (dict, list)): + conf = got + break + else: + if any(k in conf for k in ("command", "url", "serverUrl", "httpUrl")): # one server on its own + conf = [conf] + if isinstance(conf, list): # [{name, command, ...}], as some apps keep them + return [(str(c.get("name") or "") if isinstance(c, dict) else "", c) for c in conf] + return list(conf.items()) if isinstance(conf, dict) else [] + + +def read(text): + """The servers in a config pasted from another app: {servers: [{name, description, spec, fill}], skipped: [{name, + why}]}. `fill` names the values written as ${NAME}, which that app fills in from its environment and Lens can't.""" + from .marketplace import slug + + text = (text or "").strip() + try: + conf = json.loads(text) + except ValueError as e: + if text[:1] in "{[": + raise ValueError(f"that isn't JSON: {e}") from None + try: + conf = yaml.safe_load(text) # some apps keep theirs in YAML + except yaml.YAMLError: + raise ValueError(f"paste an MCP config, such as {EXAMPLE}") from None + servers = _servers(conf) + if not servers: + raise ValueError(f"paste an MCP config, such as {EXAMPLE}") + out, skipped, names = [], [], set() + for given, c in servers[:MAX_SERVERS]: + spec, why = entry(c) + if spec is None: + skipped.append({"name": given or "a server", "why": why}) + continue + try: + name = slug(given or guess_name(spec)) + except ValueError: + name = "mcp_server" + base, n = name, 2 + while name in names: + name, n = f"{base[:38]}_{n}", n + 1 + names.add(name) + out.append({"name": name, "description": f"The {given or name} MCP server", "spec": spec, "fill": _fill(spec)}) + skipped += [{"name": n or "a server", "why": f"a config adds at most {MAX_SERVERS} servers at once"} for n, _ in servers[MAX_SERVERS:]] + return {"servers": out, "skipped": skipped} + + +# ---------- upgrading ---------- +def migrate_seal(db): + """Upgrade step: seal the credentials MCP servers kept in plain text in their headers and env, in every version of + every MCP server and plugin. Safe to run twice: sealed values are left as they are.""" + for d in db.rows("SELECT record::id(id) AS id, name, kind FROM extension WHERE kind IN ['mcp', 'plugin']"): + for v in db.rows("SELECT record::id(id) AS id, spec FROM extension_version WHERE extension = $e", e=d["id"]): + if not isinstance(v.get("spec"), dict): + continue + spec = seal(db, d["id"], d["name"], d["kind"], v["spec"]) + if spec != v["spec"]: + db.q("UPDATE $r SET spec = $s", r=store.R("extension_version", v["id"]), s=spec) diff --git a/fastapi_backend/app/domain/migrations.py b/fastapi_backend/app/domain/migrations.py index 78e7de9e3..346e21da5 100644 --- a/fastapi_backend/app/domain/migrations.py +++ b/fastapi_backend/app/domain/migrations.py @@ -49,7 +49,7 @@ def steps(): """[(name, fn(db))] in the order they run. Append only.""" - from . import access, auth, hierarchy, jobs + from . import access, auth, hierarchy, jobs, mcp_servers return [ # IIIF-only access levels (public, transcript, signed-in, private) become the access setting @@ -60,6 +60,8 @@ def steps(): ("tour-seen", auth.migrate_tours), # documents and images queued to be transcribed are read instead, and those that failed there run again ("document-read-step", jobs.migrate_document_steps), + # MCP servers' tokens and keys in headers and env are sealed, as they now are when saved + ("mcp-sealed-secrets", mcp_servers.migrate_seal), ] diff --git a/fastapi_backend/app/schemas/extensions.py b/fastapi_backend/app/schemas/extensions.py index a55f05be2..f91bf5da9 100644 --- a/fastapi_backend/app/schemas/extensions.py +++ b/fastapi_backend/app/schemas/extensions.py @@ -85,6 +85,42 @@ class ExtensionTestResult(ResponseModel): output: Any = None +class McpConfigText(RequestModel): + text: str = Field(description="an MCP config from another app: Claude's .mcp.json or mcpServers, VS Code's servers, or one server") + + +class McpServerFound(ResponseModel): + name: str = Field(description="a name for it, from the config or guessed from its package or address") + description: str | None = None + spec: dict[str, Any] = Field(description="{url, headers}, or {command, args, env} for one that runs as a program") + fill: list[str] = Field(default_factory=list, description="values written as ${NAME}, which its app filled in and Lens can't") + + +class McpServerSkipped(ResponseModel): + name: str + why: str + + +class McpConfig(ResponseModel): + servers: list[McpServerFound] = [] + skipped: list[McpServerSkipped] = [] + + +class McpServerTry(RequestModel): + spec: dict[str, Any] = Field(description="{url, headers}, or {command, args, env} for one that runs as a program") + extension: int | None = Field(None, description="the MCP server whose saved secrets fill in values sent as ••••") + + +class McpServerTools(ResponseModel): + tools: list[dict[str, Any]] = Field(description="its tools, as it lists them now: {name, description, schema, read_only}") + + +class McpToolSwitch(RequestModel): + tool: str = Field(description="the tool's name, as the server lists it") + on: bool | None = Field(None, description="switch it on or off") + ask: bool | None = Field(None, description="whether it asks first (default: unless the server says it only reads)") + + class Marketplace(ResponseModel): id: int name: str = Field(description="the name its marketplace.json gives it") diff --git a/fastapi_backend/tests/api/test_mcp_servers.py b/fastapi_backend/tests/api/test_mcp_servers.py index 831c1148a..1e624e4c9 100644 --- a/fastapi_backend/tests/api/test_mcp_servers.py +++ b/fastapi_backend/tests/api/test_mcp_servers.py @@ -1,5 +1,6 @@ -"""MCP servers as extensions: an admin adds one, Lens lists its tools, and the assistant calls them (a read-only one at -once, the others after a yes); a plugin's MCP servers come along when an admin installs it.""" +"""MCP servers as extensions: an admin adds one (by a manifest, or a config pasted from another app), Lens lists its +tools, and the assistant calls them (a read-only one at once, the others after a yes, each switched on or off); its +tokens are sealed and never shown; a plugin's MCP servers come along when an admin installs it.""" from __future__ import annotations @@ -7,7 +8,8 @@ import pytest -from app.domain import extensions, marketplace, mcp_client +from app.domain import extensions, marketplace, mcp_client, mcp_servers +from app.domain.store import R from tests import fake_llm from tests.api._assist import Assist, sse, start_llm from tests.api.test_marketplaces import tarball @@ -162,7 +164,7 @@ def test_a_plugins_mcp_servers_come_with_an_admin_install(app, db, cfg, folder, FAKE_STDIO = r""" -import json, sys +import json, os, sys for line in sys.stdin: m = json.loads(line) if "id" not in m: @@ -174,7 +176,8 @@ def test_a_plugins_mcp_servers_come_with_an_admin_install(app, db, cfg, folder, elif m["method"] == "tools/call": if m["params"]["arguments"].get("die"): sys.exit(3) - r = {"content": [{"type": "text", "text": "echo " + json.dumps(m["params"]["arguments"]) + " " + sys.argv[1]}]} + said = "echo " + json.dumps(m["params"]["arguments"]) + " " + sys.argv[1] + os.environ.get("API_KEY", "") + r = {"content": [{"type": "text", "text": said}]} else: print(json.dumps({"jsonrpc": "2.0", "id": m["id"], "error": {"code": -32601, "message": "no"}}), flush=True) continue @@ -237,3 +240,179 @@ def test_a_server_that_runs_as_a_program_runs_in_the_runner(app, db, cfg, folder monkeypatch.delenv("LENS_MCP_RUNNER_URL") no = ca.post("/api/v1/extensions", headers=ha, json={"manifest": {**manifest, "name": "other"}}) assert no.status_code == 400 and "COMPOSE_PROFILES=mcp" in no.json()["detail"] + + +def test_a_programs_keys_are_sealed_and_go_to_that_program_only(app, db, cfg, folder, new_client, runner): + s = Assist(app, db, cfg, folder, new_client) + ca, ha = s.cl["admin"] + manifest = {"name": "keyed", "kind": "mcp", "command": runner["command"], "args": runner["args"], "env": {"API_KEY": "-k3y", "X": "1"}} + eid = ca.post("/api/v1/extensions", headers=ha, json={"manifest": manifest}).json()["id"] + env = extensions.get(db, eid)["spec"]["env"] + assert mcp_servers.is_sealed(env["API_KEY"]) and env["X"] == "1" + got = ca.get(f"/api/v1/extensions/{eid}", headers=ha).json() + assert got["spec"]["env"] == {"API_KEY": "••••", "X": "1"} + tried = ca.post(f"/api/v1/extensions/{eid}/test", headers=ha, json={"tool": "keyed__echo", "args": {}}) + assert tried.json()["output"] == {"text": "echo {} hi-k3y"} # the program got it, opened + # another package is another program: the key isn't handed on + other = {**manifest, "args": [*runner["args"][:-1], "other"], "env": {"API_KEY": "••••", "X": "1"}} + no = ca.post(f"/api/v1/extensions/{eid}/versions", headers=ha, json={"manifest": other}) + assert no.status_code == 400 and "goes somewhere else" in no.json()["detail"] + + +def test_its_secrets_are_sealed_and_never_shown(app, db, cfg, folder, new_client, server): + s = Assist(app, db, cfg, folder, new_client) + ca, ha = s.cl["admin"] + eid = ca.post("/api/v1/extensions", headers=ha, json={"text": SERVER}).json()["id"] + kept = extensions.get(db, eid)["spec"]["headers"]["Authorization"] + assert mcp_servers.is_sealed(kept) and "t0ken" not in kept + got = ca.get(f"/api/v1/extensions/{eid}", headers=ha).json() + assert got["spec"]["headers"] == {"Authorization": "••••"} and "t0ken" not in got["manifest"] + assert "Authorization: ••••" in got["manifest"] + assert "t0ken" not in json.dumps(ca.get("/api/v1/extensions", headers=ha).json()) + # opened only to reach the server + tried = ca.post(f"/api/v1/extensions/{eid}/test", headers=ha, json={"tool": "tracker__search", "args": {"q": "x"}}) + assert tried.json()["output"] == {"text": 'search: {"q": "x"}'} + + # saving the manifest as shown keeps the token, and its tools are listed again with it + server.clear() + saved = ca.post(f"/api/v1/extensions/{eid}/versions", headers=ha, json={"text": got["manifest"], "notes": "again"}) + assert saved.status_code == 200, saved.text + assert any(b["method"] == "tools/list" for _, _, b in server) + assert extensions.get(db, eid)["spec"]["headers"]["Authorization"] != kept # sealed again: the same token + again = ca.post(f"/api/v1/extensions/{eid}/test", headers=ha, json={"tool": "tracker__search", "args": {"q": "y"}}) + assert again.status_code == 200 + # but not to another host, nor into another extension + moved = got["manifest"].replace("mcp.example.com", "evil.example.net") + no = ca.post(f"/api/v1/extensions/{eid}/versions", headers=ha, json={"text": moved}) + assert no.status_code == 400 and "goes somewhere else" in no.json()["detail"] + new = ca.post("/api/v1/extensions", headers=ha, json={"text": got["manifest"].replace("name: tracker", "name: copy")}) + assert new.status_code == 400 and "enter the Authorization value of copy" in new.json()["detail"] + pasted = SERVER.replace("name: tracker", "name: copy").replace("Bearer t0ken", kept) + no = ca.post("/api/v1/extensions", headers=ha, json={"text": pasted}) + assert no.status_code == 400 and "sealed for another extension" in no.json()["detail"] + # a header that isn't a credential stays as it is + headers = {"Authorization": "Bearer t0ken", "X-Team": "blue"} + other = {"name": "plain", "kind": "mcp", "url": "https://mcp.example.com/mcp", "headers": headers} + pid = ca.post("/api/v1/extensions", headers=ha, json={"manifest": other}).json()["id"] + assert extensions.get(db, pid)["spec"]["headers"]["X-Team"] == "blue" + assert ca.get(f"/api/v1/extensions/{pid}", headers=ha).json()["spec"]["headers"] == {"Authorization": "••••", "X-Team": "blue"} + + +def test_upgrading_seals_tokens_saved_before(app, db, cfg, folder, new_client, server): + s = Assist(app, db, cfg, folder, new_client) + ca, ha = s.cl["admin"] + eid = ca.post("/api/v1/extensions", headers=ha, json={"text": SERVER}).json()["id"] + plain = {**extensions.get(db, eid)["spec"], "headers": {"Authorization": "Bearer t0ken"}} + db.q("UPDATE $r SET spec = $s", r=R("extension_version", f"{eid}-1"), s=plain) # as an older Lens kept it + mcp_servers.migrate_seal(db) + kept = extensions.get(db, eid)["spec"]["headers"]["Authorization"] + assert mcp_servers.is_sealed(kept) + mcp_servers.migrate_seal(db) # twice: nothing changes + assert extensions.get(db, eid)["spec"]["headers"]["Authorization"] == kept + tried = ca.post(f"/api/v1/extensions/{eid}/test", headers=ha, json={"tool": "tracker__search", "args": {"q": "x"}}) + assert tried.json()["output"] == {"text": 'search: {"q": "x"}'} + + +def test_each_tool_is_switched_and_says_whether_it_asks(app, db, cfg, folder, new_client, server, llm): + s = Assist(app, db, cfg, folder, new_client) + c, h = s.cl["editor"] + ca, ha = s.cl["admin"] + eid = ca.post("/api/v1/extensions", headers=ha, json={"text": SERVER}).json()["id"] + ca.patch(f"/api/v1/extensions/{eid}", headers=ha, json={"visibility": "everyone"}) + + def effects(): + return {t["name"]: t["spec"]["effect"] for t in extensions.tool_items(extensions.get(db, eid))} + + def switch(body): + return ca.patch(f"/api/v1/extensions/{eid}/tools", headers=ha, json=body) + + assert effects() == {"tracker__search": "read", "tracker__create-issue": "change"} # as the server says + assert switch({"tool": "search", "ask": True}).json()["version"] == 2 + assert switch({"tool": "create-issue", "on": False}).json()["version"] == 3 + assert effects() == {"tracker__search": "change"} + got = ca.get(f"/api/v1/extensions/{eid}", headers=ha).json() + assert got["spec"]["off"] == ["create-issue"] and got["spec"]["ask"] == {"search": True} + assert got["history"][0]["notes"] == "create-issue off" + # they stay when its tools are listed again on saving its manifest + ca.post(f"/api/v1/extensions/{eid}/versions", headers=ha, json={"text": got["manifest"]}) + assert effects() == {"tracker__search": "change"} + # back as the server says: not written down + switch({"tool": "search", "ask": False}) + switch({"tool": "create-issue", "on": True, "ask": False}) + assert effects() == {"tracker__search": "read", "tracker__create-issue": "read"} + assert extensions.get(db, eid)["spec"]["ask"] == {"create-issue": False} + assert switch({"tool": "nope", "on": False}).status_code == 400 + assert c.patch(f"/api/v1/extensions/{eid}/tools", headers=h, json={"tool": "search", "on": False}).status_code == 403 + + # in a conversation: a tool switched off isn't offered, and one set to ask first waits for a yes + switch({"tool": "create-issue", "on": False}) + switch({"tool": "search", "ask": True}) + llm.seen.clear() + llm.tool_script = [{"content": "", "tool_calls": [call(1, "tracker__search", {"q": "login"})]}, {"content": "Asked."}] + cid = c.post("/api/v1/chats", headers=h, json={}).json()["id"] + ev = sse(c.post(f"/api/v1/chats/{cid}/messages", headers=h, json={"content": "Any login bugs?"}).text) + names = [t["function"]["name"] for t in [b for b in llm.seen if b.get("tools")][0]["tools"]] + assert "tracker__search" in names and "tracker__create-issue" not in names + assert ev["step"][0]["summary"] == 'Asked for approval: Run tracker__search(q="login")' + + +CLAUDE = { + "mcpServers": { + "tracker": {"type": "http", "url": "https://mcp.example.com/mcp", "headers": {"Authorization": "Bearer ${TRACKER_TOKEN}"}}, + "github": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": {"GITHUB_TOKEN": "${GH}"}}, + "old": {"type": "sse", "url": "https://old.example.com/sse"}, + } +} + + +def test_a_pasted_config_reads_as_servers_to_add(app, db, cfg, folder, new_client, server): + s = Assist(app, db, cfg, folder, new_client) + ca, ha = s.cl["admin"] + + def read(text): + return ca.post("/api/v1/extensions/mcp/read", headers=ha, json={"text": text}) + + got = read(json.dumps(CLAUDE)).json() + assert [(x["name"], x["fill"]) for x in got["servers"]] == [("tracker", ["TRACKER_TOKEN"]), ("github", ["GH"])] + github = {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": {"GITHUB_TOKEN": "${GH}"}} + assert got["servers"][1]["spec"] == github + assert [x["name"] for x in got["skipped"]] == ["old"] and "SSE" in got["skipped"][0]["why"] + # VS Code's, a list, and one server on its own, its name guessed + vscode = {"servers": {"fetch": {"type": "stdio", "command": "uvx", "args": ["mcp-server-fetch"]}}} + assert [x["name"] for x in read(json.dumps(vscode)).json()["servers"]] == ["fetch"] + one = read('{"command": "npx", "args": ["@playwright/mcp@latest", "--headless"]}').json()["servers"] + assert [x["name"] for x in one] == ["playwright"] + two = read(json.dumps([{"url": "https://mcp.linear.app/mcp"}, {"url": "https://mcp.linear.app/other"}])).json()["servers"] + assert [x["name"] for x in two] == ["linear", "linear_2"] + for bad in ('{"mcpServers": {"x": ', "hello there", "[]"): + assert read(bad).status_code == 400 + + # one is tried, then added with its token filled in + first = {**got["servers"][0]["spec"], "headers": {"Authorization": "Bearer t0ken"}} + tried = ca.post("/api/v1/extensions/mcp/test", headers=ha, json={"spec": first}).json() + assert [t["name"] for t in tried["tools"]] == ["search", "create-issue"] + eid = ca.post("/api/v1/extensions", headers=ha, json={"manifest": {"name": "tracker", "kind": "mcp", **first}}).json()["id"] + # tried again as saved, its token as •••• + shown = {**first, "headers": {"Authorization": "••••"}} + again = ca.post("/api/v1/extensions/mcp/test", headers=ha, json={"spec": shown, "extension": eid}) + assert again.status_code == 200 and len(again.json()["tools"]) == 2 + no = ca.post("/api/v1/extensions/mcp/test", headers=ha, json={"spec": shown}) + assert no.status_code == 400 and "there is none" in no.json()["detail"] + c, h = s.cl["editor"] + no = c.post("/api/v1/extensions/mcp/test", headers=h, json={"spec": first}) + assert no.status_code == 400 and "only admins" in no.json()["detail"] + + +@pytest.mark.parametrize( + "server, name", + [ + ({"command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"]}, "github"), + ({"command": "uvx", "args": ["mcp-server-fetch"]}, "fetch"), + ({"command": "docker", "args": ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server"]}, "github"), + ({"command": "npx", "args": ["@playwright/mcp@latest"]}, "playwright"), + ({"url": "https://api.githubcopilot.com/mcp/"}, "githubcopilot"), + ({"url": "http://localhost:8931/mcp"}, "localhost"), + ], +) +def test_a_server_without_a_name_gets_one(server, name): + assert mcp_servers.guess_name(server) == name diff --git a/fastapi_backend/tests/domain/test_migrations.py b/fastapi_backend/tests/domain/test_migrations.py index 650bbcdd7..190d1368d 100644 --- a/fastapi_backend/tests/domain/test_migrations.py +++ b/fastapi_backend/tests/domain/test_migrations.py @@ -14,7 +14,7 @@ # Every step that has shipped, in order. A database remembers steps by name, so these may never be renamed, reordered # or removed: add new steps to the end of migrations.steps() and here. -SHIPPED = ["access-levels", "collection-homes", "tour-seen", "document-read-step"] +SHIPPED = ["access-levels", "collection-homes", "tour-seen", "document-read-step", "mcp-sealed-secrets"] def test_steps_are_append_only(): @@ -33,10 +33,14 @@ def test_a_fresh_database_has_run_every_step(db): def _old_shape(db): - """Data as an older Lens left it: an IIIF-only access level and a recording without a collection.""" + """Data as an older Lens left it: an IIIF-only access level, a recording without a collection, an MCP token in plain text.""" sid = store.ns_id(db, "pods") rid = db.next_id("recording") db.q("CREATE $r CONTENT $d", r=R("recording", rid), d={"space": sid, "title": "old", "meta_json": json.dumps({"access": "signed-in"})}) + eid = db.next_id("extension") # an MCP server with its token in plain text + db.q("CREATE $r CONTENT $d", r=R("extension", eid), d={"name": "tracker", "kind": "mcp", "current": 1, "enabled": True}) + spec = {"url": "https://mcp.example.com/mcp", "headers": {"Authorization": "Bearer t0ken"}, "tools": []} + db.q("CREATE $r CONTENT $d", r=R("extension_version", f"{eid}-1"), d={"extension": eid, "version": 1, "spec": spec}) return rid @@ -62,8 +66,8 @@ def test_steps_an_older_lens_counted_are_not_run_again(db): db.q("DELETE migration") db.q("UPSERT $r SET n = 1", r=R("seq", "migrations")) rid = _old_shape(db) - assert migrations.pending(db) == ["collection-homes", "tour-seen", "document-read-step"] - assert store.migrate(db) == ["collection-homes", "tour-seen", "document-read-step"] + assert migrations.pending(db) == SHIPPED[1:] + assert store.migrate(db) == SHIPPED[1:] row = db.one("SELECT meta_json, collection FROM $r", r=R("recording", rid)) assert json.loads(row["meta_json"]) == {"access": "signed-in"} # access-levels was counted as done, so not rerun assert row["collection"] == store.default_collection(db, store.ns_id(db, "pods")) @@ -139,7 +143,7 @@ def test_lens_migrations_lists_and_runs(tmp_path, monkeypatch, capsys): assert "pending access-levels" in out and "pending collection-homes" in out cli.main(["--config", str(cfg_path), "migrations", "--run"]) out = capsys.readouterr().out - assert "ran 4 upgrade(s): access-levels, collection-homes, tour-seen, document-read-step" in out + assert f"ran {len(SHIPPED)} upgrade(s): {', '.join(SHIPPED)}" in out assert "done access-levels" in out diff --git a/nextjs-frontend/__tests__/mcp-server-ui.test.tsx b/nextjs-frontend/__tests__/mcp-server-ui.test.tsx new file mode 100644 index 000000000..8377f1b0f --- /dev/null +++ b/nextjs-frontend/__tests__/mcp-server-ui.test.tsx @@ -0,0 +1,176 @@ +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { fireEvent, render, screen, waitFor } from "@testing-library/react"; +import "@testing-library/jest-dom"; +import type { ReactNode } from "react"; + +import { Extensions } from "@/app/openapi-client"; +import { ExtensionEditor } from "@/components/extensions/extension-editor"; +import { McpServerForm } from "@/components/extensions/mcp-server-form"; +import { TooltipProvider } from "@/components/ui/tooltip"; + +jest.mock("@/app/openapi-client", () => ({ + Extensions: { + readMcpConfig: jest.fn(), + testMcpServer: jest.fn(), + createExtension: jest.fn(), + getExtension: jest.fn(), + switchMcpTool: jest.fn(), + testExtension: jest.fn(), + updateExtension: jest.fn(), + deleteExtension: jest.fn(), + }, +})); +jest.mock("next-auth/react", () => ({ useSession: () => ({ data: { accessToken: "t" } }) })); +const push = jest.fn(); +jest.mock("next/navigation", () => ({ useRouter: () => ({ push }) })); +const toast = jest.fn(); +jest.mock("@/components/ui/toast", () => ({ useToast: () => toast })); +const archive = { admin: true, namespaces: [{ name: "pods" }], can: () => true }; +jest.mock("@/lib/hooks/session", () => ({ useArchive: () => archive })); + +const ok = (data: unknown) => Promise.resolve({ data, response: { ok: true, status: 200 } }); +const m = (f: unknown) => f as jest.Mock; + +function wrap(ui: ReactNode) { + const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } }); + return render( + + {ui} + , + ); +} + +const tracker = { + name: "tracker", + description: "The tracker MCP server", + spec: { url: "https://mcp.example.com/mcp", headers: { Authorization: "Bearer ${TRACKER_TOKEN}" } }, + fill: ["TRACKER_TOKEN"], +}; +const fetcher = { + name: "fetch", + description: "The fetch MCP server", + spec: { command: "uvx", args: ["mcp-server-fetch"] }, + fill: [], +}; + +describe("adding an MCP server", () => { + beforeEach(() => { + jest.clearAllMocks(); + archive.admin = true; + }); + + it("reads a pasted config, fills in its token, tests it and saves it with Enter", async () => { + m(Extensions.readMcpConfig).mockReturnValue(ok({ servers: [tracker], skipped: [] })); + m(Extensions.testMcpServer).mockReturnValue( + ok({ tools: [{ name: "search", description: "Search issues", read_only: true }, { name: "create" }] }), + ); + m(Extensions.createExtension).mockReturnValue(ok({ ok: true, id: 4 })); + wrap(); + fireEvent.click(screen.getByRole("radio", { name: /Paste a config/ })); + fireEvent.change(screen.getByLabelText("Config"), { target: { value: JSON.stringify({ mcpServers: {} }) } }); + fireEvent.click(screen.getByRole("button", { name: "Read it" })); + // one server: straight into the form, its token to fill in + const name = await screen.findByLabelText("Name"); + expect(name).toHaveValue("tracker"); + expect(screen.getByLabelText("Address")).toHaveValue("https://mcp.example.com/mcp"); + expect(screen.getByText(/Fill in TRACKER_TOKEN/)).toBeInTheDocument(); + const token = screen.getByLabelText("Headers: value of Authorization"); + expect(token).toHaveAttribute("type", "password"); + fireEvent.change(token, { target: { value: "Bearer t0ken" } }); + expect(screen.queryByText(/Fill in TRACKER_TOKEN/)).not.toBeInTheDocument(); + + fireEvent.click(screen.getByRole("button", { name: "Test" })); + expect(await screen.findByText("search")).toBeInTheDocument(); + expect(screen.getByText("reads")).toBeInTheDocument(); + expect(screen.getByText("asks first")).toBeInTheDocument(); + expect(m(Extensions.testMcpServer).mock.calls[0][0].body).toEqual({ + spec: { url: "https://mcp.example.com/mcp", headers: { Authorization: "Bearer t0ken" } }, + }); + + fireEvent.submit(name); + await waitFor(() => expect(push).toHaveBeenCalledWith("/extensions/4")); + expect(m(Extensions.createExtension).mock.calls[0][0].body.manifest).toEqual({ + name: "tracker", + kind: "mcp", + description: "The tracker MCP server", + url: "https://mcp.example.com/mcp", + headers: { Authorization: "Bearer t0ken" }, + }); + }); + + it("adds every server of a config at once, and says what it left out", async () => { + const other = { ...fetcher, name: "time", spec: { command: "uvx", args: ["mcp-server-time"] } }; + m(Extensions.readMcpConfig).mockReturnValue( + ok({ servers: [fetcher, other], skipped: [{ name: "old", why: "it uses the older SSE transport" }] }), + ); + m(Extensions.createExtension) + .mockReturnValueOnce(ok({ ok: true, id: 5 })) + .mockReturnValueOnce(ok({ ok: true, id: 6 })); + wrap(); + fireEvent.click(screen.getByRole("radio", { name: /Paste a config/ })); + fireEvent.change(screen.getByLabelText("Config"), { target: { value: "{}" } }); + fireEvent.click(screen.getByRole("button", { name: "Read it" })); + expect(await screen.findByText(/it uses the older SSE transport/)).toBeInTheDocument(); + fireEvent.click(screen.getByRole("button", { name: "Add all 2" })); + await waitFor(() => expect(push).toHaveBeenCalledWith("/extensions")); + expect(m(Extensions.createExtension).mock.calls.map((c) => c[0].body.manifest)).toEqual([ + { name: "fetch", kind: "mcp", description: "The fetch MCP server", command: "uvx", args: ["mcp-server-fetch"] }, + { name: "time", kind: "mcp", description: "The fetch MCP server", command: "uvx", args: ["mcp-server-time"] }, + ]); + }); + + it("is for admins", () => { + archive.admin = false; + wrap(); + expect(screen.getByText("Only admins add MCP servers")).toBeInTheDocument(); + }); + + it("switches a server's tools one by one", async () => { + m(Extensions.getExtension).mockReturnValue( + ok({ + id: 3, + name: "tracker", + kind: "mcp", + enabled: true, + editable: true, + current: 1, + version: 1, + visibility: "everyone", + namespaces: [], + manifest: "name: tracker\nkind: mcp\n", + history: [], + spec: { + url: "https://mcp.example.com/mcp", + headers: { Authorization: "••••" }, + tools: [ + { name: "search", read_only: true }, + { name: "create-issue", read_only: false }, + ], + off: ["create-issue"], + }, + }), + ); + m(Extensions.switchMcpTool).mockReturnValue(ok({ ok: true, version: 2 })); + wrap(); + const search = await screen.findByRole("switch", { name: "search on" }); + expect(search).toBeChecked(); + expect(screen.getByRole("switch", { name: "create-issue on" })).not.toBeChecked(); + expect(screen.getByRole("checkbox", { name: "search asks first" })).not.toBeChecked(); + expect(screen.queryByRole("checkbox", { name: "create-issue asks first" })).not.toBeInTheDocument(); + fireEvent.click(screen.getByRole("checkbox", { name: "search asks first" })); + await waitFor(() => + expect(Extensions.switchMcpTool).toHaveBeenCalledWith( + expect.objectContaining({ path: { eid: 3 }, body: { tool: "search", ask: true } }), + ), + ); + fireEvent.click(screen.getByRole("switch", { name: "create-issue on" })); + await waitFor(() => + expect(Extensions.switchMcpTool).toHaveBeenLastCalledWith( + expect.objectContaining({ body: { tool: "create-issue", on: true } }), + ), + ); + // tried by the name the assistant calls it, only the tools that are on + expect(screen.getByRole("button", { name: "Run" })).toBeInTheDocument(); + expect(screen.queryByLabelText("Tool")).not.toBeInTheDocument(); + }); +}); diff --git a/nextjs-frontend/app/(app)/extensions/new/mcp/page.tsx b/nextjs-frontend/app/(app)/extensions/new/mcp/page.tsx new file mode 100644 index 000000000..a221a6288 --- /dev/null +++ b/nextjs-frontend/app/(app)/extensions/new/mcp/page.tsx @@ -0,0 +1,10 @@ +import type { Metadata } from "next"; + +import { McpServerForm } from "@/components/extensions/mcp-server-form"; + +export const metadata: Metadata = { title: "Add MCP server" }; + +/** A new MCP server, by a short form or a pasted config. */ +export default function Page() { + return ; +} diff --git a/nextjs-frontend/app/openapi-client/index.ts b/nextjs-frontend/app/openapi-client/index.ts index b5db04b3b..ef9dc761d 100644 --- a/nextjs-frontend/app/openapi-client/index.ts +++ b/nextjs-frontend/app/openapi-client/index.ts @@ -2111,6 +2111,13 @@ export type { MarksOut, MatterbridgeRoom, MatterbridgeStatus, + McpConfig, + McpConfigText, + McpServerFound, + McpServerSkipped, + McpServerTools, + McpServerTry, + McpToolSwitch, Me, MeData, Member, @@ -2492,6 +2499,11 @@ export type { ReadLogsErrors, ReadLogsResponse, ReadLogsResponses, + ReadMcpConfigData, + ReadMcpConfigError, + ReadMcpConfigErrors, + ReadMcpConfigResponse, + ReadMcpConfigResponses, Recording, RecordingAccess, RecordingAccessUpdate, @@ -3107,6 +3119,11 @@ export type { SuggestTermsErrors, SuggestTermsResponse, SuggestTermsResponses, + SwitchMcpToolData, + SwitchMcpToolError, + SwitchMcpToolErrors, + SwitchMcpToolResponse, + SwitchMcpToolResponses, SyncFedoraData, SyncFedoraResponse, SyncFedoraResponses, @@ -3191,6 +3208,11 @@ export type { TestMailData, TestMailResponse, TestMailResponses, + TestMcpServerData, + TestMcpServerError, + TestMcpServerErrors, + TestMcpServerResponse, + TestMcpServerResponses, TestNotifyTargetData, TestNotifyTargetError, TestNotifyTargetErrors, diff --git a/nextjs-frontend/app/openapi-client/sdk.gen.ts b/nextjs-frontend/app/openapi-client/sdk.gen.ts index 552691e6a..f9e7c26e5 100644 --- a/nextjs-frontend/app/openapi-client/sdk.gen.ts +++ b/nextjs-frontend/app/openapi-client/sdk.gen.ts @@ -1203,6 +1203,9 @@ import type { ReadLogsData, ReadLogsErrors, ReadLogsResponses, + ReadMcpConfigData, + ReadMcpConfigErrors, + ReadMcpConfigResponses, RecordingTopicsData, RecordingTopicsErrors, RecordingTopicsResponses, @@ -1488,6 +1491,9 @@ import type { SuggestTermsData, SuggestTermsErrors, SuggestTermsResponses, + SwitchMcpToolData, + SwitchMcpToolErrors, + SwitchMcpToolResponses, SyncFedoraData, SyncFedoraResponses, TagRecordingsData, @@ -1529,6 +1535,9 @@ import type { TestMailboxResponses, TestMailData, TestMailResponses, + TestMcpServerData, + TestMcpServerErrors, + TestMcpServerResponses, TestNotifyTargetData, TestNotifyTargetErrors, TestNotifyTargetResponses, @@ -9682,6 +9691,44 @@ export class Extensions { }); } + /** + * Read Mcp Config + * + * The MCP servers in a config pasted from another app (Claude's .mcp.json, VS Code's mcp.json), ready to add: each + * as an MCP extension keeps it, and what was left out and why. Nothing is reached or saved. + */ + public static readMcpConfig( + options: Options, + ): RequestResult { + return (options.client ?? client).post({ + url: "/api/v1/extensions/mcp/read", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Test Mcp Server + * + * Ask an MCP server for its tools without saving it (admins). With `extension`, values sent as •••• are that + * server's saved ones. + */ + public static testMcpServer( + options: Options, + ): RequestResult { + return (options.client ?? client).post({ + url: "/api/v1/extensions/mcp/test", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + /** * Delete Extension * @@ -9746,6 +9793,24 @@ export class Extensions { ); } + /** + * Switch Mcp Tool + * + * Switch one of an MCP server's tools on or off, or say whether it asks first (admins): a new version. + */ + public static switchMcpTool( + options: Options, + ): RequestResult { + return (options.client ?? client).patch({ + url: "/api/v1/extensions/{eid}/tools", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + /** * Test Extension * diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index 06ed72de5..17cbd7e57 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -10424,6 +10424,138 @@ export type MatterbridgeStatus = { [key: string]: unknown; }; +/** + * McpConfig + */ +export type McpConfig = { + /** + * Servers + */ + servers?: Array; + /** + * Skipped + */ + skipped?: Array; + [key: string]: unknown; +}; + +/** + * McpConfigText + */ +export type McpConfigText = { + /** + * Text + * + * an MCP config from another app: Claude's .mcp.json or mcpServers, VS Code's servers, or one server + */ + text: string; +}; + +/** + * McpServerFound + */ +export type McpServerFound = { + /** + * Name + * + * a name for it, from the config or guessed from its package or address + */ + name: string; + /** + * Description + */ + description?: string | null; + /** + * Spec + * + * {url, headers}, or {command, args, env} for one that runs as a program + */ + spec: { + [key: string]: unknown; + }; + /** + * Fill + * + * values written as ${NAME}, which its app filled in and Lens can't + */ + fill?: Array; + [key: string]: unknown; +}; + +/** + * McpServerSkipped + */ +export type McpServerSkipped = { + /** + * Name + */ + name: string; + /** + * Why + */ + why: string; + [key: string]: unknown; +}; + +/** + * McpServerTools + */ +export type McpServerTools = { + /** + * Tools + * + * its tools, as it lists them now: {name, description, schema, read_only} + */ + tools: Array<{ + [key: string]: unknown; + }>; + [key: string]: unknown; +}; + +/** + * McpServerTry + */ +export type McpServerTry = { + /** + * Spec + * + * {url, headers}, or {command, args, env} for one that runs as a program + */ + spec: { + [key: string]: unknown; + }; + /** + * Extension + * + * the MCP server whose saved secrets fill in values sent as •••• + */ + extension?: number | null; +}; + +/** + * McpToolSwitch + */ +export type McpToolSwitch = { + /** + * Tool + * + * the tool's name, as the server lists it + */ + tool: string; + /** + * On + * + * switch it on or off + */ + on?: boolean | null; + /** + * Ask + * + * whether it asks first (default: unless the server says it only reads) + */ + ask?: boolean | null; +}; + /** * Me */ @@ -37776,6 +37908,56 @@ export type ImportArchiveResponses = { export type ImportArchiveResponse = ImportArchiveResponses[keyof ImportArchiveResponses]; +export type ReadMcpConfigData = { + body: McpConfigText; + path?: never; + query?: never; + url: "/api/v1/extensions/mcp/read"; +}; + +export type ReadMcpConfigErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type ReadMcpConfigError = ReadMcpConfigErrors[keyof ReadMcpConfigErrors]; + +export type ReadMcpConfigResponses = { + /** + * Successful Response + */ + 200: McpConfig; +}; + +export type ReadMcpConfigResponse = ReadMcpConfigResponses[keyof ReadMcpConfigResponses]; + +export type TestMcpServerData = { + body: McpServerTry; + path?: never; + query?: never; + url: "/api/v1/extensions/mcp/test"; +}; + +export type TestMcpServerErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type TestMcpServerError = TestMcpServerErrors[keyof TestMcpServerErrors]; + +export type TestMcpServerResponses = { + /** + * Successful Response + */ + 200: McpServerTools; +}; + +export type TestMcpServerResponse = TestMcpServerResponses[keyof TestMcpServerResponses]; + export type DeleteExtensionData = { body?: never; path: { @@ -37901,6 +38083,36 @@ export type CreateExtensionVersionResponses = { export type CreateExtensionVersionResponse = CreateExtensionVersionResponses[keyof CreateExtensionVersionResponses]; +export type SwitchMcpToolData = { + body: McpToolSwitch; + path: { + /** + * Eid + */ + eid: number; + }; + query?: never; + url: "/api/v1/extensions/{eid}/tools"; +}; + +export type SwitchMcpToolErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type SwitchMcpToolError = SwitchMcpToolErrors[keyof SwitchMcpToolErrors]; + +export type SwitchMcpToolResponses = { + /** + * Successful Response + */ + 200: VersionSaved; +}; + +export type SwitchMcpToolResponse = SwitchMcpToolResponses[keyof SwitchMcpToolResponses]; + export type TestExtensionData = { body: ExtensionTest; path: { diff --git a/nextjs-frontend/components/extensions/extension-editor.tsx b/nextjs-frontend/components/extensions/extension-editor.tsx index 8a1416cce..8118d0a0a 100644 --- a/nextjs-frontend/components/extensions/extension-editor.tsx +++ b/nextjs-frontend/components/extensions/extension-editor.tsx @@ -88,6 +88,21 @@ headers: }; type Item = { kind: string; name: string; spec: { effect?: string } }; +type McpTool = { name: string; description?: string; read_only?: boolean }; +type McpSpec = { tools?: McpTool[]; off?: string[]; ask?: Record }; + +/** An MCP server's tools as the assistant has them (extensions.mcp_tools): named server__tool, less those switched + * off, each asking first unless it only reads or an admin said it needn't. */ +export function mcpItems(name: string, spec: McpSpec): Item[] { + const off = spec.off ?? []; + return (spec.tools ?? []) + .filter((t) => !off.includes(t.name)) + .map((t) => ({ + kind: "tool", + name: `${name}__${t.name}`.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64), + spec: { effect: (spec.ask?.[t.name] ?? !t.read_only) ? "change" : "read" }, + })); +} /** One extension: its manifest (written as code, checked as you go), on or off, who can use it, trying its tools, * and its versions. With no id, a new one. */ @@ -219,6 +234,15 @@ export function ExtensionEditor({ id }: { id?: number }) { setChecked(null); }} /> + {id == null && kind === "mcp" && ( +

+ Or{" "} + + add it with a form, or paste a config + {" "} + from Claude or VS Code. +

+ )} {checked && (

it.kind === "tool") - : []; + : e.kind === "mcp" + ? mcpItems(e.name, e.spec as McpSpec) + : []; return (

@@ -325,7 +351,8 @@ function SidePanels({ id }: { id: number }) { )}
- {tools.length > 0 && } + {e.kind === "mcp" && } + {tools.length > 0 && t.name).join()} id={id} tools={tools} />}
    {(e.history ?? []).map((h) => ( @@ -355,6 +382,61 @@ function SidePanels({ id }: { id: number }) { ); } +/** An MCP server's tools, each switched on or off and set to ask first or not: a new version each time. */ +function McpToolsPanel({ id, spec, editable }: { id: number; spec: McpSpec; editable: boolean }) { + const client = useApiClient(); + const qc = useQueryClient(); + const toast = useToast(); + const change = useMutation({ + mutationFn: (body: { tool: string; on?: boolean; ask?: boolean }) => + data(Extensions.switchMcpTool({ client, path: { eid: id }, body })), + onSuccess: () => void qc.invalidateQueries({ queryKey: ["extensions"] }), + onError: (err) => toast({ tone: "red", title: "Couldn’t change it", body: (err as Error).message }), + }); + const tools = spec.tools ?? []; + return ( + +
      + {tools.map((t) => { + const on = !(spec.off ?? []).includes(t.name); + const asks = spec.ask?.[t.name] ?? !t.read_only; + return ( +
    • + {t.name}} + checked={on} + disabled={!editable || change.isPending} + onCheckedChange={(v) => change.mutate({ tool: t.name, on: v })} + /> + {t.description && ( + {t.description} + )} + {on && ( + Asks first} + checked={asks} + disabled={!editable || change.isPending} + onCheckedChange={(v) => change.mutate({ tool: t.name, ask: v })} + /> + )} +
    • + ); + })} +
    +
    + ); +} + function TryPanel({ id, tools }: { id: number; tools: Item[] }) { const client = useApiClient(); const [tool, setTool] = useState(tools[0].name); diff --git a/nextjs-frontend/components/extensions/extensions-page.tsx b/nextjs-frontend/components/extensions/extensions-page.tsx index a27885869..9adb161e8 100644 --- a/nextjs-frontend/components/extensions/extensions-page.tsx +++ b/nextjs-frontend/components/extensions/extensions-page.tsx @@ -1,7 +1,7 @@ "use client"; import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; -import { Blocks, MessagesSquare, Mic, Plus, Store, Workflow } from "lucide-react"; +import { Blocks, MessagesSquare, Mic, Plus, Server, Store, Workflow } from "lucide-react"; import Link from "next/link"; import { Extensions } from "@/app/openapi-client"; @@ -15,6 +15,7 @@ import { useToast } from "@/components/ui/toast"; import { VISIBILITY } from "@/components/workflows/save-custom-dialog"; import { data, useApiClient } from "@/lib/api/browser"; import { relative } from "@/lib/format"; +import { useArchive } from "@/lib/hooks/session"; export const KIND_LABEL: Record = { tool: "Tool", @@ -53,6 +54,7 @@ export function ExtensionsPage() { const qc = useQueryClient(); const toast = useToast(); const list = useExtensions(); + const { admin } = useArchive(); const toggle = useMutation({ mutationFn: (v: { id: number; enabled: boolean }) => data(Extensions.updateExtension({ client, path: { eid: v.id }, body: { enabled: v.enabled } })), @@ -85,6 +87,14 @@ export function ExtensionsPage() { Marketplace + {admin && ( + + )} + + + ); +} + +/** "Add MCP server": a short form (an address and its headers, or a command with its args and env), or a config + * pasted from another app. Test asks the server for its tools; Enter saves. Tokens are sealed when saved. */ +export function McpServerForm() { + const client = useApiClient(); + const qc = useQueryClient(); + const toast = useToast(); + const router = useRouter(); + const { admin } = useArchive(); + const [mode, setMode] = useState<"url" | "command" | "paste">("url"); + const [draft, setDraft] = useState(EMPTY); + const [pasted, setPasted] = useState(""); + const [found, setFound] = useState(null); + const [tools, setTools] = useState(null); + const [error, setError] = useState(null); + const edit = (d: Partial) => { + setDraft((old) => ({ ...old, ...d })); + setTools(null); + setError(null); + }; + const pick = (f: McpServerFound) => { + const d = draftOf(f); + setDraft(d); + setMode(d.how); + setTools(null); + setError(null); + }; + + const read = useMutation({ + mutationFn: () => data(Extensions.readMcpConfig({ client, body: { text: pasted } })), + onSuccess: (r) => { + setError(null); + if (r.servers?.length === 1 && !r.skipped?.length) pick(r.servers[0]); + else setFound(r); + }, + onError: (e) => setError((e as Error).message), + }); + const test = useMutation({ + mutationFn: () => data(Extensions.testMcpServer({ client, body: { spec: specOf(draft) } })), + onSuccess: (r) => { + setTools(r.tools as Tool[]); + setError(null); + }, + onError: (e) => setError((e as Error).message), + }); + const save = useMutation({ + mutationFn: async (ds: Draft[]) => { + const ids: number[] = []; + for (const d of ds) + ids.push((await data(Extensions.createExtension({ client, body: { manifest: manifestOf(d) } }))).id); + return ids; + }, + onSuccess: (ids) => { + void qc.invalidateQueries({ queryKey: ["extensions"] }); + toast({ tone: "green", title: ids.length > 1 ? `Added ${ids.length} MCP servers` : "Added to the assistant" }); + router.push(ids.length > 1 ? "/extensions" : `/extensions/${ids[0]}`); + }, + onError: (e) => setError((e as Error).message), + }); + + if (!admin) + return ( + } title="Only admins add MCP servers"> + An MCP server can reach other services and run programs, so an admin adds it. Ask one, or ask the assistant to + list the servers already added. + + ); + + const ready = draft.name.trim() && (draft.how === "url" ? draft.url.trim() : draft.command.trim()); + return ( +
    +
    + + Extensions + +
    + +
    + { + setMode(v as typeof mode); + if (v !== "paste") edit({ how: v as Draft["how"] }); + }} + items={[ + { value: "url", label: "Address" }, + { value: "command", label: "Command" }, + { value: "paste", label: "Paste a config", icon: }, + ]} + /> + } + > + {mode === "paste" ? ( +
    { + ev.preventDefault(); + read.mutate(); + }} + > + + {({ id, describedBy }) => ( +