mcpspan 0.1.0__py3-none-any.whl

mcpspan/__init__.py

@@ -0,0 +1,34 @@
+"""Analytics for MCP servers.
+
+The usual integration is one line at startup:
+
+    from mcp.server.fastmcp import FastMCP
+    import mcpspan
+
+    mcp = FastMCP("flights")
+    mcpspan.instrument(mcp, api_key=os.environ["MCPSPAN_API_KEY"])
+
+Every tool on the server is measured from then on, whether it was registered
+before that line or after. Without an API key nothing is collected and
+nothing is sent.
+"""
+
+from ._config import configure, shutdown
+from ._instrument import instrument
+from ._track import exclude, track
+from ._types import ClientType, ErrorSource, ToolCallEvent
+from ._version import SDK_VERSION
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "ClientType",
+    "ErrorSource",
+    "ToolCallEvent",
+    "__version__",
+    "configure",
+    "exclude",
+    "instrument",
+    "shutdown",
+    "track",
+]

mcpspan/_call.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Any
+
+from ._client import ClientInfo
+
+
+@dataclass
+class CallState:
+    """What instrumentation knows about the tool call now running.
+
+    `track` wraps the developer's function and sees only its arguments. Which
+    connection the call arrived on, which client sent it, and the arguments as
+    the client sent them are known one layer out, where the MCP server looks
+    the tool up. They reach the function's wrapper through a context variable,
+    which follows the call into the task or worker thread that runs it and is
+    never shared with a concurrent call.
+
+    `reached` is set by the wrapper, so the layer outside knows whether the
+    call got as far as the tool or was refused before it.
+    """
+
+    session_id: str | None
+    client: ClientInfo | None
+    arguments: Any
+    server_version: str | None = None
+    reached: bool = False
+    interim: bool = False
+
+
+current_call: ContextVar[CallState | None] = ContextVar("mcpspan_call", default=None)
+
+
+MODERN_PROTOCOL = "2026-07-28"
+"""The first protocol revision on which a tool can ask the client for input."""
+
+
+def cannot_ask(request_context: Any) -> bool:
+    """Whether the connection is on a protocol with no way to ask for input.
+
+    There, an interim `input_required` result cannot be delivered, and the MCP
+    SDK answers the client with an error in its place: v2 of the official SDK
+    and FastMCP both do. Revisions are dates, so they compare as text.
+    """
+    version = getattr(getattr(request_context, "session", None), "protocol_version", None)
+
+    return isinstance(version, str) and version < MODERN_PROTOCOL

