MCP servers declare tool annotations — readOnlyHint, destructiveHint, openWorldHint — that tell agent runtimes which tools need human approval. Nothing verifies these annotations are accurate. HintLint does.

It reads the source code, detects what each tool actually does, and reports where annotations don't match behavior. A tool that calls iam.delete_access_key() but omits destructiveHint means the agent skips confirmation on an irreversible action.

In a 20-repo pilot, HintLint confirmed 23 annotation mismatches at 82% precision, including 19 AWS tools performing destructive cloud operations without destructiveHint.

Install and Run

npx hintlint ./my-mcp-server

# CI mode — exit 1 on high-severity findings
npx hintlint ./my-mcp-server --ci --fail-on high

# SARIF for GitHub Security tab
npx hintlint ./my-mcp-server --format sarif --output hintlint.sarif

Zero dependencies. Node.js 20+.

GitHub Action

- uses: complira/hintlint@v0
  with:
    target: .
    fail-on: high
    upload-sarif: "true"
    pr-comment: "true"

Also works with GitLab CI, Jenkins, Azure DevOps, CircleCI.

What It Finds

| ID | What's Wrong | Severity | |----|-------------|----------| | READONLY-001 | Says readOnlyHint=true, source shows writes | High | | DESTRUCTIVE-001 | Calls destructive API, no destructiveHint | High | | OPEN-WORLD-001 | Says openWorldHint=false, makes external calls | Medium | | FLOW-PROCESS-001 | User input reaches exec() / subprocess.run() | Critical | | FLOW-QUERY-001 | User input reaches raw SQL without binding | Critical | | FLOW-URL-001 | User input controls outbound URL | High | | FLOW-FILESYSTEM-001 | User input reaches file write without path check | High | | FLOW-CONNECTION-001 | User input in connection string without sanitizer | High |

Full details with CWE IDs and repair guidance: Finding Reference

How It Works

Source Code
    |
    v
 Extract tools        TypeScript, JavaScript, Python
    |
    v
 Detect sinks         10 categories (DB, filesystem, HTTP, process, cloud, ...)
    |
    v
 Compare annotations  Declared vs verified behavior
    |
    v
 Report drift         Terminal, JSON, SARIF 2.1.0, Registry artifact
    |
    v
 CI policy            Fail only on source-backed findings (L3/L4)

Only findings with handler-scoped source evidence can fail your build. Metadata-only guesses never block CI.

Language Support

| Language | Handler Resolution | |----------|--------------------| | TypeScript / JavaScript | 88% | | Python | 100% |

Output Formats

| Format | Use Case | |--------|----------| | Terminal | Developer review | | JSON | Programmatic consumption | | SARIF 2.1.0 | GitHub Security, Defect Dojo, SIEM | | Registry artifact | MCP gateway trust metadata |

Documentation

| | | |---|---| | FAQ | Common questions, comparisons | | CLI Reference | Flags, config, exit codes | | Finding Reference | Every finding, CWE, repair guidance | | CI Integration | GitHub, GitLab, Jenkins, Azure DevOps, CircleCI | | Enterprise Usage | Pre-registry scanning, catalog management, continuous monitoring | | Registry Artifact | Gateway integration format | | Findings Report | Validated pilot results with methodology |

Contributing

See CONTRIBUTING.md. Zero-dependency policy is intentional.

License

Apache 2.0 — LICENSE | Security issues — SECURITY.md