Performs read-only codebase audits to detect secrets, dependency drift, RLS mistakes, and security vulnerabilities for coding agents.
Also known as subhajitlucky/codebase-doctor
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.10
- Last commit
- Nov 13, 2026
- License
- MIT
What is codebase-doctor MCP?
codebase-doctor performs read-only codebase audits to detect secrets, dependency drift, RLS mistakes, and security vulnerabilities for coding agents.
Summary generated from the project's README
About codebase-doctor MCP server
Codebase Doctor provides read-only audits designed to verify the work of coding agents and developers. It functions as a verification layer that identifies security vulnerabilities, secret leaks, dependency drift, and RLS mistakes without executing any repository code. The tool builds a static source graph across languages including JavaScript, TypeScript, Python, Go, Java, and Rust to understand how changes impact the broader project.
Users can run the tool locally via npx or install it globally. It supports various workflows, such as auditing full repositories, checking only changed files via the --changed flag, or performing pull request reviews with the review command. The server can be integrated into CI/CD pipelines using GitHub Actions and supports multiple output formats like JSON, SARIF, and HTML. It is built to be transparent, explicitly reporting what it could not analyze during a run to ensure users understand the coverage limits.
What you can do with it
- 1Detect committed secrets in historyAn agent can scan the most recent 200 commits to find sensitive material that was committed and subsequently deleted.
- 2Verify pull request safetyA developer can use the review command to narrow findings to added diff lines and receive a verdict for a PR.
- 3Identify dependency driftThe tool can check lockfiles for npm, pnpm, Yarn, Bun, or Python poetry to ensure manifest and lockfile consistency.
- 4Analyze code change impactA user can determine the shortest impact path from a changed file to understand what might break.
Written from the project's README. Every use case is checked against a quote from it.
How to install codebase-doctor MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall codebase-doctor MCP in Claude Code
$ claude mcp add codebase-doctor -- npx -y codebase-doctorInstall codebase-doctor MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"codebase-doctor": {
"command": "npx",
"args": [
"-y",
"codebase-doctor"
]
}
}
}Install codebase-doctor MCP in VS Code
.vscode/mcp.json
{
"servers": {
"codebase-doctor": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"codebase-doctor"
]
}
}
}Install codebase-doctor MCP in VS Code CLI
$ code --add-mcp '{"name":"codebase-doctor","type":"stdio","command":"npx","args":["-y","codebase-doctor"]}'Install codebase-doctor MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"codebase-doctor": {
"command": "npx",
"args": [
"-y",
"codebase-doctor"
]
}
}
}Install codebase-doctor MCP in Codex
$ codex mcp add codebase-doctor -- npx -y codebase-doctorInstall codebase-doctor MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.codebase-doctor] command = "npx" args = ["-y", "codebase-doctor"]
Install codebase-doctor MCP in Gemini CLI
$ gemini mcp add -s user codebase-doctor npx -- -y codebase-doctorInstall codebase-doctor MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"codebase-doctor": {
"command": "npx",
"args": [
"-y",
"codebase-doctor"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesubhajitlucky/codebase-doctor is public and reachablegithub.com/subhajitlucky/codebase-doctor ↗Pass
- Package names this repository as its sourcecodebase-doctor names subhajitlucky/codebase-doctor as sourcenpmjs.com/package/codebase-doctor ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/subhajitlucky/codebase-doctor ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from codebase-doctorPass
- No critical advisory in the package or its dependencies120 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCodebase Doctor
Models build. Codebase Doctor verifies.
It finds the thing, and it never guesses.
Most repository scanners fail in one of two ways: they flood you with false positives, or they silently skip the hard case and report "clean." Codebase Doctor does neither. Every finding carries evidence, every audit reports what it couldn't analyze, and a clean run means the scope was actually checked.
npx -y codebase-doctor audit . --changed --format brief
codebase-doctor brief
scope=full findings=1 shown=1 coverage=incomplete score=80
[high] security/secrets/provider-token src/config.ts:12 —
Have an authorized human or external coding agent remove the value and rotate it,
then rerun the audit.
coverage-limitations: validation: skipped, database: skipped, security: partial
That last line is the point. Most tools print findings and stop. This one tells you what it didn't check, every single run.

Why this exists
Coding agents ship code faster than review can keep up. The failure isn't that agents can't write code — it's that nothing verifies what they wrote before it merges.
Codebase Doctor is that verification step. It builds a source graph, scans for committed secrets, dependency drift, unsafe Dockerfiles, workflow injection, RLS mistakes, and accessibility regressions — then tells you exactly what it could not verify.
Benchmarked, not vibes: 17 seeded single-defect fixtures score 100% rule recall and zero medium+ false positives (results, reproducible with npm run benchmark).
Red-teamed: an adversarial mutation corpus tries to hide each defect in a different shape — 11/11 mutants caught, 7/7 controls clean, gated in CI (corpus, reproducible with npm run red-team).
Cross-checked: two independently written offline analyzers (this repo's sql-rls and rls-doctor) run over the same SQL corpus — 10 findings matched, 0 severity mismatches, 1 documented coverage difference, safe schema clean under both (scoreboard, npm run differential).
Field study: of 100 agent-configured public repositories, 23% ship at least one high-severity finding — 10% have broken imports, 4% committed key material, 11% risky agent configuration (report, anonymized and reproducible).
Install
npx -y codebase-doctor audit . # no install
npm install -g codebase-doctor # global
Quick start
codebase-doctor demo # disposable fixture: secret, broken import, blast radius
codebase-doctor bisect security/secrets/provider-token . # when did this enter history?
codebase-doctor audit . --json # full audit
codebase-doctor audit . --changed --json # just my diff
codebase-doctor audit . --changed --base main --json # PR review
codebase-doctor audit . --format sarif # GitHub code scanning
codebase-doctor audit . --format html > report.html # shareable standalone report
codebase-doctor verify . --baseline before.json # confirm fixes landed
demo needs no configuration and no repository: it builds a disposable git
fixture with a tracked secret and a broken import, audits the simulated agent
edit with the real pipeline, prints the blast radius, and exits 1 to show the
CI gate. Nothing outside a temp directory is touched.
Options
--run-checks Permit configured validation commands
--changed Audit Git changes and their affected scope (implied by review)
--base <ref> Compare changed scope from the merge base with this ref
--json Emit schema-versioned JSON
--format <format> Output format: text, json, sarif, brief, or html (review adds markdown, github)
--all-findings Review only: include findings outside the changed lines
--output <file> Review only: write the report to a file as well as stdout
--exclude <glob> Exclude a repository-relative path glob; repeatable
--baseline <path> Compare with a prior Codebase Doctor JSON report
--timeout <ms> Per-command timeout (default: 120000)
--fail-on <severity> info|low|medium|high|critical|none (default: high)
--require-complete Exit 2 when audit coverage is incomplete
--max-findings <n> Cap brief output (default: 100)
--score Print only the Repo Health score
--badge Print a shields.io badge URL for the Repo Health score
--receipt <path> Write a portable coverage receipt (digest-verified)
--receipt-key <path> Sign the receipt with an Ed25519 private key (PEM)
--pheromone <path> Write a privacy-bounded signal (rules and counts only)
--with-database Permit live PostgreSQL catalog access
--with-advisories Opt-in OSV advisory lookup over lockfile packages
--database-schema Schema to inspect; repeatable (default: public)
--database-timeout Catalog statement timeout in ms (default: 10000)
Code review
review is the pull-request command. It always audits changed scope, narrows
findings to added diff lines, and prints a verdict — NO_CHANGES, APPROVE,
COMMENT, or REQUEST_CHANGES — so unrelated old issues never fail a PR and
an empty checkout is never represented as an approval:
codebase-doctor review . --base origin/main --format markdown > review.md
codebase-doctor review . --base origin/main --format github
codebase-doctor review . --format json # includes a machine-readable review envelope
codebase-doctor review . --base origin/main --receipt review.json
codebase-doctor review . --base origin/main --receipt review.json --receipt-key key.pem
--format markdownrenders a PR-comment-ready body with the verdict, findings, source impact, and coverage limitations.--format githubemits::error/::warning/::noticeworkflow commands that annotate pull-request diffs inline from Actions logs, with no network access.- A finding on an unchanged line is out of scope for the verdict and counted
as omitted; the full
auditstill reports it.--all-findingsdisables narrowing, and--output <file>writes the report to a file as well as stdout. - With
--baseline, only new findings in the diff gate the verdict. - An empty diff reports
NO_CHANGES, notAPPROVE. Use--require-basein CI to fail closed when the base ref was not supplied. --receipt <path>writes a portable review receipt with the verdict, diff-scope counts, coverage limitations, and finding fingerprints. Add--receipt-keyto sign it with Ed25519;verify-receiptchecks integrity and prints the review verdict.- Exit
1means the review requests changes; exit2is an operational failure, never a clean result. Inspect coverage before calling the reviewed diff verified or clean.
GitHub Action
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
- uses: subhajitlucky/codebase-doctor@v0.5.0
with:
format: sarif
upload: "true"
fail-on: high
Findings appear in the Security tab. See docs/github-action.md.
What it checks
Secrets — working tree and history
Precision-first and not exhaustive: it detects private-key material, provider-token shapes, paired AWS credentials, credential-bearing URLs, and high-confidence sensitive assignments. A Git-ignored .env is normal storage and is not a finding; a tracked one containing a real credential is.
security/secrets-history catches the case that matters most: a secret committed and later deleted from the working tree, so a rotated-looking repo doesn't hide an exposure. It inspects the most recent 200 commits across all branches without ever checking out, rewriting, or executing repository content. Changed audits scope the history log to changed paths, so deleting a leaked file cannot review clean.
Matched values are withheld from every finding, fingerprint, error, and report. Codebase Doctor never prints your secrets — including in its own SARIF. An external authorized human or agent must remediate the shareable content and rotate or revoke the credential, then rerun the same audit.
Dependencies
security/dependencies is read-only and offline. Lockfile-aware for npm lockfile versions 2 and 3, pnpm (v5+), Yarn (classic and Berry), Bun, and Python poetry and uv locks. Remaining ecosystems stay explicitly unsupported rather than receiving guessed findings.
Rule families: security/dependencies/missing-lockfile, security/dependencies/manifest-lock-drift, security/dependencies/insecure-source, security/dependencies/mutable-git-source, security/dependencies/missing-integrity, security/dependencies/workspace-registry-resolution, security/dependencies/competing-npm-lockfiles, and security/dependencies/competing-lockfiles.
A normal semver range such as ^5.0.0 is not a finding when the lock agrees. Raw dependency specifications and resolved URLs are withheld from reports and never enter a fingerprint. An external authorized human or agent must correct the metadata and rerun the same scope. Inspect coverage before calling the dependency graph clean or verified.
It never invokes npm, another package manager, a shell, an installer, or a lifecycle script, and makes no network request. It makes no CVE or advisory claim on its own. Python coverage parses poetry.lock and uv.lock package blocks and pyproject.toml Poetry and PEP 621 declarations with a bounded line scanner (no TOML dependency): insecure transports, unpinned git references, missing hash evidence, missing lockfiles, competing lockfiles, and decidable manifest-lock drift are reported, while undecidable specifiers, markers, direct-URL drift, transitive-only entries, and requirements-only layouts stay visible as partial coverage.
--with-advisories performs one bounded OSV lookup against resolved packages. Only names, versions, and ecosystems leave the machine.
Source impact — what breaks if I change this file
repository/source-graph uses a real syntax parser (never executes your code) to build a static import graph across JS/TS, Python, Go, Java, and Rust. In changed mode it walks reverse edges and reports a deterministic shortest impact path from each changed file.
Changed mode is mixed-scope per doctor, not a universal file filter: Project Doctor structural rules run with the full repository snapshot and may report findings outside changed paths for manifests, lockfiles, workspaces, and test visibility. File-local doctors (backend, frontend, infrastructure, agent surface, performance) examine only changed files present in the inventory, so changed audits stay proportional to the change. Configured validation check plans are built from full project topology and then filtered to affectedProjectIds. Static SQL selects affected migration streams and replays full current history for every selected stream. Live database remains a full observed schema-set audit only with separately requested --with-database. Zero changed findings is not a full clean result.
repository/source-graph recognizes static import, re-export, type-only import, literal require, and literal dynamic import edges across JavaScript and TypeScript (plus Python, Go, Java, and Rust) with a real syntax parser that never executes repository code. Cycles are valid topology, not findings, and this module is finding-free by design.
A separate precision-first repository/source-integrity Doctor emits only the source/import-target-missing rule, keeping topology limitations from becoming guessed bugs. It diagnoses only four proof classes: an explicit relative target with a supported source extension; a single deterministic alias whose configured target explicitly names a supported source file; a unique workspace package whose explicit entry names a supported source file; and an internal Go package under a module path without a replace directive.
Extensionless, JSON, custom-loader, conditional, ambiguous, external, and dynamic references and cycles are not findings. It does not check named exports or validate that a referenced export name exists.
Full mode examines all qualifying edges; changed mode examines changed importers and complete reverse-impacted importers. A deleted or renamed target selects its unchanged importer.
It emits at most 1,000 findings per audit and reports partial coverage whenever that ceiling or any upstream graph limitation applies. Partial coverage is not a clean source-integrity result. Raw import specifiers and source text are withheld from findings, which expose only normalized paths, import kind, proof class, and safe location.
An external authorized human or agent must correct or restore the intended target and rerun the same scope.
codebase-doctor audit . --changed --base main
src/db/schema.ts → src/repositories/user.ts → src/api/users/[id]/route.ts
→ src/app/dashboard/page.tsx → tests/integration/user.test.ts
Cycles are valid topology, not findings. The graph module intentionally emits no bug findings — repository/source-graph is finding-free by design, and the separate precision-first repository/source-integrity Doctor reports only provably missing import targets, so topology limits never become guessed bugs.
Schema-1 reports may include sourceImpact (schema 1). Changed mode walks reverse internal edges, adds impacted projects to affectedProjectIds, and reports a deterministic shortest impact path per changed source root. Reports preserve full impacted-file counts while serializing only bounded impact records. A path proves only the static edge chain, not a bug in the dependant. Raw import specifiers and source text are withheld; the module uses no plugins, network requests, or writes.
Local tsconfig and jsconfig files contribute a deterministic subset of relative aliases; this is not complete Node or TypeScript module resolution. Dynamic non-literal imports, ambiguous targets, unsupported configuration or syntax, unreadable input, and graph ceilings are coverage limitations, not findings.
Workflow and infrastructure
script-injection (attacker-controlled ${{ github.event.* }} in a run: step), pull-request-target-checkout, write-all-permissions, unpinned action refs, unpinned Docker base images, pipe-to-shell, root-user, and world-writable files. Workflows are never dispatched and images are never built.
PostgreSQL and Supabase RLS
Offline database/sql-rls runs automatically when a supported PostgreSQL migration stream is discovered: it requires no credentials, makes no network request, and never executes migration SQL, reconstructing expected table, policy, RLS, and grant state from supported migrations. Partial coverage is not a clean static SQL result.
Live database/rls inspects observed database state through a read-only catalog of policies, privileges, roles, memberships, enforcement, and bypass paths, permissioned separately with --with-database using environment credentials and a read-only, repeatable-read transaction.
database/rls-drift compares the two — expected migration state against observed live state — and reports table-missing-live, rls-disabled-live, force-rls-disabled-live, policy-missing-live, grant-missing-live, rls-enabled-live-only, and policy-unmanaged-live.
database/rls-probe is the behavioral layer. With --probe-db, it impersonates each --app-roles identity inside a read-only, rolled-back transaction, optionally sets Supabase request.jwt.claims for each --subjects UUID, and proves whether the role can read rows across ownership or tenant boundaries:
codebase-doctor audit . --with-database --probe-db \
--app-roles authenticated \
--subjects 00000000-0000-0000-0000-000000000001,00000000-0000-0000-0000-000000000002 \
--owner-columns owner_id,tenant_id \
--database-schema public
A cross-subject or cross-owner read is high severity. The probe never writes, never commits, and always rolls back.
Database and Drizzle hazards
The read-only, offline database/drizzle module and its database/drizzle/raw-sql-date-parameter rule catch a runtime boundary: a JavaScript Date interpolated into a raw Drizzle sql template can bypass the column's timestamp encoder, so postgres-js may throw ERR_INVALID_ARG_TYPE, while equivalent SQL can still work in psql.
// Before: raw interpolation can bypass the timestamp column encoder.
const rows = await db.execute(sql`select * from jobs where run_at <= ${date}`);
// After: guidance for a human or separately authorized external coding agent.
const rows = await db.select().from(jobs).where(lte(jobs.runAt, date));
Applicability requires an exact drizzle-orm/postgres-js adapter import, or scoped owning/workspace evidence for both drizzle-orm and postgres. It reports only statically proven Date flows and never infers from a variable name. Findings are medium severity, high confidence.
Not findings: Date(), Date.now(), an encoded toISOString() string, typed comparisons such as lte(column, date), and a fresh inline encoder object passed directly to sql.param(value, encoder). Encoder identifiers and aliases are not statically proven safe even when declared const, because their objects may be mutated elsewhere; those interpolations and unresolved flows become partial coverage limitations rather than guessed findings. Partial coverage is not a clean Drizzle audit. Raw SQL and parameter values are withheld from findings, fingerprints, and reports. An external authorized human or agent must make the repair and rerun the same scope.
Agent surface — the newest attack target
Audits the agent configuration surface without executing or contacting any of it:
- MCP client configs: unpinned package runners, shell commands, inline credentials, broad filesystem grants
SKILL.md: unscopedallowed-toolsgrants (Bash(*), bareWrite)- Permission bypass:
bypassPermissions,--dangerously-skip-permissions,--yolo,yes-always, broadpermissions.allow
Frontend
JSX/TSX and static HTML accessibility (img-missing-alt, iframe-missing-title, html-missing-lang, positive-tabindex) and static SEO (missing-title, missing-meta-description). No browser, no build.
frontend/security is read-only and offline over JSX sources: dangerously-set-inner-html fires for a dynamically computed value without a provable sanitizer call (DOMPurify.sanitize, sanitizeHtml). Static literals are safe and spread props suppress the check.
Backend and auth
backend/auth is read-only and offline over JavaScript and TypeScript sources, plus Go sources for the OAuth callback-binding rule. It never starts a server, sends a request, or issues a token — it reads source text only.
Rules: cors-wildcard-origin-with-credentials (wildcard origin: "*", reflected origin: true, or an allowlist containing *, with credentials enabled), session-cookie-security-disabled (cookie secure or httpOnly explicitly false), jwt-decode-without-verify (a decode call in a file containing no verify call), jwt-verify-algorithm-unrestricted (no algorithms allowlist), and oauth-callback-session-binding (a callback route reads a query-string session identifier and assigns a token to that session without a browser-bound state cookie). The OAuth rule parses the Babel AST for JS/TS and a bounded Go tokenizer with a cross-file function index for Go. It reports an unresolved callback handler or a Go-only gap as a coverage limitation, never as a finding. CORS, session-cookie, and JWT rules remain JavaScript/TypeScript-only.
backend/api is read-only and offline over the same sources: sql-string-concat-query fires for concatenated or interpolated SQL text passed to a provably bound pg, postgres, mysql, mysql2, better-sqlite3, or sqlite3 query call (parameterized queries with a values array are safe), and child-process-exec-dynamic fires for non-static commands passed to a provably bound child_process exec/execSync (including spawn with shell: true), while execFile and plain spawn never fire. Instance calls through new Pool()-style construction resolve like direct imports. Unresolvable query text stays a coverage limitation.
A rule fires only when the callee provably resolves to the audited package through an import declaration or CommonJS require, so an unrelated local helper named cors or decode is never reported. Configuration that cannot be resolved statically — a non-literal options expression, a computed cookie flag, or a spread property that could supply the value — is a coverage limitation, never a guessed finding, so inspect backend coverage before calling a codebase clean. The decode and algorithm rules are file-scoped: a verify call in middleware in another file does not suppress them. Configured origin and secret literals are withheld from reports and never enter a fingerprint.
Not covered: API shape validation, worker, webhook, cron, and rate-limit analysis. An external authorized human or agent corrects the configuration, then reruns the same scope.
codebase-doctor MCP questions
How do I add codebase-doctor MCP to Claude Code?
Run claude mcp add codebase-doctor -- npx -y codebase-doctor in your terminal. Add --scope user to make it available in every project.
How do I add codebase-doctor MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does it handle secrets in reports?
Matched secret values are withheld from every finding, fingerprint, error, and report to ensure security.
Does it execute my code during the audit?
No, it uses a real syntax parser to build a static import graph without ever executing your code.
Can it be used in a CI/CD pipeline?
Yes, it can be integrated via GitHub Actions to annotate pull-request diffs and gate merges.