mcpsignals 1.0.1__py3-none-any.whl

mcpsignals/__init__.py

@@ -0,0 +1,10 @@
+from mcpsignals.events import SessionSummaryEvent, ToolCallEvent
+from mcpsignals.instrument import instrument
+from mcpsignals.redaction import RedactionConfig
+
+__all__ = [
+    "instrument",
+    "RedactionConfig",
+    "ToolCallEvent",
+    "SessionSummaryEvent",
+]

mcpsignals/buffer.py

@@ -0,0 +1,98 @@
+"""Batches events and flushes to every configured sink on a size threshold
+or an interval, whichever comes first. A sink failure is caught, logged at
+most once per sink instance, and never propagates - a broken sink must
+never break the host MCP server.
+"""
+
+import asyncio
+import atexit
+import logging
+from collections.abc import Sequence
+
+from mcpsignals.events import SessionSummaryEvent, ToolCallEvent
+from mcpsignals.sinks.base import Sink
+
+logger = logging.getLogger("mcpsignals")
+
+Event = ToolCallEvent | SessionSummaryEvent
+
+
+class EventBuffer:
+    def __init__(
+        self,
+        sinks: Sequence[Sink],
+        buffer_size: int = 20,
+        flush_interval_s: float = 5.0,
+    ):
+        self._sinks = list(sinks)
+        self._buffer_size = buffer_size
+        self._flush_interval_s = flush_interval_s
+        self._events: list[Event] = []
+        self._lock = asyncio.Lock()
+        self._warned_sinks: set[int] = set()
+        self._interval_task: asyncio.Task | None = None
+        atexit.register(self._atexit_flush)
+
+    def _ensure_interval_task(self) -> None:
+        # Started lazily on first event, from inside a running event loop -
+        # constructing EventBuffer itself must not require a loop to exist yet.
+        if self._interval_task is not None:
+            return
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return
+        self._interval_task = loop.create_task(self._interval_loop())
+
+    async def _interval_loop(self) -> None:
+        while True:
+            await asyncio.sleep(self._flush_interval_s)
+            await self.flush()
+
+    async def add(self, event: Event) -> None:
+        self._ensure_interval_task()
+        async with self._lock:
+            self._events.append(event)
+            should_flush = len(self._events) >= self._buffer_size
+        if should_flush:
+            await self.flush()
+
+    async def flush(self) -> None:
+        async with self._lock:
+            if not self._events:
+                return
+            batch, self._events = self._events, []
+
+        results = await asyncio.gather(
+            *(self._write_to_sink(sink, batch) for sink in self._sinks),
+            return_exceptions=True,
+        )
+        for result in results:
+            if isinstance(result, Exception):
+                # _write_to_sink already logged; nothing else to do here.
+                pass
+
+    async def _write_to_sink(self, sink: Sink, batch: list[Event]) -> None:
+        try:
+            await sink.write(batch)
+        except Exception as exc:  # noqa: BLE001 - a sink must never break the host server
+            sink_id = id(sink)
+            if sink_id not in self._warned_sinks:
+                self._warned_sinks.add(sink_id)
+                logger.error("mcpsignals: sink %r failed, dropping batch: %s", sink, exc)
+
+    def _atexit_flush(self) -> None:
+        if not self._events:
+            return
+        # Best-effort only: there is no guarantee a loop is available to
+        # await a real flush at interpreter shutdown. Callers that need a
+        # guaranteed flush should call `await buffer.flush()` explicitly
+        # before shutting down.
+        try:
+            asyncio.run(self.flush())
+        except RuntimeError:
+            logger.warning(
+                "mcpsignals: %d buffered event(s) dropped at exit (no event loop available "
+                "to flush) - call `await flush()` explicitly before shutdown for a guarantee",
+                len(self._events),
+            )

mcpsignals/error_kind.py

@@ -0,0 +1,26 @@
+"""Best-effort classification of a free-text error message into a coarse
+bucket. This is NOT ground truth - `success` is. See schema/events.md for
+the documented false-positive mode.
+"""
+
+import re
+
+_NOT_FOUND = re.compile(r"not found|does not exist|no such", re.IGNORECASE)
+_EMPTY = re.compile(r"\bempty\b|no results?|nothing found|zero results", re.IGNORECASE)
+_VALIDATION = re.compile(r"invalid|required|expected|must be|validation|schema", re.IGNORECASE)
+
+
+def classify_error(message: str | None) -> str | None:
+    """Bucket an error message into not_found / empty / validation / internal.
+
+    Returns None when there is no message to classify (i.e. the call succeeded).
+    """
+    if not message:
+        return None
+    if _NOT_FOUND.search(message):
+        return "not_found"
+    if _EMPTY.search(message):
+        return "empty"
+    if _VALIDATION.search(message):
+        return "validation"
+    return "internal"

