RANJITHROSAN17/mcp-doctor

Static Security Scanner · Schema Linter · Token-Budget Auditor for MCP Servers
Enterprise-grade GitHub Actions bot stack. Zero external runtime dependencies. 90.77% test coverage.
## 🎯 Product Overview
Every MCP server exposes two invisible failure surfaces:
| Failure Surface | How vexar-mcp Handles It |
| Security sinks — subprocess.run(shell=True), unvalidated urlopen, unconfined open(path) | 8 modular rules (MCP001–MCP008) detect at AST level; never executes untrusted code |
| Schema / token tax — missing descriptions, Any params, unbounded pagination, bloated docstrings | Token-budget calculator + schema validator + 4 reporters (terminal / JSON / SARIF / GitHub) |
Target: Python MCP servers (FastMCP, official mcp SDK, @tool decorators) + JSON manifests (OpenAI, Anthropic, tools/list).
## 🏆 Key Metrics (Live)
| Metric | Value | Source |
| Test Coverage | 90.77% (pytest, --cov-fail-under=85) | tests/ |
| Quality Gates | 0 ruff / 0 mypy errors | CI (3.10 / 3.11 / 3.12) |
| Contributor Issues | 8 open (#1–#8) — good first issue + help wanted | issues/ |
| Queued Roadmap | 15 tasks (RM-001 → RM-015) | .github/roadmap.json |
| Labels | 23 color-coded | Bot-curated |
| Bot Workflows | 11 (7 new + CI / governance / release / dusty / welcome) | .github/workflows/ |
| Community Health | 100% | GitHub Insights |
| Release | v0.1.0 (.whl + .tar.gz) | releases/v0.1.0 |
## ⚡ Quickstart
bash
# Install (direct from repo — no PyPI dependency conflicts)
pip install git+https://github.com/RANJITHROSAN17/Vexar-MCP.git@main
# Or with uv / pipx
uvx --from git+https://github.com/RANJITHROSAN17/Vexar-MCP.git vexar-mcp --help
# Run on a server
vexar-mcp audit examples/cleanserver.py
# Use as reusable GitHub Action (composite)
uses: RANJITHROSAN17/Vexar-MCP@main
Output formats: terminal scorecard (A+ → F, token leaderboards), JSON, SARIF v2.1.0 (GitHub Security tab), GitHub Markdown ($GITHUBSTEPSUMMARY).
## 🧩 What It Ships
### Core Engine (src/mcpdoctor/)
AST Parser (pythonast.py) — ast.parse only; never executes untrusted code
JSON Loaders (loaders/) — MCP tools/list, OpenAI manifest, Anthropic schema
Rules (rules/) — 8 modular diagnostics (MCP001–MCP008): security sinks (shell, SSRF, path traversal), schema drift (Any, missing descriptions), token overflow, pagination, duplicates
Engine (engine.py) — scan → diagnose → score (0–100) → report; fixed SIM110 / SIM102
Reporters (reporters/) — 4 output formats (terminal / JSON / SARIF / GitHub Markdown)
CLI (cli.py) — audit, init, --format, --baseline, --stdio
### Enterprise Bot Stack (7 Flow Suites — All Dynamic / Live)
Only 3 notification sources — zero noise for contributors:
| Bot | Trigger | What It Does | Notifies? |
| Feature Upgrade | Daily 09:00 UTC + push/pullrequest | Proposes next queued roadmap item (RM-009...) | Silent (opens only if queued) |
| Issue Raise | Mon 10:00 UTC + pullrequest | Opens structured contributor issue (good first / help wanted) | Silent open (max 8 live) |
| Issue Resolve | pullrequest merge + push | Verifies linked fix, closes issue, promotes next queued | Silent (only linked issue) |
| Code Review | Every PR event (5+ triggers) | Required gate: ruff + mypy + pytest ≥85% + format + labels | Only if blocked |