CodeAudit MCP

CodeAudit MCP is a read-only MCP server that helps AI coding agents inspect repositories, route engineering skills, verify docs claims, audit code quality, and plan safer issue/PR workflows.

The current MVP is read-only by default. It supports local stdio and Streamable HTTP transports. It does not implement unrestricted shell execution, remote repository mutation, auto-push, auto-delete, or auto-merge.

Production Status

CodeAudit is usable now for production-style read-only repository inspection and agent workflow routing when deployed with the documented controls:

• use stdio for local trusted agent clients, or Streamable HTTP behind HTTPS for remote clients
• set CODEAUDIT_API_KEY for any HTTP deployment that is not strictly local
• set CODEAUDIT_ALLOWED_ROOTS for hosted HTTP deployments so project reads stay inside approved workspaces
• restrict CODEAUDIT_ALLOWED_ORIGINS for browser-accessible deployments
• keep the server read-only; do not add write/GitHub mutation tools without an approval model

Validated in this repository with CI, pnpm check, pnpm build, HTTP health/metadata smoke testing, allowed-root rejection tests, docs-claims audit, and installed-skill audit. OAuth multi-user identity is not implemented yet; use API-key/Bearer protection for hosted HTTP deployments.

What Works

• detect_project identifies empty/existing projects, package manager, framework, language, tests, auth, database, deployment, CI, and risk notes.
• Python detection covers pyproject.toml, uv.lock, FastAPI, Django, Flask, Python MCP SDK, pytest, typing/lint tooling, auth, database, and deployment indicators.
• route_skills returns a skill-routing manifest with workflow phases, recommended tool sequence, skill activation order, quality gates, required outputs, strict instructions, and disallowed actions.
• scan_repo summarizes trees and classifies important, risk, docs, test, and config files.
• audit_code_quality runs heuristic maintainability checks for long files, weak schema boundaries, missing tests, mixed responsibilities, and weak error handling.
• audit_nextjs_security runs heuristic checks for Next.js route, middleware, env, headers, validation, logging, redirect, SSRF, upload, rate-limit, and auth indicators.
• audit_docs_claims maps strong README/docs claims to evidence found or missing.
• audit_tests summarizes test setup and missing test areas.
• audit_installed_skills checks local agent skills for supply-chain, prompt-injection, secret-leakage, dependency-install, webhook, destructive-shell, manifest-quality, duplicate-name, auxiliary-doc, and resource-discovery risks.
• official_docs_router recommends where to look up official/current docs.
• generate_issue_plan, generate_pr_plan, and generate_report produce planning artifacts from findings.
• Resources expose codeaudit://docs/llms and codeaudit://skills/index for MCP-native discovery.

Quick Start

Run the free public npm package directly:

npx -y @priyanshuchawda/codeaudit

For local development from the GitHub checkout:

pnpm install
pnpm build

Run local stdio:

pnpm --filter @priyanshuchawda/codeaudit start

Run local development stdio:

pnpm --filter @priyanshuchawda/codeaudit dev

Run Streamable HTTP with API-key protection:

pnpm build
CODEAUDIT_API_KEY=change-me pnpm --filter @priyanshuchawda/codeaudit start:http

HTTP endpoints:

• MCP: http://127.0.0.1:3000/mcp
• health: http://127.0.0.1:3000/health
• metadata: http://127.0.0.1:3000/.well-known/codeaudit

Example MCP Inspector command:

npx @modelcontextprotocol/inspector pnpm --filter @priyanshuchawda/codeaudit dev

Add To Codex

Npm stdio config for ~/.codex/config.toml or project-local .codex/config.toml:

[mcp_servers.codeaudit]
command = "npx"
args = ["-y", "@priyanshuchawda/codeaudit"]
startup_timeout_sec = 40

Local checkout stdio config:

[mcp_servers.codeaudit]
command = "pnpm"
args = [
  "--dir",
  "/absolute/path/to/codeaudit",
  "--filter",
  "@priyanshuchawda/codeaudit",
  "start"
]
startup_timeout_sec = 40

Windows example:

[mcp_servers.codeaudit]
command = "pnpm"
args = [
  "--dir",
  "C:\\Users\\Admin\\Desktop\\skills\\codeaudit",
  "--filter",
  "@priyanshuchawda/codeaudit",
  "start"
]
startup_timeout_sec = 40

HTTP config:

[mcp_servers.codeaudit]
url = "https://your-codeaudit-host.example.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }

Recommended first prompt after connecting:

Use CodeAudit MCP on this local project. First call detect_project, then route_skills. Follow workflowPhases, recommendedToolSequence, skillActivationOrder, and qualityGates before making any changes.

Documentation

