mcpcat 0.1.0__py3-none-any.whl

mcpcat/__init__.py

@@ -0,0 +1,106 @@
+"""MCPCat - Analytics Tool for MCP Servers."""
+
+from typing import Any, Optional
+
+from mcpcat.modules.overrides.fastmcp import override_fastmcp
+from mcpcat.modules.overrides.mcp_server import override_lowlevel_mcp_server
+
+from .modules.compatibility import is_compatible_server, is_fastmcp_server
+from .modules.internal import get_mcpcat_data, has_mcpcat_data, set_mcpcat_data
+from .modules.logging import log_error, log_info
+from .modules.session import get_unknown_or_stdio_session
+from .modules.tools import handle_report_missing as handleReportMissing
+from .types import MCPCatData, MCPCatOptions, UserData
+
+__version__ = "1.0.0"
+
+
+def track(server: Any, options: MCPCatOptions | None = None) -> Any:
+    """
+    Enable analytics tracking for an MCP server.
+    
+    This function modifies the server's tool handlers to add analytics tracking,
+    context parameter injection, and additional MCP tools.
+    
+    Args:
+        server: The MCP server instance (e.g., FastMCP)
+        options: Optional configuration options
+        
+    Raises:
+        TypeError: If the server is not compatible
+    """
+    # Use default options if not provided
+    if options is None:
+        options = MCPCatOptions()
+
+    # Validate server compatibility
+    if not is_compatible_server(server):
+        raise TypeError(
+            "Server must be a FastMCP instance or MCP Low-level Server instance"
+        )
+
+    # Check if already tracked
+    if has_mcpcat_data(server):
+        log_info(
+            "MCPCat already initialized for this server",
+            {"server": server.__class__.__name__},
+            options
+        )
+        return server
+
+    # Create and store tracking data
+    data = MCPCatData(options=options)
+    set_mcpcat_data(server, data)
+
+    try:
+        # Set up tool handlers
+        if is_fastmcp_server(server):
+            override_fastmcp(server, data)
+        else:
+            override_lowlevel_mcp_server(server, data)
+
+        # Log initialization
+        log_info(
+            "MCPCat tracking initialized",
+            {
+                "server": server.__class__.__name__,
+                "features": {
+                    "context": options.enableToolCallContext,
+                    "tracing": options.enableTracing,
+                    "report_missing": options.enableReportMissing,
+                }
+            },
+            options
+        )
+    except Exception as e:
+        # Clean up on failure
+        if has_mcpcat_data(server):
+            # Remove from tracking
+            get_mcpcat_data(server)  # This will remove the weak reference
+
+        log_error(
+            "Failed to initialize MCPCat",
+            e,
+            {"server": server.__class__.__name__},
+            options
+        )
+
+        raise
+
+    # Return the server (like TypeScript version)
+    return server
+
+
+def _getServerTrackingData(server: Any) -> MCPCatData | None:
+    """Get server tracking data (for testing)."""
+    return get_mcpcat_data(server)
+
+__all__ = [
+    "track",
+    "get_unknown_or_stdio_session",
+    "_getServerTrackingData",
+    "handleReportMissing",
+    "MCPCatOptions",
+    "UserData",
+    "__version__",
+]

mcpcat/modules/__init__.py

@@ -0,0 +1,38 @@
+"""MCPCat modules."""
+
+from .compatibility import is_compatible_server, is_fastmcp_server
+from .context_parameters import (
+    add_context_parameter_to_schema,
+    add_context_parameter_to_tools,
+)
+from .internal import get_mcpcat_data, has_mcpcat_data, set_mcpcat_data
+from .logging import log_error, log_info, log_trace, log_warning
+from .session import capture_session_info, get_unknown_or_stdio_session
+from .tools import handle_report_missing
+from .tracing import record_trace
+
+__all__ = [
+    # Compatibility
+    "is_compatible_server",
+    "is_fastmcp_server",
+    # Context parameters
+    "add_context_parameter_to_schema",
+    "add_context_parameter_to_tools",
+    # Internal
+    "get_mcpcat_data",
+    "has_mcpcat_data",
+    "set_mcpcat_data",
+    # Logging
+    "log_error",
+    "log_info",
+    "log_trace",
+    "log_warning",
+    # Redaction
+    # Session
+    "get_unknown_or_stdio_session",
+    "capture_session_info",
+    # Tools
+    "handle_report_missing",
+    # Tracing
+    "record_trace",
+]

mcpcat/modules/compatibility.py

