bolt-mcp 0.1.0__tar.gz

bolt_mcp-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+target/
+# Virtual environments
+.venv
+ignore/
+db.sqlite3
+python/django_bolt/_core.cpython-312-x86_64-linux-gnu.so
+plan.md
+python/django_bolt/_core.abi3.so
+python/django_bolt/_core.pyd
+.vscode/
+# Lock files (not used in this project)
+poetry.lock
+Pipfile.lock
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+.claude/settings.local.json

bolt_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: bolt-mcp
+Version: 0.1.0
+Summary: Build MCP (Model Context Protocol) servers on django-bolt with native Streamable HTTP transport
+Project-URL: Homepage, https://github.com/FarhanAliRaza/django-bolt
+Project-URL: Repository, https://github.com/FarhanAliRaza/django-bolt
+Author-email: Farhan <farhanalirazaazeemi@gmail.com>
+License: MIT
+Keywords: agent,django,django-bolt,llm,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.12
+Requires-Dist: django-bolt>=0.8.1
+Requires-Dist: msgspec>=0.20
+Requires-Dist: pyjwt>=2.8
+Description-Content-Type: text/markdown
+
+# bolt-mcp
+
+Build [MCP (Model Context Protocol)](https://modelcontextprotocol.io) servers on top of
+[django-bolt](https://github.com/FarhanAliRaza/django-bolt), served natively over the MCP
+**Streamable HTTP** transport by django-bolt's Rust pipeline — no Starlette/`mcp`-SDK stack.
+
+```python
+from django_bolt import BoltAPI
+from bolt_mcp import MCP
+
+api = BoltAPI()
+mcp = MCP("my-server", "1.0.0")
+
+
+@mcp.tool
+async def greet(name: str) -> dict:
+    """Greet someone by name."""
+    return {"greeting": f"Hello, {name}!"}
+
+
+@mcp.resource("config://app", mime_type="application/json")
+async def app_config() -> str:
+    return '{"env": "prod"}'
+
+
+@mcp.prompt
+async def summarize(topic: str) -> str:
+    return f"Please summarize: {topic}"
+
+
+api.mount_mcp(mcp)  # MCP endpoint mounted at /mcp
+```
+
+Point an MCP client (Claude Desktop, MCP Inspector) at `http://<host>/mcp`.
+
+## Transport
+
+`mount_mcp` registers `POST`/`GET`/`DELETE` on `/mcp`:
+
+- **POST** — JSON-RPC requests. By default every request response is streamed as a finite
+  `text/event-stream` message (MCP-SDK-faithful). Use `MCP(json_response=True)` to return a single
+  `application/json` object instead — the multi-process-friendly mode.
+- **GET** — opens the long-lived SSE listen channel for server→client messages (one per session).
+- **DELETE** — terminates the session.
+
+Sessions are tracked in-process via `Mcp-Session-Id`. **Stateful mode requires a single worker**
+(`runbolt --processes 1`) or sticky sessions; for multiple workers use `MCP(stateless=True)`
+(no GET channel, each POST self-contained).
+
+## Streaming tools: progress, logging, sampling, elicitation
+
+A tool that takes a `Context` can stream while it runs: call `ctx.report_progress`/`ctx.info`
+as work advances (those become live notifications on the POST SSE stream), then `return` the
+final result.
+
+```python
+from bolt_mcp import Context
+
+@mcp.tool
+async def crunch(n: int, ctx: Context) -> dict:
+    for i in range(n):
+        await ctx.report_progress(i + 1, n)   # → notifications/progress (if client sent a progressToken)
+        await ctx.info("working")             # → notifications/message
+    return {"done": n}
+```
+
+`ctx` is injected by type annotation (excluded from the tool's input schema, like `request`).
+Beyond `report_progress`/`debug`/`info`/`warning`/`error` and `read_resource` (one-way / local),
+the Context can call **back into the client and await a reply**:
+
+```python
+@mcp.tool
+async def assist(text: str, ctx: Context) -> dict:
+    summary = await ctx.sample(text)                 # ask the client's LLM (sampling/createMessage)
+    ok = await ctx.elicit("Save this summary?")      # ask the user (elicitation/create)
+    return {"summary": summary["content"]["text"], "saved": ok["action"] == "accept"}
+```
+
+`sample`/`elicit` are bidirectional: the server sends a request on the POST SSE stream and the
+client replies on a separate POST (correlated by id). They therefore require **stateful streaming**
+(`MCP(stateless=False, json_response=False)`, single worker) and a client that advertises those
+capabilities — otherwise they raise (surfaced as an in-band tool error). `report_progress`/logging
+work in stateless mode too.
+
+## Expose existing endpoints as tools
+
+Existing REST routes are **never exposed implicitly** — `api.mount_mcp(mcp)` serves only
+native `@mcp.tool`/`@mcp.resource`/`@mcp.prompt` components. To expose REST routes, list
+their handlers explicitly:
+
+```python
+@api.get("/items/{item_id}")
+async def get_item(item_id: int) -> dict:
+    """Fetch an item by id."""
+    return {"id": item_id}
+
+
+api.mount_mcp(mcp, expose=[get_item])  # tool name "get_item", description from the docstring
+```
+
+The tool's name comes from the function name and its description from the route's
+description/docstring — no extra decorator needed. Use `@expose_as_tool(name=..., description=...)`
+only to override those. A handler that isn't a route on `api`, that takes file/form
+parameters, or whose name collides with another tool raises `ValueError` rather than being
+silently dropped or shadowed.
+
+Exposure is **per-handler by design**: there is no "expose everything" switch, because a
+marker scattered across the codebase must never silently turn a route into an AI-callable
+tool. For deliberate bulk selection, call `expose_routes(mcp, api, include=[...], methods=(...))`
+explicitly before mounting.
+
+## Authentication
+
+**Tier 1 — reuse django-bolt auth** (validated in Rust before the handler):
+
+```python
+from django_bolt import JWTAuthentication, IsAuthenticated
+
+api.mount_mcp(mcp, auth=[JWTAuthentication(secret=...)], guards=[IsAuthenticated()])
+```
+
+Per-tool guards: `@mcp.tool(guards=[HasPermission("x")])` — failing tools are filtered from
+`tools/list` and rejected on `tools/call`. Tools may declare `request: Request` to read
+`request.context` (the authenticated principal).
+
+**Tier 2 — OAuth 2.1 Resource Server** (RFC 9728 metadata + `WWW-Authenticate` challenge):
+
+```python
+from bolt_mcp import ProtectedResource
+
+api.mount_mcp(mcp, oauth=ProtectedResource(
+    resource_url="https://api.example.com/mcp",
+    authorization_servers=["https://idp.example.com"],
+    token_verifier=my_verifier,  # (token: str) -> claims | None
+))
+```
+
+## Development
+
+This package is a uv-workspace member of the django-bolt repo.
+
+```bash
+uv sync                                                  # install workspace (editable)
+uv run pytest python/bolt-mcp/tests -s -vv        # full suite (incl. subprocess integration)
+```
+
+## Status / v1 scope
+
+Implemented: `initialize`/`ping`, `tools/{list,call}`, `resources/{list,read,templates/list}`,
+`prompts/{list,get}`, Streamable HTTP (POST/GET/DELETE), sessions, both auth tiers, auto-expose,
+and streaming tools (progress/logging/sampling/elicitation) via a tool `Context`.
+
+Not yet (v2): `completion/complete`, `logging/setLevel`, resumability (`Last-Event-ID`), and
+Host/Origin DNS-rebinding protection.

bolt_mcp-0.1.0/README.md

@@ -0,0 +1,154 @@
+# bolt-mcp
+
+Build [MCP (Model Context Protocol)](https://modelcontextprotocol.io) servers on top of
+[django-bolt](https://github.com/FarhanAliRaza/django-bolt), served natively over the MCP
+**Streamable HTTP** transport by django-bolt's Rust pipeline — no Starlette/`mcp`-SDK stack.
+
+```python
+from django_bolt import BoltAPI
+from bolt_mcp import MCP
+
+api = BoltAPI()
+mcp = MCP("my-server", "1.0.0")
+
+
+@mcp.tool
+async def greet(name: str) -> dict:
+    """Greet someone by name."""
+    return {"greeting": f"Hello, {name}!"}
+
+
+@mcp.resource("config://app", mime_type="application/json")
+async def app_config() -> str:
+    return '{"env": "prod"}'
+
+
+@mcp.prompt
+async def summarize(topic: str) -> str:
+    return f"Please summarize: {topic}"
+
+
+api.mount_mcp(mcp)  # MCP endpoint mounted at /mcp
+```
+
+Point an MCP client (Claude Desktop, MCP Inspector) at `http://<host>/mcp`.
+
+## Transport
+
+`mount_mcp` registers `POST`/`GET`/`DELETE` on `/mcp`:
+
+- **POST** — JSON-RPC requests. By default every request response is streamed as a finite
+  `text/event-stream` message (MCP-SDK-faithful). Use `MCP(json_response=True)` to return a single
+  `application/json` object instead — the multi-process-friendly mode.
+- **GET** — opens the long-lived SSE listen channel for server→client messages (one per session).
+- **DELETE** — terminates the session.
+
+Sessions are tracked in-process via `Mcp-Session-Id`. **Stateful mode requires a single worker**
+(`runbolt --processes 1`) or sticky sessions; for multiple workers use `MCP(stateless=True)`
+(no GET channel, each POST self-contained).
+
+## Streaming tools: progress, logging, sampling, elicitation
+
+A tool that takes a `Context` can stream while it runs: call `ctx.report_progress`/`ctx.info`
+as work advances (those become live notifications on the POST SSE stream), then `return` the
+final result.
+
+```python
+from bolt_mcp import Context
+
+@mcp.tool
+async def crunch(n: int, ctx: Context) -> dict:
+    for i in range(n):
+        await ctx.report_progress(i + 1, n)   # → notifications/progress (if client sent a progressToken)
+        await ctx.info("working")             # → notifications/message
+    return {"done": n}
+```
+
+`ctx` is injected by type annotation (excluded from the tool's input schema, like `request`).
+Beyond `report_progress`/`debug`/`info`/`warning`/`error` and `read_resource` (one-way / local),
+the Context can call **back into the client and await a reply**:
+
+```python
+@mcp.tool
+async def assist(text: str, ctx: Context) -> dict:
+    summary = await ctx.sample(text)                 # ask the client's LLM (sampling/createMessage)
+    ok = await ctx.elicit("Save this summary?")      # ask the user (elicitation/create)
+    return {"summary": summary["content"]["text"], "saved": ok["action"] == "accept"}
+```
+
+`sample`/`elicit` are bidirectional: the server sends a request on the POST SSE stream and the
+client replies on a separate POST (correlated by id). They therefore require **stateful streaming**
+(`MCP(stateless=False, json_response=False)`, single worker) and a client that advertises those
+capabilities — otherwise they raise (surfaced as an in-band tool error). `report_progress`/logging
+work in stateless mode too.
+
+## Expose existing endpoints as tools
+
+Existing REST routes are **never exposed implicitly** — `api.mount_mcp(mcp)` serves only
+native `@mcp.tool`/`@mcp.resource`/`@mcp.prompt` components. To expose REST routes, list
+their handlers explicitly:
+
+```python
+@api.get("/items/{item_id}")
+async def get_item(item_id: int) -> dict:
+    """Fetch an item by id."""
+    return {"id": item_id}
+
+
+api.mount_mcp(mcp, expose=[get_item])  # tool name "get_item", description from the docstring
+```
+
+The tool's name comes from the function name and its description from the route's
+description/docstring — no extra decorator needed. Use `@expose_as_tool(name=..., description=...)`
+only to override those. A handler that isn't a route on `api`, that takes file/form
+parameters, or whose name collides with another tool raises `ValueError` rather than being
+silently dropped or shadowed.
+
+Exposure is **per-handler by design**: there is no "expose everything" switch, because a
+marker scattered across the codebase must never silently turn a route into an AI-callable
+tool. For deliberate bulk selection, call `expose_routes(mcp, api, include=[...], methods=(...))`
+explicitly before mounting.
+
+## Authentication
+
+**Tier 1 — reuse django-bolt auth** (validated in Rust before the handler):
+
+```python
+from django_bolt import JWTAuthentication, IsAuthenticated
+
+api.mount_mcp(mcp, auth=[JWTAuthentication(secret=...)], guards=[IsAuthenticated()])
+```
+
+Per-tool guards: `@mcp.tool(guards=[HasPermission("x")])` — failing tools are filtered from
+`tools/list` and rejected on `tools/call`. Tools may declare `request: Request` to read
+`request.context` (the authenticated principal).
+
+**Tier 2 — OAuth 2.1 Resource Server** (RFC 9728 metadata + `WWW-Authenticate` challenge):
+
+```python
+from bolt_mcp import ProtectedResource
+
+api.mount_mcp(mcp, oauth=ProtectedResource(
+    resource_url="https://api.example.com/mcp",
+    authorization_servers=["https://idp.example.com"],
+    token_verifier=my_verifier,  # (token: str) -> claims | None
+))
+```
+
+## Development
+
+This package is a uv-workspace member of the django-bolt repo.
+
+```bash
+uv sync                                                  # install workspace (editable)
+uv run pytest python/bolt-mcp/tests -s -vv        # full suite (incl. subprocess integration)
+```
+
+## Status / v1 scope
+
+Implemented: `initialize`/`ping`, `tools/{list,call}`, `resources/{list,read,templates/list}`,
+`prompts/{list,get}`, Streamable HTTP (POST/GET/DELETE), sessions, both auth tiers, auto-expose,
+and streaming tools (progress/logging/sampling/elicitation) via a tool `Context`.
+
+Not yet (v2): `completion/complete`, `logging/setLevel`, resumability (`Last-Event-ID`), and
+Host/Origin DNS-rebinding protection.

bolt_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "bolt-mcp"
+dynamic = ["version"]  # derived from the `bolt-mcp-v*` git tag (see [tool.hatch.version])
+description = "Build MCP (Model Context Protocol) servers on django-bolt with native Streamable HTTP transport"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Farhan", email = "farhanalirazaazeemi@gmail.com" }]
+keywords = ["django", "mcp", "model-context-protocol", "django-bolt", "llm", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: Django",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    # bolt-mcp reads django-bolt internals (FieldDefinition, handler metadata), so it is
+    # version-coupled — keep this floor in lockstep with django-bolt releases.
+    "django-bolt>=0.8.1",
+    "msgspec>=0.20",
+    # The built-in OAuth Authorization Server (bolt_mcp.oauth) signs/validates JWTs with
+    # PyJWT. django-bolt already imports it transitively; declared here for hygiene.
+    "pyjwt>=2.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/FarhanAliRaza/django-bolt"
+Repository = "https://github.com/FarhanAliRaza/django-bolt"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+# Version comes from git tags — no hardcoded version, nothing to bump by hand.
+# `--match "bolt-mcp-v*"` restricts to this package's tags so django-bolt's `v*`
+# tags are ignored; the default tag regex strips the `bolt-mcp-` prefix
+# (bolt-mcp-v0.1.0 -> 0.1.0). Builds with no matching tag get a dev version.
+[tool.hatch.version]
+source = "vcs"
+# root = "../.." → the git repo is two levels up (python/bolt-mcp is a subdir package).
+raw-options = { root = "../..", git_describe_command = ["git", "describe", "--dirty", "--tags", "--long", "--match", "bolt-mcp-v*"] }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bolt_mcp"]
+
+[tool.uv.sources]
+django-bolt = { workspace = true }

bolt_mcp-0.1.0/src/bolt_mcp/__init__.py

@@ -0,0 +1,36 @@
+"""bolt-mcp: build MCP servers on django-bolt.
+
+    from django_bolt import BoltAPI
+    from bolt_mcp import MCP
+
+    api = BoltAPI()
+    mcp = MCP("my-server")
+
+    @mcp.tool
+    async def greet(name: str) -> dict:
+        return {"hello": name}
+
+    api.mount_mcp(mcp)   # serves the MCP Streamable HTTP endpoint at /mcp
+
+The free function ``mount_mcp(api, mcp)`` is the underlying implementation, equivalent
+to the ``api.mount_mcp(mcp)`` method.
+"""
+
+from __future__ import annotations
+
+from .autoexpose import expose_as_tool, expose_routes
+from .context import Context
+from .oauth import AuthorizationServer
+from .server import MCP, principal
+from .transport import ProtectedResource, mount_mcp
+
+__all__ = [
+    "MCP",
+    "mount_mcp",
+    "ProtectedResource",
+    "AuthorizationServer",
+    "principal",
+    "expose_routes",
+    "expose_as_tool",
+    "Context",
+]

bolt_mcp-0.1.0/src/bolt_mcp/_execute.py

@@ -0,0 +1,58 @@
+"""Tool invocation and MCP result mapping.
+
+Calls sync/async tool functions and maps their return value into an MCP
+``CallToolResult`` (``content`` text + ``structuredContent``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import msgspec
+
+from django_bolt._json import default_serializer
+from django_bolt._json import encode as json_encode
+
+from .registry import ToolDef
+
+
+def _text_content(text: str) -> dict[str, Any]:
+    return {"type": "text", "text": text}
+
+
+def error_result(message: str) -> dict[str, Any]:
+    """An in-band CallToolResult error (the MCP way to surface tool failures)."""
+    return {"content": [_text_content(message)], "isError": True}
+
+
+def to_call_tool_result(result: Any) -> dict[str, Any]:
+    """Map a tool's return value into a CallToolResult dict."""
+    if isinstance(result, str):
+        return {"content": [_text_content(result)], "isError": False}
+    if isinstance(result, dict):
+        text = json_encode(result).decode()
+        return {"content": [_text_content(text)], "structuredContent": result, "isError": False}
+    payload = msgspec.to_builtins(result, enc_hook=default_serializer)
+    structured = payload if isinstance(payload, dict) else {"result": payload}
+    text = json_encode(payload).decode()
+    return {"content": [_text_content(text)], "structuredContent": structured, "isError": False}
+
+
+async def run_tool(tool: ToolDef, kwargs: dict[str, Any]) -> Any:
+    """Invoke a tool and return its result value (awaiting async, off-loading sync)."""
+    if tool.is_async:
+        return await tool.fn(**kwargs)
+    return await asyncio.to_thread(tool.fn, **kwargs)
+
+
+async def execute_tool(tool: ToolDef, kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Run a tool and map its return value (or exception) to a CallToolResult dict.
+
+    A raised exception becomes an in-band error result, per MCP tool semantics —
+    shared by the non-streaming and streaming call paths.
+    """
+    try:
+        return to_call_tool_result(await run_tool(tool, kwargs))
+    except Exception as exc:
+        return error_result(str(exc))

bolt_mcp-0.1.0/src/bolt_mcp/autoexpose.py

@@ -0,0 +1,138 @@
+"""Expose existing django-bolt endpoints as MCP tools.
+
+``expose_as_tool`` marks a handler; ``expose_routes`` walks a BoltAPI, reads each
+marked route's pre-computed ``FieldDefinition`` metadata, and registers an MCP tool
+that calls the original handler.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import inspect
+import re
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from . import schema
+from .registry import ToolDef
+from .server import MCP
+
+_MARKER_ATTR = "__bolt_mcp__"
+_SKIP_SOURCES = frozenset({"file", "form"})
+
+
+def expose_as_tool(name: str | None = None, description: str | None = None):
+    """Mark a BoltAPI handler so ``expose_routes`` turns it into an MCP tool."""
+
+    def decorator(fn: Callable) -> Callable:
+        setattr(fn, _MARKER_ATTR, {"name": name, "description": description})
+        return fn
+
+    return decorator
+
+
+def _slug(method: str, path: str) -> str:
+    return f"{method.lower()}_{re.sub(r'[^a-zA-Z0-9]+', '_', path).strip('_')}"
+
+
+def _name(handler: Callable) -> str:
+    return getattr(handler, "__name__", repr(handler))
+
+
+def _tool_name(handler: Callable, method: str, path: str) -> str:
+    """Default MCP tool name: the handler's function name, else a path slug."""
+    name = getattr(handler, "__name__", None)
+    return name if name and not name.startswith("<") else _slug(method, path)
+
+
+def expose_routes(
+    mcp: MCP,
+    api: Any,
+    *,
+    handlers: Iterable[Callable] | None = None,
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+    methods: tuple[str, ...] = ("GET", "POST"),
+    only_marked: bool = True,
+) -> None:
+    """Synthesize MCP tools from selected BoltAPI routes.
+
+    By default every ``@expose_as_tool``-marked GET/POST route becomes a tool.
+
+    ``handlers`` is an explicit allowlist of route handler callables. When given, only
+    those handlers are exposed — regardless of HTTP method or marker (naming a handler
+    is intent enough) — and ``include``/``exclude``/``methods``/``only_marked`` are
+    ignored. A listed handler that isn't a route on ``api``, or that takes file/form
+    parameters (which can't be represented as JSON tool arguments), raises ``ValueError``
+    rather than being silently skipped.
+    """
+    explicit = handlers is not None
+    # Materialize once — `handlers` may be a generator, and we iterate it twice
+    # (to build `allow` here, and to compute `missing` after the route walk).
+    handler_list = list(handlers) if handlers is not None else []
+    allow = {id(h) for h in handler_list}
+    matched: set[int] = set()
+    wanted = {m.upper() for m in methods}
+
+    for method, path, handler_id, handler in api._routes:
+        if explicit:
+            if id(handler) not in allow:
+                continue
+            matched.add(id(handler))
+        else:
+            if method.upper() not in wanted:
+                continue
+            if include and not any(fnmatch.fnmatch(path, pat) for pat in include):
+                continue
+            if exclude and any(fnmatch.fnmatch(path, pat) for pat in exclude):
+                continue
+
+        marker = getattr(handler, _MARKER_ATTR, None)
+        if not explicit and only_marked and marker is None:
+            continue
+
+        meta = api._handler_meta.get(handler_id) or {}
+        fields = meta.get("fields") or []
+        unsupported = sorted({f.source for f in fields if f.source in _SKIP_SOURCES})
+        if unsupported:
+            if explicit:
+                raise ValueError(
+                    f"Cannot expose handler {_name(handler)!r} as an MCP tool: it uses "
+                    f"unsupported parameter source(s) {unsupported} — file/form uploads "
+                    f"can't be represented as JSON tool arguments."
+                )
+            continue
+
+        marker = marker or {}
+        # Name/description derive from the route itself; @expose_as_tool only overrides.
+        name = marker.get("name") or _tool_name(handler, method, path)
+        if name in mcp._tools:
+            raise ValueError(
+                f"MCP tool name {name!r} is already registered — two exposed routes (or a "
+                f"route and a native tool) resolve to the same name. Disambiguate with "
+                f"@expose_as_tool(name=...)."
+            )
+        description = (
+            marker.get("description")
+            or meta.get("openapi_description")
+            or inspect.getdoc(handler)
+            or meta.get("openapi_summary")
+        )
+        args_struct = schema.struct_from_fields(name, fields)
+        mcp.add_tool(
+            ToolDef(
+                name=name,
+                fn=handler,
+                description=description,
+                args_struct=args_struct,
+                input_schema=schema.input_schema_for(args_struct),
+                is_async=inspect.iscoroutinefunction(handler),
+                injects_request=any(f.source == "request" for f in fields),
+            )
+        )
+
+    if explicit:
+        missing = [h for h in handler_list if id(h) not in matched]
+        if missing:
+            names = ", ".join(_name(h) for h in missing)
+            raise ValueError(f"Handler(s) not registered as a route on this BoltAPI: {names}")