MCP 服务器

mcpsnoop

Zero-dependency MCP server inspector for protocol conformance, tool annotations, and capability checks.

README

mcpsnoop

Zero-dependency MCP server inspector — protocol conformance, tool annotations, and capability checks.

"Validate your MCP server before your users do."

mcpsnoop statically analyzes a Python MCP server module and reports protocol violations, missing tool annotations, and capability gaps — without installing the MCP SDK or standing up a live server.

Quick Start

pip install mcpsnoop-mcp-mcp-mcp

from mcpsnoop import inspect_server, check_capabilities, lint_annotations

# Inspect a Python MCP server module (stdlib only, no mcp SDK import required)
issues = inspect_server("path.to.your.server_module")
# Returns: list of Issue(severity, code, message, path)

# Check capability declarations against a target MCP version
gap = check_capabilities(server_module, target_version="1.0.0")

# Lint tool annotations for MCP 1.x compliance
report = lint_annotations(server_module)

CLI

# Inspect a Python file
mcpsnoop inspect ./src/myserver.py --target-version 1.0.0

# Lint tool annotations
mcpsnoop lint ./src

# Check capability declarations
mcpsnoop check-capabilities ./src/myserver.py --target 1.0.0

# Output formats
mcpsnoop inspect ./src --output sarif   # SARIF format for CI
mcpsnoop inspect ./src --output json    # Raw JSON

# Run as stdio MCP server (for use inside MCP-powered agents)
mcpsnoop serve --inspect ./path/to/server.py

⚡ Performance & Benchmarks

Workload	Tools	mcpsnoop (mean)	mcpaudit (mean)	Speedup
empty_module	0	19.45ms	N/A	N/A
few_tools	2	19.08ms	N/A	N/A
many_tools	50	18.98ms	N/A	N/A
mixed_issues	30	19.25ms	N/A	N/A
large_file	200	19.40ms	N/A	N/A

Benchmarked on: Linux (Python 3.11). mcpaudit requires Node.js and is not available in this environment — mcpsnoop is zero-dependency and runs entirely offline. Run: python3 benchmarks/run_benchmark.py

Key Features

Zero runtime dependencies — stdlib only (importlib, json, typing)
Static analysis — no live server, no network, works offline in CI
Three inspection dimensions: protocol conformance, tool annotations, capability gaps
MCP stdio server mode — exposes a snoop tool for use inside MCP agents
SARIF output — CI-friendly integration with GitHub Actions, Semgrep, etc.
Python 3.11+ with full type hints

API Reference

`mcpsnoop.inspect_server(module_path: str) -> list[Issue]`

Inspect a Python MCP server module and return protocol conformance issues.

Issue codes:

Code	Severity	Meaning
`TOOL_MISSING_INPUT_SCHEMA`	HIGH	Tool has no `inputSchema` or `input_schema` field
`TOOL_MISSING_NAME`	HIGH	Tool dict is missing the `name` field
`NAME_CAMEL_CASE`	LOW	Tool name is not `camelCase` per MCP convention
`MODULE_NOT_FOUND`	HIGH	Module/path could not be resolved
`MODULE_IMPORT_ERROR`	HIGH	Module loaded but raised an exception

Example:

from mcpsnoop import inspect_server
issues = inspect_server("my_mcp_server")
for issue in issues:
    print(f"[{issue.severity.value}] {issue.code.value}: {issue.message}")

`mcpsnoop.check_capabilities(module_path: str, target_version: str = "1.0.0") -> CapabilityGap`

Check capability declarations against a target MCP version. Returns CapabilityGap(missing, deprecated, extra).

Version support:

Version	Expected capabilities
`1.0.0`	`roots`, `sampling`, `resources`
`2.0.0`	`roots`, `sampling`, `resources`, `prompts`, `tools` + deprecated `logging`

`mcpsnoop.lint_annotations(module_path: str) -> AnnotationReport`

Lint tool annotations for MCP 1.x compliance. Checks for idempotentHint, openWorldHint, readOnlyHint. Returns AnnotationReport(missing_idempotent_hint, missing_open_world_hint, missing_read_only_hint).

`mcpsnoop.format_report(issues: list[Issue]) -> str`

Format a list of issues into a human-readable multi-line report with pass/warn/fail counts.

`mcpsnoop.server.MCPStdioServer`

Minimal MCP stdio server exposing the snoop tool. Initialize and call run() to start the server loop.

from mcpsnoop.server import MCPStdioServer
server = MCPStdioServer(inspect_path=".", target_version="1.0.0")
server.run()  # reads JSON-RPC from stdin, writes to stdout

Limitations

Static analysis only — dynamically constructed tools (factory functions that return tool dicts at runtime) may not be detected; inspect_server reads what importlib exposes at module load time.
Python-only — inspection targets Python MCP server modules, not TypeScript/Node.js servers.
MCP 1.x annotations — tool annotation fields (idempotentHint, openWorldHint, readOnlyHint) are from MCP 1.x and may change in 2.0. Use target_version to pin to a known baseline.
No auto-fix — mcpsnoop reports issues but does not modify code.