streamlit-mcp 0.1.0__tar.gz

streamlit_mcp-0.1.0/.gitattributes

@@ -0,0 +1,5 @@
+# Normalize line endings: store LF in the repo, check out native on each platform.
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.gif binary

streamlit_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: release
+
+# Tag a release (e.g. `git tag v0.1.0 && git push --tags`) to build and publish to PyPI.
+# Publishing uses PyPI Trusted Publishing (OIDC) — no API token stored in the repo.
+# One-time setup on pypi.org: add a Trusted Publisher for project `streamlit-mcp` with
+# owner `dkedar7`, repository `streamlit-mcp`, workflow `release.yml`, environment `pypi`.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Run tests
+        run: uv run --with pytest pytest -q
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing)
+        run: uv publish

streamlit_mcp-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run tests
+        run: uv run --with pytest pytest -q

streamlit_mcp-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Secrets / local
+.env
+*.local

streamlit_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First release. Serve an existing Streamlit app as an MCP server, driven headlessly via
+`streamlit.testing.v1.AppTest` — no browser automation.
+
+- Auto-introspect all ten v1 widget kinds (text_input, number_input, text_area, slider,
+  selectbox, multiselect, checkbox, radio, button, date_input) into MCP tools.
+- Core MCP tools: `list_widgets`, `get_layout`, `set_widget`, `click`, `read_output`,
+  `get_state`. Unsupported elements are reported explicitly.
+- Transports: stdio and HTTP/SSE (see Known issues for HTTP auth status).
+- Human-first CLI (`serve`/`inspect`/`call`) with parity to the MCP tools.
+- `@mcp_tool` decorator for opt-in semantic tools.
+- Guardrails: read-only mode and widget allow-list (enforced on both CLI and MCP).
+
+### Known issues / immediate follow-ups
+- **HTTP bearer auth is not yet enforced on the transport.** The token primitive
+  (`Guardrails.require_bearer`) is implemented and tested, but is not yet bound to the
+  FastMCP HTTP/SSE request path. As a safeguard, `serve` refuses to start an HTTP/SSE
+  server on a non-loopback host. Wiring `FastMCP(auth=...)` with a token verifier is the
+  top follow-up before networked HTTP is supported.
+- **Sessions are not yet disposed.** Per-client isolation works, but there is no
+  session-close hook, so long-running HTTP servers accumulate runtimes. Single-client and
+  stdio use are unaffected.
+- **No concurrency locking.** Concurrent requests sharing one session are not serialized;
+  AppTest is not known to be re-entrant. Use one in-flight request per session for now.
+- Output capture covers headings/markdown/caption/text; `st.write`/`st.error`/etc. are a
+  planned coverage expansion.

streamlit_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kedar Dabhadkar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

streamlit_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: streamlit-mcp
+Version: 0.1.0
+Summary: Serve an existing Streamlit app as an MCP server — agents drive it natively, no browser.
+Project-URL: Homepage, https://github.com/dkedar7/streamlit-mcp
+Project-URL: Source, https://github.com/dkedar7/streamlit-mcp
+Project-URL: Bug Tracker, https://github.com/dkedar7/streamlit-mcp/issues
+Project-URL: Changelog, https://github.com/dkedar7/streamlit-mcp/blob/main/CHANGELOG.md
+Author: Kedar Dabhadkar
+License: MIT License
+        
+        Copyright (c) 2026 Kedar Dabhadkar
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agent,automation,llm,mcp,model-context-protocol,streamlit
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: fastmcp<4,>=3
+Requires-Dist: streamlit>=1.58
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# streamlit-mcp
+
+**Serve any Streamlit app as an MCP server.** Agents introspect your app's widgets,
+set values, click buttons, and read the rendered output and `session_state` — natively,
+over MCP, with **no browser automation**.
+
+```bash
+uv tool install .        # or: pip install .
+
+# serve an app over MCP (stdio for local clients, or HTTP/SSE for networked agents)
+streamlit-mcp serve app.py
+streamlit-mcp serve app.py --transport http --host 127.0.0.1 --port 8000
+
+# drive it yourself from the terminal (same engine the agent uses)
+streamlit-mcp inspect app.py
+streamlit-mcp call app.py --set "Name=agent" --click "Save" --read
+```
+
+Streamlit has no callback graph — it reruns the whole script per interaction — so
+streamlit-mcp drives the app headlessly through Streamlit's own test runtime
+(`streamlit.testing.v1.AppTest`) and returns the **semantic element tree**, not pixels.
+Gradio and Dash already shipped native app-as-MCP; this fills the Streamlit gap.
+
+## Tools exposed to agents
+
+| Tool | What it does |
+|---|---|
+| `list_widgets` / `get_layout` | introspect widgets (kind, label, value, constraints) |
+| `set_widget(identifier, value)` | set a widget and rerun |
+| `click(identifier)` | click a button and rerun |
+| `read_output()` | the rendered element tree, agent-readable |
+| `get_state()` | the app's `session_state` |
+
+Supported widgets (v1): text_input, number_input, text_area, slider, selectbox,
+multiselect, checkbox, radio, button, date_input. Unsupported elements (file_uploader,
+custom components, `st.chat`, fragments) are reported explicitly, never silently dropped.
+
+## Human ↔ agent parity
+
+Everything an agent can do over MCP, a human can do via the CLI — both call the same
+engine. The read-only mode and widget allow-list guardrails apply identically to both
+surfaces.
+
+## Security / trust model
+
+- **`app_path` is executed as trusted code** in the server process (that's how AppTest
+  runs it). Only serve apps you trust.
+- **`get_state` / `read_output` expose the app's `session_state`** to the caller — do not
+  put secrets there.
+- **HTTP/SSE is loopback-only in v1.** A bearer-token primitive exists, but it is **not yet
+  enforced** on the transport, so `serve` refuses to bind HTTP/SSE to a non-loopback host.
+  Use stdio for local clients, or HTTP/SSE on `127.0.0.1`. Enforced networked auth is the
+  top follow-up (see `CHANGELOG.md`).
+
+## License
+
+MIT

