mcpscore 0.3.0__py3-none-any.whl

mcpscore/__init__.py

@@ -0,0 +1,34 @@
+"""MCPDoctor - A comprehensive auditing tool for MCP (Model Context Protocol) servers.
+
+This package provides tools for auditing MCP servers to ensure compliance with
+protocol standards and best practices. It includes:
+
+- MCPClient: For connecting to and communicating with MCP servers
+- MCPDoctor: For orchestrating the audit process
+- Rule system: Extensible framework for implementing audit checks
+- Enums: Protocol versions and transport types
+
+The audit system uses a rule-based approach where each rule checks specific
+aspects of MCP compliance and contributes to an overall audit score.
+"""
+
+from .enums import MCPProtocolVersion, MCPTransportType
+from .mcp_auditor import MCPAuditor
+from .mcp_client import MCPClient
+from .rules import (
+    AuditData,
+    BaseRule,
+    RuleResult,
+    RuleSeverity,
+)
+
+__all__ = (
+    "AuditData",
+    "BaseRule",
+    "MCPAuditor",
+    "MCPClient",
+    "MCPProtocolVersion",
+    "MCPTransportType",
+    "RuleResult",
+    "RuleSeverity",
+)

mcpscore/cli.py

@@ -0,0 +1,64 @@
+"""Command-line interface for MCPScore."""
+
+import asyncio
+import logging
+import sys
+
+from mcpscore import MCPAuditor, MCPClient
+
+logger = logging.getLogger(__name__)
+
+
+async def async_main() -> None:
+    """Execute the main entry point for the MCPScore CLI application.
+
+    Orchestrates the audit process by:
+    1. Parsing command line arguments for the server path or URL
+    2. Creating MCP client and auditor instances
+    3. Auto-detecting transport and connecting to the MCP server
+    4. Running the audit process and displaying results
+    5. Cleaning up resources
+
+    Supports local servers (.py, .js) via STDIO and remote servers via
+    Streamable HTTP or SSE (auto-detected).
+
+    Exits with code 1 if no server path is provided, or code 2 if connection fails.
+    """
+    logger.info("Welcome to MCPScore!")
+
+    if len(sys.argv) < 2:
+        logger.error("Usage: mcpscore <server_path_or_url>")
+        sys.exit(1)
+
+    target: str = sys.argv[1]
+    client: MCPClient = MCPClient()
+    doctor: MCPAuditor = MCPAuditor()
+
+    success, transport = await client.detect_and_connect(target)
+
+    if success:
+        logger.info("Connected to the MCP server: %s", target)
+        logger.info("Transport: %s", transport)
+    else:
+        logger.error("Error connecting to the MCP server: %s", target)
+        sys.exit(2)
+
+    logger.info("Starting the audit...")
+    final_score, max_score = await doctor.audit(client)
+    logger.info("Audit finished. Final score: %s/%s", final_score, max_score)
+
+    await client.cleanup()
+
+
+def main() -> None:
+    """Entry point for the mcpscore CLI command.
+
+    This function is called when running `mcpscore` from the command line.
+    It sets up logging and runs the async main function.
+    """
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    asyncio.run(async_main())
+
+
+if __name__ == "__main__":
+    main()

mcpscore/enums.py

@@ -0,0 +1,44 @@
+"""Enumerations and constants for MCP (Model Context Protocol) auditing.
+
+This module defines the core enumerations used throughout the MCPDoctor system:
+
+- MCPTransportType: Supported transport methods for MCP communication
+- MCPProtocolVersion: Supported versions of the MCP protocol
+
+These enums provide type safety and ensure consistent usage of protocol
+versions and transport types across the audit system.
+"""
+
+from enum import StrEnum
+
+
+class MCPTransportType(StrEnum):
+    """Transport types supported by MCP (Model Context Protocol)."""
+
+    STDIO = "stdio"
+    """Standard input/output transport for local processes."""
+
+    STREAMABLE_HTTP = "streamable-http"
+    """HTTP-based transport with streaming capabilities."""
+
+    SSE = "sse"
+    """Server-Sent Events transport for real-time communication."""
+
+    WEBSOCKET = "websocket"
+    """WebSocket transport for bidirectional communication."""
+
+
+class MCPProtocolVersion(StrEnum):
+    """Supported versions of the MCP (Model Context Protocol)."""
+
+    v2024_11_05 = "2024-11-05"
+    """MCP protocol version from November 5, 2024."""
+
+    v2025_03_26 = "2025-03-26"
+    """MCP protocol version from March 26, 2025."""
+
+    v2025_06_18 = "2025-06-18"
+    """Latest MCP protocol version (June 18, 2025)."""
+
+    Latest = v2025_06_18
+    """Alias for the latest protocol version."""