@@ -0,0 +1,63 @@
+"""Compatibility checks for MCP servers."""
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class MCPServerProtocol(Protocol):
+    """Protocol for MCP server compatibility."""
+
+    def list_tools(self) -> Any:
+        """List available tools."""
+        ...
+
+    def call_tool(self, name: str, arguments: dict) -> Any:
+        """Call a tool by name."""
+        ...
+
+
+def is_fastmcp_server(server: Any) -> bool:
+    """Check if the server is a FastMCP instance."""
+    # Check for FastMCP class name or specific attributes
+    return hasattr(server, "_mcp_server")
+
+def has_neccessary_attributes(server: Any) -> bool:
+    """Check if the server has necessary attributes for compatibility."""
+    required_methods = ["list_tools", "call_tool"]
+    
+    # Check for core methods that both FastMCP and Server implementations have
+    for method in required_methods:
+        if not hasattr(server, method):
+            return False
+    
+    # For FastMCP servers, verify internal MCP server exists
+    if hasattr(server, "_mcp_server"):
+        # FastMCP server - check that internal MCP server has request_context
+        # Use dir() to avoid triggering property getters that might raise exceptions
+        if "request_context" not in dir(server._mcp_server):
+            return False
+        # Check for get_context method which is FastMCP specific
+        if not hasattr(server, "get_context"):
+            return False
+        # Check for request_handlers dictionary on internal server
+        if not hasattr(server._mcp_server, "request_handlers"):
+            return False
+        if not isinstance(server._mcp_server.request_handlers, dict):
+            return False
+    else:
+        # Regular Server implementation - check for request_context directly
+        # Use dir() to avoid triggering property getters that might raise exceptions
+        if "request_context" not in dir(server):
+            return False
+        # Check for request_handlers dictionary
+        if not hasattr(server, "request_handlers"):
+            return False
+        if not isinstance(server.request_handlers, dict):
+            return False
+    
+    return True
+
+
+def is_compatible_server(server: Any) -> bool:
+    """Check if the server is compatible with MCPCat."""
+    return has_neccessary_attributes(server)

mcpcat/modules/context_parameters.py