streamlit_mcp-0.1.0/README.md

@@ -0,0 +1,57 @@
+# streamlit-mcp
+
+**Serve any Streamlit app as an MCP server.** Agents introspect your app's widgets,
+set values, click buttons, and read the rendered output and `session_state` — natively,
+over MCP, with **no browser automation**.
+
+```bash
+uv tool install .        # or: pip install .
+
+# serve an app over MCP (stdio for local clients, or HTTP/SSE for networked agents)
+streamlit-mcp serve app.py
+streamlit-mcp serve app.py --transport http --host 127.0.0.1 --port 8000
+
+# drive it yourself from the terminal (same engine the agent uses)
+streamlit-mcp inspect app.py
+streamlit-mcp call app.py --set "Name=agent" --click "Save" --read
+```
+
+Streamlit has no callback graph — it reruns the whole script per interaction — so
+streamlit-mcp drives the app headlessly through Streamlit's own test runtime
+(`streamlit.testing.v1.AppTest`) and returns the **semantic element tree**, not pixels.
+Gradio and Dash already shipped native app-as-MCP; this fills the Streamlit gap.
+
+## Tools exposed to agents
+
+| Tool | What it does |
+|---|---|
+| `list_widgets` / `get_layout` | introspect widgets (kind, label, value, constraints) |
+| `set_widget(identifier, value)` | set a widget and rerun |
+| `click(identifier)` | click a button and rerun |
+| `read_output()` | the rendered element tree, agent-readable |
+| `get_state()` | the app's `session_state` |
+
+Supported widgets (v1): text_input, number_input, text_area, slider, selectbox,
+multiselect, checkbox, radio, button, date_input. Unsupported elements (file_uploader,
+custom components, `st.chat`, fragments) are reported explicitly, never silently dropped.
+
+## Human ↔ agent parity
+
+Everything an agent can do over MCP, a human can do via the CLI — both call the same
+engine. The read-only mode and widget allow-list guardrails apply identically to both
+surfaces.
+
+## Security / trust model
+
+- **`app_path` is executed as trusted code** in the server process (that's how AppTest
+  runs it). Only serve apps you trust.
+- **`get_state` / `read_output` expose the app's `session_state`** to the caller — do not
+  put secrets there.
+- **HTTP/SSE is loopback-only in v1.** A bearer-token primitive exists, but it is **not yet
+  enforced** on the transport, so `serve` refuses to bind HTTP/SSE to a non-loopback host.
+  Use stdio for local clients, or HTTP/SSE on `127.0.0.1`. Enforced networked auth is the
+  top follow-up (see `CHANGELOG.md`).
+
+## License
+
+MIT

streamlit_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "streamlit-mcp"
+version = "0.1.0"
+description = "Serve an existing Streamlit app as an MCP server — agents drive it natively, no browser."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Kedar Dabhadkar" }]
+keywords = ["streamlit", "mcp", "model-context-protocol", "agent", "llm", "automation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "streamlit>=1.58",
+    "fastmcp>=3,<4",
+]
+
+[project.urls]
+Homepage = "https://github.com/dkedar7/streamlit-mcp"
+Source = "https://github.com/dkedar7/streamlit-mcp"
+"Bug Tracker" = "https://github.com/dkedar7/streamlit-mcp/issues"
+Changelog = "https://github.com/dkedar7/streamlit-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+streamlit-mcp = "streamlit_mcp.cli:_cli"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/streamlit_mcp"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