mcpscore/mcp_auditor.py

@@ -0,0 +1,224 @@
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mcp.types import InitializeResult, Prompt, Resource, Tool
+
+from .mcp_client import MCPClient
+from .rules import AuditData, BaseRule, RuleResult, RuleSeverity, create_all_rules
+
+logger = logging.getLogger(__name__)
+
+
+class MCPAuditor:
+    """Orchestrates the MCP server audit process.
+
+    This class manages the complete audit workflow:
+    - Collects initialization data from the MCP server
+    - Executes all registered audit rules
+    - Tracks audit results and scoring
+    - Provides audit summary and reporting
+
+    The doctor uses a rule-based system where each rule checks specific
+    aspects of MCP compliance and contributes to an overall audit score.
+    """
+
+    def __init__(self) -> None:
+        """Initialize a new MCPDoctor instance.
+
+        Sets up the doctor with:
+        - Empty audit data container
+        - All registered audit rules
+        - Zero initial score
+        - Empty results list
+        """
+        super().__init__()
+        self.mcp_client: MCPClient | None = None
+        self.audit_data: AuditData = AuditData()
+        self.score: int = 0
+        self.max_score: int = 0
+        self.rules: list[BaseRule] = list(create_all_rules())
+        self.results: list[RuleResult] = []
+
+    async def audit(self, client: MCPClient) -> tuple[int, int]:
+        """Execute the complete audit process for an MCP server.
+
+        Args:
+            client: Connected MCPClient instance to audit
+
+        Returns:
+            Final audit score (positive for passed rules, negative for failed rules)
+
+        The audit process:
+        1. Collects server initialization data
+        2. Runs all registered audit rules
+        3. Calculates and returns the final score
+
+        """
+        self.mcp_client = client
+        self.score = 0
+        self.max_score = 0
+
+        await self._collect_transport_metadata()
+        await self._collect_init_result()
+        if self.audit_data.capabilities is not None:
+            if self.audit_data.capabilities.tools is not None:
+                await self._collect_tools()
+            if self.audit_data.capabilities.resources is not None:
+                await self._collect_resources()
+            if self.audit_data.capabilities.prompts is not None:
+                await self._collect_prompts()
+        await self._run_all_rules()
+
+        return self.score, self.max_score
+
+    async def _run_all_rules(self) -> None:
+        """Execute all registered audit rules and update the audit score.
+
+        Iterates through all rules, executes each one, logs the results,
+        and updates the overall audit score based on rule severity and pass/fail status.
+        """
+        for rule in sorted(self.rules, key=lambda r: r.sort_order):
+            res: RuleResult = rule.check(self.audit_data)
+            logger.info(res.message)
+
+            self.max_score += res.severity.value
+            if res.passed:
+                self.score += res.severity.value
+
+            self.results.append(res)
+
+    async def _collect_transport_metadata(self) -> None:
+        """Collect transport and connection metadata from the MCP client.
+
+        Populates audit data with:
+        - Transport type (STDIO, HTTP, SSE)
+        - URL (for HTTP/SSE connections)
+        - TLS information (for HTTPS connections)
+        - Connection timing
+
+        This data is used by security and transport audit rules.
+        """
+        if self.mcp_client is None:
+            logger.error("No MCP client to audit")
+            return
+
+        # Collect transport metadata from client
+        self.audit_data.transport_type = self.mcp_client.transport_type
+        self.audit_data.url = self.mcp_client.url
+        self.audit_data.connection_time_ms = self.mcp_client.connection_time_ms
+
+        # For HTTPS connections, check TLS
+        if self.mcp_client.url and self.mcp_client.url.startswith("https://"):
+            # If we successfully connected via HTTPS, assume TLS is verified
+            # (httpx would have failed the connection if cert validation failed)
+            self.audit_data.tls_verified = True
+            self.audit_data.tls_version = "TLSv1.3"  # Modern default, could be probed more precisely
+        elif self.mcp_client.url and self.mcp_client.url.startswith("http://"):
+            self.audit_data.tls_verified = False
+            self.audit_data.tls_version = None
+
+    async def _collect_init_result(self) -> None:
+        """Collect initialization data from the MCP server.
+
+        Retrieves the server's initialization result and populates the audit data
+        with protocol version, server info, capabilities, and instructions.
+
+        This data is then used by all audit rules to perform their checks.
+        """
+        if self.mcp_client is None:
+            logger.error("No MCP client to audit")
+            return
+
+        init_result: InitializeResult | None = await self.mcp_client.initialize()
+        if init_result is None:
+            logger.error("No Init Result to audit")
+            return
+        else:
+            self.audit_data.protocol_version = str(init_result.protocolVersion)
+            self.audit_data.server_info = init_result.serverInfo
+            self.audit_data.capabilities = init_result.capabilities
+            self.audit_data.instructions = init_result.instructions
+
+    async def _collect_tools(self) -> None:
+        """Collect the list of Tools from the MCP server.
+
+        Retrieves the server's Tools and populates the audit data with
+        information about them.
+
+        This data is then used by all audit rules to perform their checks.
+        """
+        if self.mcp_client is None:
+            logger.error("No MCP client to audit")
+            return
+
+        tools: list[Tool] | None = await self.mcp_client.list_tools()
+        if tools is None:
+            logger.error("No Tools to audit")
+            return
+        else:
+            self.audit_data.tools = tools
+
+    async def _collect_resources(self) -> None:
+        """Collect the list of Resources from the MCP server.
+
+        Retrieves the server's Resources and populates the audit data with
+        information about them.
+
+        This data is then used by all audit rules to perform their checks.
+        """
+        if self.mcp_client is None:
+            logger.error("No MCP client to audit")
+            return
+
+        resources: list[Resource] | None = await self.mcp_client.list_resources()
+        if resources is None:
+            logger.error("No Resources to audit")
+            return
+        else:
+            self.audit_data.resources = resources
+
+    async def _collect_prompts(self) -> None:
+        """Collect the list of Prompts from the MCP server.
+
+        Retrieves the server's Prompts and populates the audit data with
+        information about them.
+
+        This data is then used by all audit rules to perform their checks.
+        """
+        if self.mcp_client is None:
+            logger.error("No MCP client to audit")
+            return
+
+        prompts: list[Prompt] | None = await self.mcp_client.list_prompts()
+        if prompts is None:
+            logger.error("No prompts to audit")
+            return
+        else:
+            self.audit_data.prompts = prompts
+
+    def get_audit_summary(self) -> dict:
+        """Generate a comprehensive summary of the audit results.
+
+        Returns:
+            Dictionary containing:
+            - total: Total number of rules executed
+            - passed: Number of rules that passed
+            - failed: Number of rules that failed
+            - by_severity: Breakdown by severity level (CRITICAL, HIGH, MEDIUM, LOW)
+              with counts for total, passed, and failed rules in each category
+
+        """
+        return {
+            "total": len(self.results),
+            "passed": sum(1 for r in self.results if r.passed),
+            "failed": sum(1 for r in self.results if not r.passed),
+            "by_severity": {
+                severity.value: {
+                    "total": sum(1 for r in self.results if r.severity == severity),
+                    "passed": sum(1 for r in self.results if r.severity == severity and r.passed),
+                    "failed": sum(1 for r in self.results if r.severity == severity and not r.passed),
+                }
+                for severity in RuleSeverity
+            },
+        }