RepoSentinel

Servidor MCP impulsado por IA que audita bases de código locales en cuanto a calidad de código, seguridad, estructura del proyecto y mantenibilidad.

GitHub
1

Documentación

CodeAudit MCP

npm CI MCP License: MIT

CodeAudit MCP es un servidor MCP de solo lectura que ayuda a los agentes de codificación de IA a inspeccionar repositorios, enrutar habilidades de ingeniería, verificar afirmaciones de documentación, auditar la calidad del código y planificar flujos de trabajo más seguros de issues/PR.

El MVP actual es de solo lectura por defecto. Soporta transporte local stdio y Streamable HTTP. No implementa ejecución de shell sin restricciones, mutación remota de repositorios, auto-push, auto-delete ni auto-merge.

Estado de Producción

CodeAudit es utilizable ahora para inspección de repositorios de solo lectura de estilo producción y enrutamiento de flujos de trabajo de agentes cuando se despliega con los controles documentados:

  • use stdio para clientes de agentes locales de confianza, o Streamable HTTP detrás de HTTPS para clientes remotos
  • establezca CODEAUDIT_API_KEY para cualquier despliegue HTTP que no sea estrictamente local
  • establezca CODEAUDIT_ALLOWED_ROOTS para despliegues HTTP alojados para que las lecturas de proyectos permanezcan dentro de los espacios de trabajo aprobados
  • restrinja CODEAUDIT_ALLOWED_ORIGINS para despliegues accesibles desde navegador
  • mantenga el servidor de solo lectura; no agregue herramientas de escritura/mutación de GitHub sin un modelo de aprobación

Validado en este repositorio con CI, pnpm check, pnpm build, pruebas de humo de salud/metadatos HTTP, pruebas de rechazo de raíz permitida, auditoría de afirmaciones de documentación y auditoría de habilidades instaladas. La identidad multi-usuario OAuth aún no está implementada; use protección API-key/Bearer para despliegues HTTP alojados.

Lo Que Funciona

  • detect_project identifica proyectos vacíos/existentes, gestor de paquetes, framework, lenguaje, pruebas, autenticación, base de datos, despliegue, CI y notas de riesgo.
  • La detección de Python cubre pyproject.toml, uv.lock, FastAPI, Django, Flask, Python MCP SDK, pytest, herramientas de tipado/lint, autenticación, base de datos e indicadores de despliegue.
  • route_skills devuelve un manifiesto de enrutamiento de habilidades con fases de flujo de trabajo, secuencia de herramientas recomendada, orden de activación de habilidades, puertas de calidad, salidas requeridas, instrucciones estrictas y acciones no permitidas.
  • scan_repo resume árboles y clasifica archivos importantes, de riesgo, de documentación, de prueba y de configuración.
  • audit_code_quality ejecuta comprobaciones heurísticas de mantenibilidad para archivos largos, límites de esquema débiles, pruebas faltantes, responsabilidades mixtas y manejo de errores débil.
  • audit_nextjs_security ejecuta comprobaciones heurísticas para rutas de Next.js, middleware, env, cabeceras, validación, registro, redirección, SSRF, subida, límite de tasa e indicadores de autenticación.
  • audit_docs_claims mapea afirmaciones sólidas de README/docs a evidencia encontrada o faltante.
  • audit_tests resume la configuración de pruebas y las áreas de prueba faltantes.
  • audit_installed_skills comprueba habilidades de agentes locales para riesgos de cadena de suministro, inyección de prompts, fuga de secretos, instalación de dependencias, webhooks, shell destructivo, calidad de manifiesto, nombres duplicados, documentos auxiliares y descubrimiento de recursos.
  • official_docs_router recomienda dónde buscar documentación oficial/actual.
  • generate_issue_plan, generate_pr_plan y generate_report producen artefactos de planificación a partir de hallazgos.
  • Los recursos exponen codeaudit://docs/llms y codeaudit://skills/index para descubrimiento nativo de MCP.

Inicio Rápido

Ejecute el paquete npm público gratuito directamente:

npx -y @priyanshuchawda/codeaudit

Para desarrollo local desde el checkout de GitHub:

pnpm install
pnpm build

Ejecute stdio local:

pnpm --filter @priyanshuchawda/codeaudit start

Ejecute stdio de desarrollo local:

pnpm --filter @priyanshuchawda/codeaudit dev

Ejecute Streamable HTTP con protección API-key:

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

Endpoints HTTP:

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

Comando de ejemplo de MCP Inspector:

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

Agregar a Codex

Configuración stdio de npm para ~/.codex/config.toml o .codex/config.toml local del proyecto:

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

