Metadata-Version: 2.4
Name: mcp-server-audit
Version: 0.1.1
Summary: Audit MCP servers for install-time issues before you install them.
Project-URL: Homepage, https://github.com/Yveshby27/mcp-server-audit
Project-URL: Repository, https://github.com/Yveshby27/mcp-server-audit
Project-URL: Issues, https://github.com/Yveshby27/mcp-server-audit/issues
Author-email: Yves Habchi <yves.habchy@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Yves Habchi
        
        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.
License-File: LICENSE
Keywords: ai-agents,audit,cli,mcp,model-context-protocol
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
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: jsonschema>=4.20.0
Requires-Dist: rich>=13.7.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# mcp-audit

Audit MCP servers for install-time issues before you install them.

`mcp-audit` is a CLI utility that runs a set of install-time validation checks
against any [Model Context Protocol](https://modelcontextprotocol.io) server,
so you can see the problems before you wire the server into your agent config
and lose an afternoon debugging silent failures.

**Status:** v0.1 alpha. Install-time validation only. Security-boundary check
lands in v0.2, runtime spec-compliance in v0.3. See "Roadmap" below.

## The problem

MCP is a fast-growing ecosystem - thousands of servers exist across public
directories, community registries, and internal deployments. Quality varies
wildly. If you have installed more than a handful, you have hit one of:

- Manifest / init response missing required fields; agent client refuses to load.
- Server declares tools in its `capabilities` but `tools/list` returns method-not-found.
- Tool `inputSchema` is not valid JSON Schema; agents pass malformed args and the tool crashes at call time.
- Server hangs on `initialize`; agent times out silently and the tool disappears from your session.

`mcp-audit` runs 4 checks in about a second and tells you which of these the
server has before you install it.

## Install

```bash
pip install mcp-server-audit
```

Requires Python 3.10+.

The PyPI package name is `mcp-server-audit`; the CLI command is `mcp-audit`.

## Use

```bash
mcp-audit "python -m my_mcp_server"
mcp-audit "npx -y @modelcontextprotocol/server-filesystem /tmp"
mcp-audit "uvx some-mcp-server" --json
mcp-audit "node build/index.js" --timeout 60 --verbose
```

The single positional argument is the shell-style command that spawns the MCP
server over stdio. `mcp-audit` will launch the subprocess, run the handshake,
probe `tools/list` / `resources/list` / `prompts/list`, run its 4 checks, and
close the server cleanly.

Default timeout is 30 seconds per request. For `npx -y` cold-cache first runs
(which can take 20-60s to download + start), the default usually works. If you
hit a CRITICAL on first run, retry with `--timeout 60` and see if it clears.
For CI where packages are pre-cached, use `--timeout 5` for tighter checks.

## What v0.1 checks

Four checks:

| Check | What it verifies |
|---|---|
| `handshake` | Server subprocess spawns; responds to `initialize` within timeout; returns a valid response envelope; shuts down cleanly on stdin close. |
| `descriptor` | `serverInfo`, `protocolVersion`, `capabilities` present and well-typed in initialize response. Each tool / resource / prompt entry has its required fields (`name`, `uri`, etc.). |
| `capabilities` | Declared capabilities match implementation. Flags "declared but not implemented" (breaks strict clients) and "implemented but not declared" (hidden from clients that respect declarations). |
| `tool_schemas` | Each declared tool's `inputSchema` (and `outputSchema` if present) is valid JSON Schema Draft 2020-12 per meta-validation. |

## Output

Human-readable colored terminal report by default. Add `--json` for machine-readable output (CI-friendly).

Exit codes:
- `0` - all checks passed
- `1` - warnings only (server usable, quality issues present)
- `2` - errors (server broken; do not install without fixing)
- `3` - critical (could not run server at all)

## Roadmap

- **v0.1 (this release):** install-time validation, 4 checks above
- **v0.2:** security-boundary check - vulnerability patterns, credential exfil, unsafe defaults, auth-boundary violations
- **v0.3:** runtime spec-compliance - error handling, rate-limit honor, timeout behavior beyond handshake
- **v0.5+:** hosted service - continuous monitoring, regression alerts
- **v1.0+:** enterprise tier - on-prem, compliance-heavy features

## Why this exists

The MCP ecosystem is at the point (2026) where quantity has outpaced ecosystem-level
quality signals. First-party curation from Anthropic will land eventually, but
the gap is real today. This tool addresses one specific slice: install-time
validation you can run in a second before adding a server to your agent config.

Adjacent tools cover different slices:
- **mcpgrade** - usability grading of published servers
- **Glama** - MCP server registry / discovery
- **MCPJam**, **Runlayer**, **Manufact**, **Reticle**, **MCPwn**, **mcp-fortress**, **mcpserver-audit** - various adjacent quality/security/observability tools

`mcp-audit` is deliberately narrow: install-time schema validation, meta-checkable properties, one shot per server, exit-code-scriptable. If you want the other axes, use the adjacent tools too.

## Contributing

Issues and PRs welcome at [github.com/Yveshby27/mcp-server-audit](https://github.com/Yveshby27/mcp-server-audit).

If you hit an MCP server that `mcp-audit` misses a real issue on - open an issue with the server command and the observed behavior. Real-world failures are the best guide to which checks matter.

## License

MIT - see [LICENSE](LICENSE).
