Getting Started

Tool-Scan scans MCP tool definitions for security vulnerabilities, MCP spec compliance, and quality issues. This guide covers installation and your first scan.

Installation

Install from PyPI:

pip install tool-scan

Your first scan

Command line

Scan a single tool definition file:

tool-scan my_tool.json

The output shows the score, letter grade, and any remarks with actionable recommendations.

Strict mode for CI

Use --strict to fail on any security issue, and --min-score to set a threshold:

tool-scan --strict --min-score 80 tools/*.json

JSON output

For automation and downstream processing:

tool-scan --json my_tool.json > report.json

SARIF output

For GitHub Code Scanning and other SARIF-compatible tools:

tool-scan --format sarif tools/*.json > results.sarif

Concurrent scanning

Process multiple files in parallel with --jobs:

tool-scan --jobs 4 --json tools/*.json

Compact and streaming

For large batches, reduce output size or memory usage:

# Compact JSON (~50% smaller, single line)
tool-scan --json --compact-json tools/*.json

# Streaming JSON (low peak memory)
tool-scan --json --stream tools/*.json

Python API

You can also scan tools programmatically:

from tool_scan import grade_tool

tool = {
    "name": "get_weather",
    "description": "Gets current weather for a location.",
    "inputSchema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name"}
        },
        "required": ["city"],
        "additionalProperties": False
    }
}

report = grade_tool(tool)

print(f"Score: {report.score}/100")
print(f"Grade: {report.grade.letter}")
print(f"Safe: {report.is_safe}")

Next steps

• Learn about the security checks Tool-Scan runs
• Understand the grading system
• Add custom rules with plugins
• Explore output formats (JSON, SARIF, streaming)
• Set up CI integration to gate deployments