mcp-telemetry 0.2.0__tar.gz

mcp_telemetry-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 threadwire
+
+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.

mcp_telemetry-0.2.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: mcp-telemetry
+Version: 0.2.0
+Summary: Zero-config observability for MCP servers. OTel GenAI conventions. Redaction on by default.
+Author: threadwire
+License: MIT
+Project-URL: Homepage, https://github.com/threadwire/mcp-telemetry
+Project-URL: Repository, https://github.com/threadwire/mcp-telemetry
+Keywords: mcp,model-context-protocol,observability,opentelemetry,ai,agents,tracing
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: otlp
+Requires-Dist: httpx>=0.27; extra == "otlp"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: admin
+Requires-Dist: fastmcp>=2.0; extra == "admin"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: mcp>=1.0; extra == "dev"
+Requires-Dist: fastmcp>=2.0; extra == "dev"
+Dynamic: license-file
+
+# mcp-telemetry
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
+[![python](https://img.shields.io/badge/python-%3E%3D3.10-3670A0)](#)
+[![runtime deps](https://img.shields.io/badge/core_deps-0-brightgreen)](#)
+
+Zero-config observability for MCP servers. OTel GenAI conventions. **Redaction on by default.**
+
+MCP hit **97 million monthly SDK downloads** — and the production playbook is still being
+written. OWASP's MCP Top 10 puts **"Lack of Audit and Telemetry"** at the top of the risk
+list. This repo is that gap, filled in three lines.
+
+## Install
+
+```bash
+pip install mcp-telemetry            # core — zero dependencies
+pip install 'mcp-telemetry[otlp]'    # + OTLP/HTTP export (httpx)
+```
+
+## Use — no changes to your server logic
+
+```python
+import mcp_telemetry as mt
+
+mt.auto()                                # patches the official `mcp` SDK, writes JSONL
+
+@mt.wrap_tool_call("issues.fetch", server="gh")
+def fetch_issue(issue_id, token=""):
+    ...
+```
+
+Every call emits an OTel GenAI `gen_ai.client.tool_call` span with:
+
+- **input fingerprint** — SHA-256 hash, never the raw payload
+- **secret scrubbing** — `token`, `secret`, `api_key`-style keys → `[REDACTED]`
+- latency, status, error type, server name
+
+Manual spans and traces work too:
+
+```python
+with mt.session():                    # one trace for the whole agent turn
+    with mt.span("chat.step"):
+        ...
+```
+
+## Distributed traces cross servers
+
+Propagation is built in. A `traceparent` header on an inbound MCP request starts a
+**continuation**, not a new trace — the span stamps `parent_span_id` and the trace id
+carries through:
+
+```python
+from mcp_telemetry.propagator import parse_traceparent
+store.start(parse_traceparent(my_header).trace_id)
+```
+
+Pair with [`mcp-hub`](https://github.com/threadwire/mcp-hub): the gateway relays W3C
+`traceparent` verbatim to every upstream, and the responder below records the far side.
+One trace, end to end. See [`examples/responder.py`](examples/responder.py) for a
+stdlib-only server that does exactly this.
+
+## Watch the firehose
+
+```bash
+mcp-trace                 # last 25 spans, ANSI table
+mcp-trace --tail          # follow the JSONL feed
+mcp-trace --json | jq .   # pipe raw records anywhere
+mcp-trace --replay store.jsonl --console   # offline replay → OTLP-shaped output
+```
+
+## Exporters
+
+| Exporter          | Where                          | Deps    |
+|-------------------|--------------------------------|---------|
+| `JsonlExporter`   | `mcp-telemetry.jsonl`          | none    |
+| `TextExporter`    | live stderr panel              | none    |
+| `OtlpExporter`    | Jaeger/Grafana/Datadog via OTLP/HTTP | `[otlp]` |
+
+Spans follow OTel GenAI semantic conventions (`gen_ai.client.tool_call`,
+`gen_ai.agent.invoke`) so traces land in your existing stack without a transform layer.
+
+## Extended surface
+
+- **Sampling** — `parent_based`, `ratio`, `rate_limited` (`mcp_telemetry.sampler`)
+- **Metrics** — `Registry` + histogram buckets, `metrics_from_store` (`mcp_telemetry.metrics`)
+- **OTel provider** — builds OTLP-shaped telemetry, `OtelProvider.export_built` (`mcp_telemetry.otel_provider`)
+- **fastmcp** — opt-in shim: `mt.make_server()`, `patch_fastmcp` (`mcp_telemetry.fastmcp`)
+- **Offline replay** — re-deliver any recorded JSONL through the exporter stack
+
+## Overhead
+
+`examples/bench.py`: **~78µs median, ~85µs p95 per instrumented call** (Python 3.14).
+There's no free lunch, but at that cost you can trace every tool call in a hot agent loop.
+
+## Design
+
+- `monkey.py` — monkeypatches the official `mcp` SDK's `call_tool`; idempotent, no-ops cleanly when the SDK is absent
+- `redact.py` — fingerprinting + secret scrubbing, deterministic hashes
+- `store.py` / `api.py` — trace lifecycle + the three-line public surface
+- `propagator.py` — W3C `traceparent`/`tracestate` continuation between services
+- `replay.py` / `cli.py` — offline re-export + `mcp-trace` renderer/tail/replay
+- Core import graph is **stdlib-only**; `httpx` lives behind `[otlp]`
+
+MIT. Ship it.

mcp_telemetry-0.2.0/README.md

@@ -0,0 +1,104 @@
+# mcp-telemetry
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
+[![python](https://img.shields.io/badge/python-%3E%3D3.10-3670A0)](#)
+[![runtime deps](https://img.shields.io/badge/core_deps-0-brightgreen)](#)
+
+Zero-config observability for MCP servers. OTel GenAI conventions. **Redaction on by default.**
+
+MCP hit **97 million monthly SDK downloads** — and the production playbook is still being
+written. OWASP's MCP Top 10 puts **"Lack of Audit and Telemetry"** at the top of the risk
+list. This repo is that gap, filled in three lines.
+
+## Install
+
+```bash
+pip install mcp-telemetry            # core — zero dependencies
+pip install 'mcp-telemetry[otlp]'    # + OTLP/HTTP export (httpx)
+```
+
+## Use — no changes to your server logic
+
+```python
+import mcp_telemetry as mt
+
+mt.auto()                                # patches the official `mcp` SDK, writes JSONL
+
+@mt.wrap_tool_call("issues.fetch", server="gh")
+def fetch_issue(issue_id, token=""):
+    ...
+```
+
+Every call emits an OTel GenAI `gen_ai.client.tool_call` span with:
+
+- **input fingerprint** — SHA-256 hash, never the raw payload
+- **secret scrubbing** — `token`, `secret`, `api_key`-style keys → `[REDACTED]`
+- latency, status, error type, server name
+
+Manual spans and traces work too:
+
+```python
+with mt.session():                    # one trace for the whole agent turn
+    with mt.span("chat.step"):
+        ...
+```
+
+## Distributed traces cross servers
+
+Propagation is built in. A `traceparent` header on an inbound MCP request starts a
+**continuation**, not a new trace — the span stamps `parent_span_id` and the trace id
+carries through:
+
+```python
+from mcp_telemetry.propagator import parse_traceparent
+store.start(parse_traceparent(my_header).trace_id)
+```
+
+Pair with [`mcp-hub`](https://github.com/threadwire/mcp-hub): the gateway relays W3C
+`traceparent` verbatim to every upstream, and the responder below records the far side.
+One trace, end to end. See [`examples/responder.py`](examples/responder.py) for a
+stdlib-only server that does exactly this.
+
+## Watch the firehose
+
+```bash
+mcp-trace                 # last 25 spans, ANSI table
+mcp-trace --tail          # follow the JSONL feed
+mcp-trace --json | jq .   # pipe raw records anywhere
+mcp-trace --replay store.jsonl --console   # offline replay → OTLP-shaped output
+```
+
+## Exporters
+
+| Exporter          | Where                          | Deps    |
+|-------------------|--------------------------------|---------|
+| `JsonlExporter`   | `mcp-telemetry.jsonl`          | none    |
+| `TextExporter`    | live stderr panel              | none    |
+| `OtlpExporter`    | Jaeger/Grafana/Datadog via OTLP/HTTP | `[otlp]` |
+
+Spans follow OTel GenAI semantic conventions (`gen_ai.client.tool_call`,
+`gen_ai.agent.invoke`) so traces land in your existing stack without a transform layer.
+
+## Extended surface
+
+- **Sampling** — `parent_based`, `ratio`, `rate_limited` (`mcp_telemetry.sampler`)
+- **Metrics** — `Registry` + histogram buckets, `metrics_from_store` (`mcp_telemetry.metrics`)
+- **OTel provider** — builds OTLP-shaped telemetry, `OtelProvider.export_built` (`mcp_telemetry.otel_provider`)
+- **fastmcp** — opt-in shim: `mt.make_server()`, `patch_fastmcp` (`mcp_telemetry.fastmcp`)
+- **Offline replay** — re-deliver any recorded JSONL through the exporter stack
+
+## Overhead
+
+`examples/bench.py`: **~78µs median, ~85µs p95 per instrumented call** (Python 3.14).
+There's no free lunch, but at that cost you can trace every tool call in a hot agent loop.
+
+## Design
+
+- `monkey.py` — monkeypatches the official `mcp` SDK's `call_tool`; idempotent, no-ops cleanly when the SDK is absent
+- `redact.py` — fingerprinting + secret scrubbing, deterministic hashes
+- `store.py` / `api.py` — trace lifecycle + the three-line public surface
+- `propagator.py` — W3C `traceparent`/`tracestate` continuation between services
+- `replay.py` / `cli.py` — offline re-export + `mcp-trace` renderer/tail/replay
+- Core import graph is **stdlib-only**; `httpx` lives behind `[otlp]`
+
+MIT. Ship it.

mcp_telemetry-0.2.0/mcp_telemetry/__init__.py

@@ -0,0 +1,41 @@
+"""mcp-telemetry — zero-config observability for MCP servers.
+
+Core is stdlib-only. Optional exporters:
+  - OTLP/HTTP (needs httpx)  -> pip install mcp-telemetry[otlp]
+  - built-in JSONL + live TUI terminal panel (no deps)
+
+Extended surface — propagation, sampling, metrics, OTel provider, replay:
+  from mcp_telemetry.propagator import generate_traceparent, parse_traceparent
+  from mcp_telemetry.sampler import parent_based, ratio, rate_limited
+  from mcp_telemetry.metrics import Registry, metrics_from_store
+  from mcp_telemetry.otel_provider import OtelProvider
+  from mcp_telemetry.fastmcp import patch_fastmcp, make_server
+  mcp-trace --replay store.jsonl --console
+"""
+from mcp_telemetry.api import (
+    auto,
+    instrument,
+    session,
+    span,
+    trace_store,
+)
+from mcp_telemetry import monkey
+from mcp_telemetry.monkey import wrap_tool_call, patch_mcp_sdk
+from mcp_telemetry.store import TraceStore, default_store, set_default_store
+
+__all__ = [
+    "auto",
+    "instrument",
+    "session",
+    "span",
+    "trace_store",
+    "monkey",
+    "wrap_tool_call",
+    "patch_mcp_sdk",
+    "TraceStore",
+    "default_store",
+    "set_default_store",
+    "__version__",
+]
+
+__version__ = "0.2.0"

mcp_telemetry-0.2.0/mcp_telemetry/api.py

@@ -0,0 +1,98 @@
+"""Public API for mcp-telemetry.
+
+  import mcp_telemetry as mt
+  mt.auto()                      # patch official mcp SDK + fanout to JSONL
+  mt.instrument(exporter=..., scrubbed=True)
+
+  with mt.span("chat"):          # manual span around an LLM call
+      ...
+"""
+from __future__ import annotations
+
+import os
+import sys
+from contextlib import contextmanager
+from typing import Iterator, Optional
+
+from mcp_telemetry import context as _ctx
+from mcp_telemetry import exporters
+from mcp_telemetry import model
+from mcp_telemetry import redact
+from mcp_telemetry.monkey import is_patched, patch_mcp_sdk, wrap_tool_call
+from mcp_telemetry.store import TraceStore, default_store, set_default_store
+
+_ENABLED = False
+
+
+def instrument(
+    store: Optional[TraceStore] = None,
+    trace_exporter: Optional[exporters.Exporter] = None,
+    enabled: bool = True,
+) -> None:
+    """Configure the active store + exporter fanout."""
+    global _ENABLED
+    eff = store or default_store()
+    if store is not None:
+        set_default_store(store)
+    _ENABLED = enabled
+    eff.on_record = exporters.DEFAULT.export if enabled else None
+    if trace_exporter is not None:
+        exporters.DEFAULT._targets = [trace_exporter]
+
+
+def auto(store: Optional[TraceStore] = None, enabled: bool = True) -> bool:
+    """All-in-one: enforce defaults + patch the official mcp SDK.
+
+    If the mcp SDK is missing, patch is a no-op and auto() still returns True
+    so callers can instrument() without knowing the runtime shape.
+    """
+    instrument(store=store, enabled=enabled)
+    if enabled and "MCP_TELEMETRY_DISABLE" not in os.environ:
+        patch_mcp_sdk(store)
+    if enabled and sys.stderr.isatty():
+        exporters.DEFAULT.add(exporters.TextExporter())
+    return patch_mcp_sdk(store) or True
+
+
+def session(trace_id: Optional[str] = None):
+    """Context manager: start a trace, attach all nested spans to it."""
+    store = default_store()
+    trace = store.start(trace_id)
+    prev = _ctx.get_current()
+    _ctx.set_current(trace)
+
+    @contextmanager
+    def _scope() -> Iterator["TraceStore"]:
+        try:
+            yield store
+        finally:
+            store.record(trace)
+            _ctx.set_current(prev)
+
+    return _scope()
+
+
+@contextmanager
+def span(name: str, kind: str = model.SPAN_AGENT) -> Iterator[model.Span]:
+    """Manual span. Attaches to the ambient session trace if one is open,
+    otherwise starts a standalone trace."""
+    store = default_store()
+    current = _ctx.get_current()
+    if current is not None:
+        trace = current
+    else:
+        trace = store.start()
+    sp = trace._make_span(name, None, kind=kind)
+    try:
+        yield sp
+    except Exception as exc:
+        sp.finish("ERROR", f"{type(exc).__name__}: {exc}")
+        store.record(trace, finished=current is None)
+        raise
+    else:
+        sp.finish("OK")
+        store.record(trace, finished=current is None)
+
+
+def trace_store() -> TraceStore:
+    return default_store()

mcp_telemetry-0.2.0/mcp_telemetry/cli.py

@@ -0,0 +1,90 @@
+"""CLI: mcp-trace — render, tail, and clear the local telemetry feed.
+
+  mcp-trace            # last 25 spans in ANSI table
+  mcp-trace --tail     # follow the JSONL feed
+  mcp-trace --json     # dump raw JSONL to stdout (pipe friendly)
+  mcp-trace --clear    # truncate the local JSONL log
+  mcp-trace --replay <file> [--console] [--max N]   # replay recorded traces through the exporter stack
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import time
+
+
+def _read(path: str) -> list[dict]:
+    rows: list[dict] = []
+    try:
+        with open(path, encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if line:
+                    rows.append(json.loads(line))
+    except FileNotFoundError:
+        pass
+    return rows
+
+
+def _render(rows: list[dict]) -> None:
+    for tr in rows[-25:]:
+        for s in tr["spans"]:
+            hit = "OK" if s["status"] == "OK" else "ERR"
+            color = 32 if hit == "OK" else 31
+            print(
+                f"\x1b[36m{tr['id']}\x1b[0m "
+                f"\x1b[1m{s['tool']}\x1b[0m "
+                f"\x1b[{color}m{hit}\x1b[0m "
+                f"\x1b[33m{s.get('latency_ms') or 0:.1f}ms\x1b[0m "
+                f"in#{s.get('input_hash') or '-'} "
+                + (f"\x1b[31m{s['error']}\x1b[0m" if s.get("error") else "")
+            )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="mcp-trace", description="Render the mcp-telemetry local feed")
+    parser.add_argument("--tail", action="store_true", help="follow the JSONL log")
+    parser.add_argument("--json", action="store_true", help="dump raw records as NDJSON")
+    parser.add_argument("--clear", action="store_true", help="clear the local log")
+    parser.add_argument("--replay", metavar="FILE", help="replay a recorded JSONL store through the exporter stack")
+    parser.add_argument("--console", action="store_true", help="with --replay, print OTLP-shaped traces")
+    parser.add_argument("--max", type=int, metavar="N", help="with --replay, cap the number of traces")
+    parser.add_argument("--path", default="mcp-telemetry.jsonl", help="log file path")
+    args = parser.parse_args()
+
+    if args.replay is not None:
+        from mcp_telemetry.replay import main as replay_main
+
+        sub = [args.replay]
+        if args.console:
+            sub.append("--console")
+        if args.max:
+            sub += ["--max", str(args.max)]
+        return replay_main(sub)
+
+    if args.clear:
+        open(args.path, "w", encoding="utf-8").close()  # noqa: SIM115
+        return 0
+
+    if args.tail:
+        seen = 0
+        while True:
+            rows = _read(args.path)
+            for tr in rows[seen:]:
+                for s in tr["spans"]:
+                    print(json.dumps({"trace": tr["id"], **s}))
+                seen += 1
+            time.sleep(0.5)
+        return 0
+
+    rows = _read(args.path)
+    if args.json:
+        for tr in rows:
+            print(json.dumps(tr))
+        return 0
+    _render(rows)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mcp_telemetry-0.2.0/mcp_telemetry/context.py

@@ -0,0 +1,17 @@
+"""Ambient trace cursor shared across api.py and monkey.py without cycles."""
+from __future__ import annotations
+
+from typing import Optional
+
+from mcp_telemetry.model import Trace
+
+_current: Optional[Trace] = None
+
+
+def set_current(trace: Optional[Trace]) -> None:
+    global _current
+    _current = trace
+
+
+def get_current() -> Optional[Trace]:
+    return _current

mcp_telemetry-0.2.0/mcp_telemetry/exporters.py

@@ -0,0 +1,117 @@
+"""Span payload builders + exporters.
+
+Exporters implement `dump(trace) -> str` so they compose cleanly:
+  - JsonlExporter  -> ndjson for pipes / local debug
+  - OtlpExporter   -> OTLP/HTTP JSON payload (httpx optional extra)
+  - TextExporter   -> ANSI table for the live TUI panel (stdlib only)
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from mcp_telemetry.model import Trace
+
+
+class Exporter(Protocol):
+    def export(self, trace: Trace) -> None: ...
+
+
+@dataclass
+class JsonlExporter:
+    path: str = "mcp-telemetry.jsonl"
+    _lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def export(self, trace: Trace) -> None:
+        with self._lock:
+            with open(self.path, "a", encoding="utf-8") as fh:
+                fh.write(json.dumps(trace.to_dict()) + "\n")
+
+
+@dataclass
+class TextExporter:
+    """Minimal ANSI 256-color renderer. No external deps."""
+
+    _lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def export(self, trace: Trace) -> None:
+        rows = []
+        for s in trace.spans:
+            status = "\x1b[32mOK\x1b[0m" if s.status == "OK" else f"\x1b[31m{s.status}\x1b[0m"
+            lines = [
+                f"  \x1b[36m{trace.id}\x1b[0m {s.tool or s.name}  {status}  "
+                f"\x1b[33m{s.latency_ms or 0:.1f}ms\x1b[0m"
+            ]
+            if s.input_hash:
+                lines.append(f"    input#{s.input_hash}  {s.server or ''}")
+            if s.error:
+                lines.append(f"    \x1b[31m{s.error}\x1b[0m")
+            rows.extend(lines)
+        payload = "\n".join(rows)
+        with self._lock:
+            print(payload, file=sys.stderr)
+
+
+@dataclass
+class OtlpExporter:
+    """OTLP/HTTP JSON (v1 logs/bridge). Requires httpx (extra: [otlp]).
+
+    Sends one span record per tool call with gen_ai keys in attributes.
+    """
+
+    endpoint: str = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318/v1/logs")
+    service_name: str = os.environ.get("OTEL_SERVICE_NAME", "mcp-server")
+    headers: dict[str, str] = field(default_factory=lambda: {"Content-Type": "application/json"})
+
+    def export(self, trace: Trace) -> None:
+        try:
+            import httpx  # type: ignore
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError("OTLP export requires httpx: pip install 'mcp-telemetry[otlp]'") from exc
+
+        records = []
+        for s in trace.spans:
+            attrs = {
+                "gen_ai.tool.name": s.tool or s.name,
+                "gen_ai.server.name": s.server or "",
+                "gen_ai.input.bytes": s.input_hash or "",
+                "gen_ai.usage.input_tokens": s.tokens_in or 0,
+                "gen_ai.usage.output_tokens": s.tokens_out or 0,
+                "gen_ai.operation.span.id": trace.id,
+                "gen_ai.operation.name": s.name,
+            }
+            if s.error:
+                attrs["gen_ai.error.type"] = s.error
+            records.append(
+                {
+                    "scope": {"name": "mcp-telemetry", "version": "0.1.0"},
+                    "resource": {"service.name": self.service_name},
+                    "severity_text": "ERROR" if s.error else "INFO",
+                    "body": {"string_value": f"{s.tool} {s.status}"},
+                    "attributes": attrs,
+                    "timeUnixNano": str(int((s.end or s.start) * 1_000_000_000)),
+                }
+            )
+        httpx.post(self.endpoint, json={"resourceLogs": [{"scopeLogs": [{"logRecords": records}]}]}, headers=self.headers, timeout=5.0)
+
+
+class Fanout:
+    def __init__(self) -> None:
+        self._targets: list[Exporter] = [JsonlExporter()]
+
+    def add(self, exporter: Exporter) -> None:
+        self._targets.append(exporter)
+
+    def export(self, trace: Trace) -> None:
+        for t in self._targets:
+            try:
+                t.export(trace)
+            except Exception:
+                pass
+
+
+DEFAULT = Fanout()

mcp_telemetry-0.2.0/mcp_telemetry/fastmcp.py

@@ -0,0 +1,54 @@
+"""FastMCP integration — one-call instrumentation.
+
+`patch_fastmcp(server)` wraps every tool handler the FastMCP server registers
+so each invocation emits a GenAI-style trace span, deduped per tool, feeding
+the active TraceStore/provider. No SDK import required to USE this module; the
+SDK is fetched lazily so `pip install mcp-telemetry` alone is harmless.
+
+If you do not run FastMCP, call `patch_mcp_sdk()` from the core to auto-wrap
+the stdlib/sdk tool handlers instead — the same spans drop out underneath.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from mcp_telemetry.api import span
+from mcp_telemetry.monkey import wrap_tool_call
+
+
+def patch_fastmcp(server: Any, *, store: Any = None) -> int:
+    """Wrap all handlers currently registered on a FastMCP server object. The
+    instance may be post-`@server.tool(...)` decorated — we walk `server._tool_manager`."""
+    try:
+        import fastmcp  # noqa: F401
+    except ImportError:
+        raise RuntimeError("fastmcp not installed — import it or pip install fastmcp")
+
+    tool_manager = getattr(server, "_tool_manager", None)
+    if tool_manager is None:
+        return 0
+    tools = getattr(tool_manager, "_tools", None) or getattr(tool_manager, "tools", {})
+    wrapped = 0
+    for tool in tools.values() if isinstance(tools, dict) else tools:
+        fn = getattr(tool, "fn", None) or getattr(tool, "func", None)
+        if fn is None:
+            continue
+        name = getattr(tool, "name", None) or getattr(fn, "__name__", "tool")
+        tool.fn = wrap_tool_call(fn, store=store, tool_name=name)  # type: ignore[attr-defined]
+        wrapped += 1
+    return wrapped
+
+
+def make_server(name: str, store: Any) -> Any:
+    """Slim FastMCP-compatible shim for a server name: emits a trace span per
+    tool invocation and records it. Use when you want instrumentation without
+    the SDK present — identical span shape, so replays report the same way."""
+    # class bodies do not close over enclosing function locals — build via type()
+    def tool(fn: Callable[..., Any], *, tool_name: Optional[str] = None) -> Callable[..., Any]:
+        return wrap_tool_call(fn, name=tool_name or getattr(fn, "__name__", "tool"), store=store)
+
+    shim = type("FastMcpShim", (), {"name": name, "tool": staticmethod(tool)})()
+    return shim
+
+
+__all__ = ["patch_fastmcp", "make_server"]