raindrop-mcp 0.0.1__py3-none-any.whl

raindrop_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""Raindrop instrumentation for Python MCP servers."""
+
+from .wrapper import INTENT, TURN_ID, McpCallContext, McpClientInfo, RaindropMcp, create_raindrop_mcp
+
+__version__ = "0.0.1"
+__all__ = ["RaindropMcp", "create_raindrop_mcp", "McpCallContext", "McpClientInfo", "TURN_ID", "INTENT"]

raindrop_mcp/wrapper.py

@@ -0,0 +1,1185 @@
+"""Raindrop instrumentation for Python MCP servers.
+
+Works with ``mcp`` 1.x (``FastMCP``) and ``mcp`` 2.x (``MCPServer``). The one
+seam both share is the server's ``ToolManager``: ``add_tool`` registers every
+tool and ``call_tool`` runs every call, so wrapping those two methods
+instruments any server without touching its tools.
+
+    from raindrop_mcp import RaindropMcp
+
+    raindrop = RaindropMcp(api_key=os.environ["RAINDROP_API_KEY"])
+    server = raindrop.wrap(FastMCP("my-server"))
+
+Every tool call becomes a tool span on an ``mcp_activity`` event. MCP has no
+turn boundary, so with ``turn_tracking`` (the default) every tool advertises an
+optional ``_turn_id`` that is appended to each result; the model copies it on
+its next call and the calls of one prompt land on one event. Every tool also
+advertises an optional ``_intent`` the model fills with what the user wants on
+the first call of a prompt, and the calling MCP client is recorded on every call.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import hashlib
+import inspect
+import logging
+import re
+import time
+import uuid
+import warnings
+from dataclasses import dataclass, replace
+from datetime import datetime, timezone
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Dict,
+    List,
+    Literal,
+    Mapping,
+    Optional,
+    Set,
+    Tuple,
+    Union,
+)
+
+import raindrop.analytics as raindrop
+from raindrop import Raindrop
+
+logger = logging.getLogger("raindrop_mcp")
+
+TURN_ID = "_turn_id"
+"""The optional argument every tool advertises and every result echoes."""
+INTENT = "_intent"
+"""What the user asked for, in the model's words; filled on the first call of a prompt."""
+
+_DESCRIPTIONS: Dict[str, str] = {
+    TURN_ID: (
+        "Copy from the most recent tool result in this turn. Omit on the first tool "
+        "call of a new user prompt; never reuse an id from an earlier prompt."
+    ),
+    INTENT: (
+        "One sentence on what the user is trying to accomplish. Fill in on the first "
+        "tool call of a new user prompt; omit on follow-up calls."
+    ),
+}
+_TURN_ID_PATTERN = re.compile(r"^[a-f0-9]{16}$")
+_INTENT_MAX_CHARS = 1_000
+_AI_INVOCATION_META = "io.modelcontextprotocol/aiInvocation"
+_CLIENT_INFO_META = "io.modelcontextprotocol/clientInfo"
+_SESSION_ID_HEADER = "mcp-session-id"
+# Serverless hosts freeze after the response, so a slow ship is dropped rather than awaited forever.
+_SHIP_DEADLINE_S = 5.0
+_DEFAULT_MAX_TEXT_FIELD_CHARS = 1_000_000
+_REDACTED = "[REDACTED]"
+_WRAPPED_ATTR = "_raindrop_mcp_wrapped"
+_MAX_META_EVENTS = 10_000
+# Same list as @raindrop-ai/core's redactSecretsInObject, matched on lowercased names without -_. separators.
+_SECRET_KEY_NAMES = frozenset(
+    {
+        "apikey", "apisecret", "apitoken", "secretaccesskey", "sessiontoken",
+        "privatekey", "privatekeyid", "clientsecret", "accesstoken", "refreshtoken",
+        "oauthtoken", "bearertoken", "authorization", "password", "passphrase",
+    }
+)
+
+
+@dataclass
+class McpClientInfo:
+    """The MCP client (``clientInfo``), e.g. ``name="claude-code", version="2.1.0"``."""
+
+    name: str
+    version: Optional[str] = None
+
+
+@dataclass
+class McpCallContext:
+    """What the server handed the tool, passed to the ``user_id`` / ``convo_id`` / ``properties`` callables."""
+
+    tool_name: str
+    args: Dict[str, Any]
+    """Tool arguments as the tool received them, without the injected fields."""
+    session_id: Optional[str]
+    """The ``mcp-session-id`` of the request, when the transport has one."""
+    context: Any
+    """The SDK's per-request ``Context`` (``None`` when the server passed none)."""
+    client: Optional[McpClientInfo] = None
+    """The MCP client that made the call, when known."""
+    intent: Optional[str] = None
+    """What the model said the user wants, when it filled ``_intent`` on this call."""
+
+
+Resolver = Callable[[McpCallContext], Optional[str]]
+PropertiesResolver = Callable[[McpCallContext], Optional[Dict[str, Any]]]
+
+
+@dataclass
+class _Turn:
+    id: str
+    is_new: bool
+    """No usable ``_turn_id`` was echoed, so this call opens a new event."""
+    source: Literal["echo", "meta"]
+    """``meta``: the client sent the id per request, so there is nothing to echo."""
+    args: Dict[str, Any]
+    """The arguments without the injected fields, as the tool expects them."""
+    intent: Optional[str] = None
+    """What the model said the user wants, when it filled ``_intent`` on this call."""
+
+
+def _new_turn(raw_args: Any) -> _Turn:
+    args = dict(raw_args) if isinstance(raw_args, Mapping) else {}
+    return _Turn(id=uuid.uuid4().hex[:16], is_new=True, source="echo", args=args)
+
+
+def _intent_of(value: Any) -> Optional[str]:
+    if not isinstance(value, str):
+        return None
+    return value.strip()[:_INTENT_MAX_CHARS] or None
+
+
+def _split_turn(raw_args: Any, fields: Tuple[str, ...] = (TURN_ID,)) -> _Turn:
+    """Splits the injected fields off the arguments; a missing or malformed ``_turn_id`` means a new turn."""
+    args = dict(raw_args) if isinstance(raw_args, Mapping) else {}
+    values = {field: args.pop(field) for field in fields if field in args}
+    echoed = values.get(TURN_ID)
+    if isinstance(echoed, str) and _TURN_ID_PATTERN.match(echoed):
+        turn = _Turn(id=echoed, is_new=False, source="echo", args=args)
+    else:
+        turn = _new_turn(args)
+    turn.intent = _intent_of(values.get(INTENT))
+    return turn
+
+
+def _text_block(text: str) -> Any:
+    from mcp.types import TextContent
+
+    return TextContent(type="text", text=text)
+
+
+def _echo_turn_id(result: Any, turn_id: str) -> Any:
+    """Appends the turn id to a tool result so the model echoes it on its next call."""
+    echo = _text_block(f"{TURN_ID}: {turn_id}")
+    content = getattr(result, "content", None)
+    if isinstance(content, list) and not isinstance(result, (list, tuple)):
+        # 2.x: a CallToolResult (also what a 1.x tool returns when it builds its own).
+        result.content = [*content, echo]
+        return result
+    if isinstance(result, tuple) and len(result) == 2 and isinstance(result[0], (list, tuple)):
+        # 1.x structured output: (unstructured content, structured content).
+        return ([*result[0], echo], result[1])
+    if isinstance(result, list):
+        # 1.x unstructured content.
+        return [*result, echo]
+    return result
+
+
+def _error_result(message: str, turn_id: str, *, standalone: bool = False) -> Any:
+    """The ``isError`` result the SDK would have built from the exception, plus the echo."""
+    content = [_text_block(message), _text_block(f"{TURN_ID}: {turn_id}")]
+    if standalone:
+        if not _standalone_has_error_results():
+            raise TypeError("this fastmcp has no error results; the exception propagates instead")
+        return _standalone_tool_result_cls()(content=content, is_error=True)
+    from mcp.types import CallToolResult
+
+    error_field = "is_error" if "is_error" in CallToolResult.model_fields else "isError"
+    return CallToolResult(content=content, **{error_field: True})
+
+
+def _standalone_tool_result_cls() -> Any:
+    """Standalone fastmcp's ``ToolResult`` (moved between its 2.x and 3.x releases)."""
+    try:
+        from fastmcp.tools import ToolResult  # type: ignore[import-not-found]
+    except ImportError:
+        from fastmcp.tools.tool import ToolResult  # type: ignore[import-not-found]
+    return ToolResult
+
+
+def _standalone_has_error_results() -> bool:
+    """fastmcp 2.x's ``ToolResult`` can't carry ``is_error``; a failing tool there propagates instead of echoing."""
+    try:
+        return "is_error" in inspect.signature(_standalone_tool_result_cls()).parameters
+    except Exception:
+        return False
+
+
+def _protocol_errors() -> Tuple[type, ...]:
+    """JSON-RPC level errors the server must answer as protocol errors, never as tool results."""
+    errors: List[type] = []
+    try:
+        from mcp.shared import exceptions as mcp_exceptions
+
+        for name in ("MCPError", "McpError"):
+            error = getattr(mcp_exceptions, name, None)
+            if inspect.isclass(error):
+                errors.append(error)
+    except Exception:
+        pass
+    try:
+        from fastmcp.exceptions import NotFoundError  # type: ignore[import-not-found]
+
+        errors.append(NotFoundError)  # standalone fastmcp: unknown tool name
+    except Exception:
+        pass
+    return tuple(errors)
+
+
+def _error_message(error: BaseException) -> str:
+    message = str(error) or type(error).__name__
+    cause = error.__cause__
+    # 2.x hides a crashed tool's text from the client; keep it for telemetry.
+    if cause is not None and str(cause) and str(cause) not in message:
+        message = f"{message}: {cause}"
+    return message
+
+
+def _result_parts(result: Any) -> Tuple[List[Any], Any, bool]:
+    """``(content blocks, structured content, is_error)`` for every result shape the SDKs produce."""
+    if isinstance(result, tuple) and len(result) == 2 and isinstance(result[0], (list, tuple)):
+        return list(result[0]), result[1], False
+    if isinstance(result, list):
+        return result, None, False
+    content = getattr(result, "content", None)
+    if isinstance(content, list):
+        structured = getattr(result, "structured_content", None)
+        if structured is None:
+            structured = getattr(result, "structuredContent", None)
+        is_error = getattr(result, "is_error", None)
+        if is_error is None:
+            is_error = getattr(result, "isError", None)
+        return content, structured, is_error is True
+    if isinstance(result, Mapping):
+        return [], result, False
+    return [], result, False
+
+
+def _is_error_result(result: Any) -> bool:
+    try:
+        return _result_parts(result)[2]
+    except Exception:
+        return False
+
+
+def _tool_result_text(result: Any, limit: int) -> str:
+    """Text a model would read from a tool result; binary blocks become stubs, no text falls back to structured content."""
+    content, structured, _ = _result_parts(result)
+    parts: List[str] = []
+    has_text = False
+    for block in content:
+        block_type = getattr(block, "type", None)
+        if block_type is None and isinstance(block, Mapping):
+            block_type = block.get("type")
+        if not isinstance(block_type, str):
+            continue
+        text = getattr(block, "text", None)
+        if text is None and isinstance(block, Mapping):
+            text = block.get("text")
+        if block_type == "text" and isinstance(text, str):
+            has_text = True
+            parts.append(text)
+        else:
+            parts.append(f"[{block_type}]")
+    if not has_text and structured is not None:
+        return _dumps(structured, limit)
+    return "\n".join(parts)[:limit]
+
+
+def _dumps(value: Any, limit: int) -> str:
+    try:
+        import json
+
+        return json.dumps(value, default=str)[:limit]
+    except Exception:
+        try:
+            return str(value)[:limit]
+        except Exception:
+            return "[unserializable]"
+
+
+def _normalize_key(name: str) -> str:
+    return re.sub(r"[-_.]", "", name.lower())
+
+
+def _redact_secrets(value: Any, budget: List[int], limit: int, depth: int = 0) -> Any:
+    """Replaces values under credential-looking keys and caps string leaves.
+
+    Bounded so a huge payload costs the budget, not the payload; whatever the budget
+    cannot visit is dropped rather than forwarded unredacted.
+    """
+    budget[0] -= 1
+    if budget[0] < 0 or depth > 16:
+        return "[truncated]"
+    if isinstance(value, Mapping):
+        return {
+            str(key): (
+                _REDACTED
+                if _normalize_key(str(key)) in _SECRET_KEY_NAMES
+                else _redact_secrets(item, budget, limit, depth + 1)
+            )
+            for key, item in value.items()
+        }
+    if isinstance(value, (list, tuple)):
+        return [_redact_secrets(item, budget, limit, depth + 1) for item in value]
+    if isinstance(value, str) and len(value) > limit:
+        return value[:limit]
+    return value
+
+
+def _headers_of(ctx: Any) -> Optional[Mapping[str, Any]]:
+    try:
+        headers = getattr(ctx, "headers", None)
+        if headers is None:
+            request_context = getattr(ctx, "request_context", None)
+            headers = getattr(getattr(request_context, "request", None), "headers", None)
+        return headers if isinstance(headers, Mapping) else None
+    except Exception:
+        return None
+
+
+def _header(ctx: Any, name: str) -> Optional[str]:
+    headers = _headers_of(ctx)
+    if headers is None:
+        return None
+    try:
+        value = headers.get(name)
+        if value is None:
+            for key, candidate in headers.items():
+                if isinstance(key, str) and key.lower() == name:
+                    value = candidate
+                    break
+        return value if isinstance(value, str) else None
+    except Exception:
+        return None
+
+
+def _session_id_of(ctx: Any) -> Optional[str]:
+    session_id = _header(ctx, _SESSION_ID_HEADER)
+    if session_id is None and _is_standalone_fastmcp(ctx):
+        # Standalone fastmcp keeps its own per-connection id on the Context (stdio has no header);
+        # the property raises outside a client request (server-side call_tool).
+        try:
+            session_id = ctx.session_id
+        except Exception:
+            session_id = None
+    if not isinstance(session_id, str):
+        return None
+    session_id = session_id.strip()[:128]
+    return session_id or None
+
+
+def _access_token() -> Any:
+    try:
+        from mcp.server.auth.middleware.auth_context import get_access_token
+
+        return get_access_token()
+    except Exception:
+        return None
+
+
+def _bearer_token_of(ctx: Any, access_token: Any) -> Optional[str]:
+    token = getattr(access_token, "token", None)
+    if isinstance(token, str) and token:
+        return token
+    header = _header(ctx, "authorization")
+    if header is None:
+        return None
+    match = re.match(r"^Bearer\s+(.+)$", header, re.IGNORECASE)
+    return match.group(1).strip() if match else None
+
+
+def _default_user_id(ctx: Any) -> str:
+    """OAuth subject, else a hash of the bearer credential (never the raw token), else the transport session, else anonymous."""
+    access_token = _access_token()
+    subject = getattr(access_token, "subject", None)
+    if isinstance(subject, str) and subject:
+        return subject
+    token = _bearer_token_of(ctx, access_token)
+    if token:
+        return f"token:{hashlib.sha256(token.encode()).hexdigest()[:32]}"
+    session_id = _session_id_of(ctx)
+    return f"session:{session_id}" if session_id else "anonymous"
+
+
+def _meta_of(ctx: Any) -> Any:
+    meta = getattr(ctx, "meta", None)
+    if meta is None:
+        request_context = getattr(ctx, "request_context", None)
+        meta = getattr(request_context, "meta", None)
+    return meta
+
+
+def _meta_turn_of(ctx: Any, args: Dict[str, Any]) -> Optional[_Turn]:
+    """Turn ids some clients already send per request (SEP-2817); nothing to echo when present."""
+    try:
+        meta = _meta_of(ctx)
+        if meta is None:
+            return None
+        if isinstance(meta, Mapping):
+            invocation = meta.get(_AI_INVOCATION_META)
+        else:
+            extra = getattr(meta, "model_extra", None) or {}
+            invocation = extra.get(_AI_INVOCATION_META, getattr(meta, _AI_INVOCATION_META, None))
+        if not isinstance(invocation, Mapping):
+            return None
+        turn_id = invocation.get("turnId")
+        if not isinstance(turn_id, str) or not turn_id.strip():
+            return None
+        return _Turn(id=turn_id.strip()[:128], is_new=True, source="meta", args=args)
+    except Exception:
+        return None
+
+
+def _with_meta_turn(ctx: Any, turn: _Turn) -> _Turn:
+    meta_turn = _meta_turn_of(ctx, turn.args)
+    return replace(meta_turn, intent=turn.intent) if meta_turn is not None else turn
+
+
+def _client_info_from(value: Any) -> Optional[McpClientInfo]:
+    if isinstance(value, Mapping):
+        name, version = value.get("name"), value.get("version")
+    else:
+        name, version = getattr(value, "name", None), getattr(value, "version", None)
+    if not isinstance(name, str) or not name.strip():
+        return None
+    info = McpClientInfo(name=name.strip()[:128])
+    if isinstance(version, str) and version.strip():
+        info.version = version.strip()[:64]
+    return info
+
+
+def _client_info_of(ctx: Any) -> Optional[McpClientInfo]:
+    """Who is calling: the per-request ``clientInfo`` 2026-era clients send in ``_meta``, else what ``initialize`` said."""
+    try:
+        meta = _meta_of(ctx)
+        if isinstance(meta, Mapping):
+            info = _client_info_from(meta.get(_CLIENT_INFO_META))
+        elif meta is not None:
+            extra = getattr(meta, "model_extra", None) or {}
+            info = _client_info_from(extra.get(_CLIENT_INFO_META))
+        else:
+            info = None
+        if info is not None:
+            return info
+    except Exception:
+        pass
+    for path in (("connection",), ("session",), ("request_context", "session")):
+        try:
+            holder: Any = ctx
+            for attr in path:
+                holder = getattr(holder, attr)
+            params = holder.client_params
+            client = getattr(params, "client_info", None)
+            if client is None:
+                client = getattr(params, "clientInfo", None)
+            info = _client_info_from(client)
+            if info is not None:
+                return info
+        except Exception:
+            continue
+    return None
+
+
+def _session_input(intent: Optional[str]) -> str:
+    """Not user text, so it is labelled as what it is; the intent is the model's one-liner."""
+    return "MCP session started" if intent is None else f"MCP session started\nSession intent:\n{intent}"
+
+
+def _collision_warning(tool_name: str, field: str) -> str:
+    """Written for whoever (or whatever agent) maintains the tool: what is lost and the two ways to fix it."""
+    if field == INTENT:
+        purpose, loss, option, feature = (
+            "the user's stated intent",
+            "intent will NOT be captured for this tool",
+            "intent=False",
+            "intent capture",
+        )
+    else:
+        purpose, loss, option, feature = (
+            "grouping one prompt's tool calls into one event",
+            "each call to this tool will be its own event",
+            "turn_tracking=False",
+            "turn grouping",
+        )
+    return (
+        f'[raindrop-mcp] Tool "{tool_name}" already has an argument named "{field}". '
+        f'raindrop-mcp reserves "{field}" for {purpose}, so {loss}. '
+        f'Fix: rename the tool\'s "{field}" argument (any other name works), or set `{option}` '
+        f"in RaindropMcp() to disable {feature} for every tool."
+    )
+
+
+
+
+def _attach_turn_trace(digest: bytes) -> Any:
+    """Puts a turn-level parent in the OTel context so every span of the turn joins one trace."""
+    try:
+        from opentelemetry import context as otel_context
+        from opentelemetry import trace
+
+        span_context = trace.SpanContext(
+            trace_id=int.from_bytes(digest[16:32], "big"),
+            span_id=int.from_bytes(digest[8:16], "big"),
+            is_remote=True,
+            trace_flags=trace.TraceFlags(trace.TraceFlags.SAMPLED),
+        )
+        return otel_context.attach(trace.set_span_in_context(trace.NonRecordingSpan(span_context)))
+    except Exception:
+        return None
+
+
+def _detach_turn_trace(token: Any) -> None:
+    if token is None:
+        return
+    try:
+        from opentelemetry import context as otel_context
+
+        otel_context.detach(token)
+    except Exception:
+        pass
+
+
+def _manager_class_for(server_cls: type) -> Optional[type]:
+    for base in inspect.getmro(server_cls):
+        module = getattr(base, "__module__", "") or ""
+        if base.__name__ == "ToolManager" and hasattr(base, "add_tool") and hasattr(base, "call_tool"):
+            return base
+        if module.startswith("mcp.server.mcpserver"):
+            from mcp.server.mcpserver.tools import ToolManager
+
+            return ToolManager
+        if module.startswith("mcp.server.fastmcp"):
+            from mcp.server.fastmcp.tools import ToolManager
+
+            return ToolManager
+        if module.startswith("fastmcp."):
+            # Standalone fastmcp 2.x keeps a ToolManager; 3.x+ has none (see _standalone_targets).
+            try:
+                from fastmcp.tools.tool_manager import ToolManager  # type: ignore[import-not-found]
+            except ImportError:
+                return None
+            return ToolManager if hasattr(ToolManager, "call_tool") else None
+    return None
+
+
+def _is_standalone_fastmcp(server: Any) -> bool:
+    cls = server if inspect.isclass(server) else type(server)
+    return any((getattr(base, "__module__", "") or "").startswith("fastmcp.") for base in inspect.getmro(cls))
+
+
+# Standalone fastmcp 3.x+ opens its Context inside call_tool and re-enters
+# call_tool(run_middleware=False) from the middleware chain. The outer call owns
+# the turn (middleware may answer from a cache without ever reaching the inner
+# call); the inner one hands its Context back through this holder.
+_inner_ctx: contextvars.ContextVar[Optional[List[Any]]] = contextvars.ContextVar("raindrop_mcp_inner_ctx", default=None)
+
+
+def _standalone_context() -> Any:
+    """The current standalone fastmcp ``Context`` (its ``call_tool`` takes no context argument)."""
+    try:
+        from fastmcp.server.dependencies import get_context  # type: ignore[import-not-found]
+
+        return get_context()
+    except Exception:
+        return None
+
+
+def _standalone_targets(server: Any) -> Optional[Tuple[Any, Any]]:
+    """``(call target, registration target)`` for standalone ``fastmcp`` 3.x+ servers.
+
+    Those keep ``call_tool`` on the server itself and register tools through a
+    ``LocalProvider`` (``@mcp.tool`` and ``mcp.add_tool`` both end in its ``add_tool``).
+    """
+    if not _is_standalone_fastmcp(server) or not hasattr(server, "call_tool"):
+        return None
+    if inspect.isclass(server):
+        try:
+            from fastmcp.server.providers import LocalProvider  # type: ignore[import-not-found]
+        except ImportError:
+            return None
+        return server, LocalProvider
+    provider = getattr(server, "_local_provider", None)
+    if provider is None or not hasattr(provider, "add_tool"):
+        return None
+    return server, provider
+
+
+def _registered_tools(target: Any) -> List[Any]:
+    tools = getattr(target, "_tools", None)
+    if isinstance(tools, Mapping):
+        return list(tools.values())
+    components = getattr(target, "_components", None)
+    if isinstance(components, Mapping):
+        return [tool for tool in components.values() if hasattr(tool, "parameters")]
+    return []
+
+
+class RaindropMcp:
+    """Instruments MCP servers so every tool call lands in Raindrop.
+
+    Args:
+        api_key: Raindrop write key. Omitting it disables shipping (a warning is
+            emitted); tools still get ``_turn_id`` so behavior is identical.
+        user_id: Who made the call: a fixed string or a callable of
+            :class:`McpCallContext` returning the id (``None`` skips the call).
+            Defaults to the OAuth subject, else a hash of the bearer token,
+            else ``session:<mcp-session-id>``, else ``anonymous``.
+        convo_id: Conversation grouping, fixed or callable. Defaults to the
+            transport session, else the caller's UTC day.
+        event_name: Event name. Defaults to ``mcp_activity``.
+        turn_tracking: Advertise ``_turn_id`` on every tool and append it to
+            every result so one prompt's calls share one event. ``False`` leaves
+            tool schemas and results untouched (and disables ``intent``); every
+            call is its own event.
+        intent: Advertise ``_intent`` on every tool, which the model fills with a
+            one-sentence description of what the user wants on the first call of
+            a prompt. Recorded as ``mcp.intent`` and appended to the event input.
+        properties: Extra properties on every event, a dict or a callable.
+        redact_arguments: Argument names never captured, on top of the default
+            credential-key redaction.
+        redact_results: Tools whose results are never captured.
+        await_delivery: Wait (at most 5s, off the event loop) for delivery
+            before returning each tool result. Needed on serverless. Default True.
+        max_text_field_chars: Per-field cap for captured arguments and results.
+        tracing_enabled / bypass_otel_for_tools: Forwarded to the Raindrop client;
+            tool spans need both (the defaults).
+        client: An existing :class:`raindrop.Raindrop` to ship through instead.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        user_id: Union[str, Resolver, None] = None,
+        convo_id: Union[str, Resolver, None] = None,
+        tracing_enabled: bool = True,
+        bypass_otel_for_tools: bool = True,
+        debug: bool = False,
+        *,
+        event_name: str = "mcp_activity",
+        turn_tracking: bool = True,
+        intent: bool = True,
+        properties: Union[Dict[str, Any], PropertiesResolver, None] = None,
+        redact_arguments: Optional[List[str]] = None,
+        redact_results: Optional[List[str]] = None,
+        await_delivery: bool = True,
+        max_text_field_chars: Optional[int] = None,
+        project_id: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        app_git: Any = True,
+        client: Optional[Raindrop] = None,
+    ) -> None:
+        if debug:
+            logger.setLevel(logging.DEBUG)
+        self._user_id = user_id
+        self._convo_id = convo_id
+        self._properties = properties
+        self._event_name = event_name or "mcp_activity"
+        self._turn_tracking = bool(turn_tracking)
+        self._intent = bool(intent)
+        self._redact_arguments: Set[str] = set(redact_arguments or ())
+        self._redact_results: Set[str] = set(redact_results or ())
+        self._await_delivery = bool(await_delivery)
+        self._max_text_field_chars = (
+            int(max_text_field_chars)
+            if isinstance(max_text_field_chars, int) and max_text_field_chars > 0
+            else _DEFAULT_MAX_TEXT_FIELD_CHARS
+        )
+        self._opened_meta_events: Set[str] = set()
+        self._injected_tools: Dict[int, Tuple[str, ...]] = {}
+        self._owned_fields: Dict[str, Set[str]] = {}
+        self._rd: Optional[Raindrop] = None
+
+        key = (api_key or "").strip()
+        if client is not None:
+            self._rd = client
+        elif not key:
+            warnings.warn(
+                "[raindrop-mcp] api_key not provided; telemetry shipping is disabled",
+                stacklevel=2,
+            )
+        else:
+            try:
+                self._rd = Raindrop(
+                    api_key=key,
+                    tracing_enabled=tracing_enabled,
+                    bypass_otel_for_tools=bypass_otel_for_tools,
+                    auto_instrument=False,
+                    project_id=project_id,
+                    app_git=app_git,
+                    max_text_field_chars=max_text_field_chars,
+                    **({"endpoint": endpoint} if endpoint is not None else {}),
+                )
+            except Exception:
+                logger.debug("Failed to configure Raindrop client", exc_info=True)
+                warnings.warn("[raindrop-mcp] telemetry disabled; see debug logs", stacklevel=2)
+
+    # -- wrapping ----------------------------------------------------------- #
+
+    def wrap(self, server: Any) -> Any:
+        """Instruments a ``FastMCP`` / ``MCPServer`` instance, including tools it already has.
+
+        Pass the class (``raindrop.wrap(FastMCP)``) to instrument every server a
+        third-party package constructs afterwards. Returns ``server`` unchanged.
+        """
+        try:
+            if inspect.isclass(server):
+                manager_cls = _manager_class_for(server)
+                if manager_cls is not None:
+                    if _WRAPPED_ATTR not in vars(manager_cls):
+                        self._install(manager_cls, manager_cls, is_class=True)
+                    return server
+                targets = _standalone_targets(server)
+                if targets is None:
+                    raise TypeError("wrap() expects a FastMCP / MCPServer instance or class")
+                call_target, add_target = targets
+                if _WRAPPED_ATTR not in vars(call_target):
+                    self._install(call_target, add_target, is_class=True)
+                return server
+            manager = getattr(server, "_tool_manager", None)
+            if manager is not None and hasattr(manager, "add_tool") and hasattr(manager, "call_tool"):
+                call_target = add_target = manager
+            else:
+                targets = _standalone_targets(server)
+                if targets is None:
+                    raise TypeError("wrap() expects a FastMCP / MCPServer instance or class")
+                call_target, add_target = targets
+            if _WRAPPED_ATTR in vars(call_target) or getattr(type(call_target), _WRAPPED_ATTR, False):
+                return server
+            self._install(call_target, add_target, is_class=False)
+            for tool in _registered_tools(add_target):
+                self._inject_fields(tool)
+        except Exception:
+            logger.debug("Failed to wrap MCP server", exc_info=True)
+            warnings.warn(
+                f"[raindrop-mcp] wrap() could not instrument {server!r}; its tool calls will not be recorded",
+                stacklevel=2,
+            )
+        return server
+
+    def _install(self, call_target: Any, add_target: Any, *, is_class: bool) -> None:
+        """Hooks ``add_tool`` on ``add_target`` and ``call_tool`` on ``call_target`` (usually the same ToolManager)."""
+        original_add = add_target.add_tool
+        original_call = call_target.call_tool
+        standalone = _is_standalone_fastmcp(call_target)
+        reenters = standalone and "run_middleware" in inspect.signature(original_call).parameters
+        wrapper = self
+
+        if is_class:
+
+            def add_tool(manager: Any, *args: Any, **kwargs: Any) -> Any:
+                return wrapper._on_add(lambda: original_add(manager, *args, **kwargs))
+
+            async def call_tool(manager: Any, *args: Any, **kwargs: Any) -> Any:
+                name, arguments, rest, kwargs = _call_args(args, kwargs)
+                return await wrapper._on_call(
+                    manager,
+                    name,
+                    arguments,
+                    _context_arg(rest, kwargs),
+                    lambda a: original_call(manager, name, a, *rest, **kwargs),
+                    standalone=standalone,
+                    passthrough=reenters and kwargs.get("run_middleware") is False,
+                )
+
+        else:
+
+            def add_tool(*args: Any, **kwargs: Any) -> Any:  # type: ignore[misc]
+                return wrapper._on_add(lambda: original_add(*args, **kwargs))
+
+            async def call_tool(*args: Any, **kwargs: Any) -> Any:  # type: ignore[misc]
+                name, arguments, rest, kwargs = _call_args(args, kwargs)
+                return await wrapper._on_call(
+                    call_target,
+                    name,
+                    arguments,
+                    _context_arg(rest, kwargs),
+                    lambda a: original_call(name, a, *rest, **kwargs),
+                    standalone=standalone,
+                    passthrough=reenters and kwargs.get("run_middleware") is False,
+                )
+
+        setattr(add_target, "add_tool", add_tool)
+        setattr(call_target, "call_tool", call_tool)
+        setattr(call_target, _WRAPPED_ATTR, True)
+        setattr(add_target, _WRAPPED_ATTR, True)
+
+    def _on_add(self, register: Callable[[], Any]) -> Any:
+        tool = register()
+        try:
+            self._inject_fields(tool)
+        except Exception:
+            logger.debug("%s not added to tool", "/".join(self._wanted_fields()), exc_info=True)
+        return tool
+
+    def _wanted_fields(self) -> Tuple[str, ...]:
+        if not self._turn_tracking:
+            return ()
+        return (TURN_ID, INTENT) if self._intent else (TURN_ID,)
+
+    def _inject_fields(self, tool: Any) -> None:
+        wanted = self._wanted_fields()
+        if not wanted or tool is None:
+            return
+        parameters = getattr(tool, "parameters", None)
+        if not isinstance(parameters, Mapping):
+            return
+        properties = parameters.get("properties")
+        properties = dict(properties) if isinstance(properties, Mapping) else {}
+        name = getattr(tool, "name", None)
+        added: List[str] = []
+        for field in wanted:
+            if field in properties:
+                # The tool's own parameter, not ours: leave it alone and hand it through untouched.
+                if isinstance(name, str):
+                    self._owned_fields.setdefault(name, set()).add(field)
+                    warnings.warn(_collision_warning(name, field), stacklevel=4)
+                continue
+            properties[field] = {"type": "string", "description": _DESCRIPTIONS[field]}
+            added.append(field)
+        tool.parameters = {**parameters, "properties": properties}
+        self._injected_tools[id(tool)] = tuple(added)
+
+    def _fields_of(self, manager: Any, name: str) -> Tuple[str, ...]:
+        """The fields this wrapper advertises on ``name`` (so a tool-owned one is never stripped)."""
+        wanted = self._wanted_fields()
+        if not wanted:
+            return ()
+        try:
+            tools = getattr(manager, "_tools", None)
+            tool = tools.get(name) if isinstance(tools, Mapping) else None
+            if tool is None:
+                owned = self._owned_fields.get(name, set())
+                return tuple(field for field in wanted if field not in owned)
+            return self._injected_tools.get(id(tool), ())
+        except Exception:
+            return wanted
+
+    # -- per call ----------------------------------------------------------- #
+
+    async def _on_call(
+        self,
+        manager: Any,
+        name: str,
+        arguments: Any,
+        ctx: Any,
+        invoke: Callable[[Any], Awaitable[Any]],
+        *,
+        standalone: bool = False,
+        passthrough: bool = False,
+    ) -> Any:
+        if passthrough:
+            holder = _inner_ctx.get()
+            if holder is not None:
+                # Re-entry from the middleware chain (however many times it retries): the outer call owns it.
+                if not holder:
+                    holder.append(_standalone_context())
+                return await invoke(arguments)
+            # call_tool(run_middleware=False) straight from server code: no outer call owns it.
+        if standalone and ctx is None:
+            ctx = _standalone_context()  # 2.x: the Context is already open around the manager call
+        lazy_ctx = standalone and ctx is None
+        try:
+            fields = self._fields_of(manager, name)
+            turn = _split_turn(arguments, fields) if fields else _new_turn(arguments)
+            if self._turn_tracking and not lazy_ctx:
+                turn = _with_meta_turn(ctx, turn)
+            # Echo only when the id we advertise is ours; a tool-owned ``_turn_id`` must not be fed one.
+            with_echo = TURN_ID in fields and turn.source == "echo"
+            started = time.time()
+        except Exception:
+            logger.debug("Failed to prepare %s; running uninstrumented", name, exc_info=True)
+            return await invoke(arguments)
+
+        holder: List[Any] = []
+        token = _inner_ctx.set(holder) if lazy_ctx else None
+        try:
+            result = await invoke(turn.args)
+        except Exception as error:
+            if token is not None:
+                _inner_ctx.reset(token)
+            if lazy_ctx and holder:
+                ctx = holder[0]
+                if self._turn_tracking:
+                    turn = _with_meta_turn(ctx, turn)
+                    with_echo = TURN_ID in fields and turn.source == "echo"
+            await self._record(name, turn, ctx, started, error=error)
+            # The SDK would turn this into an error result without the echo, and
+            # the model's next call would open a new turn; build the same result ourselves.
+            if not with_echo or isinstance(error, _protocol_errors()):
+                raise
+            try:
+                return _error_result(str(error) or type(error).__name__, turn.id, standalone=standalone)
+            except Exception:
+                raise error
+
+        if token is not None:
+            _inner_ctx.reset(token)
+        if lazy_ctx and holder:
+            ctx = holder[0]
+            if self._turn_tracking:
+                turn = _with_meta_turn(ctx, turn)
+                with_echo = TURN_ID in fields and turn.source == "echo"
+        await self._record(name, turn, ctx, started, result=result)
+        if not with_echo:
+            return result
+        try:
+            return _echo_turn_id(result, turn.id)
+        except Exception:
+            logger.debug("Failed to echo %s on %s", TURN_ID, name, exc_info=True)
+            return result
+
+    async def _record(
+        self,
+        name: str,
+        turn: _Turn,
+        ctx: Any,
+        started: float,
+        *,
+        result: Any = None,
+        error: Optional[BaseException] = None,
+    ) -> None:
+        if self._rd is None:
+            return
+        try:
+            self._ship(name, turn, ctx, started, result, error)
+        except Exception:
+            logger.debug("%s not shipped", name, exc_info=True)
+            return
+        if not self._await_delivery:
+            return
+        try:
+            import anyio
+
+            # Abandon (not join) the flush thread at the deadline, or the result stays blocked for a slow ingest.
+            abandon = "abandon_on_cancel" if "abandon_on_cancel" in inspect.signature(anyio.to_thread.run_sync).parameters else "cancellable"
+            with anyio.move_on_after(_SHIP_DEADLINE_S):
+                await anyio.to_thread.run_sync(self._rd.flush, **{abandon: True})
+        except Exception:
+            logger.debug("Delivery wait for %s failed", name, exc_info=True)
+
+    def _ship(
+        self,
+        name: str,
+        turn: _Turn,
+        ctx: Any,
+        started: float,
+        result: Any,
+        error: Optional[BaseException],
+    ) -> None:
+        assert self._rd is not None
+        # Free text the model wrote; ``redact_arguments=["_intent"]`` keeps it out of telemetry entirely.
+        intent = None if INTENT in self._redact_arguments else turn.intent
+        call = McpCallContext(
+            tool_name=name,
+            args=turn.args,
+            session_id=_session_id_of(ctx),
+            context=ctx,
+            client=_client_info_of(ctx),
+            intent=intent,
+        )
+        user_id = self._resolve_user_id(call)
+        if not user_id:
+            return
+        # Hashed with the caller so an echoed id from another caller can never land on their event.
+        digest = hashlib.sha256(f"{user_id}\n{turn.id}".encode()).digest()
+        event_id = digest[:16].hex()
+        convo_id = self._resolve_convo_id(call, user_id, started)
+        is_new = self._is_new_meta_event(event_id) if turn.source == "meta" else turn.is_new
+        is_error = error is not None or _is_error_result(result)
+        output = self._output_of(name, result, error)
+        ended = time.time()
+
+        properties: Dict[str, Any] = dict(self._resolve_properties(call))
+        properties.update({"mcp.turn_id": turn.id, "mcp.tool": name, "mcp.is_error": is_error})
+        span_properties: Dict[str, Any] = {"mcp.turn_id": turn.id}
+        if call.session_id:
+            properties["mcp.session_id"] = call.session_id
+            span_properties["mcp.session_id"] = call.session_id
+        if call.client is not None:
+            properties["mcp.client_name"] = span_properties["mcp.client_name"] = call.client.name
+            if call.client.version is not None:
+                properties["mcp.client_version"] = span_properties["mcp.client_version"] = call.client.version
+        if intent is not None:
+            properties["mcp.intent"] = span_properties["mcp.intent"] = intent
+
+        token = _attach_turn_trace(digest)
+        try:
+            interaction = self._rd.begin(
+                user_id,
+                self._event_name,
+                event_id=event_id,
+                convo_id=convo_id,
+                input=_session_input(intent) if is_new or intent is not None else None,
+            )
+            interaction.track_tool(
+                name=name,
+                input=self._args_of(turn.args),
+                output=output,
+                error=(output or "Tool reported an error") if is_error else None,
+                duration_ms=max(0.0, (ended - started) * 1000),
+                start_time=started,
+                properties=span_properties,
+            )
+            finish_kwargs: Dict[str, Any] = {"properties": properties}
+            if is_new:
+                finish_kwargs["timestamp"] = datetime.fromtimestamp(started, tz=timezone.utc)
+            interaction.finish(output="MCP session ended", **finish_kwargs)
+        finally:
+            _detach_turn_trace(token)
+
+    def _is_new_meta_event(self, event_id: str) -> bool:
+        if event_id in self._opened_meta_events:
+            return False
+        if len(self._opened_meta_events) >= _MAX_META_EVENTS:
+            self._opened_meta_events.clear()
+        self._opened_meta_events.add(event_id)
+        return True
+
+    def _resolve_user_id(self, call: McpCallContext) -> Optional[str]:
+        if self._user_id is None:
+            return _default_user_id(call.context)
+        if isinstance(self._user_id, str):
+            return self._user_id
+        value = self._user_id(call)
+        return value if isinstance(value, str) and value else None
+
+    def _resolve_convo_id(self, call: McpCallContext, user_id: str, started: float) -> Optional[str]:
+        """Clients choose the session id, so it is hashed with the caller; without one, a caller's calls group by UTC day."""
+        if isinstance(self._convo_id, str):
+            return self._convo_id
+        if self._convo_id is not None:
+            value = self._convo_id(call)
+            return value if isinstance(value, str) and value else None
+        key = call.session_id or datetime.fromtimestamp(started, tz=timezone.utc).strftime("%Y-%m-%d")
+        return hashlib.sha256(f"{user_id}\n{key}".encode()).hexdigest()[:32]
+
+    def _resolve_properties(self, call: McpCallContext) -> Dict[str, Any]:
+        try:
+            if self._properties is None:
+                return {}
+            if isinstance(self._properties, Mapping):
+                return dict(self._properties)
+            value = self._properties(call)
+            return dict(value) if isinstance(value, Mapping) else {}
+        except Exception:
+            logger.debug("properties callable failed", exc_info=True)
+            return {}
+
+    def _args_of(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        kept = {key: value for key, value in args.items() if key not in self._redact_arguments}
+        redacted = _redact_secrets(kept, [10_000], self._max_text_field_chars)
+        return redacted if isinstance(redacted, dict) else {}
+
+    def _output_of(self, name: str, result: Any, error: Optional[BaseException]) -> str:
+        if name in self._redact_results:
+            return "[redacted]"
+        if error is not None:
+            return _error_message(error)[: self._max_text_field_chars]
+        return _tool_result_text(result, self._max_text_field_chars)
+
+    # -- pass-through API ---------------------------------------------------- #
+
+    def flush(self) -> None:
+        try:
+            if self._rd is not None:
+                self._rd.flush()
+        except Exception:
+            logger.debug("Failed to flush", exc_info=True)
+
+    def shutdown(self) -> None:
+        try:
+            if self._rd is not None:
+                self._rd.shutdown()
+        except Exception:
+            logger.debug("Failed to shutdown", exc_info=True)
+
+    def identify(self, user_id: str, traits: Optional[Dict[str, Union[str, int, bool, float]]] = None) -> None:
+        try:
+            if self._rd is not None:
+                self._rd.identify(user_id, traits)
+        except Exception:
+            logger.debug("Failed to identify", exc_info=True)
+
+    def track_signal(
+        self,
+        event_id: str,
+        name: str,
+        signal_type: Literal["default", "feedback", "edit"] = "default",
+        *,
+        timestamp: Optional[str] = None,
+        properties: Optional[Dict[str, object]] = None,
+        attachment_id: Optional[str] = None,
+        comment: Optional[str] = None,
+        after: Optional[str] = None,
+        sentiment: Optional[Literal["POSITIVE", "NEGATIVE"]] = None,
+    ) -> None:
+        try:
+            if self._rd is not None:
+                self._rd.track_signal(
+                    event_id=event_id,
+                    name=name,
+                    signal_type=signal_type,
+                    timestamp=timestamp,
+                    properties=properties,
+                    attachment_id=attachment_id,
+                    comment=comment,
+                    after=after,
+                    sentiment=sentiment,
+                )
+        except Exception:
+            logger.debug("Failed to track signal", exc_info=True)
+
+    def __getitem__(self, key: str) -> Any:
+        methods = {
+            "wrap": self.wrap,
+            "flush": self.flush,
+            "shutdown": self.shutdown,
+            "identify": self.identify,
+            "track_signal": self.track_signal,
+        }
+        if key not in methods:
+            raise KeyError(key)
+        return methods[key]
+
+
+def _call_args(args: Tuple[Any, ...], kwargs: Dict[str, Any]) -> Tuple[Any, Any, Tuple[Any, ...], Dict[str, Any]]:
+    """``(name, arguments, remaining args, kwargs)`` however the SDK spelled the call (``key=`` in standalone fastmcp 2.x)."""
+    rest = list(args)
+    kwargs = dict(kwargs)
+    if rest:
+        name = rest.pop(0)
+    else:
+        name = kwargs.pop("name") if "name" in kwargs else kwargs.pop("key")
+    arguments = rest.pop(0) if rest else kwargs.pop("arguments", None)
+    return name, arguments, tuple(rest), kwargs
+
+
+def _context_arg(args: Tuple[Any, ...], kwargs: Dict[str, Any]) -> Any:
+    if "context" in kwargs:
+        return kwargs["context"]
+    return args[0] if args else None
+
+
+def create_raindrop_mcp(**kwargs: Any) -> RaindropMcp:
+    """Factory form of :class:`RaindropMcp`; returns a no-op instance instead of raising."""
+    try:
+        return RaindropMcp(**kwargs)
+    except Exception:
+        logger.debug("Failed to construct RaindropMcp", exc_info=True)
+        warnings.warn("[raindrop-mcp] telemetry disabled; see debug logs", stacklevel=2)
+        instance = object.__new__(RaindropMcp)
+        instance._rd = None
+        instance._turn_tracking = bool(kwargs.get("turn_tracking", True))
+        instance._intent = bool(kwargs.get("intent", True))
+        instance._user_id = kwargs.get("user_id")
+        instance._convo_id = kwargs.get("convo_id")
+        instance._properties = kwargs.get("properties")
+        instance._event_name = kwargs.get("event_name") or "mcp_activity"
+        instance._redact_arguments = set(kwargs.get("redact_arguments") or ())
+        instance._redact_results = set(kwargs.get("redact_results") or ())
+        instance._await_delivery = bool(kwargs.get("await_delivery", True))
+        instance._max_text_field_chars = _DEFAULT_MAX_TEXT_FIELD_CHARS
+        instance._opened_meta_events = set()
+        instance._injected_tools = {}
+        instance._owned_fields = {}
+        return instance

raindrop_mcp-0.0.1.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: raindrop-mcp
+Version: 0.0.1
+Summary: Raindrop instrumentation for Python MCP servers: one event per turn, one tool span per call, for any FastMCP / MCPServer.
+Project-URL: Homepage, https://raindrop.ai
+Project-URL: Repository, https://github.com/invisible-tools/dawn
+Author-email: Raindrop AI <sdk@raindrop.ai>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.10.0
+Requires-Dist: raindrop-ai>=0.0.70
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# raindrop-mcp
+
+Raindrop instrumentation for Python MCP servers. Works with the official SDK's `mcp` 1.x (`FastMCP`) and `mcp` 2.x (`MCPServer`), with the standalone [`fastmcp`](https://pypi.org/project/fastmcp/) package (2.x and 3.x+), and with any server built on them: wrap it once and every tool call lands in Raindrop as a tool span on an `mcp_activity` event. Python twin of [`@raindrop-ai/mcp`](https://github.com/raindrop-ai/raindrop-js/tree/main/packages/mcp).
+
+## Install
+
+```bash
+pip install raindrop-mcp
+```
+
+## Quick Start
+
+```python
+import os
+from mcp.server.fastmcp import FastMCP  # mcp 2.x: from mcp.server.mcpserver import MCPServer
+from raindrop_mcp import RaindropMcp
+
+raindrop = RaindropMcp(api_key=os.environ.get("RAINDROP_API_KEY"))
+mcp = raindrop.wrap(FastMCP("my-server"))
+
+@mcp.tool()
+def search(query: str) -> str:
+    ...
+
+mcp.run()
+```
+
+Omitting `api_key` disables shipping (a warning is emitted) but never crashes the server.
+
+Third-party servers usually build their own `FastMCP` at import time. Wrap the class before importing them, or wrap the instance afterwards (tools already registered are instrumented too):
+
+```python
+from mcp.server.fastmcp import FastMCP
+from raindrop_mcp import RaindropMcp
+
+RaindropMcp(api_key=...).wrap(FastMCP)   # every FastMCP built from now on
+import some_mcp_server                   # noqa: E402
+some_mcp_server.mcp.run()
+```
+
+The standalone `fastmcp` package works the same way:
+
+```python
+from fastmcp import FastMCP
+from raindrop_mcp import RaindropMcp
+
+mcp = RaindropMcp(api_key=...).wrap(FastMCP("Demo"))
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    return a + b
+```
+
+## Turn tracking
+
+MCP has no turn boundary, so by default every tool advertises an optional `_turn_id` argument and every result ends with a `_turn_id: <id>` text block. The model copies it on its next call and omits it on a new prompt, so the calls of one prompt share one event (one trace, one tool span per call). The argument is removed before your tool runs. A tool that raises still echoes the id, so the model's next call stays on the same event.
+
+If the client sends `_meta["io.modelcontextprotocol/aiInvocation"].turnId` (SEP-2817), that id is used and nothing is echoed.
+
+`turn_tracking=False` leaves schemas and results untouched (this also disables `intent`); every call is then its own event.
+
+## Intent and client
+
+Every tool also advertises an optional `_intent` argument: one sentence on what the user is trying to accomplish, which the model fills on the first call of a prompt. It is stripped before your tool runs, recorded as the `mcp.intent` property, and appended to the event input under a `Session intent:` line after `MCP session started`. Set `intent=False` to leave it out. It is free text the model wrote, so the key-based secret redaction does not apply to it; list `_intent` in `redact_arguments` to keep the field advertised but out of telemetry.
+
+The MCP client that made the call (`clientInfo`, e.g. `claude-code 2.1.0`, `Cursor`, `codex-mcp-client`) is recorded as `mcp.client_name` / `mcp.client_version` on every span and event. It comes from the per-request `_meta` of 2026-era clients, or from the `initialize` handshake on older ones.
+
+## Options
+
+| Option                 | Default                                                            | Description                                                                                                                                  |
+| ---------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api_key`              | –                                                                  | Raindrop write key. Without one, nothing ships and a warning is emitted.                                                                     |
+| `endpoint`             | `https://api.raindrop.ai/v1/`                                      | Ingest endpoint.                                                                                                                             |
+| `project_id`           | –                                                                  | Raindrop project slug.                                                                                                                       |
+| `event_name`           | `mcp_activity`                                                     | Event name.                                                                                                                                  |
+| `turn_tracking`        | `True`                                                             | Advertise and echo `_turn_id` to group a prompt's calls into one event.                                                                      |
+| `intent`               | `True`                                                             | Advertise `_intent` so the model states the user's goal on the first call of a prompt.                                                       |
+| `user_id`              | OAuth subject → hashed bearer token → `session:<id>` → `anonymous` | Fixed id or `callable(call) -> str \| None`. Returning `None` skips the call.                                                                |
+| `convo_id`             | transport session, else the caller's UTC day                       | Fixed id or `callable(call) -> str \| None`.                                                                                                 |
+| `properties`           | –                                                                  | Extra event properties, a dict or `callable(call) -> dict`.                                                                                  |
+| `redact_arguments`     | `[]`                                                               | Argument names never captured. Keys that look like secrets (`password`, `authorization`, `api_key`, …) are always redacted.                 |
+| `redact_results`       | `[]`                                                               | Tools whose results are never captured, e.g. ones that return credentials.                                                                   |
+| `await_delivery`       | `True`                                                             | Wait (at most 5s, off the event loop) for delivery before returning each tool result. Needed on serverless. Set `False` on long-running servers to keep tool latency unchanged. |
+| `max_text_field_chars` | `1,000,000`                                                        | Per-field character cap for captured arguments and results.                                                                                  |
+| `debug`                | `False`                                                            | Log shipping details.                                                                                                                        |
+| `app_git`              | auto-detect                                                        | Application Git identity; `False` disables.                                                                                                  |
+| `client`               | –                                                                  | An existing `raindrop.Raindrop` client to ship through (multi-project setups).                                                               |
+
+`call` passed to the callables is a `McpCallContext(tool_name, args, session_id, context)`, where `context` is the SDK's per-request `Context`.
+
+## Event properties
+
+`mcp.turn_id`, `mcp.tool` (the latest tool in the turn), `mcp.is_error`, `mcp.client_name` / `mcp.client_version` when the client identified itself, `mcp.intent` when the model filled `_intent`, `mcp.session_id` when the transport has one, plus anything from `properties`. Tool spans carry the arguments, the result text (or the error), `mcp.turn_id`, `mcp.session_id`, the client and the intent.
+
+## Known limitations
+
+- Servers built on the official SDK's `FastMCP` / `MCPServer` or on standalone `fastmcp` are supported; the low-level `mcp.server.Server` is not.
+- On standalone `fastmcp` 2.x a tool that raises cannot echo the id (its `ToolResult` has no error form), so the model's next call starts a new event; 3.x+ echoes like the official SDK.
+- `_turn_id` and `_intent` are added to the tool's JSON schema. A tool that declares either name itself keeps it: the field is neither advertised by this package nor stripped from the arguments for that tool, and a warning is emitted at registration since that tool then has no intent (or no turn grouping).
+- Grouping depends on the model echoing `_turn_id`; clients that strip unknown result blocks start a new event per call.
+- Delivery runs on the Raindrop SDK's background thread; `await_delivery` flushes before returning but cannot wait for a flush that thread already started.
+
+## Testing
+
+```bash
+pip install -e ".[dev]" && pytest
+```
+
+The suite runs unchanged against `mcp<2` and `mcp>=2`.

raindrop_mcp-0.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+raindrop_mcp/__init__.py,sha256=hnjKmlU9hwP_N-grV6Bvix_d0jjo2pvNAeLID9158Io,286
+raindrop_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+raindrop_mcp/wrapper.py,sha256=ZevzmSgBM9Pwy1TJU4DohAz8CSyHHxHqtJOb1G72nL8,47983
+raindrop_mcp-0.0.1.dist-info/METADATA,sha256=fZuLJ1zCSZGbGSla7RnyQrC-yb9wHO6F3E7v5vbWDuk,9857
+raindrop_mcp-0.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+raindrop_mcp-0.0.1.dist-info/licenses/LICENSE,sha256=75M-fO9wwGEb_cxFixHCC7ubCg-Y0ryPwIySFUuMr-o,1068
+raindrop_mcp-0.0.1.dist-info/RECORD,,

raindrop_mcp-0.0.1.dist-info/WHEEL

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

raindrop_mcp-0.0.1.dist-info/licenses/LICENSE

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