mcpsignals/events.py

@@ -0,0 +1,44 @@
+"""Event dataclasses. Field names match schema/events.md exactly."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Literal
+
+
+@dataclass
+class ToolCallEvent:
+    event_type: Literal["tool_call"] = field(init=False, default="tool_call")
+    ts: datetime = field(default=None)  # type: ignore[assignment]
+    server_name: str = ""
+    server_version: str | None = None
+    tool_name: str = ""
+    session_id: str | None = None
+    agent_id: str | None = None
+    client_name: str | None = None
+    client_version: str | None = None
+    user_id: str | None = None
+    org_id: str | None = None
+    duration_ms: int = 0
+    success: bool = True
+    error_kind: str | None = None
+    error_message: str | None = None
+    request_bytes: int = 0
+    response_bytes: int = 0
+    arguments: dict[str, Any] | None = None
+    intent: str | None = None
+    transport: str | None = None
+
+
+@dataclass
+class SessionSummaryEvent:
+    event_type: Literal["session_summary"] = field(init=False, default="session_summary")
+    ts: datetime = field(default=None)  # type: ignore[assignment]
+    session_id: str = ""
+    server_name: str = ""
+    server_version: str | None = None
+    user_id: str | None = None
+    org_id: str | None = None
+    call_count: int = 0
+    distinct_tools_used: int = 0
+    wall_duration_ms: int = 0
+    error_count: int = 0

mcpsignals/instrument.py

@@ -0,0 +1,212 @@
+"""Core instrumentation entry point.
+
+Built on the `mcp` v2 SDK's `middleware` list (`server.middleware.append(fn)`),
+present on both `MCPServer` and the low-level `Server` - the same mechanism
+works for both, no separate code paths needed. See
+https://py.sdk.modelcontextprotocol.io/v2/advanced/middleware/.
+
+Known SDK limitation (verified against the installed mcp==2.0.0 source,
+mcp/server/context.py): `ServerRequestContext` - what middleware receives -
+does not publicly expose the transport's connection-level session id or a
+`connection` accessor (only the handler-facing `Context` class does, via a
+private `Connection` it doesn't share with middleware). We do not reach into
+that private attribute. As a result `session_id` on emitted events is only
+ever populated from the optional intent-capture value the calling agent
+supplies - it is `None` for calls where intent capture is off or the caller
+didn't pass one, even though the connection may well have a real session id.
+Track https://github.com/modelcontextprotocol/python-sdk for this being
+exposed to middleware in a future release.
+"""
+
+import inspect
+import json
+import time
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import replace
+from datetime import datetime, timezone
+from typing import Any
+
+from mcpsignals.buffer import EventBuffer
+from mcpsignals.error_kind import classify_error
+from mcpsignals.events import ToolCallEvent
+from mcpsignals.intent_capture import enabled_for, inject_schema, strip_injected
+from mcpsignals.redaction import RedactionConfig, redact_arguments
+from mcpsignals.sinks.base import Sink
+from mcpsignals.sinks.console import ConsoleSink
+
+ResolveIdentity = Callable[
+    [Any], tuple[str | None, str | None] | Awaitable[tuple[str | None, str | None]]
+]
+
+
+def _is_error_result(result: Any) -> bool:
+    # `call_next` for `tools/call` returns a plain dict (wire-shaped, camelCase
+    # keys) in mcp==2.0.0, not a CallToolResult instance - verified against the
+    # installed package. Handle both shapes so this survives either.
+    if isinstance(result, Mapping):
+        return bool(result.get("isError", result.get("is_error", False)))
+    return bool(getattr(result, "is_error", False))
+
+
+def _result_content(result: Any) -> Any:
+    if isinstance(result, Mapping):
+        return result.get("content")
+    return getattr(result, "content", None)
+
+
+def _content_to_text(content: Any) -> str | None:
+    if not content:
+        return None
+    parts = []
+    for block in content:
+        text = block.get("text") if isinstance(block, Mapping) else getattr(block, "text", None)
+        if text:
+            parts.append(text)
+    return "\n".join(parts) if parts else None
+
+
+def _serialize_for_bytes(value: Any) -> bytes:
+    if value is None:
+        return b""
+    dump = getattr(value, "model_dump_json", None)
+    if callable(dump):
+        return dump().encode()
+    return json.dumps(value, default=str).encode()
+
+
+def instrument(
+    server: Any,
+    *,
+    server_name: str,
+    server_version: str | None = None,
+    sinks: Sequence[Sink] | None = None,
+    capture_arguments: bool = False,
+    redaction: RedactionConfig | None = None,
+    intent_capture: bool = False,
+    intent_capture_tools: Mapping[str, bool] | None = None,
+    resolve_identity: ResolveIdentity | None = None,
+    buffer_size: int = 20,
+    flush_interval_s: float = 5.0,
+) -> Any:
+    """Wrap `server` (an `MCPServer` or a low-level `Server`) so every tool
+    call is recorded as a `tool_call` event, per schema/events.md. Appends
+    one middleware function; call this once, right after constructing your
+    server. Returns the same instance, unmodified otherwise.
+    """
+    active_sinks: list[Sink] = list(sinks) if sinks else [ConsoleSink()]
+    buffer = EventBuffer(active_sinks, buffer_size=buffer_size, flush_interval_s=flush_interval_s)
+
+    async def _mcpsignals_middleware(ctx, call_next):
+        if ctx.method == "tools/list":
+            result = await call_next(ctx)
+            if intent_capture or intent_capture_tools:
+                # `call_next` returns a wire-shaped dict here (camelCase keys),
+                # not a ListToolsResult/Tool instance - verified against the
+                # installed mcp==2.0.0 package. Handle both shapes defensively.
+                if isinstance(result, Mapping):
+                    for tool in result.get("tools") or []:
+                        name = tool.get("name")
+                        if enabled_for(
+                            name, global_enabled=intent_capture, overrides=intent_capture_tools
+                        ):
+                            tool["inputSchema"] = inject_schema(tool.get("inputSchema"))
+                else:
+                    for tool in getattr(result, "tools", None) or []:
+                        if enabled_for(
+                            tool.name, global_enabled=intent_capture, overrides=intent_capture_tools
+                        ):
+                            tool.input_schema = inject_schema(tool.input_schema)
+            return result
+
+        if ctx.method != "tools/call":
+            return await call_next(ctx)
+
+        params = ctx.params or {}
+        tool_name = params.get("name", "")
+        raw_arguments = params.get("arguments") or {}
+        request_bytes = len(json.dumps(raw_arguments, default=str).encode())
+
+        tool_intent_enabled = enabled_for(
+            tool_name, global_enabled=intent_capture, overrides=intent_capture_tools
+        )
+        if tool_intent_enabled:
+            clean_arguments, extracted = strip_injected(raw_arguments)
+            forwarded_params = dict(params)
+            forwarded_params["arguments"] = clean_arguments
+            forward_ctx = replace(ctx, params=forwarded_params)
+        else:
+            clean_arguments = raw_arguments
+            extracted = {"session_id": None, "agent_id": None, "intent": None}
+            forward_ctx = ctx
+
+        user_id: str | None = None
+        org_id: str | None = None
+        if resolve_identity is not None:
+            identity = resolve_identity(ctx)
+            if inspect.isawaitable(identity):
+                identity = await identity
+            if identity:
+                user_id, org_id = identity
+
+        client_name: str | None = None
+        client_version: str | None = None
+        client_params = getattr(ctx.session, "client_params", None)
+        client_info = getattr(client_params, "client_info", None) if client_params else None
+        if client_info is not None:
+            client_name = client_info.name
+            client_version = client_info.version
+
+        transport = "http" if getattr(ctx, "request", None) is not None else "stdio"
+
+        start = time.perf_counter()
+        error: BaseException | None = None
+        result = None
+        try:
+            result = await call_next(forward_ctx)
+            return result
+        except BaseException as exc:
+            error = exc
+            raise
+        finally:
+            duration_ms = int((time.perf_counter() - start) * 1000)
+            if error is not None:
+                success = False
+                error_message: str | None = str(error)[:2000]
+                response_bytes = 0
+            else:
+                success = not _is_error_result(result)
+                error_message = None if success else _content_to_text(_result_content(result))
+                if error_message:
+                    error_message = error_message[:2000]
+                response_bytes = len(_serialize_for_bytes(result))
+
+            arguments = redact_arguments(clean_arguments, redaction) if capture_arguments else None
+
+            event = ToolCallEvent(
+                # Not datetime.UTC: that alias is 3.11+, and requires-python
+                # allows 3.10. Ruff's UP017 would rewrite this, which is why
+                # ruff.toml pins target-version to py310.
+                ts=datetime.now(timezone.utc),
+                server_name=server_name,
+                server_version=server_version,
+                tool_name=tool_name,
+                session_id=extracted.get("session_id"),
+                agent_id=extracted.get("agent_id"),
+                client_name=client_name,
+                client_version=client_version,
+                user_id=user_id,
+                org_id=org_id,
+                duration_ms=duration_ms,
+                success=success,
+                error_kind=classify_error(error_message),
+                error_message=error_message,
+                request_bytes=request_bytes,
+                response_bytes=response_bytes,
+                arguments=arguments,
+                intent=extracted.get("intent"),
+                transport=transport,
+            )
+            await buffer.add(event)
+
+    server.middleware.append(_mcpsignals_middleware)
+    return server

mcpsignals/intent_capture.py

@@ -0,0 +1,62 @@
+"""Intent capture: optionally injects session_id/agent_id/intent into the
+JSON schema a tool advertises, and strips those same keys back out of the
+arguments before the user's tool handler runs, so the handler receives
+exactly the arguments it would have received without the library.
+
+Off by default. See prompt spec / README for the documented tradeoff: this
+adds tokens to every advertised tool schema and asks the calling model to do
+extra work it may ignore or fabricate.
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+INJECTED_KEYS = ("session_id", "agent_id", "intent")
+
+_INJECTED_PROPERTIES = {
+    "session_id": {
+        "type": "string",
+        "description": "Opaque id grouping this call with other calls in the same task, if known.",
+    },
+    "agent_id": {
+        "type": "string",
+        "description": "Opaque id identifying which agent is making this call, if multiple agents share a session.",
+    },
+    "intent": {
+        "type": "string",
+        "description": "Why you are calling this tool.",
+    },
+}
+
+
+def enabled_for(
+    tool_name: str, *, global_enabled: bool, overrides: Mapping[str, bool] | None
+) -> bool:
+    if overrides is not None and tool_name in overrides:
+        return overrides[tool_name]
+    return global_enabled
+
+
+def inject_schema(input_schema: dict[str, Any] | None) -> dict[str, Any]:
+    """Return a new JSON schema with the injected properties added. Never
+    mutates the input schema in place.
+    """
+    schema = dict(input_schema) if input_schema else {"type": "object"}
+    properties = dict(schema.get("properties") or {})
+    for key, spec in _INJECTED_PROPERTIES.items():
+        properties.setdefault(key, spec)
+    schema["properties"] = properties
+    return schema
+
+
+def strip_injected(
+    arguments: Mapping[str, Any] | None,
+) -> tuple[dict[str, Any], dict[str, str | None]]:
+    """Split raw arguments into (clean_arguments, extracted) where
+    `extracted` holds session_id/agent_id/intent (None if absent) and
+    `clean_arguments` has those three keys removed - exactly what the
+    handler would have received without the library.
+    """
+    args = dict(arguments) if arguments else {}
+    extracted = {key: args.pop(key, None) for key in INJECTED_KEYS}
+    return args, extracted

mcpsignals/redaction.py

@@ -0,0 +1,52 @@
+"""Argument redaction. Only ever invoked when argument capture is explicitly
+enabled. Default behavior (capture on, no config): record keys and value
+types only, never values. See the redaction section of the root README
+before changing this file - it is the single most safety-critical part of
+the library.
+"""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+
+def _type_marker(value: Any) -> dict[str, str]:
+    if isinstance(value, bool):
+        type_name = "bool"
+    elif isinstance(value, list):
+        type_name = "array"
+    elif value is None:
+        type_name = "null"
+    else:
+        type_name = type(value).__name__
+    return {"__type": type_name}
+
+
+@dataclass
+class RedactionConfig:
+    allow: list[str] | None = None
+    deny: list[str] | None = None
+    redactor: Callable[[Mapping[str, Any]], Mapping[str, Any]] | None = None
+
+
+def redact_arguments(args: Mapping[str, Any], config: RedactionConfig | None) -> dict[str, Any]:
+    if config is not None and config.redactor is not None:
+        return dict(config.redactor(args))
+
+    # Fail-safe by design: only `allow` ever reveals a real value. A bare
+    # `deny` with no `allow` does NOT imply "reveal everything else" - it
+    # would be a footgun if denying one sensitive key silently leaked every
+    # other field the caller didn't think to deny.
+    allow = set(config.allow) if config is not None and config.allow else None
+    deny = set(config.deny) if config is not None and config.deny else set()
+
+    result: dict[str, Any] = {}
+    for key, value in args.items():
+        if key in deny:
+            result[key] = _type_marker(value)
+        elif allow is not None:
+            result[key] = value if key in allow else _type_marker(value)
+        else:
+            # No allow/deny configured at all: keys and value types only, never values.
+            result[key] = _type_marker(value)
+    return result

mcpsignals/sinks/__init__.py

@@ -0,0 +1,25 @@
+from mcpsignals.sinks.base import Sink
+from mcpsignals.sinks.console import ConsoleSink
+
+__all__ = ["Sink", "ConsoleSink"]
+
+try:
+    from mcpsignals.sinks.postgres import PostgresSink  # noqa: F401
+
+    __all__.append("PostgresSink")
+except ImportError:
+    pass
+
+try:
+    from mcpsignals.sinks.bigquery import BigQuerySink  # noqa: F401
+
+    __all__.append("BigQuerySink")
+except ImportError:
+    pass
+
+try:
+    from mcpsignals.sinks.otlp import OtlpSink  # noqa: F401
+
+    __all__.append("OtlpSink")
+except ImportError:
+    pass

mcpsignals/sinks/base.py

@@ -0,0 +1,13 @@
+from typing import Protocol, runtime_checkable
+
+from mcpsignals.events import SessionSummaryEvent, ToolCallEvent
+
+
+@runtime_checkable
+class Sink(Protocol):
+    """A sink accepts a batch of events, writes them, and reports failure by
+    raising. It does nothing else - no retries, no local queueing beyond
+    what EventBuffer already does upstream.
+    """
+
+    async def write(self, events: list[ToolCallEvent | SessionSummaryEvent]) -> None: ...

mcpsignals/sinks/bigquery.py

@@ -0,0 +1,47 @@
+"""BigQuery sink. Requires the `bigquery` extra (google-cloud-bigquery).
+Credentials come from Application Default Credentials, same as the client
+library's own defaults - never an invented config file. The client library
+is synchronous, so writes run in a thread via asyncio.to_thread and never
+block the event loop.
+"""
+
+import asyncio
+import dataclasses
+
+from mcpsignals.events import SessionSummaryEvent, ToolCallEvent
+
+
+class BigQuerySink:
+    def __init__(self, dataset: str, project: str | None = None, client=None):
+        self._dataset = dataset
+        self._project = project
+        self._client = client
+
+    def _get_client(self):
+        if self._client is None:
+            from google.cloud import bigquery  # local import: don't require the SDK unless used
+
+            self._client = bigquery.Client(project=self._project)
+        return self._client
+
+    def _row(self, event) -> dict:
+        row = dataclasses.asdict(event)
+        row.pop("event_type", None)
+        row["ts"] = event.ts.isoformat() if event.ts else None
+        return row
+
+    def _insert_sync(self, table: str, rows: list[dict]) -> None:
+        client = self._get_client()
+        table_ref = f"{self._dataset}.{table}"
+        errors = client.insert_rows_json(table_ref, rows)
+        if errors:
+            raise RuntimeError(f"bigquery insert errors for {table_ref}: {errors}")
+
+    async def write(self, events: list[ToolCallEvent | SessionSummaryEvent]) -> None:
+        tool_calls = [self._row(e) for e in events if isinstance(e, ToolCallEvent)]
+        summaries = [self._row(e) for e in events if isinstance(e, SessionSummaryEvent)]
+
+        if tool_calls:
+            await asyncio.to_thread(self._insert_sync, "tool_call", tool_calls)
+        if summaries:
+            await asyncio.to_thread(self._insert_sync, "session_summary", summaries)

mcpsignals/sinks/console.py

@@ -0,0 +1,17 @@
+import dataclasses
+import json
+import sys
+
+from mcpsignals.events import SessionSummaryEvent, ToolCallEvent
+
+
+class ConsoleSink:
+    """The default sink. Zero configuration, writes one JSON line per event
+    to stdout so the library is useful without setting up a warehouse.
+    """
+
+    async def write(self, events: list[ToolCallEvent | SessionSummaryEvent]) -> None:
+        for event in events:
+            payload = dataclasses.asdict(event)
+            payload["ts"] = event.ts.isoformat() if event.ts else None
+            print(json.dumps(payload, default=str), file=sys.stdout, flush=True)

mcpsignals/sinks/otlp.py

@@ -0,0 +1,86 @@
+"""OTLP sink. Requires the `otlp` extra (opentelemetry-api only, not an SDK
+or exporter - relies on whatever global TracerProvider the host app already
+configured, the standard "zero-code" OTel pattern).
+
+Field mapping verified against the live OpenTelemetry GenAI semantic
+conventions for MCP (open-telemetry/semantic-conventions-genai,
+docs/gen-ai/mcp.md) as of this writing. Everything in that document is
+Development/Experimental status, not Stable, except where noted below.
+Where our schema has no equivalent convention, we use a custom
+`mcpsignals.*` attribute rather than force a bad fit (see `transport`).
+"""
+
+import json
+
+from mcpsignals.events import SessionSummaryEvent, ToolCallEvent
+
+
+class OtlpSink:
+    def __init__(self, tracer=None):
+        if tracer is None:
+            from opentelemetry import trace  # local import: don't require the API unless used
+
+            tracer = trace.get_tracer("mcpsignals")
+        self._tracer = tracer
+
+    async def write(self, events: list[ToolCallEvent | SessionSummaryEvent]) -> None:
+        from opentelemetry.trace import SpanKind, Status, StatusCode
+
+        for event in events:
+            if not isinstance(event, ToolCallEvent):
+                continue  # session_summary has no OTel span mapping; warehouse sinks carry it
+
+            attributes = {
+                "gen_ai.operation.name": "execute_tool",
+                "gen_ai.tool.name": event.tool_name,
+                "mcpsignals.server.name": event.server_name,
+                "mcpsignals.request.bytes": event.request_bytes,
+                "mcpsignals.response.bytes": event.response_bytes,
+            }
+            if event.session_id:
+                attributes["mcp.session.id"] = event.session_id
+            if event.server_version:
+                attributes["mcpsignals.server.version"] = event.server_version
+            if event.client_name:
+                attributes["mcpsignals.client.name"] = event.client_name
+            if event.client_version:
+                attributes["mcpsignals.client.version"] = event.client_version
+            if event.agent_id:
+                attributes["mcpsignals.agent.id"] = event.agent_id
+            if event.user_id:
+                # enduser.id is Stable in general OTel semconv, but is
+                # security-sensitive/opt-in - only set when the host supplied one.
+                attributes["enduser.id"] = event.user_id
+            if event.org_id:
+                attributes["mcpsignals.org.id"] = event.org_id
+            if event.transport:
+                # Deliberately NOT network.transport: that attribute's vocabulary
+                # (tcp/udp/quic/pipe/unix) does not fit MCP's stdio/http.
+                attributes["mcpsignals.transport"] = event.transport
+            if event.intent:
+                attributes["mcpsignals.intent"] = event.intent
+            if event.error_kind:
+                attributes["mcpsignals.error.kind"] = event.error_kind
+            if event.arguments is not None:
+                attributes["gen_ai.tool.call.arguments"] = json.dumps(event.arguments)
+
+            # Events are written in batches, potentially long after the call
+            # happened, so the span's start/end must be stamped from the
+            # event's own ts/duration_ms rather than "now" - otherwise every
+            # span would report the buffer's flush time as its duration.
+            start_ns = int(event.ts.timestamp() * 1_000_000_000) if event.ts else None
+            end_ns = start_ns + event.duration_ms * 1_000_000 if start_ns is not None else None
+
+            span = self._tracer.start_span(
+                f"tools/call {event.tool_name}",
+                kind=SpanKind.SERVER,
+                attributes=attributes,
+                start_time=start_ns,
+            )
+            if event.success:
+                span.set_status(Status(StatusCode.OK))
+            else:
+                span.set_status(Status(StatusCode.ERROR, description=event.error_message))
+                if event.error_message:
+                    span.record_exception(Exception(event.error_message))
+            span.end(end_time=end_ns)

mcpsignals/sinks/postgres.py

@@ -0,0 +1,115 @@
+"""Postgres sink. Requires the `postgres` extra (asyncpg). Table DDL lives in
+schema/events.md. Connection info comes from asyncpg's own env var defaults
+(PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE) or an explicit dsn/pool -
+never an invented config file.
+"""
+
+from mcpsignals.events import SessionSummaryEvent, ToolCallEvent
+
+_TOOL_CALL_COLUMNS = [
+    "ts",
+    "server_name",
+    "server_version",
+    "tool_name",
+    "session_id",
+    "agent_id",
+    "client_name",
+    "client_version",
+    "user_id",
+    "org_id",
+    "duration_ms",
+    "success",
+    "error_kind",
+    "error_message",
+    "request_bytes",
+    "response_bytes",
+    "arguments",
+    "intent",
+    "transport",
+]
+
+_SESSION_SUMMARY_COLUMNS = [
+    "ts",
+    "session_id",
+    "server_name",
+    "server_version",
+    "user_id",
+    "org_id",
+    "call_count",
+    "distinct_tools_used",
+    "wall_duration_ms",
+    "error_count",
+]
+
+
+class PostgresSink:
+    def __init__(self, dsn: str | None = None, pool=None):
+        """Provide either `dsn` (asyncpg will connect lazily) or an existing
+        `pool` (an asyncpg.Pool you already manage). If neither is given,
+        asyncpg's own environment-variable defaults apply.
+        """
+        self._dsn = dsn
+        self._pool = pool
+
+    async def _get_pool(self):
+        import asyncpg  # local import: don't require asyncpg unless this sink is used
+
+        if self._pool is None:
+            self._pool = await asyncpg.create_pool(dsn=self._dsn)
+        return self._pool
+
+    async def write(self, events: list[ToolCallEvent | SessionSummaryEvent]) -> None:
+        import json as _json
+
+        tool_calls = [e for e in events if isinstance(e, ToolCallEvent)]
+        summaries = [e for e in events if isinstance(e, SessionSummaryEvent)]
+
+        pool = await self._get_pool()
+        async with pool.acquire() as conn:
+            if tool_calls:
+                rows = [
+                    (
+                        e.ts,
+                        e.server_name,
+                        e.server_version,
+                        e.tool_name,
+                        e.session_id,
+                        e.agent_id,
+                        e.client_name,
+                        e.client_version,
+                        e.user_id,
+                        e.org_id,
+                        e.duration_ms,
+                        e.success,
+                        e.error_kind,
+                        e.error_message,
+                        e.request_bytes,
+                        e.response_bytes,
+                        _json.dumps(e.arguments) if e.arguments is not None else None,
+                        e.intent,
+                        e.transport,
+                    )
+                    for e in tool_calls
+                ]
+                await conn.copy_records_to_table(
+                    "mcpsignals_tool_call", records=rows, columns=_TOOL_CALL_COLUMNS
+                )
+            if summaries:
+                rows = [
+                    (
+                        e.ts,
+                        e.session_id,
+                        e.server_name,
+                        e.server_version,
+                        e.user_id,
+                        e.org_id,
+                        e.call_count,
+                        e.distinct_tools_used,
+                        e.wall_duration_ms,
+                        e.error_count,
+                    )
+                    for e in summaries
+                ]
+                await conn.copy_records_to_table(
+                    "mcpsignals_session_summary", records=rows, columns=_SESSION_SUMMARY_COLUMNS
+                )

mcpsignals-1.0.1.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: mcpsignals
+Version: 1.0.1
+Summary: Drop-in instrumentation for MCP servers. Writes tool-call events to a database you own.
+Project-URL: Homepage, https://github.com/zentered-studios/mcpsignals#readme
+Project-URL: Repository, https://github.com/zentered-studios/mcpsignals
+Project-URL: Issues, https://github.com/zentered-studios/mcpsignals/issues
+Author: mcpsignals contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: mcp>=2.0.0
+Provides-Extra: bigquery
+Requires-Dist: google-cloud-bigquery>=3.11; extra == 'bigquery'
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otlp'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# mcpsignals (Python)
+
+Drop-in instrumentation for MCP servers. Wrap your server, point it at a
+sink, and it records what agents did with your tools into a database you
+own - no hosted service, no account.
+
+Requires **Python 3.10 or newer**. Targets the v2 `mcp` SDK (`MCPServer` /
+low-level `Server`, `mcp>=2.0.0`).
+
+## Install
+
+```bash
+pip install mcpsignals
+# with a warehouse sink:
+pip install "mcpsignals[postgres]"   # or [bigquery], [otlp]
+```
+
+## Usage
+
+```python
+from mcp.server.mcpserver import MCPServer
+from mcpsignals import instrument
+
+server = MCPServer("my-server")
+instrument(server, server_name="my-server", server_version="1.0.0")
+
+
+@server.tool()
+def search(query: str) -> str:
+    """Search something."""
+    return f"results for {query}"
+```
+
+Call `instrument()` any time before the server starts handling requests. It
+appends to `server.middleware`, and that chain is rebuilt from the live list
+on every request, so calling it before or after your `@server.tool()`
+definitions makes no difference. The Node.js package differs here: it wraps
+`registerTool`, so it has to run before any tool is registered.
+
+With no sink configured it writes JSON lines to stdout. To write to your
+own warehouse instead:
+
+```python
+from mcpsignals import instrument
+from mcpsignals.sinks import PostgresSink
+
+instrument(server, server_name="my-server", sinks=[PostgresSink(dsn="postgresql://...")])
+```
+
+## Argument capture and redaction
+
+Off by default: no tool arguments are recorded unless you opt in with
+`capture_arguments=True`. Even then, by default only argument **keys and
+value types** are recorded, never values. See the root README's redaction
+section before enabling this in anything handling real user data.
+
+## Known limitation: `session_id`
+
+`mcp` 2.0.0's middleware-facing `ServerRequestContext` does not publicly
+expose the transport's connection-level session id (only the
+handler-facing `Context` class does, via a private accessor middleware
+doesn't have). `session_id` on emitted events is therefore only ever
+populated when intent capture is enabled and the calling agent supplies
+one - not from the underlying transport connection. See `instrument.py`
+for details; this will be revisited if/when upstream exposes it to
+middleware.
+
+## Full docs
+
+See the [root README](../../README.md) for the redaction model, the sink
+comparison, and intent capture, and [`schema/events.md`](../../schema/events.md)
+for the event field reference.

mcpsignals-1.0.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+mcpsignals/__init__.py,sha256=UUlteWZUvribqzzyjqN-o_t_wwSxuJvCZyOqjnLLUhY,263
+mcpsignals/buffer.py,sha256=pR-jXkSIgivK43LSo6utoBRDLuGdeFQvVfKzjrwvm_w,3533
+mcpsignals/error_kind.py,sha256=hdDDIcR1qdHnvByNbsgVsLRJ-N-6UwDmiEGQyqb3iU4,927
+mcpsignals/events.py,sha256=goRlcGMUjF2kap6RCEnpqT5ULE-7wh6KV41F2c6ZF6A,1382
+mcpsignals/instrument.py,sha256=qyUEj1rct1PdhfRuZLIZJWWlYVlE5wBG3mMMfJS14ts,8847
+mcpsignals/intent_capture.py,sha256=FQSGW_cQoz_Zic10Ctndm0fCvGAK4Zjl1mULTFuQPY0,2277
+mcpsignals/redaction.py,sha256=NZD__B3zz6Mz1JldA5GyqYQvWUohVgZ3ERLJ_1borJ8,1947
+mcpsignals/sinks/__init__.py,sha256=neQVvVCFZWKytGMf3uzwAXmLxsXksx7WQLf4iMA_Q2I,531
+mcpsignals/sinks/base.py,sha256=7JjZNe0aoi4v6cbMDyIt_iAHVRBvDTsdIjHBwMSTLa0,449
+mcpsignals/sinks/bigquery.py,sha256=E6GaL7d0M1xOOZFa01dVRqilHvW9TYXo2tA_eoAFeQY,1847
+mcpsignals/sinks/console.py,sha256=926pA2B9CT_j7qAqVhXbikesjRhqknf5Do5biD9hXYY,600
+mcpsignals/sinks/otlp.py,sha256=mVr5Y3DWK_aML7R1RO1DQcrCq2u49nEvILvxqoFTwLs,4140
+mcpsignals/sinks/postgres.py,sha256=a5b_1SArzNkWrTFeVv_j-4qFhzYsGYOblItseAusoI0,3632
+mcpsignals-1.0.1.dist-info/METADATA,sha256=FvnK02msnXcdJFljEI9oK0mN5Zon08AbLGKSOmaP-Ck,3547
+mcpsignals-1.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mcpsignals-1.0.1.dist-info/licenses/LICENSE,sha256=l_eNViACILOiQuQ8PWYLhzbtpxPj7-SggB-HmydLiuQ,1080
+mcpsignals-1.0.1.dist-info/RECORD,,

mcpsignals-1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcpsignals-1.0.1.dist-info/licenses/LICENSE

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