Metadata-Version: 2.4
Name: mcpscore
Version: 0.4.0
Summary: CLI tool to analyze your MCP server and get a comprehensive report on its quality
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,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
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.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
- **Library-friendly**: Fully typed (`py.typed`); use `MCPClient` + `MCPAuditor` programmatically

## 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

- **Tools**: Names (presence, uniqueness, format), titles, descriptions, and JSON Schema validity of input/output schemas

- **Security**:
  - ✅ HTTPS/TLS usage with the actually negotiated TLS version
  - ✅ Valid certificate checks
  - ✅ Error responses checked for data leaks

- **Transport**:
  - ✅ Streamable HTTP usage (the current MCP standard; SSE-only servers get migration advice)

## Requirements

- 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

## 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-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
✅ 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
```

## Troubleshooting

**Connection fails**

- Check the path or URL is correct and reachable
- For local servers, make sure Python or Node.js is on `PATH`
- "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>.

## License

MIT — see [LICENSE](LICENSE).
