forgesight-mcp 0.1.0__tar.gz

forgesight_mcp-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# venv / tooling
+.venv/
+venv/
+.uv/
+uv.lock
+
+# test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# secrets / local env (never commit)
+.env
+.env.*
+
+# editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# local-only session working state (per the workspace pipeline)
+.claude/state/
+
+# local-only launch planning (not part of the published repo)
+/launch/

forgesight_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: forgesight-mcp
+Version: 0.1.0
+Summary: ForgeSight MCP instrumentation — client + server spans, mcp.* conventions, W3C propagation.
+Project-URL: Homepage, https://github.com/Scaffoldic/forgesight
+Project-URL: Repository, https://github.com/Scaffoldic/forgesight
+Project-URL: Issues, https://github.com/Scaffoldic/forgesight/issues
+Project-URL: Changelog, https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md
+Author: kjoshi
+License-Expression: Apache-2.0
+Keywords: ai-agents,forgesight,mcp,model-context-protocol,observability
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: forgesight-core
+Requires-Dist: mcp>=1
+Description-Content-Type: text/markdown
+
+# forgesight-mcp
+
+MCP instrumentation for [ForgeSight](https://github.com/Scaffoldic/forgesight). Turns every
+[Model Context Protocol](https://modelcontextprotocol.io) `tools/call` / `tools/list` /
+`prompts/get` / `resources/read` into a correctly-mapped span — with W3C trace propagation
+across the transport, so a `pr-reviewer → github-mcp → internal-api-mcp` chain is **one
+trace**.
+
+```bash
+pip install forgesight-mcp
+```
+
+```python
+# client side — an agent calling an MCP server
+import forgesight
+from forgesight_mcp import instrument_mcp_client
+from mcp import ClientSession
+
+forgesight.configure()
+
+async with ClientSession(read, write) as session:
+    instrument_mcp_client(session)          # one line; wraps the transport
+    await session.initialize()
+    result = await session.call_tool("get_diff", {"pr": 42})   # execute_tool get_diff
+```
+
+```python
+# server side — a tool/resource server
+import forgesight
+from forgesight_mcp import instrument_mcp_server
+from mcp.server import Server
+
+forgesight.configure()
+server = Server("github-mcp")
+instrument_mcp_server(server)               # extracts traceparent, opens child spans
+```
+
+## What you get
+
+- **One span per request**, mapped per the OTel MCP conventions. A `tools/call` is the
+  *single* span carrying both `mcp.method.name = tools/call` **and**
+  `gen_ai.operation.name = execute_tool` / `gen_ai.tool.name` — never double-instrumented.
+- **Uniform tool telemetry.** A tool reached via MCP and the same tool reached natively both
+  land under `gen_ai.tool.name`, so "failure rate of `get_diff`" is one query across both.
+- **Traces stitch automatically.** The client injects `traceparent` into the request `_meta`;
+  the server extracts it and opens its span as a child of the caller's — same `trace_id`.
+- **Metrics for free.** Each call feeds `mcp.client.operation.duration` and the derived
+  `agentforge.mcp.invocations_total` (server / method / tool / status).
+- **Secure by default (P7).** `tools/call` arguments and results are captured **only** when
+  `capture_content` resolves true; the redaction interceptor still runs.
+
+## Idempotent + reversible
+
+`instrument_mcp_client` / `instrument_mcp_server` are idempotent (re-instrumenting is a
+no-op) and reversible (`uninstrument_mcp_client` / `uninstrument_mcp_server` restore the
+originals). Auto-instrument new sessions/servers at `configure()` via the `install()` entry
+point:
+
+```yaml
+# forgesight.yaml
+integrations:
+  mcp:
+    enabled: true
+    auto_instrument: true
+    capture_content: false    # P7 default
+```
+
+## License
+
+Apache-2.0

forgesight_mcp-0.1.0/README.md

@@ -0,0 +1,70 @@
+# forgesight-mcp
+
+MCP instrumentation for [ForgeSight](https://github.com/Scaffoldic/forgesight). Turns every
+[Model Context Protocol](https://modelcontextprotocol.io) `tools/call` / `tools/list` /
+`prompts/get` / `resources/read` into a correctly-mapped span — with W3C trace propagation
+across the transport, so a `pr-reviewer → github-mcp → internal-api-mcp` chain is **one
+trace**.
+
+```bash
+pip install forgesight-mcp
+```
+
+```python
+# client side — an agent calling an MCP server
+import forgesight
+from forgesight_mcp import instrument_mcp_client
+from mcp import ClientSession
+
+forgesight.configure()
+
+async with ClientSession(read, write) as session:
+    instrument_mcp_client(session)          # one line; wraps the transport
+    await session.initialize()
+    result = await session.call_tool("get_diff", {"pr": 42})   # execute_tool get_diff
+```
+
+```python
+# server side — a tool/resource server
+import forgesight
+from forgesight_mcp import instrument_mcp_server
+from mcp.server import Server
+
+forgesight.configure()
+server = Server("github-mcp")
+instrument_mcp_server(server)               # extracts traceparent, opens child spans
+```
+
+## What you get
+
+- **One span per request**, mapped per the OTel MCP conventions. A `tools/call` is the
+  *single* span carrying both `mcp.method.name = tools/call` **and**
+  `gen_ai.operation.name = execute_tool` / `gen_ai.tool.name` — never double-instrumented.
+- **Uniform tool telemetry.** A tool reached via MCP and the same tool reached natively both
+  land under `gen_ai.tool.name`, so "failure rate of `get_diff`" is one query across both.
+- **Traces stitch automatically.** The client injects `traceparent` into the request `_meta`;
+  the server extracts it and opens its span as a child of the caller's — same `trace_id`.
+- **Metrics for free.** Each call feeds `mcp.client.operation.duration` and the derived
+  `agentforge.mcp.invocations_total` (server / method / tool / status).
+- **Secure by default (P7).** `tools/call` arguments and results are captured **only** when
+  `capture_content` resolves true; the redaction interceptor still runs.
+
+## Idempotent + reversible
+
+`instrument_mcp_client` / `instrument_mcp_server` are idempotent (re-instrumenting is a
+no-op) and reversible (`uninstrument_mcp_client` / `uninstrument_mcp_server` restore the
+originals). Auto-instrument new sessions/servers at `configure()` via the `install()` entry
+point:
+
+```yaml
+# forgesight.yaml
+integrations:
+  mcp:
+    enabled: true
+    auto_instrument: true
+    capture_content: false    # P7 default
+```
+
+## License
+
+Apache-2.0

forgesight_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "forgesight-mcp"
+version = "0.1.0"
+description = "ForgeSight MCP instrumentation — client + server spans, mcp.* conventions, W3C propagation."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "kjoshi" }]
+keywords = ["observability", "mcp", "model-context-protocol", "ai-agents", "forgesight"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Topic :: System :: Monitoring",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["forgesight-core", "mcp>=1"]
+
+[project.entry-points."forgesight.integrations"]
+mcp = "forgesight_mcp:install"
+
+[project.urls]
+Homepage = "https://github.com/Scaffoldic/forgesight"
+Repository = "https://github.com/Scaffoldic/forgesight"
+Issues = "https://github.com/Scaffoldic/forgesight/issues"
+Changelog = "https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forgesight_mcp"]
+
+[tool.uv.sources]
+forgesight-core = { workspace = true }

forgesight_mcp-0.1.0/src/forgesight_mcp/__init__.py

@@ -0,0 +1,118 @@
+"""ForgeSight MCP instrumentation — client + server spans, ``mcp.*`` conventions, W3C propagation.
+
+Public surface (stable for 0.2): :func:`instrument_mcp_client`, :func:`instrument_mcp_server`,
+:func:`uninstrument_mcp_client`, :func:`uninstrument_mcp_server`. :func:`install` is the
+``forgesight.integrations`` entry point that auto-instruments new sessions/servers when
+``auto_instrument`` is on.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from typing import Any
+
+from .client import in_mcp_tool_call, instrument_mcp_client, uninstrument_mcp_client
+from .mapping import KNOWN_METHODS
+from .server import instrument_mcp_server, uninstrument_mcp_server
+
+_log = logging.getLogger("forgesight.mcp")
+__version__ = "0.1.0"
+
+# class-patch registry for install()/uninstall(): key → (class, original __init__)
+_PATCHED: dict[str, tuple[type, Any]] = {}
+_CONTENT_LOGGED = False
+
+
+def install(
+    config: dict[str, object] | None = None,
+    *,
+    _client_cls: type | None = None,
+    _server_cls: type | None = None,
+) -> bool:
+    """Auto-instrument MCP: patch new ``ClientSession`` / ``Server`` instances at creation.
+
+    The ``forgesight.integrations`` entry point. Honours the ``integrations.mcp`` config
+    block (``enabled`` / ``auto_instrument`` / ``methods`` / ``capture_content``). Returns
+    True if patching was applied. Idempotent.
+    """
+    cfg = dict(config or {})
+    if not cfg.get("enabled", True) or not cfg.get("auto_instrument", True):
+        return False
+    if _PATCHED:
+        return True  # already installed
+    capture = cfg.get("capture_content")
+    capture_opt = bool(capture) if capture is not None else None
+    methods = cfg.get("methods")
+    methods_opt = (
+        list(methods) if isinstance(methods, Sequence) and not isinstance(methods, str) else None
+    )
+    if capture_opt:
+        _log_content_capture()
+
+    client_cls = _client_cls or _import("mcp", "ClientSession")
+    server_cls = _server_cls or _import("mcp.server", "Server")
+    if client_cls is not None:
+        _patch_init("client", client_cls, instrument_mcp_client, capture_opt, methods_opt)
+    if server_cls is not None:
+        _patch_init("server", server_cls, instrument_mcp_server, capture_opt, methods_opt)
+    return bool(_PATCHED)
+
+
+def uninstall() -> None:
+    """Undo :func:`install` — restore the original class constructors."""
+    for cls, original in _PATCHED.values():
+        setattr(cls, "__init__", original)  # noqa: B010 - direct __init__ assign trips mypy
+    _PATCHED.clear()
+
+
+def _patch_init(
+    key: str,
+    cls: type,
+    instrument: Any,
+    capture: bool | None,
+    methods: list[str] | None,
+) -> None:
+    original_init = getattr(cls, "__init__")  # noqa: B009 - keep mypy off __init__ specialcasing
+
+    def patched_init(self: Any, *args: Any, **kwargs: Any) -> None:
+        original_init(self, *args, **kwargs)
+        try:
+            instrument(self, capture_content=capture, methods=methods)
+        except Exception:  # pragma: no cover - defensive; auto-instrument must never break init
+            _log.warning("forgesight-mcp: auto-instrument failed for %s", cls.__name__)
+
+    setattr(cls, "__init__", patched_init)  # noqa: B010 - direct __init__ assign trips mypy
+    _PATCHED[key] = (cls, original_init)
+
+
+def _import(module: str, attr: str) -> type | None:
+    import importlib
+
+    try:
+        return getattr(importlib.import_module(module), attr)  # type: ignore[no-any-return]
+    except Exception:  # pragma: no cover - mcp is a declared dep; absent only in odd installs
+        _log.warning(
+            "forgesight-mcp: could not import %s.%s; auto-instrument skipped", module, attr
+        )
+        return None
+
+
+def _log_content_capture() -> None:
+    global _CONTENT_LOGGED
+    if not _CONTENT_LOGGED:
+        _log.info("forgesight-mcp: MCP content capture is ON (tools/call args + results)")
+        _CONTENT_LOGGED = True
+
+
+__all__ = [
+    "KNOWN_METHODS",
+    "__version__",
+    "in_mcp_tool_call",
+    "install",
+    "instrument_mcp_client",
+    "instrument_mcp_server",
+    "uninstall",
+    "uninstrument_mcp_client",
+    "uninstrument_mcp_server",
+]

forgesight_mcp-0.1.0/src/forgesight_mcp/client.py

@@ -0,0 +1,226 @@
+"""MCP **client** instrumentation — a span per outgoing request, W3C inject, ``mcp.*`` attrs.
+
+``instrument_mcp_client`` replaces the public request methods on a ``ClientSession`` instance
+with wrappers that open the right :class:`~forgesight_core.MCPScope` via the runtime, inject
+``traceparent`` into the request ``_meta`` (so the server continues the trace), and close the
+span with status / duration. A ``tools/call`` becomes the single span carrying both the
+``mcp.*`` attributes and ``gen_ai.operation.name = execute_tool`` — never a second span.
+
+Wrapping the *public* session API (not transport internals) keeps it resilient to MCP-SDK
+churn (risk table §8). Idempotent; ``uninstrument_mcp_client`` restores the originals.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import logging
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from forgesight_core import MCPScope, get_runtime
+
+from .mapping import (
+    MCP_PROMPT_NAME,
+    MCP_RESOURCE_URI,
+    PROMPTS_GET,
+    RESOURCES_READ,
+    TOOL_CALL_ARGUMENTS,
+    TOOL_CALL_RESULT,
+    TOOLS_CALL,
+    resolve_methods,
+    unknown_methods,
+)
+from .propagation import inject_traceparent
+
+_log = logging.getLogger("forgesight.mcp")
+
+_MARKER = "_forgesight_mcp"
+# method string → the ClientSession attribute that issues it
+_METHOD_ATTRS: dict[str, str] = {
+    TOOLS_CALL: "call_tool",
+    "tools/list": "list_tools",
+    PROMPTS_GET: "get_prompt",
+    "prompts/list": "list_prompts",
+    RESOURCES_READ: "read_resource",
+    "resources/list": "list_resources",
+}
+
+# Set while a tools/call span is in flight so a framework adapter (feat-019) can defer to
+# the MCP span instead of opening a second execute_tool span (no double-instrument).
+_IN_TOOLS_CALL: contextvars.ContextVar[bool] = contextvars.ContextVar(
+    "forgesight_mcp_in_tools_call", default=False
+)
+
+
+def in_mcp_tool_call() -> bool:
+    """True while an MCP ``tools/call`` span is open on this context (re-entrancy guard)."""
+    return _IN_TOOLS_CALL.get()
+
+
+class tool_error(Exception):
+    """Marks a ``CallToolResult.isError`` so the span records ``error.type = tool_error``.
+
+    The runtime derives ``error.type`` from the exception's class name (feat-009), so the
+    name is load-bearing — it is the exact ``error.type`` the MCP semconv mandates for an
+    ``isError`` result (otel mapping §4.2).
+    """
+
+
+def instrument_mcp_client(
+    session: Any,
+    *,
+    capture_content: bool | None = None,
+    methods: Sequence[str] | None = None,
+    server_name: str = "mcp",
+) -> Any:
+    """Wrap an MCP client session: span per request, W3C inject, ``mcp.*`` attrs.
+
+    Idempotent — instrumenting an already-instrumented session is a no-op. Returns the same
+    session for chaining.
+    """
+    if getattr(session, _MARKER, None) is not None:
+        return session
+    for name in unknown_methods(methods):
+        _log.warning("forgesight-mcp: ignoring unknown MCP method %r", name)
+    instrumentation = _ClientInstrumentation(
+        session, capture_content=capture_content, methods=methods, server_name=server_name
+    )
+    instrumentation.apply()
+    setattr(session, _MARKER, instrumentation)
+    return session
+
+
+def uninstrument_mcp_client(session: Any) -> None:
+    """Restore a session's original methods. No-op if it was never instrumented."""
+    instrumentation = getattr(session, _MARKER, None)
+    if instrumentation is None:
+        return
+    instrumentation.restore()
+    delattr(session, _MARKER)
+
+
+class _ClientInstrumentation:
+    def __init__(
+        self,
+        session: Any,
+        *,
+        capture_content: bool | None,
+        methods: Sequence[str] | None,
+        server_name: str,
+    ) -> None:
+        self._session = session
+        self._capture_opt = capture_content
+        self._methods = resolve_methods(methods)
+        self._server_name = server_name
+        self._originals: dict[str, Callable[..., Any]] = {}
+        self._protocol_version: str | None = None
+
+    # --- (un)patching ----------------------------------------------------
+    def apply(self) -> None:
+        self._wrap_initialize()
+        for method in self._methods:
+            attr = _METHOD_ATTRS[method]
+            original = getattr(self._session, attr, None)
+            if original is None or not callable(original):
+                continue
+            self._originals[attr] = original
+            setattr(self._session, attr, self._make_wrapper(method, attr, original))
+
+    def restore(self) -> None:
+        for attr, original in self._originals.items():
+            setattr(self._session, attr, original)
+        self._originals.clear()
+
+    # --- wrappers --------------------------------------------------------
+    def _wrap_initialize(self) -> None:
+        original = getattr(self._session, "initialize", None)
+        if original is None or not callable(original):
+            return
+        self._originals["initialize"] = original
+
+        async def initialize(*args: Any, **kwargs: Any) -> Any:
+            result = await original(*args, **kwargs)
+            version = getattr(result, "protocolVersion", None)
+            if version is not None:
+                self._protocol_version = str(version)
+            return result
+
+        self._session.initialize = initialize
+
+    def _make_wrapper(
+        self, method: str, attr: str, original: Callable[..., Any]
+    ) -> Callable[..., Any]:
+        is_tools_call = method == TOOLS_CALL
+
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            tool = _first_name(args, kwargs) if is_tools_call else None
+            scope = MCPScope(
+                get_runtime(), server=self._server_name, method=method, tool=tool, session_id=None
+            )
+            async with scope:
+                if self._protocol_version is not None:
+                    scope._call.protocol_version = self._protocol_version
+                self._set_request_metadata(scope, method, args, kwargs)
+                capture = self._resolve_capture()
+                if is_tools_call:
+                    kwargs = dict(kwargs)
+                    kwargs["meta"] = inject_traceparent(
+                        kwargs.get("meta"), trace_id=scope.trace_id, span_id=scope.span_id
+                    )
+                    if capture:
+                        scope.set_metadata(**{TOOL_CALL_ARGUMENTS: _arguments(args, kwargs)})
+                token = _IN_TOOLS_CALL.set(True) if is_tools_call else None
+                try:
+                    result = await original(*args, **kwargs)
+                finally:
+                    if token is not None:
+                        _IN_TOOLS_CALL.reset(token)
+                if is_tools_call:
+                    self._handle_tool_result(scope, result, capture)
+                return result
+
+        return wrapper
+
+    @staticmethod
+    def _set_request_metadata(
+        scope: MCPScope, method: str, args: tuple[Any, ...], kwargs: dict[str, Any]
+    ) -> None:
+        if method == RESOURCES_READ:
+            uri = args[0] if args else kwargs.get("uri")
+            if uri is not None:
+                scope.set_metadata(**{MCP_RESOURCE_URI: str(uri)})
+        elif method == PROMPTS_GET:
+            name = _first_name(args, kwargs)
+            if name is not None:
+                scope.set_metadata(**{MCP_PROMPT_NAME: name})
+
+    def _handle_tool_result(self, scope: MCPScope, result: Any, capture: bool) -> None:
+        if getattr(result, "isError", False):
+            scope.record_error(tool_error("MCP tools/call returned isError"))
+        elif capture:
+            scope.set_metadata(**{TOOL_CALL_RESULT: _result_repr(result)})
+
+    def _resolve_capture(self) -> bool:
+        if self._capture_opt is not None:
+            return self._capture_opt
+        try:
+            return bool(get_runtime().config.capture_content)
+        except Exception:  # pragma: no cover - runtime always configured in practice
+            return False
+
+
+def _first_name(args: tuple[Any, ...], kwargs: dict[str, Any]) -> str | None:
+    if args:
+        return str(args[0])
+    name = kwargs.get("name")
+    return str(name) if name is not None else None
+
+
+def _arguments(args: tuple[Any, ...], kwargs: dict[str, Any]) -> str:
+    value = args[1] if len(args) > 1 else kwargs.get("arguments")
+    return repr(value)
+
+
+def _result_repr(result: Any) -> str:
+    content = getattr(result, "content", result)
+    return repr(content)

forgesight_mcp-0.1.0/src/forgesight_mcp/mapping.py

@@ -0,0 +1,60 @@
+"""MCP method ↔ span mapping (otel-semantic-conventions §4.2).
+
+A ``tools/call`` is *both* an MCP method (``mcp.method.name = tools/call``) and a tool
+execution (``gen_ai.operation.name = execute_tool``, ``gen_ai.tool.name = <tool>``) — the
+SDK's ``MCPScope`` already emits that single span (no double-instrument). This module owns
+the small, stable facts the instrumentation needs: which methods are known, and how to pull
+the tool / resource / prompt name off each call.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+# Methods the client/server instrumentation spans by default.
+TOOLS_CALL = "tools/call"
+TOOLS_LIST = "tools/list"
+PROMPTS_GET = "prompts/get"
+PROMPTS_LIST = "prompts/list"
+RESOURCES_READ = "resources/read"
+RESOURCES_LIST = "resources/list"
+
+KNOWN_METHODS: frozenset[str] = frozenset(
+    {TOOLS_CALL, TOOLS_LIST, PROMPTS_GET, PROMPTS_LIST, RESOURCES_READ, RESOURCES_LIST}
+)
+
+# Extra span metadata keys (mapped onto the record's attributes).
+MCP_RESOURCE_URI = "mcp.resource.uri"
+MCP_PROMPT_NAME = "mcp.prompt.name"
+TOOL_CALL_ARGUMENTS = "gen_ai.tool.call.arguments"
+TOOL_CALL_RESULT = "gen_ai.tool.call.result"
+
+# Server-side: low-level MCP request type name → method string. Type *names* (not the
+# imported classes) keep this resilient to mcp-SDK import churn.
+REQUEST_TYPE_TO_METHOD: dict[str, str] = {
+    "CallToolRequest": TOOLS_CALL,
+    "ListToolsRequest": TOOLS_LIST,
+    "GetPromptRequest": PROMPTS_GET,
+    "ListPromptsRequest": PROMPTS_LIST,
+    "ReadResourceRequest": RESOURCES_READ,
+    "ListResourcesRequest": RESOURCES_LIST,
+}
+
+
+def resolve_methods(methods: Sequence[str] | None) -> frozenset[str]:
+    """Resolve a caller's ``methods`` option to a known-method set.
+
+    ``None`` ⇒ all known methods. Unknown names are dropped (forward-compat with new MCP
+    methods); the caller is responsible for logging the drop.
+    """
+    if methods is None:
+        return KNOWN_METHODS
+    requested = {str(m) for m in methods}
+    return frozenset(requested & KNOWN_METHODS)
+
+
+def unknown_methods(methods: Sequence[str] | None) -> list[str]:
+    """Return requested method names that are not known (for a one-time WARN)."""
+    if methods is None:
+        return []
+    return sorted({str(m) for m in methods} - KNOWN_METHODS)