mcpsignals 1.0.1__tar.gz

mcpsignals-1.0.1/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.venv/
+.env
+.claude/worktrees

mcpsignals-1.0.1/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.

mcpsignals-1.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,72 @@
+# 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/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcpsignals"
+# Placeholder, and deliberately not kept in sync by hand. semantic-release
+# stamps the real version in at release time and never commits it back, exactly
+# as packages/node/package.json is left at 0.1.0. Do not read this as the
+# published version - check PyPI or the git tags for that.
+version = "1.0.1"
+description = "Drop-in instrumentation for MCP servers. Writes tool-call events to a database you own."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "mcpsignals contributors" }]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = ["mcp>=2.0.0"]
+
+[project.optional-dependencies]
+postgres = ["asyncpg>=0.29"]
+bigquery = ["google-cloud-bigquery>=3.11"]
+otlp = ["opentelemetry-api>=1.20"]
+
+[project.urls]
+Homepage = "https://github.com/zentered-studios/mcpsignals#readme"
+Repository = "https://github.com/zentered-studios/mcpsignals"
+Issues = "https://github.com/zentered-studios/mcpsignals/issues"
+
+# Not an optional-dependencies extra: dev tooling should not be installable by
+# consumers as `pip install mcpsignals[dev]`. PEP 735 groups stay out of the
+# published metadata entirely.
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24", # required by asyncio_mode = "auto" below
+    "ruff>=0.15,<0.16",     # single source of truth for the version CI uses
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcpsignals"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

mcpsignals-1.0.1/src/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-1.0.1/src/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-1.0.1/src/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-1.0.1/src/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-1.0.1/src/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