mcpscore 0.3.0__tar.gz → 0.4.0__tar.gz

{mcpscore-0.3.0 → mcpscore-0.4.0}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.4
 Name: mcpscore
-Version: 0.3.0
+Version: 0.4.0
 Summary: CLI tool to analyze your MCP server and get a comprehensive report on its quality
-Project-URL: Homepage, https://mcp-box.dev
+Project-URL: Homepage, https://mcpaudit.dev
 Project-URL: Repository, https://github.com/mcp-box/mcpscore
 Project-URL: Issues, https://github.com/mcp-box/mcpscore/issues
+Project-URL: Documentation, https://github.com/mcp-box/mcpscore#readme
+Project-URL: Changelog, https://github.com/mcp-box/mcpscore/blob/main/CHANGELOG.md
 Author: Alex Akimov
 License-Expression: MIT
 License-File: LICENSE
-Keywords: ai,audit,cli,developer-tools,llm,mcp,mcp-server,model-context-protocol,quality
+Keywords: ai,audit,cli,compliance,developer-tools,llm,mcp,mcp-audit,mcp-server,model-context-protocol,protocol,quality,validation
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -16,29 +18,61 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Typing :: Typed
-Requires-Python: >=3.13
-Requires-Dist: httpx-sse>=0.4.0
-Requires-Dist: httpx>=0.28.0
-Requires-Dist: mcp>=1.23.0
+Requires-Python: >=3.11
+Requires-Dist: httpx-sse>=0.4.3
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp>=1.27.2
 Description-Content-Type: text/markdown
 
 # MCPScore
 