• Start with docs/llms.txt for the complete documentation index.
• Use docs/clients.md for Codex, Claude Code, Cursor, VS Code, Claude Desktop, Gemini CLI, and MCP Inspector setup examples.
• Use docs/deployment.md for production HTTP deployment, Docker, environment variables, and verification.
• CodeAudit supports local stdio and Streamable HTTP MCP connections. HTTP deployments can be protected with an API key or Bearer token.

Free Public Distribution

• Npm public package: @priyanshuchawda/codeaudit
• Current npm version: 0.1.5
• Npm public packages are free to publish with npm publish --access public.
• Release publishing is configured through .github/workflows/publish-npm.yml.
• To publish, add a granular npm write token with bypass 2FA enabled as the GitHub secret NPM_TOKEN, then create a GitHub release.
• Users can install and run without cloning GitHub by using npx -y @priyanshuchawda/codeaudit.

Skills CLI

Install the public CodeAudit skill without cloning this repository:

npx skills add priyanshuchawda/codeaudit --skill codeaudit

List available public skills:

npx skills add priyanshuchawda/codeaudit --list

The public catalog shape intentionally exposes one skill, codeaudit. Specialist workflows under skills/ are marked metadata.internal: true so CodeAudit can keep its internal routing vocabulary without duplicating public skills on skills.sh.

Safety Model

• Tools are registered with read-only annotations.
• Filesystem access is bounded to the supplied project root.
• Hosted HTTP deployments restrict projectPath to CODEAUDIT_ALLOWED_ROOTS; when unset in HTTP mode, the server defaults to process.cwd().
• Common secret formats are redacted before output.
• Command execution is not exposed as an MCP tool.
• The internal command runner only supports a small allowlist.
• Skill files are treated as untrusted input and can be audited before use.
• External documentation is treated as untrusted reference data.
• Generated reports are returned as markdown strings; this server does not write them into target repositories.

Skills Pack

Custom skills live in skills/:

• codeaudit public umbrella skill for npx skills add
• codeaudit-orchestrator
• python-backend-quality
• python-mcp-server-quality
• enterprise-code-quality
• nextjs-security-review
• ai-app-security-review
• docs-claims-evidence-review
• refactor-with-tests
• github-issue-pr-workflow
• official-docs-grounding
• skill-supply-chain-auditor

These skills are written so clients that cannot literally activate skills can still use route_skills as a manifest of recommended skills, ordered workflow phases, tool sequence, outputs, and guardrails.

Example Workflow

{
  "tool": "detect_project",
  "input": {
    "projectPath": "./some-project"
  }
}

Then route:

{
  "tool": "route_skills",
  "input": {
    "projectPath": "./some-project",
    "userTask": "Audit and improve this repo",
    "detectedProject": "<detect_project output>"
  }
}

For an existing project, run audits before refactors:

scan_repo -> audit_code_quality -> audit_nextjs_security -> audit_docs_claims -> audit_tests -> audit_installed_skills -> generate_issue_plan -> generate_pr_plan

Example Output

When run on an existing Next.js project, CodeAudit returns detected stack and risk notes, important/risk/docs/test/config file lists, code quality findings, docs claims with evidence found or missing, a recommended issue plan, and a recommended PR plan.

{
  "projectState": "existing",
  "requiredWorkflow": "repo_audit_then_issue_pr_plan",
  "recommendedSkills": ["codeaudit-orchestrator", "enterprise-code-quality", "next-best-practices"],
  "qualityGates": [
    "Existing project is scanned and audited before refactor work.",
    "Every finding includes file evidence or a clear missing-evidence note."
  ],
  "docsClaim": {
    "claim": "Production-ready and secure by default.",
    "evidenceFound": ["middleware", "test"],
    "evidenceMissing": ["threat-model", "rateLimit"],
    "recommendation": "add-evidence"
  },
  "prPlan": {
    "branchName": "refactor/p1-route-handler-validation",
    "testsToRun": ["unit tests", "typecheck"],
    "docsToUpdate": ["README.md if public behavior changed"]
  }
}

What CodeAudit Is Not

• Not a replacement for Semgrep, CodeQL, or SAST.
• Not a vulnerability scanner.
• Not an autonomous GitHub mutation bot.
• Not a deep AST analyzer yet.
• Best used as a read-only planning and evidence-gathering layer for AI coding agents.

Future Work

• More language/framework detectors.
• AST-based checks using the TypeScript compiler API or ts-morph.
• JSON and SARIF report formats.
• Deeper AST-based duplicate and complexity analysis.
• Optional report writer tool gated by explicit approval.
• Optional GitHub issue/PR creation gated by explicit approval.
• Broader security policy packs for Firebase, Azure, and AI agents.
• Optional OAuth provider integration for hosted multi-user deployments.