mcpscore 0.3.0__tar.gz

mcpscore-0.3.0/.gitignore

@@ -0,0 +1,157 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+coverage.json
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Ruff
+.ruff_cache/
+
+# Pyright
+pyrightconfig.json
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

mcpscore-0.3.0/LICENSE

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

mcpscore-0.3.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: mcpscore
+Version: 0.3.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: Repository, https://github.com/mcp-box/mcpscore
+Project-URL: Issues, https://github.com/mcp-box/mcpscore/issues
+Author: Alex Akimov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,audit,cli,developer-tools,llm,mcp,mcp-server,model-context-protocol,quality
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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.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
+Description-Content-Type: text/markdown
+
+# MCPScore
+
+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.
+
+## 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
+- **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
+
+## What it audits
+
+- **Protocol Version Compliance**:
+  - ✅ Allowed versions check (CRITICAL)
+  - ✅ Latest version recommendation (MEDIUM)
+  - ✅ Deprecated version detection (HIGH)
+
+- **Server Information**:
+  - ✅ Server name presence (CRITICAL)
+  - ✅ Server title presence (MEDIUM)
+  - ✅ Server version presence (HIGH)
+
+- **Capabilities**: Tools, resources, prompts, logging, and subscription support
+
+- **Security**:
+  - ✅ HTTPS/TLS usage verification
+  - ✅ Valid certificate checks
+
+- **Transport**:
+  - ✅ SSE transport support detection
+
+## Requirements
+
+- Python 3.13+
+- Node.js on `PATH` if auditing a Node.js MCP server
+- A Python interpreter on `PATH` if auditing a Python MCP server
+
+## Installation
+
+```bash
+pip install mcpscore
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install mcpscore
+```
+
+## Quick start
+
+Run `mcpscore` against any MCP server — local script or remote URL. The transport is detected automatically.
+
+```bash
+# Local Python MCP server (STDIO)
+mcpscore path/to/your/server.py
+
+# Local Node.js MCP server (STDIO)
+mcpscore path/to/your/server.js
+
+# Remote MCP server (auto-detects Streamable HTTP or SSE)
+mcpscore https://example.com/mcp
+```
+
+### Example output
+
+```
+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
+✅ Server name is present: 'weather'
+✅ Server version is present: '1.17.0'
+❌ Server title is not present in server info
+✅ Tools capability is present
+❌ listChanged is not supported by Tools
+✅ Prompts capability is present
+❌ listChanged is not supported by Prompts
+✅ Resources capability is present
+❌ listChanged is not supported by Resources
+❌ subscribe is not supported by Resources
+❌ Logging is not present in capabilities
+✅ MCP Server provides at least one tool
+✅ All Tools have a Name property specified
+✅ All Tools have a Title property specified
+✅ All Tools have a Description property specified
+✅ All Tools have a valid Input Schema
+✅ All Tools have a valid Output Schema
+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
+
+**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)
+
+## Feedback
+
+Bug reports, feature requests, and general feedback are welcome at <https://github.com/mcp-box/mcpscore/issues>.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcpscore-0.3.0/README.md

@@ -0,0 +1,120 @@
+# MCPScore
+
+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.
+
+## 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
+- **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
+
+## What it audits
+
+- **Protocol Version Compliance**:
+  - ✅ Allowed versions check (CRITICAL)
+  - ✅ Latest version recommendation (MEDIUM)
+  - ✅ Deprecated version detection (HIGH)
+
+- **Server Information**:
+  - ✅ Server name presence (CRITICAL)
+  - ✅ Server title presence (MEDIUM)
+  - ✅ Server version presence (HIGH)
+
+- **Capabilities**: Tools, resources, prompts, logging, and subscription support
+
+- **Security**:
+  - ✅ HTTPS/TLS usage verification
+  - ✅ Valid certificate checks
+
+- **Transport**:
+  - ✅ SSE transport support detection
+
+## Requirements
+
+- Python 3.13+
+- Node.js on `PATH` if auditing a Node.js MCP server
+- A Python interpreter on `PATH` if auditing a Python MCP server
+
+## Installation
+
+```bash
+pip install mcpscore
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install mcpscore
+```
+
+## Quick start
+
+Run `mcpscore` against any MCP server — local script or remote URL. The transport is detected automatically.
+
+```bash
+# Local Python MCP server (STDIO)
+mcpscore path/to/your/server.py
+
+# Local Node.js MCP server (STDIO)
+mcpscore path/to/your/server.js
+
+# Remote MCP server (auto-detects Streamable HTTP or SSE)
+mcpscore https://example.com/mcp
+```
+
+### Example output
+
+```
+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
+✅ Server name is present: 'weather'
+✅ Server version is present: '1.17.0'
+❌ Server title is not present in server info
+✅ Tools capability is present
+❌ listChanged is not supported by Tools
+✅ Prompts capability is present
+❌ listChanged is not supported by Prompts
+✅ Resources capability is present
+❌ listChanged is not supported by Resources
+❌ subscribe is not supported by Resources
+❌ Logging is not present in capabilities
+✅ MCP Server provides at least one tool
+✅ All Tools have a Name property specified
+✅ All Tools have a Title property specified
+✅ All Tools have a Description property specified
+✅ All Tools have a valid Input Schema
+✅ All Tools have a valid Output Schema
+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
+
+**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)
+
+## Feedback
+
+Bug reports, feature requests, and general feedback are welcome at <https://github.com/mcp-box/mcpscore/issues>.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcpscore-0.3.0/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-0.3.0/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-0.3.0/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."""