mcpspan/_client.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, NamedTuple
+
+from ._failure import MAX_NAME_LENGTH, truncate
+from ._types import ClientType
+
+
+class ClientInfo(NamedTuple):
+    """How a client described itself: its name and version, as sent.
+
+    On the 2025 protocol a client says this once, in the `initialize`
+    handshake; on the 2026-07-28 protocol it repeats it in every request's
+    `_meta`.
+    """
+
+    name: str | None
+    version: str | None
+
+
+_KNOWN_CLIENTS: tuple[tuple[str, ClientType], ...] = (
+    # Measured: Claude Code sends `claude-code`. It has to come before the
+    # plain Claude entry, which would otherwise swallow it.
+    ("claude-code", "claude-code"),
+    ("claude code", "claude-code"),
+    ("claude", "claude"),
+    ("cursor", "cursor"),
+    ("chatgpt", "chatgpt"),
+    ("openai", "chatgpt"),
+    # Measured: the official Inspector sends `inspector-cli`, which is why
+    # names are matched as substrings.
+    ("inspector", "mcp-inspector"),
+)
+"""Names we recognise, matched as substrings of what a client reports, first
+match wins. The same table as every other mcpspan SDK (contract, section 7)."""
+
+
+def detect_client(info: ClientInfo | None) -> ClientType:
+    """Which application a tool call came from, as far as its name tells."""
+    name = (info.name or "").strip().lower() if info is not None else ""
+    if not name:
+        return "unknown"
+
+    for pattern, client_type in _KNOWN_CLIENTS:
+        if pattern in name:
+            return client_type
+
+    return "other"
+
+
+def client_name(info: ClientInfo | None) -> str | None:
+    """The name a client reported, cut to what the API takes.
+
+    Kept alongside the recognised type so an unfamiliar client is a lead
+    rather than a dead end. The client chooses its own name, and one over the
+    API's limit would lose every event in its batch.
+    """
+    name = (info.name or "").strip() if info is not None else ""
+
+    return truncate(name, MAX_NAME_LENGTH) if name else None
+
+
+CLIENT_INFO_META_KEY = "io.modelcontextprotocol/clientInfo"
+"""Where a request on the 2026-07-28 protocol names its client."""
+
+
+def _read(value: Any, *names: str) -> Any:
+    """The first of several spellings of a field, on a model or in a dict."""
+    for name in names:
+        if isinstance(value, Mapping):
+            if name in value:
+                return value[name]
+        else:
+            found = getattr(value, name, None)
+            if found is not None:
+                return found
+
+    return None
+
+
+def _as_client_info(value: Any) -> ClientInfo | None:
+    name = _read(value, "name")
+    version = _read(value, "version")
+
+    if not isinstance(name, str) and not isinstance(version, str):
+        return None
+
+    return ClientInfo(
+        name if isinstance(name, str) else None,
+        version if isinstance(version, str) else None,
+    )
+
+
+def _declared_in_meta(meta: Any) -> Any:
+    """The client a request's `_meta` names, whatever form `_meta` takes.
+
+    v2 of the official MCP SDK hands `_meta` over as a dict. v1 keeps it as a
+    model, with keys it does not know among its extra fields.
+    """
+    if meta is None:
+        return None
+    if isinstance(meta, Mapping):
+        return meta.get(CLIENT_INFO_META_KEY)
+
+    extra = getattr(meta, "model_extra", None)
+
+    return extra.get(CLIENT_INFO_META_KEY) if isinstance(extra, Mapping) else None
+
+
+def client_from_request(request_context: Any) -> ClientInfo | None:
+    """The client that sent one request, from the MCP SDK's request context.
+
+    The request itself is read first: on the 2026-07-28 protocol it names its
+    client. Otherwise the handshake of the connection the request arrived on,
+    and never any other connection's. A stateless HTTP endpoint on the 2025
+    protocol has neither, and its calls are recorded with an unknown client
+    rather than a guess.
+
+    Every read is defensive. Knowing the client is a convenience; a request
+    context of an unexpected shape leaves it unknown and nothing else.
+    """
+    if request_context is None:
+        return None
+
+    try:
+        # `meta` first. v2 of the official SDK may keep only part of `_meta`
+        # there, and the request's raw `params` still hold all of it.
+        params = getattr(request_context, "params", None)
+        for meta in (
+            getattr(request_context, "meta", None),
+            params.get("_meta") if isinstance(params, Mapping) else None,
+        ):
+            declared = _as_client_info(_declared_in_meta(meta))
+            if declared is not None:
+                return declared
+
+        # v2 keeps the handshake on the connection; v1, and v2 as well, on the
+        # session. `clientInfo` in v1, `client_info` in v2.
+        for holder in ("connection", "session"):
+            params = _read(getattr(request_context, holder, None), "client_params")
+            info = _as_client_info(_read(params, "clientInfo", "client_info"))
+            if info is not None:
+                return info
+    except Exception:
+        return None
+
+    return None