streamlit_mcp-0.1.0/src/streamlit_mcp/__init__.py

@@ -0,0 +1,29 @@
+"""streamlit-mcp — serve a Streamlit app as an MCP server, no browser.
+
+The app is driven headlessly through Streamlit's AppTest runtime (behind a Runtime
+interface); widgets auto-map to MCP tools, and a human-first CLI exercises the same
+engine an agent uses (parity).
+"""
+
+__version__ = "0.1.0"
+
+# Public API
+from .decorator import mcp_tool  # noqa: E402
+from .engine import Engine, PermissionDenied  # noqa: E402
+from .guardrails import Guardrails  # noqa: E402
+from .runtime import AppTestRuntime, Runtime, RuntimeError_, WidgetNotFound  # noqa: E402
+from .server import build_server, serve  # noqa: E402
+
+__all__ = [
+    "__version__",
+    "mcp_tool",
+    "Engine",
+    "PermissionDenied",
+    "Guardrails",
+    "AppTestRuntime",
+    "Runtime",
+    "RuntimeError_",
+    "WidgetNotFound",
+    "build_server",
+    "serve",
+]

streamlit_mcp-0.1.0/src/streamlit_mcp/cli.py

@@ -0,0 +1,180 @@
+"""streamlit-mcp CLI — the human-first surface.
+
+`serve` launches the MCP server; `inspect`/`call` let a human drive the app from the
+terminal. All three go through the same engine an agent uses over MCP, so parity (R2)
+holds by construction. Guardrail flags apply identically to the CLI and the server.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Optional
+
+from .engine import Engine
+from .guardrails import Guardrails
+from .runtime import AppTestRuntime
+
+
+def _force_utf8_output() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+
+def build_guardrails(args: argparse.Namespace) -> Optional[Guardrails]:
+    read_only = getattr(args, "read_only", False)
+    allow = getattr(args, "allow", None)
+    bearer = getattr(args, "bearer_token", None)
+    if not read_only and not allow and not bearer:
+        return None
+    return Guardrails(
+        read_only=read_only,
+        allow_list=set(allow) if allow else None,
+        bearer_token=bearer,
+    )
+
+
+def _engine(args: argparse.Namespace) -> Engine:
+    rt = AppTestRuntime(args.app)
+    rt.run()
+    return Engine(rt, guard=build_guardrails(args), app_path=args.app)
+
+
+def _parse_value(raw: str) -> Any:
+    """Parse a --set value: JSON when possible (true/41/["a"]), else a plain string."""
+    try:
+        return json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return raw
+
+
+def _split_assignment(item: str) -> tuple[str, Any]:
+    if "=" not in item:
+        raise ValueError(f"--set expects 'identifier=value', got {item!r}")
+    identifier, raw = item.split("=", 1)
+    return identifier.strip(), _parse_value(raw)
+
+
+# --------------------------------------------------------------------- commands
+def cmd_serve(args: argparse.Namespace) -> int:
+    from .server import serve
+    try:
+        serve(
+            args.app,
+            transport=args.transport,
+            host=args.host,
+            port=args.port,
+            guard=build_guardrails(args),
+        )
+    except ValueError as e:  # fail-closed / bad transport -> clean message, not a traceback
+        print(str(e), file=sys.stderr)
+        return 1
+    return 0
+
+
+def cmd_inspect(args: argparse.Namespace) -> int:
+    eng = _engine(args)
+    out = eng.get_layout() if args.layout else eng.list_widgets()
+    if args.json:
+        print(json.dumps(out, indent=2, default=str))
+        return 0
+    for w in out["widgets"]:
+        flag = " [action]" if w.get("action") else ""
+        print(f"  {w['kind']:<13} {w['identifier']:<14} = {w['value']!r}{flag}")
+    if args.layout:
+        for o in out.get("outputs", []):
+            print(f"  [{o['kind']}] {o['text']}")
+        state = out.get("session_state") or {}
+        if state:
+            print("  session_state:")
+            for k, v in state.items():
+                print(f"    {k} = {v!r}")
+    return 0
+
+
+def cmd_call(args: argparse.Namespace) -> int:
+    try:
+        eng = _engine(args)
+        for item in args.set or []:
+            ident, value = _split_assignment(item)
+            eng.set_widget(ident, value)
+        for ident in args.click or []:
+            eng.click(ident)
+        result = eng.get_state() if args.state else eng.read_output()
+    except Exception as e:  # CLI: surface any failure as a clean message + exit 1
+        print(str(e), file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(result, indent=2, default=str))
+        return 0
+    if args.state:
+        for k, v in result.items():
+            print(f"  {k} = {v!r}")
+    else:
+        for o in result.get("outputs", []):
+            print(f"  [{o['kind']}] {o['text']}")
+    return 0
+
+
+# --------------------------------------------------------------------- parser
+def _add_guard_flags(p: argparse.ArgumentParser, *, bearer: bool) -> None:
+    p.add_argument("--read-only", dest="read_only", action="store_true",
+                   help="block state-changing actions")
+    p.add_argument("--allow", action="append",
+                   help="allow-list a widget identifier (repeatable)")
+    if bearer:
+        p.add_argument("--bearer-token", dest="bearer_token",
+                       help="require this bearer token on HTTP/SSE")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="streamlit-mcp",
+                                     description="Serve a Streamlit app as an MCP server.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_serve = sub.add_parser("serve", help="serve an app over MCP")
+    p_serve.add_argument("app")
+    p_serve.add_argument("--transport", choices=["stdio", "http", "sse"], default="stdio")
+    p_serve.add_argument("--host", default="127.0.0.1")
+    p_serve.add_argument("--port", type=int, default=8000)
+    _add_guard_flags(p_serve, bearer=True)
+    p_serve.set_defaults(func=cmd_serve)
+
+    p_inspect = sub.add_parser("inspect", help="print the app's widgets")
+    p_inspect.add_argument("app")
+    p_inspect.add_argument("--layout", action="store_true", help="full layout (outputs, state, unsupported)")
+    p_inspect.add_argument("--json", action="store_true")
+    _add_guard_flags(p_inspect, bearer=False)
+    p_inspect.set_defaults(func=cmd_inspect)
+
+    p_call = sub.add_parser("call", help="drive the app (same engine agents use)")
+    p_call.add_argument("app")
+    p_call.add_argument("--set", action="append", help="identifier=value (repeatable)")
+    p_call.add_argument("--click", action="append", help="button identifier (repeatable)")
+    p_call.add_argument("--read", action="store_true", help="print rendered output (default)")
+    p_call.add_argument("--state", action="store_true", help="print session_state instead")
+    p_call.add_argument("--json", action="store_true")
+    _add_guard_flags(p_call, bearer=False)
+    p_call.set_defaults(func=cmd_call)
+
+    return parser
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    _force_utf8_output()
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+def _cli() -> None:
+    """Console-script entry point. Propagates the exit code — entry-point shims call the
+    target and ignore its return value, so returning from main() would always exit 0."""
+    raise SystemExit(main())
+
+
+if __name__ == "__main__":
+    _cli()

streamlit_mcp-0.1.0/src/streamlit_mcp/decorator.py

@@ -0,0 +1,70 @@
+"""Opt-in semantic tools: expose a developer-chosen function as a clean MCP tool.
+
+The auto path (widget tools) needs no app changes. When a developer wants higher-level,
+named actions, they decorate a function with ``@mcp_tool`` and it is registered alongside
+the auto-generated widget tools (origin R8). Names must not collide with the core tools or
+with each other (AE5 reporting).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+# Mirror of server.TOOL_NAMES, kept here to avoid a server<->decorator import cycle.
+RESERVED_NAMES = (
+    "list_widgets",
+    "get_layout",
+    "set_widget",
+    "click",
+    "read_output",
+    "get_state",
+)
+
+
+@dataclass
+class SemanticToolSpec:
+    name: str
+    description: str
+    func: Callable
+
+
+_REGISTRY: dict[str, SemanticToolSpec] = {}
+
+
+def mcp_tool(func: Optional[Callable] = None, *, name: Optional[str] = None,
+             description: Optional[str] = None):
+    """Register ``func`` as a semantic MCP tool. Usable bare or with arguments::
+
+        @mcp_tool
+        def reset(): ...
+
+        @mcp_tool(name="reset_all", description="Reset everything")
+        def reset(): ...
+    """
+
+    def register(fn: Callable) -> Callable:
+        tool_name = name or fn.__name__
+        if tool_name in RESERVED_NAMES:
+            raise ValueError(f"semantic tool name {tool_name!r} collides with a core tool")
+        if tool_name in _REGISTRY:
+            raise ValueError(f"semantic tool name {tool_name!r} is already registered")
+        _REGISTRY[tool_name] = SemanticToolSpec(
+            name=tool_name,
+            description=description or (fn.__doc__ or "").strip(),
+            func=fn,
+        )
+        return fn
+
+    if func is not None:  # used as @mcp_tool
+        return register(func)
+    return register  # used as @mcp_tool(...)
+
+
+def registered_semantic_tools() -> list[SemanticToolSpec]:
+    return list(_REGISTRY.values())
+
+
+def clear_registry() -> None:
+    """Reset the registry (test isolation)."""
+    _REGISTRY.clear()