Configuración stdio de checkout local:

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

Ejemplo de Windows:

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

Configuración HTTP:

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

Primer prompt recomendado después de conectar:

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

Documentación

  • Comience con docs/llms.txt para el índice completo de documentación.
  • Use docs/clients.md para ejemplos de configuración de Codex, Claude Code, Cursor, VS Code, Claude Desktop, Gemini CLI y MCP Inspector.
  • Use docs/deployment.md para despliegue HTTP de producción, Docker, variables de entorno y verificación.
  • CodeAudit soporta conexiones MCP stdio local y Streamable HTTP. Los despliegues HTTP pueden protegerse con una API key o token Bearer.

Distribución Pública Gratuita

  • Paquete público npm: @priyanshuchawda/codeaudit
  • Versión npm actual: 0.1.5
  • Los paquetes públicos npm son gratuitos de publicar con npm publish --access public.
  • La publicación de versiones está configurada a través de .github/workflows/publish-npm.yml.
  • Para publicar, agregue un token npm de escritura granular con 2FA omitido habilitado como secreto de GitHub NPM_TOKEN, luego cree una versión de GitHub.
  • Los usuarios pueden instalar y ejecutar sin clonar GitHub usando npx -y @priyanshuchawda/codeaudit.

CLI de Habilidades

Instale la habilidad pública de CodeAudit sin clonar este repositorio:

npx skills add priyanshuchawda/codeaudit --skill codeaudit

Liste las habilidades públicas disponibles:

npx skills add priyanshuchawda/codeaudit --list

La forma del catálogo público expone intencionalmente una habilidad, codeaudit. Los flujos de trabajo especializados bajo skills/ están marcados como metadata.internal: true para que CodeAudit pueda mantener su vocabulario interno de enrutamiento sin duplicar habilidades públicas en skills.sh.

Modelo de Seguridad

  • Las herramientas están registradas con anotaciones de solo lectura.
  • El acceso al sistema de archivos está limitado a la raíz del proyecto suministrada.
  • Los despliegues HTTP alojados restringen projectPath a CODEAUDIT_ALLOWED_ROOTS; cuando no se establece en modo HTTP, el servidor usa por defecto process.cwd().
  • Los formatos comunes de secretos se redactan antes de la salida.
  • La ejecución de comandos no se expone como herramienta MCP.
  • El ejecutor de comandos interno solo soporta una pequeña lista de permitidos.
  • Los archivos de habilidades se tratan como entrada no confiable y pueden auditarse antes de su uso.
  • La documentación externa se trata como datos de referencia no confiables.
  • Los informes generados se devuelven como cadenas markdown; este servidor no los escribe en los repositorios de destino.

Paquete de Habilidades

Las habilidades personalizadas viven en skills/:

  • codeaudit habilidad general pública para 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

Estas habilidades están escritas para que los clientes que no pueden activar habilidades literalmente aún puedan usar route_skills como manifiesto de habilidades recomendadas, fases de flujo de trabajo ordenadas, secuencia de herramientas, salidas y salvaguardas.

Flujo de Trabajo de Ejemplo

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

Luego enrute:

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

Para un proyecto existente, ejecute auditorías antes de refactorizaciones:

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

Salida de Ejemplo

Cuando se ejecuta en un proyecto Next.js existente, CodeAudit devuelve la pila detectada y notas de riesgo, listas de archivos importantes/riesgo/docs/pruebas/configuración, hallazgos de calidad de código, afirmaciones de documentación con evidencia encontrada o faltante, un plan de issues recomendado y un plan de PR recomendado.

{
  "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"]
  }
}

Lo Que CodeAudit No Es

  • No es un reemplazo de Semgrep, CodeQL o SAST.
  • No es un escáner de vulnerabilidades.
  • No es un bot autónomo de mutación de GitHub.
  • Aún no es un analizador AST profundo.
  • Mejor usado como capa de planificación y recopilación de evidencia de solo lectura para agentes de codificación de IA.

Trabajo Futuro

  • Más detectores de lenguaje/framework.
  • Comprobaciones basadas en AST usando la API del compilador de TypeScript o ts-morph.
  • Formatos de informe JSON y SARIF.
  • Análisis más profundo de duplicados y complejidad basado en AST.
  • Herramienta opcional de escritura de informes controlada por aprobación explícita.
  • Creación opcional de issues/PR de GitHub controlada por aprobación explícita.
  • Paquetes de políticas de seguridad más amplios para Firebase, Azure y agentes de IA.
  • Integración opcional de proveedor OAuth para despliegues alojados multi-usuario.