mcpspan/_config.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import atexit
+import os
+import sys
+import threading
+from collections.abc import Callable
+from typing import Any
+
+from ._reporter import EventReporter
+from ._track import set_capture_parameter_names, set_event_sink, set_server_version
+
+NO_ENDPOINT = (
+    "mcpspan: an API key is set but no endpoint, so nothing is collected. "
+    "Set MCPSPAN_ENDPOINT (or the endpoint option) to your mcpspan installation, "
+    "for example http://localhost:6271."
+)
+"""Said when there is a key and nowhere to send: somebody meant to collect.
+
+There is no default endpoint, since mcpspan runs wherever its user runs it,
+and a default would send their data somewhere they did not choose.
+"""
+
+_lock = threading.RLock()
+_reporter: EventReporter | None = None
+_active: tuple[tuple[Any, ...], Callable[[str], object] | None] | None = None
+_exit_hook_installed = False
+_fork_hook_installed = False
+_said_no_endpoint = False
+
+
+def _first_non_empty(*values: str | None) -> str | None:
+    for value in values:
+        if value is not None and value.strip():
+            return value.strip()
+
+    return None
+
+
+def _positive(name: str, value: Any, debug: bool, *, integer: bool) -> Any:
+    """The value if it is usable, otherwise None and, when asked, a note why."""
+    if value is None:
+        return None
+
+    kinds: tuple[type, ...] = (int,) if integer else (int, float)
+    usable = isinstance(value, kinds) and not isinstance(value, bool)
+    if not usable or value <= 0:
+        if debug:
+            expected = "a positive integer" if integer else "a positive number"
+            print(f"mcpspan: ignoring {name}={value!r}, expected {expected}", file=sys.stderr)
+        return None
+
+    return value
+
+
+def configure(
+    *,
+    api_key: str | None = None,
+    endpoint: str | None = None,
+    debug: bool | None = None,
+    on_diagnostic: Callable[[str], object] | None = None,
+    flush_on_exit: bool = True,
+    flush_interval: float | None = None,
+    max_batch_size: int | None = None,
+    max_queue_size: int | None = None,
+    capture_parameter_names: bool = False,
+    server_version: str | None = None,
+) -> None:
+    """Starts collecting, or stops if there is nothing to collect with.
+
+    - `api_key`: falls back to `MCPSPAN_API_KEY`. Without either the SDK
+      does nothing at all, which is the normal state in development and CI.
+    - `endpoint`: base URL of the ingest API; falls back to
+      `MCPSPAN_ENDPOINT`. There is no default: without either, nothing is
+      collected, and the SDK says so once.
+    - `debug`: delivery diagnostics on standard error. `on_diagnostic`
+      receives them instead, and implies `debug`.
+    - `flush_on_exit`: send what is queued when the interpreter exits.
+    - `flush_interval`: seconds a partly filled batch waits (default 5).
+    - `max_batch_size`, `max_queue_size`: events per request (100) and held
+      while delivery fails (10,000).
+    - `capture_parameter_names`: record which parameters a tool was called
+      with, by name and type. Off by default; values are never read.
+    - `server_version`: the version to record calls under, a release or a
+      commit; falls back to `MCPSPAN_SERVER_VERSION`, then to the version the
+      server gives itself. The dashboard marks where each version began.
+
+    Calling it again with the same settings changes nothing. That is the
+    common case: a server built per request configures on every request, and
+    starting over each time would announce the server once per request.
+    Different settings replace the running configuration, sending what the
+    old one held.
+
+    Never raises. It runs during a server's startup, and a mistyped option
+    must not be why a server fails to boot.
+    """
+    try:
+        _configure(
+            api_key=api_key,
+            endpoint=endpoint,
+            debug=debug,
+            on_diagnostic=on_diagnostic,
+            flush_on_exit=flush_on_exit,
+            flush_interval=flush_interval,
+            max_batch_size=max_batch_size,
+            max_queue_size=max_queue_size,
+            capture_parameter_names=capture_parameter_names,
+            server_version=server_version,
+        )
+    except Exception as error:
+        if debug:
+            print(f"mcpspan: could not configure ({error})", file=sys.stderr)
+
+
+def _configure(
+    *,
+    api_key: str | None,
+    endpoint: str | None,
+    debug: bool | None,
+    on_diagnostic: Callable[[str], object] | None,
+    flush_on_exit: bool,
+    flush_interval: float | None,
+    max_batch_size: int | None,
+    max_queue_size: int | None,
+    capture_parameter_names: bool,
+    server_version: str | None,
+) -> None:
+    global _reporter, _active, _said_no_endpoint
+
+    key = _first_non_empty(api_key, os.environ.get("MCPSPAN_API_KEY"))
+    url = _first_non_empty(endpoint, os.environ.get("MCPSPAN_ENDPOINT"))
+    version = _first_non_empty(server_version, os.environ.get("MCPSPAN_SERVER_VERSION"))
+    settings = (
+        key,
+        url,
+        debug,
+        flush_on_exit,
+        flush_interval,
+        max_batch_size,
+        max_queue_size,
+        capture_parameter_names,
+        version,
+    )
+
+    with _lock:
+        if _reporter is not None and _active == (settings, on_diagnostic):
+            return
+
+        previous = _reporter
+        _stop_collecting()
+        if previous is not None:
+            previous.stop()
+
+        verbose = debug if debug is not None else on_diagnostic is not None
+
+        # No key is a normal state, not a mistake. Saying so on every start
+        # would be noise.
+        if key is None:
+            return
+
+        if url is None:
+            # Said unasked, as a refused key is: without it the data goes
+            # nowhere and nothing tells anyone.
+            if not _said_no_endpoint:
+                _said_no_endpoint = True
+                try:
+                    if on_diagnostic is not None:
+                        on_diagnostic(NO_ENDPOINT)
+                    else:
+                        print(NO_ENDPOINT, file=sys.stderr)
+                except Exception:
+                    pass
+            return
+
+        options: dict[str, Any] = {}
+        interval = _positive("flush_interval", flush_interval, verbose, integer=False)
+        if interval is not None:
+            options["flush_interval"] = float(interval)
+        batch = _positive("max_batch_size", max_batch_size, verbose, integer=True)
+        if batch is not None:
+            # The API takes at most 1,000 events per request.
+            options["max_batch_size"] = min(batch, 1_000)
+        queue = _positive("max_queue_size", max_queue_size, verbose, integer=True)
+        if queue is not None:
+            options["max_queue_size"] = queue
+
+        reporter = EventReporter(
+            endpoint=url,
+            api_key=key,
+            debug=verbose,
+            on_diagnostic=on_diagnostic,
+            **options,
+        )
+        _reporter = reporter
+        _active = (settings, on_diagnostic)
+        set_capture_parameter_names(capture_parameter_names)
+        set_server_version(version)
+        set_event_sink(reporter.record)
+
+        if flush_on_exit:
+            _install_exit_hook()
+        _install_fork_hook()
+
+        # In the background: startup does not wait for the network.
+        reporter.start()
+
+
+def _stop_collecting() -> None:
+    global _reporter, _active
+    _reporter = None
+    _active = None
+    set_event_sink(None)
+    set_capture_parameter_names(False)
+    set_server_version(None)
+
+
+def shutdown() -> None:
+    """Stops collecting and makes a final attempt to deliver what is queued.
+
+    Worth calling from a server's own shutdown path. Without it, and with
+    `flush_on_exit` off, the last partly filled batch dies with the process.
+    Blocks for as long as that delivery takes, at most a few seconds.
+    """
+    try:
+        with _lock:
+            previous = _reporter
+            _stop_collecting()
+        if previous is not None:
+            previous.stop()
+    except Exception:
+        pass
+
+
+def is_collecting() -> bool:
+    """Whether the SDK is currently recording tool calls."""
+    return _reporter is not None
+
+
+def _on_exit() -> None:
+    # Only when this configuration asked for it: a later configure() may have
+    # turned it off, and atexit offers no way to ask which one registered.
+    active = _active
+    if active is not None and active[0][3]:
+        shutdown()
+
+
+def _install_exit_hook() -> None:
+    """Arranges one last delivery as the interpreter exits.
+
+    atexit runs once the program's own code is done, including on the normal
+    end of a stdio server when its client leaves. It does not intercept
+    signals and does not change how or when the server exits.
+    """
+    global _exit_hook_installed
+    if not _exit_hook_installed:
+        atexit.register(_on_exit)
+        _exit_hook_installed = True
+
+
+def _install_fork_hook() -> None:
+    """Keeps a forked worker (gunicorn, multiprocessing) collecting.
+
+    A child inherits no threads. The reporter notices the new process on its
+    own when the next event arrives; this only makes sure the configuration
+    lock was not inherited in a held state.
+    """
+    global _fork_hook_installed
+    if _fork_hook_installed or not hasattr(os, "register_at_fork"):
+        return
+
+    def reset_lock() -> None:
+        global _lock
+        _lock = threading.RLock()
+
+    os.register_at_fork(after_in_child=reset_lock)
+    _fork_hook_installed = True