+[![CI](https://github.com/mcp-box/mcpscore/actions/workflows/ci.yml/badge.svg)](https://github.com/mcp-box/mcpscore/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/mcp-box/mcpscore/graph/badge.svg)](https://codecov.io/gh/mcp-box/mcpscore)
+[![PyPI](https://img.shields.io/pypi/v/mcpscore.svg)](https://pypi.org/project/mcpscore/)
+[![Python](https://img.shields.io/pypi/pyversions/mcpscore.svg)](https://pypi.org/project/mcpscore/)
+[![License](https://img.shields.io/github/license/mcp-box/mcpscore.svg)](LICENSE)
+
 A command-line tool for auditing MCP (Model Context Protocol) servers. MCPScore connects to your server, runs a comprehensive set of validation rules against it, and produces a severity-based report showing what's compliant and what needs attention.
 
+## Why MCPScore?
+
+MCP servers that violate the spec fail silently in the worst place: inside someone else's AI agent. A missing tool description, an outdated protocol version, or an unencrypted endpoint won't crash your server — it will just make agents pick the wrong tool, drop your server from their registry, or leak traffic. MCPScore catches these issues in seconds, before your users do.
+
+```bash
+pip install mcpscore
+mcpscore https://your-server.example/mcp
+```
+
+## How scoring works
+
+Every rule has a severity, and each passing rule contributes its weight to the score:
+
+| Severity | Points | Meaning |
+|----------|--------|---------|
+| CRITICAL | 5 | Spec violations that break interoperability (protocol version, server name, TLS) |
+| HIGH | 3 | Strong spec expectations (server version, valid tool schemas) |
+| MEDIUM | 2 | Recommendations that improve agent UX (titles, descriptions, error hygiene) |
+| LOW | 1 | Nice-to-haves (capability extras, transport recommendations) |
+
+The final score is reported as `earned/maximum` — higher means better MCP compliance.
+
 ## Features
 
 - **Multiple transports**: STDIO (local servers), Streamable HTTP, and SSE (remote servers)
 - **Auto-detection**: Picks the right transport automatically — tries Streamable HTTP first, falls back to SSE for URLs
+- **Real handshake verification**: A connection only counts once the server completes the MCP `initialize` handshake — pointing it at a non-MCP endpoint fails cleanly
 - **Multi-language**: Audits both Python (`.py`) and Node.js (`.js`) MCP servers via STDIO
 - **Severity-based reporting**: Rules categorized as CRITICAL, HIGH, MEDIUM, or LOW
-- **Comprehensive validation**: Protocol compliance, server metadata, capabilities, security, and transport
+- **Library-friendly**: Fully typed (`py.typed`); use `MCPClient` + `MCPAuditor` programmatically
 
 ## What it audits
 
@@ -54,16 +88,19 @@ A command-line tool for auditing MCP (Model Context Protocol) servers. MCPScore
 
 - **Capabilities**: Tools, resources, prompts, logging, and subscription support
 
+- **Tools**: Names (presence, uniqueness, format), titles, descriptions, and JSON Schema validity of input/output schemas
+
 - **Security**:
-  - ✅ HTTPS/TLS usage verification
+  - ✅ HTTPS/TLS usage with the actually negotiated TLS version
   - ✅ Valid certificate checks
+  - ✅ Error responses checked for data leaks
 
 - **Transport**:
-  - ✅ SSE transport support detection
+  - ✅ Streamable HTTP usage (the current MCP standard; SSE-only servers get migration advice)
 
 ## Requirements
 
-- Python 3.13+
+- Python 3.11+
 - Node.js on `PATH` if auditing a Node.js MCP server
 - A Python interpreter on `PATH` if auditing a Python MCP server
 
@@ -101,9 +138,9 @@ Welcome to MCPScore!
 Connected to the MCP server: /path/to/server.py
 Transport: stdio
 Starting the audit...
-✅ Protocol version '2025-06-18' is one of the allowed versions
-✅ Protocol version '2025-06-18' is not deprecated
-✅ Protocol version '2025-06-18' is the latest version
+✅ Protocol version '2025-11-25' is one of the allowed versions
+✅ Protocol version '2025-11-25' is not deprecated
+✅ Protocol version '2025-11-25' is the latest version
 ✅ Server name is present: 'weather'
 ✅ Server version is present: '1.17.0'
 ❌ Server title is not present in server info
@@ -124,23 +161,23 @@ Starting the audit...
 Audit finished. Final score: 55/71
 ```
 
-### Understanding the score
-
-Each passing rule contributes points equal to its severity weight: **CRITICAL = 5, HIGH = 3, MEDIUM = 2, LOW = 1**. Higher scores indicate better compliance with MCP standards.
-
 ## Troubleshooting
 
 **Connection fails**
 
 - Check the path or URL is correct and reachable
 - For local servers, make sure Python or Node.js is on `PATH`
-- Verify the server actually implements the MCP protocol
+- "Not a valid MCP server (handshake failed)" means the endpoint responded but did not complete the MCP `initialize` handshake — verify the URL points at an actual MCP endpoint (often `/mcp`)
 
 **Protocol version errors**
 
 - Confirm your server uses a currently supported MCP protocol version
 - If your server uses a newer version that MCPScore doesn't yet recognize, please [open an issue](https://github.com/mcp-box/mcpscore/issues)
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and how to add audit rules. Security reports: [SECURITY.md](SECURITY.md). Release history: [CHANGELOG.md](CHANGELOG.md).
+
 ## Feedback
 
 Bug reports, feature requests, and general feedback are welcome at <https://github.com/mcp-box/mcpscore/issues>.

{mcpscore-0.3.0 → mcpscore-0.4.0}/README.md

@@ -1,14 +1,43 @@
 # MCPScore
 
+[![CI](https://github.com/mcp-box/mcpscore/actions/workflows/ci.yml/badge.svg)](https://github.com/mcp-box/mcpscore/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/mcp-box/mcpscore/graph/badge.svg)](https://codecov.io/gh/mcp-box/mcpscore)
+[![PyPI](https://img.shields.io/pypi/v/mcpscore.svg)](https://pypi.org/project/mcpscore/)
+[![Python](https://img.shields.io/pypi/pyversions/mcpscore.svg)](https://pypi.org/project/mcpscore/)
+[![License](https://img.shields.io/github/license/mcp-box/mcpscore.svg)](LICENSE)
+
 A command-line tool for auditing MCP (Model Context Protocol) servers. MCPScore connects to your server, runs a comprehensive set of validation rules against it, and produces a severity-based report showing what's compliant and what needs attention.
 
+## Why MCPScore?
+
+MCP servers that violate the spec fail silently in the worst place: inside someone else's AI agent. A missing tool description, an outdated protocol version, or an unencrypted endpoint won't crash your server — it will just make agents pick the wrong tool, drop your server from their registry, or leak traffic. MCPScore catches these issues in seconds, before your users do.
+
+```bash
+pip install mcpscore
+mcpscore https://your-server.example/mcp
+```
+
+## How scoring works
+
+Every rule has a severity, and each passing rule contributes its weight to the score:
+
+| Severity | Points | Meaning |
+|----------|--------|---------|
+| CRITICAL | 5 | Spec violations that break interoperability (protocol version, server name, TLS) |
+| HIGH | 3 | Strong spec expectations (server version, valid tool schemas) |
+| MEDIUM | 2 | Recommendations that improve agent UX (titles, descriptions, error hygiene) |
+| LOW | 1 | Nice-to-haves (capability extras, transport recommendations) |
+
+The final score is reported as `earned/maximum` — higher means better MCP compliance.
+
 ## Features
 
 - **Multiple transports**: STDIO (local servers), Streamable HTTP, and SSE (remote servers)
 - **Auto-detection**: Picks the right transport automatically — tries Streamable HTTP first, falls back to SSE for URLs
+- **Real handshake verification**: A connection only counts once the server completes the MCP `initialize` handshake — pointing it at a non-MCP endpoint fails cleanly
 - **Multi-language**: Audits both Python (`.py`) and Node.js (`.js`) MCP servers via STDIO
 - **Severity-based reporting**: Rules categorized as CRITICAL, HIGH, MEDIUM, or LOW
-- **Comprehensive validation**: Protocol compliance, server metadata, capabilities, security, and transport
+- **Library-friendly**: Fully typed (`py.typed`); use `MCPClient` + `MCPAuditor` programmatically
 
 ## What it audits
 
@@ -24,16 +53,19 @@ A command-line tool for auditing MCP (Model Context Protocol) servers. MCPScore
 
 - **Capabilities**: Tools, resources, prompts, logging, and subscription support
 
+- **Tools**: Names (presence, uniqueness, format), titles, descriptions, and JSON Schema validity of input/output schemas
+
 - **Security**:
-  - ✅ HTTPS/TLS usage verification
+  - ✅ HTTPS/TLS usage with the actually negotiated TLS version
   - ✅ Valid certificate checks
+  - ✅ Error responses checked for data leaks
 
 - **Transport**:
-  - ✅ SSE transport support detection
+  - ✅ Streamable HTTP usage (the current MCP standard; SSE-only servers get migration advice)
 
 ## Requirements
 
-- Python 3.13+
+- Python 3.11+
 - Node.js on `PATH` if auditing a Node.js MCP server
 - A Python interpreter on `PATH` if auditing a Python MCP server
 
@@ -71,9 +103,9 @@ Welcome to MCPScore!
 Connected to the MCP server: /path/to/server.py
 Transport: stdio
 Starting the audit...
-✅ Protocol version '2025-06-18' is one of the allowed versions
-✅ Protocol version '2025-06-18' is not deprecated
-✅ Protocol version '2025-06-18' is the latest version
+✅ Protocol version '2025-11-25' is one of the allowed versions
+✅ Protocol version '2025-11-25' is not deprecated
+✅ Protocol version '2025-11-25' is the latest version
 ✅ Server name is present: 'weather'
 ✅ Server version is present: '1.17.0'
 ❌ Server title is not present in server info
@@ -94,23 +126,23 @@ Starting the audit...
 Audit finished. Final score: 55/71
 ```
 
-### Understanding the score
-
-Each passing rule contributes points equal to its severity weight: **CRITICAL = 5, HIGH = 3, MEDIUM = 2, LOW = 1**. Higher scores indicate better compliance with MCP standards.
-
 ## Troubleshooting
 
 **Connection fails**
 
 - Check the path or URL is correct and reachable
 - For local servers, make sure Python or Node.js is on `PATH`
-- Verify the server actually implements the MCP protocol
+- "Not a valid MCP server (handshake failed)" means the endpoint responded but did not complete the MCP `initialize` handshake — verify the URL points at an actual MCP endpoint (often `/mcp`)
 
 **Protocol version errors**
 
 - Confirm your server uses a currently supported MCP protocol version
 - If your server uses a newer version that MCPScore doesn't yet recognize, please [open an issue](https://github.com/mcp-box/mcpscore/issues)
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and how to add audit rules. Security reports: [SECURITY.md](SECURITY.md). Release history: [CHANGELOG.md](CHANGELOG.md).
+
 ## Feedback
 
 Bug reports, feature requests, and general feedback are welcome at <https://github.com/mcp-box/mcpscore/issues>.

{mcpscore-0.3.0 → mcpscore-0.4.0}/mcpscore/__init__.py

@@ -1,10 +1,10 @@
-"""MCPDoctor - A comprehensive auditing tool for MCP (Model Context Protocol) servers.
+"""MCPScore - 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:
 
+- MCPAuditor: For orchestrating the audit process
 - 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
 

{mcpscore-0.3.0 → mcpscore-0.4.0}/mcpscore/cli.py

@@ -32,22 +32,23 @@ async def async_main() -> None:
 
     target: str = sys.argv[1]
     client: MCPClient = MCPClient()
-    doctor: MCPAuditor = MCPAuditor()
+    auditor: 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:
+    if not success:
         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)
+    logger.info("Connected to the MCP server: %s", target)
+    logger.info("Transport: %s", transport)
 
-    await client.cleanup()
+    try:
+        logger.info("Starting the audit...")
+        final_score, max_score = await auditor.audit(client)
+        logger.info("Audit finished. Final score: %s/%s", final_score, max_score)
+    finally:
+        await client.cleanup()
 
 
 def main() -> None:

{mcpscore-0.3.0 → mcpscore-0.4.0}/mcpscore/enums.py

@@ -1,6 +1,6 @@
 """Enumerations and constants for MCP (Model Context Protocol) auditing.
 
-This module defines the core enumerations used throughout the MCPDoctor system:
+This module defines the core enumerations used throughout the MCPScore system:
 
 - MCPTransportType: Supported transport methods for MCP communication
 - MCPProtocolVersion: Supported versions of the MCP protocol
@@ -38,7 +38,14 @@ class MCPProtocolVersion(StrEnum):
     """MCP protocol version from March 26, 2025."""
 
     v2025_06_18 = "2025-06-18"
-    """Latest MCP protocol version (June 18, 2025)."""
+    """MCP protocol version from June 18, 2025."""
 
-    Latest = v2025_06_18
-    """Alias for the latest protocol version."""
+    v2025_11_25 = "2025-11-25"
+    """Latest MCP protocol version (November 25, 2025)."""
+
+    Latest = v2025_11_25
+    """Alias for the latest protocol version.
+
+    This is an enum alias, not a distinct member: it does not appear in
+    `list(MCPProtocolVersion)` or in iteration-derived version lists.
+    """

{mcpscore-0.3.0 → mcpscore-0.4.0}/mcpscore/mcp_auditor.py

@@ -1,5 +1,8 @@
+import asyncio
 import logging
+import ssl
 from typing import TYPE_CHECKING
+from urllib.parse import urlparse
 
 if TYPE_CHECKING:
     from mcp.types import InitializeResult, Prompt, Resource, Tool
@@ -9,6 +12,9 @@ from .rules import AuditData, BaseRule, RuleResult, RuleSeverity, create_all_rul
 
 logger = logging.getLogger(__name__)
 
+TLS_PROBE_TIMEOUT_S = 10
+"""Timeout for probing the negotiated TLS version of an HTTPS server."""
+
 
 class MCPAuditor:
     """Orchestrates the MCP server audit process.
@@ -19,14 +25,14 @@ class MCPAuditor:
     - Tracks audit results and scoring
     - Provides audit summary and reporting
 
-    The doctor uses a rule-based system where each rule checks specific
+    The auditor 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.
+        """Initialize a new MCPAuditor instance.
 
-        Sets up the doctor with:
+        Sets up the auditor with:
         - Empty audit data container
         - All registered audit rules
         - Zero initial score
@@ -68,11 +74,11 @@ class MCPAuditor:
                 await self._collect_resources()
             if self.audit_data.capabilities.prompts is not None:
                 await self._collect_prompts()
-        await self._run_all_rules()
+        self._run_all_rules()
 
         return self.score, self.max_score
 
-    async def _run_all_rules(self) -> None:
+    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,
@@ -110,14 +116,48 @@ class MCPAuditor:
 
         # 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
+            # If we successfully connected via HTTPS, 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
+            self.audit_data.tls_version = await self._probe_tls_version(self.mcp_client.url)
         elif self.mcp_client.url and self.mcp_client.url.startswith("http://"):
             self.audit_data.tls_verified = False
             self.audit_data.tls_version = None
 
+    @staticmethod
+    async def _probe_tls_version(url: str) -> str | None:
+        """Probe the TLS version negotiated with an HTTPS server.
+
+        Opens a short-lived TLS connection to the server and reads the
+        negotiated protocol version (e.g. "TLSv1.3") from the SSL object.
+
+        Returns:
+            The negotiated TLS version string, or None if it could not be
+            determined (the TLS rules treat an unknown version leniently).
+
+        """
+        parsed = urlparse(url)
+        host = parsed.hostname
+        if host is None:
+            return None
+        port = parsed.port or 443
+
+        writer = None
+        try:
+            context = ssl.create_default_context()
+            _reader, writer = await asyncio.wait_for(
+                asyncio.open_connection(host, port, ssl=context),
+                timeout=TLS_PROBE_TIMEOUT_S,
+            )
+            ssl_object = writer.get_extra_info("ssl_object")
+            return ssl_object.version() if ssl_object is not None else None
+        except Exception as e:  # noqa: BLE001 — probe failure must not abort the audit
+            logger.info("Could not probe TLS version for %s: %s", url, e)
+            return None
+        finally:
+            if writer is not None:
+                writer.close()
+
     async def _collect_init_result(self) -> None:
         """Collect initialization data from the MCP server.