@@ -0,0 +1,52 @@
+"""Context parameter injection for MCP tools."""
+
+from typing import Any
+
+
+def add_context_parameter_to_tools(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Add context parameter to tool schemas."""
+    modified_tools = []
+
+    for tool in tools:
+        # Create a copy to avoid modifying original
+        modified_tool = tool.copy()
+
+        if "inputSchema" in modified_tool:
+            modified_tool["inputSchema"] = add_context_parameter_to_schema(
+                modified_tool["inputSchema"]
+            )
+
+        modified_tools.append(modified_tool)
+
+    return modified_tools
+
+
+def add_context_parameter_to_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    """Add context parameter to a JSON schema."""
+    # Create a copy to avoid modifying original
+    modified_schema = schema.copy()
+
+    # Ensure properties exists
+    if "properties" not in modified_schema:
+        modified_schema["properties"] = {}
+    else:
+        # Deep copy properties
+        modified_schema["properties"] = modified_schema["properties"].copy()
+
+    # Add context parameter
+    modified_schema["properties"]["context"] = {
+        "type": "string",
+        "description": "Describe why you are calling this tool and how it fits into your overall task"
+    }
+
+    # Add to required fields
+    if "required" not in modified_schema:
+        modified_schema["required"] = []
+    else:
+        # Copy required list
+        modified_schema["required"] = list(modified_schema["required"])
+
+    if "context" not in modified_schema["required"]:
+        modified_schema["required"].append("context")
+
+    return modified_schema

mcpcat/modules/internal.py

@@ -0,0 +1,40 @@
+"""Internal data storage for MCPCat."""
+
+import weakref
+from typing import Any
+
+from ..types import MCPCatData
+from .compatibility import is_fastmcp_server
+
+# WeakKeyDictionary to store data associated with server instances
+_server_data_map: weakref.WeakKeyDictionary[Any, MCPCatData] = weakref.WeakKeyDictionary()
+
+
+def set_mcpcat_data(server: Any, data: MCPCatData) -> None:
+    """Store MCPCat data for a server instance."""
+    # Always use low-level server as key
+    if is_fastmcp_server(server):
+        key = server._mcp_server
+    else:
+        key = server
+    _server_data_map[key] = data
+
+
+def get_mcpcat_data(server: Any) -> MCPCatData | None:
+    """Retrieve MCPCat data for a server instance."""
+    # Always use low-level server as key
+    if is_fastmcp_server(server):
+        key = server._mcp_server
+    else:
+        key = server
+    return _server_data_map.get(key)
+
+
+def has_mcpcat_data(server: Any) -> bool:
+    """Check if a server instance has MCPCat data."""
+    # Always use low-level server as key
+    if is_fastmcp_server(server):
+        key = server._mcp_server
+    else:
+        key = server
+    return key in _server_data_map

mcpcat/modules/logging.py

@@ -0,0 +1,128 @@
+"""Logging functionality for MCPCat."""
+
+import json
+import os
+from datetime import datetime
+from typing import Any
+
+from ..types import MCPCatOptions, Trace
+
+logPath = "mcpcat.log"  # Default log file path
+
+async def log_trace(trace: Trace, options: MCPCatOptions) -> None:
+    """Log a tool call trace."""
+    # Convert Trace to dict using Pydantic's model_dump
+    log_data = trace.model_dump()
+    # Convert datetime to ISO format string for JSON serialization
+    log_data["timestamp"] = trace.timestamp.isoformat()
+
+    # Apply redaction if configured and function exists
+    if hasattr(options, 'redactSensitiveInformation') and options.redactSensitiveInformation is not None:
+        if log_data.get("context"):
+            log_data["context"] = await redact_message(log_data["context"], options)
+        if log_data.get("arguments"):
+            log_data["arguments"] = await redact_message(log_data["arguments"], options)
+        if log_data.get("response"):
+            log_data["response"] = await redact_message(log_data["response"], options)
+
+    _write_log(log_data, options)
+
+
+def log_info(message: str, data: dict[str, Any], options: MCPCatOptions) -> None:
+    """Log an informational message."""
+    log_data = {
+        "timestamp": datetime.now().isoformat(),
+        "event": "info",
+        "message": message,
+        **data
+    }
+
+    _write_log(log_data, options)
+
+
+def log_warning(message: str, data: dict[str, Any], options: MCPCatOptions) -> None:
+    """Log a warning message."""
+    log_data = {
+        "timestamp": datetime.now().isoformat(),
+        "event": "warning",
+        "message": message,
+        **data
+    }
+
+    _write_log(log_data, options)
+
+
+def log_error(message: str, error: Exception, data: dict[str, Any], options: MCPCatOptions) -> None:
+    """Log an error message."""
+    log_data = {
+        "timestamp": datetime.now().isoformat(),
+        "event": "error",
+        "message": message,
+        "error": str(error),
+        "error_type": type(error).__name__,
+        **data
+    }
+
+    _write_log(log_data, options)
+
+
+def _write_log(log_data: dict[str, Any], options: MCPCatOptions) -> None:
+    """Write log data to file."""
+    try:
+        # Ensure log directory exists
+        log_dir = os.path.dirname(logPath)
+        if log_dir and not os.path.exists(log_dir):
+            os.makedirs(log_dir, exist_ok=True)
+
+        # Write to log file in JSON format
+        with open(logPath, "a") as f:
+            f.write(json.dumps(log_data) + "\n")
+    except Exception:
+        # Silently fail - we don't want logging errors to break the server
+        pass
+
+
+def write_to_log(message: str, options: MCPCatOptions) -> None:
+    """Write a simple text message to log (TypeScript-compatible format)."""
+    timestamp = datetime.now().isoformat()
+    log_entry = f"[{timestamp}] {message}\n"
+
+    try:
+        # Ensure log directory exists
+        log_dir = os.path.dirname(logPath)
+        if log_dir and not os.path.exists(log_dir):
+            os.makedirs(log_dir, exist_ok=True)
+
+        # Write to log file
+        with open(logPath, "a") as f:
+            f.write(log_entry)
+    except Exception:
+        # Silently fail - we don't want logging errors to break the server
+        pass
+
+
+async def redact_message(message: str, options: MCPCatOptions) -> str:
+    """Apply redaction to a message if enabled."""
+    if not hasattr(options, 'redactSensitiveInformation'):
+        return message
+
+    try:
+        if options.redactSensitiveInformation:
+            return await options.redactSensitiveInformation(message)
+        return message
+    except Exception as e:
+        write_to_log(f"Warning: Failed to redact message - Error: {e}", options)
+        return message
+
+
+async def log_with_session(server, session_id: str, user_id: str | None, message: str, options: MCPCatOptions) -> None:
+    """Log a message with session information (TypeScript-compatible format)."""
+    try:
+        user_info = f" (User: {user_id})" if user_id else ""
+        full_message = f"[Session: {session_id}{user_info}] {message}"
+
+        # Apply redaction
+        redacted_message = await redact_message(full_message, options)
+        write_to_log(redacted_message, options)
+    except Exception as e:
+        write_to_log(f"Warning: Failed to log message - {e}", options)

mcpcat/modules/overrides/fastmcp.py

@@ -0,0 +1,31 @@
+from typing import Any, TYPE_CHECKING
+
+from mcp import ServerResult, Tool
+from mcp.types import CallToolRequest, CallToolResult, ListToolsRequest, TextContent
+
+from mcpcat.modules.overrides.mcp_server import override_lowlevel_mcp_server
+from mcpcat.modules.tools import handle_report_missing
+from mcpcat.modules.tracing import record_trace
+
+from ...types import MCPCatData
+from ..logging import log_info, log_warning
+from ..session import capture_session_info
+from ..version_detection import has_fastmcp_support
+
+"""Tool management and interception for MCPCat."""
+
+if TYPE_CHECKING or has_fastmcp_support():
+    try:
+        from mcp.server import FastMCP
+    except ImportError:
+        FastMCP = None
+else:
+    FastMCP = None
+
+
+def override_fastmcp(server: Any, data: MCPCatData) -> None:
+    """Set up tool list and call handlers for FastMCP."""
+    if FastMCP is None:
+        raise ImportError("FastMCP is not available in this MCP version")
+    from mcp.types import CallToolResult, ListToolsResult
+    override_lowlevel_mcp_server(server._mcp_server, data)

mcpcat/modules/overrides/mcp_server.py

@@ -0,0 +1,160 @@
+from typing import Any
+
+from mcp import ServerResult, Tool
+from mcp.server import Server
+from mcp.types import CallToolRequest, CallToolResult, ListToolsRequest, TextContent
+
+from mcpcat.modules.tools import handle_report_missing
+from mcpcat.modules.tracing import record_trace
+
+from ...types import MCPCatData
+from ..logging import log_info, log_warning
+from ..session import capture_session_info
+
+"""Tool management and interception for MCPCat."""
+
+
+def override_lowlevel_mcp_server(server: Server, data: MCPCatData) -> None:
+    """Set up tool list and call handlers for FastMCP."""
+    from mcp.types import CallToolResult, ListToolsResult
+
+    # Store original request handlers - we only need to intercept at the low-level
+    original_call_tool_handler = server.request_handlers.get(CallToolRequest)
+    original_list_tools_handler = server.request_handlers.get(ListToolsRequest)
+
+    async def wrapped_list_tools_handler(request: ListToolsRequest) -> ServerResult:
+        """Intercept list_tools requests to add MCPCat tools and modify existing ones."""
+        # Call the original handler to get the tools
+        original_result = await original_list_tools_handler(request)
+        if not original_result or not hasattr(original_result, 'root') or not hasattr(original_result.root, 'tools'):
+            return original_result
+        tools_list = original_result.root.tools
+
+        # Add report_missing tool if enabled
+        if data.options.enableReportMissing:
+            report_missing_tool = Tool(
+                name="report_missing",
+                description="Report when a tool you need is missing from this server",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "missing_tool": {
+                            "type": "string",
+                            "description": "Name of the missing tool"
+                        },
+                        "description": {
+                            "type": "string",
+                            "description": "Description of what the tool should do"
+                        }
+                    },
+                    "required": ["missing_tool", "description"]
+                }
+            )
+            tools_list.append(report_missing_tool)
+
+        # Add context parameters to existing tools if enabled
+        if data.options.enableToolCallContext:
+            for tool in tools_list:
+                if tool.name != "report_missing":  # Don't modify our own tool
+                    if not tool.inputSchema:
+                        tool.inputSchema = {
+                            "type": "object",
+                            "properties": {},
+                            "required": []
+                        }
+
+                    # Add context property if it doesn't exist
+                    if "context" not in tool.inputSchema.get("properties", {}):
+                        if "properties" not in tool.inputSchema:
+                            tool.inputSchema["properties"] = {}
+
+                        tool.inputSchema["properties"]["context"] = {
+                            "type": "string",
+                            "description": "Describe why you are calling this tool and how it fits into your overall task"
+                        }
+
+                        # Add context to required array if it exists
+                        if isinstance(tool.inputSchema.get("required"), list):
+                            if "context" not in tool.inputSchema["required"]:
+                                tool.inputSchema["required"].append("context")
+                        else:
+                            tool.inputSchema["required"] = ["context"]
+
+        return ServerResult(ListToolsResult(tools=tools_list))
+
+    async def wrapped_call_tool_handler(request: CallToolRequest) -> ServerResult:
+        """Intercept call_tool requests to add MCPCat tracking and handle special tools."""
+        tool_name = request.params.name
+        arguments = request.params.arguments or {}
+
+        # Handle report_missing tool directly
+        if tool_name == "report_missing":
+            return await handle_report_missing(arguments, data)
+
+        # Extract MCPCat context if enabled
+        mcpcat_user_context = None
+        if data.options.enableToolCallContext:
+            mcpcat_user_context = arguments.pop("context", None)
+            # Log warning if context is missing and tool is not report_missing
+            if mcpcat_user_context is None and tool_name != "report_missing":
+                log_warning("Missing context parameter", {"tool_name": tool_name}, data.options)
+
+        # Get session info for tracking
+        try:
+            request_context = server.request_context
+            session_id, user_id = await capture_session_info(server, arguments=arguments, request_context=request_context)
+        except:
+            request_context = None
+            session_id, user_id = None, None
+
+        # If tracing is enabled, wrap the call with timing and logging
+        if data.options.enableTracing:
+            import time
+            start_time = time.time()
+
+            try:
+                # Call the original handler
+                result = await original_call_tool_handler(request)
+                duration = time.time() - start_time
+
+                # Record the trace using existing infrastructure
+                await record_trace(
+                    server=server,
+                    tool_name=tool_name,
+                    arguments=arguments,
+                    request_context=request_context,
+                    session_id=session_id,
+                    user_id=user_id,
+                    tool_result=result.model_dump() if result else None,
+                    duration=duration,
+                    mcpcat_context=mcpcat_user_context
+                )
+
+                return result
+
+            except Exception as e:
+                duration = time.time() - start_time
+
+                # Record the error trace
+                await record_trace(
+                    server=server,
+                    tool_name=tool_name,
+                    arguments=arguments,
+                    request_context=request_context,
+                    session_id=session_id,
+                    user_id=user_id,
+                    tool_result=None,
+                    duration=duration,
+                    mcpcat_context=mcpcat_user_context,
+                    error=str(e)
+                )
+                # Re-raise the exception
+                raise
+        else:
+            # No tracing, just call the original handler
+            return await original_call_tool_handler(request)
+
+    # Replace only the low-level request handlers
+    server.request_handlers[CallToolRequest] = wrapped_call_tool_handler
+    server.request_handlers[ListToolsRequest] = wrapped_list_tools_handler
+

mcpcat/modules/redaction.py

@@ -0,0 +1,42 @@
+from datafog import DataFog
+from typing import Any
+"""PII redaction for MCPCat logs."""
+
+def create_datafog_redactor():
+    """Create a default Datafog redactor function.
+    Returns a redactor function that uses Datafog for PII detection
+    and replaces all detected PII with '[Redacted by MCPCat]'.
+    Falls back to regex-based redaction if Datafog is not available.
+    """
+    def datafog_redact(data: Any) -> Any:
+        """Redact sensitive information using Datafog."""
+        if isinstance(data, dict):
+            return {k: datafog_redact(v) for k, v in data.items()}
+        elif isinstance(data, list):
+            return [datafog_redact(item) for item in data]
+        elif isinstance(data, str):
+            # Use Datafog to scan and redact with custom replacement
+            redactor = DataFog(operations=["scan", "redact"])
+            # Process the text - Datafog will replace detected PII with [REDACTED]
+            redacted_text = redactor.process_text(data)
+            # Replace Datafog's [REDACTED] with our custom message
+            return redacted_text.replace("[REDACTED]", "[Redacted by MCPCat]")
+        else:
+            return data
+    return datafog_redact
+# Singleton redactor instance
+_default_redactor = None
+def get_default_redactor():
+    """Get or create the singleton default redactor."""
+    global _default_redactor
+    if _default_redactor is None:
+        _default_redactor = create_datafog_redactor()
+    return _default_redactor
+
+
+async def defaultRedactor(text: str) -> str:
+    """Default async redactor function using Datafog."""
+    return text  # For now, just pass through
+    # TODO: Implement actual redaction
+    # redactor = get_default_redactor()
+    # return redactor(text)

mcpcat/modules/session.py

@@ -0,0 +1,85 @@
+"""Session management for MCPCat."""
+
+import uuid
+from datetime import datetime, timedelta
+from typing import Any
+
+from mcp.server import Server
+
+from mcpcat.modules.internal import get_mcpcat_data
+
+from ..types import MCPSession, UserData
+from .logging import log_info, log_warning
+
+
+def get_unknown_or_stdio_session(server: Server) -> str:
+    """Get or create an unknown/STDIO session."""
+    data = get_mcpcat_data(server)
+    now = datetime.now()
+
+    # Check if we have an existing session
+    if data.unknown_session:
+        # Check if session is still valid (30 minutes)
+        if now - data.unknown_session.last_used < timedelta(minutes=30):
+            # Update last used time
+            data.unknown_session.last_used = now
+            return data.unknown_session.id
+
+    # Create new session
+    session_id = str(uuid.uuid4())
+    data.unknown_session = MCPSession(
+        id=session_id,
+        created=now,
+        last_used=now
+    )
+
+    return session_id
+
+
+async def capture_session_info(server: Server, arguments: dict[str, Any] | None = None, request_context: Any | None = None ) -> tuple[str | None, str | None]:
+    """Get session and user ID from request context."""
+    session_id = None
+    user_id = 'unidentified-user-id'
+
+    # Extract session_id from request context if available
+    if request_context is not None:
+        try:
+            session = request_context.session  # assumes .session is always present
+            session_id = getattr(session, "session_id", None) or getattr(session, "id", None)
+        except (ValueError, AttributeError):
+            # No valid session in context
+            pass
+
+    # If session_id is not found, use the unknown session ID for stdio implementations
+    if not session_id:
+        session_id = get_unknown_or_stdio_session(server)
+
+    data = get_mcpcat_data(server)
+
+    found_user_for_session = data.identified_sessions.get(session_id, None)
+    if found_user_for_session:
+        return session_id, found_user_for_session
+
+    # Try custom identification for user data if no user ID is found
+    if data.options.identify:
+        try:
+            # Call identify function with (arguments, context) signature
+            user_data: UserData = await data.options.identify(arguments, request_context)
+            if user_data:
+                user_id = user_data.get("userId")
+                # Store identified session with user ID
+                if user_id:
+                    data.identified_sessions[session_id] = user_id
+                    log_info(f"User identified (ID: {user_id})", {
+                        "userId": user_id,
+                        "sessionId": session_id,
+                        "userData": user_data.get("userData") if user_data else None
+                    }, data.options)
+        except Exception as e:
+            # Log identification errors
+            log_warning(f"Failed to identify session: {str(e)}", {
+                "sessionId": session_id,
+                "error": str(e)
+            }, data.options)
+
+    return session_id, user_id

mcpcat/modules/tools.py

@@ -0,0 +1,39 @@
+"""Tool management and interception for MCPCat."""
+
+from typing import Any, TYPE_CHECKING
+
+from mcp import ServerResult, Tool
+from mcp.types import CallToolRequest, CallToolResult, ListToolsRequest, TextContent
+
+from mcpcat.modules.tracing import record_trace
+from mcpcat.modules.version_detection import has_fastmcp_support
+
+from ..types import MCPCatData
+from .logging import log_info
+from .session import capture_session_info
+
+if TYPE_CHECKING or has_fastmcp_support():
+    try:
+        from mcp.server import FastMCP
+    except ImportError:
+        FastMCP = None
+
+async def handle_report_missing(arguments: dict[str, Any], data: MCPCatData) -> CallToolResult:
+    """Handle the report_missing tool."""
+    missing_tool = arguments.get("missing_tool", "")
+    description = arguments.get("description", "")
+
+    # Log the report
+    log_info("Missing tool reported", {
+        "missing_tool": missing_tool,
+        "description": description,
+    }, data.options)
+
+    return CallToolResult(
+        content=[
+            TextContent(
+                type="text",
+                text=f"Thank you for reporting that you need a '{missing_tool}' tool. This feedback helps improve the server."
+            )
+        ]
+    )

mcpcat/modules/tracing.py

@@ -0,0 +1,101 @@
+"""Tool call tracing for MCPCat."""
+
+import json
+from collections.abc import Sequence
+from datetime import datetime
+from typing import Any
+
+from mcp import Tool
+
+from ..types import Trace
+from .logging import log_trace
+
+
+async def record_trace(
+    server: Any,
+    tool_name: str,
+    arguments: dict[str, Any],
+    request_context: Any,
+    session_id: str | None,
+    user_id: str | None,
+    tool_result: Any,
+    duration: float,
+    mcpcat_context: str | None = None,
+    error: str | None = None
+) -> None:
+    """Record trace information for a tool call."""
+    from .internal import get_mcpcat_data
+    # Check if call result is an error using the isError property or passed error
+    is_error = False
+    response = ""
+    # handle unexpected exception raised
+    if error:
+        response = error
+        is_error = True
+    # handle application error in tool result
+    elif 'isError' in tool_result:
+        is_error = tool_result['isError']
+
+    # handle tool content
+    if tool_result and 'content' in tool_result:
+        # if tool_result is a dict, use its content
+        if isinstance(tool_result['content'], dict) or isinstance(tool_result['content'], Sequence):
+            response = json.dumps(tool_result['content'], separators=(',', ':'))
+        else:
+            response = str(tool_result['content'])
+
+
+    # Get MCPCat data and options
+    data = get_mcpcat_data(server)
+
+    # Store the trace
+    if data:
+        # Debug: verify all values are strings
+        context_value = mcpcat_context or ""
+        arguments_value = json.dumps(arguments, separators=(',', ':'))
+        response_value = response or ""
+
+        trace = Trace(
+            timestamp=datetime.now(),
+            session_id=session_id or "unknown",
+            user_id=user_id or "unknown",
+            event_type="tool_call",
+            tool_name=tool_name,
+            is_error=is_error,
+            duration=duration,
+            context=context_value,
+            arguments=arguments_value,
+            response=response_value
+        )
+        if data.options.enableTracing:
+            data.traces.append(trace)
+            await log_trace(trace, data.options)
+
+def add_user_context_to_existing_tools(toolList: list[Tool]) -> list[Tool]:
+    """Add MCPCat's user intention context to every existing tool."""
+    for tool in toolList:
+        if not tool.inputSchema:
+            tool.inputSchema = {
+                "type": "object",
+                "properties": {},
+                "required": []
+            }
+
+        # Add context property if it doesn't exist
+        if "context" not in tool.inputSchema.get("properties", {}):
+            if "properties" not in tool.inputSchema:
+                tool.inputSchema["properties"] = {}
+
+            tool.inputSchema["properties"]["context"] = {
+                "type": "string",
+                "description": "Describe why you are calling this tool and how it fits into your overall task"
+            }
+
+            # Add context to required array if it exists
+            if isinstance(tool.inputSchema.get("required"), list):
+                if "context" not in tool.inputSchema["required"]:
+                    tool.inputSchema["required"].append("context")
+            else:
+                tool.inputSchema["required"] = ["context"]
+
+    return toolList

mcpcat/modules/version_detection.py

@@ -0,0 +1,47 @@
+"""MCP version detection utilities."""
+
+import importlib.metadata
+from typing import Tuple, Optional
+
+
+def get_mcp_version() -> Optional[str]:
+    """Get the installed MCP version."""
+    try:
+        return importlib.metadata.version("mcp")
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def parse_version(version_str: str) -> Tuple[int, int, int]:
+    """Parse version string to tuple of integers."""
+    parts = version_str.split(".")
+    major = int(parts[0]) if len(parts) > 0 else 0
+    minor = int(parts[1]) if len(parts) > 1 else 0
+    patch = int(parts[2]) if len(parts) > 2 else 0
+    return (major, minor, patch)
+
+
+def has_fastmcp_support() -> bool:
+    """Check if the current MCP version supports FastMCP."""
+    version = get_mcp_version()
+    if not version:
+        return False
+    
+    major, minor, _ = parse_version(version)
+    
+    # FastMCP was introduced after version 1.1
+    if major < 1:
+        return False
+    if major == 1 and minor <= 1:
+        return False
+    
+    return True
+
+
+def can_import_fastmcp() -> bool:
+    """Check if FastMCP can be imported."""
+    try:
+        from mcp.server import FastMCP
+        return True
+    except ImportError:
+        return False

mcpcat/types.py

@@ -0,0 +1,66 @@
+"""Type definitions for MCPCat."""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Optional, TypedDict
+
+from pydantic import BaseModel
+
+# Type alias for identify function
+IdentifyFunction = Callable[[dict[str, Any], Any], Optional["UserData"]]
+# Type alias for redaction function
+RedactionFunction = Callable[[str], str | Awaitable[str]]
+
+# Import default redactor
+from .modules.redaction import defaultRedactor
+
+
+class UserData(TypedDict, total=False):
+    """User identification data."""
+    userId: str
+    userData: dict[str, str] | None
+
+
+@dataclass
+class MCPCatOptions:
+    """Configuration options for MCPCat."""
+    enableToolCallContext: bool = True
+    enableTracing: bool = True
+    enableReportMissing: bool = True
+    identify: IdentifyFunction | None = None
+    redactSensitiveInformation: RedactionFunction | None = defaultRedactor
+
+
+@dataclass
+class MCPSession:
+    """Session information."""
+    id: str
+    created: datetime
+    last_used: datetime
+
+
+class Trace(BaseModel):
+    """Pydantic model for structured trace data."""
+    # Structured fields
+    timestamp: datetime
+    session_id: str
+    user_id: str
+    event_type: str
+    tool_name: str
+    is_error: bool
+    duration: float
+    context: str
+
+    # Unstructured fields
+    arguments: str = ""
+    response: str = ""
+
+
+@dataclass
+class MCPCatData:
+    """Internal data structure for tracking."""
+    options: MCPCatOptions
+    traces: list[Trace] = field(default_factory=list)
+    identified_sessions: dict[str, str] = field(default_factory=dict)
+    unknown_session: MCPSession | None = None

mcpcat-0.1.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: mcpcat
+Version: 0.1.0
+Summary: Analytics Tool for MCP Servers - provides insights into MCP tool usage patterns
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Requires-Python: >=3.10
+Requires-Dist: datafog>=4.1.1
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MCPCat Python SDK
+
+Analytics tool for MCP (Model Context Protocol) servers that provides insights into tool usage patterns.
+
+## Features
+
+- **Tool Usage Analytics**: Tracks which tools are called and how frequently
+- **Context Injection**: Adds context parameters to tools to understand user intent  
+- **Session Tracking**: Identifies and tracks user sessions
+- **Report Missing Tools**: Allows clients to report when needed tools are missing
+- **PII Redaction**: Automatically redacts sensitive information from logs
+- **Non-invasive Integration**: Simple one-line integration with existing MCP servers
+
+## Installation
+
+```bash
+pip install mcpcat
+```
+
+## Quick Start
+
+```python
+from fastmcp import FastMCP
+from mcpcat import track
+
+# Create your MCP server
+mcp = FastMCP("my-server")
+
+# Add your tools
+@mcp.tool()
+def my_tool(arg: str) -> str:
+    return f"Result: {arg}"
+
+# Enable MCPCat tracking
+track(mcp)
+
+# Run the server
+mcp.run()
+```
+
+## Configuration
+
+MCPCat can be configured with various options:
+
+```python
+from mcpcat import track, MCPCatOptions
+
+options = MCPCatOptions(
+    enableToolCallContext=True,   # Add context parameters to tools
+    enableTracing=True,           # Trace tool calls
+    enableReportMissing=True,     # Add report_missing tool
+    identify=my_identify_func     # Custom session identification
+)
+
+track(mcp, options)
+```
+
+## How It Works
+
+1. MCPCat intercepts the MCP server's tool listing and calling mechanisms
+2. It injects a `context` parameter into each tool's schema
+3. When tools are called, it captures analytics data including timing, arguments, and results
+4. The `report_missing` tool allows LLMs to report when they need functionality that isn't available
+
+## Custom Session Identification
+
+You can provide a custom function to identify users:
+
+```python
+def identify_user(request_context):
+    # Your logic to identify the user
+    return {
+        "sessionId": "session-123",
+        "userId": "user-456"
+    }
+
+options = MCPCatOptions(identify=identify_user)
+```
+
+## Log Format
+
+MCPCat logs are written in JSON format with the following structure:
+
+```json
+{
+  "timestamp": "2024-01-20T10:30:00Z",
+  "event": "tool_call",
+  "tool_name": "my_tool",
+  "session_id": "session-123",
+  "user_id": "user-456",
+  "duration": 0.123,
+  "result": "success",
+  "context_provided": true
+}
+```
+
+## Development
+
+To set up for development:
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/mcpcat-python-sdk.git
+cd mcpcat-python-sdk
+
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run type checking
+mypy src
+
+# Run linting
+ruff check src
+```
+
+## License
+
+MIT

mcpcat-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+mcpcat/__init__.py,sha256=4wfzE16AWIOR0SyA_4cBt_93LcJF6pkHWV4E83FBgjo,3151
+mcpcat/types.py,sha256=rfclJNO3snn2RB31lSqmXt5Hy7vEPKeRtKqo5haze1o,1671
+mcpcat/modules/__init__.py,sha256=xUtsS9mcbN55RsGs6U6jcQAHbDCo6eNgwy8dPBFm13E,1009
+mcpcat/modules/compatibility.py,sha256=QbJIS3u7Mcf6JZ6JbOV34za-LxFD8LDvpdR3s4M-aE0,2322
+mcpcat/modules/context_parameters.py,sha256=1jrVP3LfqlU7ePOtQE96RsPkdsEkGlU5fZS4DhtIUaE,1626
+mcpcat/modules/internal.py,sha256=xbA643LUGQjnLDHRXnb3eRf5rC2vh-5DCRxL3vIeZqI,1159
+mcpcat/modules/logging.py,sha256=sKCgOeDUnPUGnfDoLgsGkrptp5D4XTwxoIuGZJf2W_M,4317
+mcpcat/modules/redaction.py,sha256=VTP2sUEXY3nEtWrL7nSJys5wt905NFvgt5d3Sb7jRTk,1735
+mcpcat/modules/session.py,sha256=vWNfNAYBg4r-8xohiikM5VUnKpy2dphTZaQJT9rsqtk,3062
+mcpcat/modules/tools.py,sha256=VNwj7dbgEUgKBnxZ2AqJggAONmpOOWqdCdqz4vMoMHo,1225
+mcpcat/modules/tracing.py,sha256=n2R7C-HsCWc97rYde0_e9LaGaG8FDltRYK5-KP8P7A0,3321
+mcpcat/modules/version_detection.py,sha256=IAZJzwC7XR76sq602kv6MoEGU8lv0GvOlW-y2AyXMCo,1231
+mcpcat/modules/overrides/fastmcp.py,sha256=Ghr6dG97apbmS91Zkx14VDKCl2c1fISQ44AeO4Yeh0Q,1064
+mcpcat/modules/overrides/mcp_server.py,sha256=6y51YUho1qGb3mLpYXcMEDryEKqgL_4Agl1bfJ7vOaQ,6892
+mcpcat-0.1.0.dist-info/METADATA,sha256=qdJ_a-z3PRJplfs0Dcd5bHDMepzbFyygUEdMHRPvTd8,3545
+mcpcat-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcpcat-0.1.0.dist-info/RECORD,,

mcpcat-0.1.0.dist-info/WHEEL

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