mcpspan/_failure.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+MAX_EXCEPTION_MESSAGE_LENGTH = 500
+"""Longest message kept from a raised exception.
+
+Exception messages are written by developers for developers, so they are
+mostly safe to keep and mostly worth reading in full.
+"""
+
+MAX_RESULT_MESSAGE_LENGTH = 200
+"""Longest message kept from a result marked as an error.
+
+Shorter than the exception limit on purpose. This text was written for a
+language model to read, so it is far more likely than an exception message to
+quote back whatever the user asked about.
+"""
+
+MAX_NAME_LENGTH = 200
+"""Longest text the ingest API takes in a name-like field: a tool, an error
+type, a client, a parameter.
+
+The API refuses a whole batch when any one field is over its limit, so an
+over-long value would take every other event in its batch down with it. These
+values come from outside the developer's control - a client names itself, an
+exception names its own class - so they are cut here rather than trusted.
+"""
+
+
+def truncate(text: str, limit: int) -> str:
+    """Cuts text to a limit, leaving a visible sign that something was removed."""
+    return text if len(text) <= limit else f"{text[: limit - 3]}..."
+
+
+def format_error(error: BaseException) -> str:
+    """Renders an exception as one readable line, for diagnostics."""
+    return f"{type(error).__name__}: {error}"
+
+
+def _field(value: Any, *names: str) -> Any:
+    """Reads the first of several spellings of a field, from a model or a dict.
+
+    The official MCP SDK names result fields in camel case in v1 (`isError`)
+    and in snake case in v2 (`is_error`), and a tool may also return a plain
+    dict in the wire's own spelling. Callers list the v2 spelling first: v2
+    keeps the old name as a deprecated alias whose every read warns, and those
+    warnings would land in the developer's logs.
+    """
+    for name in names:
+        if isinstance(value, Mapping):
+            if name in value:
+                return value[name]
+        elif hasattr(value, name):
+            return getattr(value, name)
+
+    return None
+
+
+def is_error_result(result: Any) -> bool:
+    """Whether a tool reported its own failure through the result.
+
+    MCP asks tools to answer with `isError` rather than raising, so that the
+    model can see what went wrong and react. A wrapper that only watched for
+    exceptions would record a correctly written server as never failing.
+    """
+    return _field(result, "is_error", "isError") is True
+
+
+_INTERIM_TYPES = ("InputRequiredResult", "InputRequiredToolResult")
+
+
+def is_input_required(result: Any) -> bool:
+    """A result the 2026-07-28 protocol calls interim: the tool needs more input first."""
+    # The official SDK's result type, and FastMCP's subclass of its own.
+    if any(cls.__name__ in _INTERIM_TYPES for cls in type(result).__mro__):
+        return True
+
+    return bool(_field(result, "result_type", "resultType") == "input_required")
+
+
+def describe_error_result(result: Any) -> str | None:
+    """Pulls a short description out of a tool result that reported an error.
+
+    Reads only text blocks. Images and binary attachments carry no message
+    worth storing, and copying them anywhere would be indefensible.
+    """
+    content = _field(result, "content")
+    if not isinstance(content, (list, tuple)):
+        return None
+
+    texts = [
+        text
+        for block in content
+        if _field(block, "type") == "text" and isinstance(text := _field(block, "text"), str)
+    ]
+    joined = " ".join(texts).strip()
+
+    return truncate(joined, MAX_RESULT_MESSAGE_LENGTH) if joined else None
+
+
+def describe_exception(error: BaseException) -> tuple[str, str | None]:
+    """The class name and message of a raised exception, cut to their limits."""
+    message = str(error)
+
+    return (
+        truncate(type(error).__name__, MAX_NAME_LENGTH),
+        truncate(message, MAX_EXCEPTION_MESSAGE_LENGTH) if message else None,
+    )