RepoSentinel

Servidor MCP com inteligência artificial que audita codebases locais quanto à qualidade do código, segurança, estrutura do projeto e capacidade de manutenção.

GitHub
1

Documentação

CodeAudit MCP

npm CI MCP License: MIT

O CodeAudit MCP é um servidor MCP somente leitura que ajuda agentes de codificação de IA a inspecionar repositórios, rotear habilidades de engenharia, verificar afirmações de documentação, auditar qualidade de código e planejar fluxos de trabalho mais seguros de issues/PRs.

O MVP atual é somente leitura por padrão. Ele suporta transporte local stdio e Streamable HTTP. Não implementa execução irrestrita de shell, mutação remota de repositórios, auto-push, auto-delete ou auto-merge.

Status de Produção

O CodeAudit é utilizável agora para inspeção de repositórios somente leitura em estilo de produção e roteamento de fluxo de trabalho de agentes quando implantado com os controles documentados:

  • use stdio para clientes de agentes locais confiáveis, ou Streamable HTTP atrás de HTTPS para clientes remotos
  • defina CODEAUDIT_API_KEY para qualquer implantação HTTP que não seja estritamente local
  • defina CODEAUDIT_ALLOWED_ROOTS para implantações HTTP hospedadas para que leituras de projetos permaneçam dentro de workspaces aprovados
  • restrinja CODEAUDIT_ALLOWED_ORIGINS para implantações acessíveis via navegador
  • mantenha o servidor somente leitura; não adicione ferramentas de escrita/mutação no GitHub sem um modelo de aprovação

Validado neste repositório com CI, pnpm check, pnpm build, testes de smoke de health/metadata HTTP, testes de rejeição de root permitido, auditoria de afirmações de documentação e auditoria de habilidades instaladas. Identidade multi-usuário OAuth ainda não foi implementada; use proteção por API-key/Bearer para implantações HTTP hospedadas.

O Que Funciona

  • detect_project identifica projetos vazios/existentes, gerenciador de pacotes, framework, linguagem, testes, autenticação, banco de dados, implantação, CI e notas de risco.
  • A detecção de Python cobre pyproject.toml, uv.lock, FastAPI, Django, Flask, Python MCP SDK, pytest, ferramentas de tipagem/lint, autenticação, banco de dados e indicadores de implantação.
  • route_skills retorna um manifesto de roteamento de habilidades com fases de fluxo de trabalho, sequência recomendada de ferramentas, ordem de ativação de habilidades, portões de qualidade, saídas obrigatórias, instruções estritas e ações proibidas.
  • scan_repo resume árvores e classifica arquivos importantes, de risco, de documentação, de teste e de configuração.
  • audit_code_quality executa verificações heurísticas de manutenibilidade para arquivos longos, limites de schema fracos, testes ausentes, responsabilidades mistas e tratamento fraco de erros.
  • audit_nextjs_security executa verificações heurísticas para rotas Next.js, middleware, env, headers, validação, logging, redirect, SSRF, upload, rate-limit e indicadores de autenticação.
  • audit_docs_claims mapeia afirmações fortes de README/documentação para evidências encontradas ou ausentes.
  • audit_tests resume a configuração de testes e áreas de teste ausentes.
  • audit_installed_skills verifica habilidades locais de agentes para riscos de supply-chain, injeção de prompt, vazamento de segredos, instalação de dependências, webhook, shell destrutivo, qualidade de manifesto, nomes duplicados, documentação auxiliar e descoberta de recursos.
  • official_docs_router recomenda onde consultar documentação oficial/atual.
  • generate_issue_plan, generate_pr_plan e generate_report produzem artefatos de planejamento a partir das descobertas.
  • Recursos expõem codeaudit://docs/llms e codeaudit://skills/index para descoberta nativa do MCP.

Início Rápido

Execute o pacote npm público gratuito diretamente:

npx -y @priyanshuchawda/codeaudit

Para desenvolvimento local a partir do checkout do GitHub:

pnpm install
pnpm build

Execute stdio local:

pnpm --filter @priyanshuchawda/codeaudit start

Execute stdio de desenvolvimento local:

pnpm --filter @priyanshuchawda/codeaudit dev

Execute Streamable HTTP com proteção por 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
  • health: http://127.0.0.1:3000/health
  • metadata: http://127.0.0.1:3000/.well-known/codeaudit

Exemplo de comando do MCP Inspector:

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

Adicionar ao Codex

Configuração stdio npm para ~/.codex/config.toml ou .codex/config.toml local do projeto:

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

Configuração stdio de checkout local:

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

Exemplo para Windows:

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

Configuração HTTP:

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

Primeiro prompt recomendado após 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.

Documentação

  • Comece com docs/llms.txt para o índice completo da documentação.
  • Use docs/clients.md para exemplos de configuração do Codex, Claude Code, Cursor, VS Code, Claude Desktop, Gemini CLI e MCP Inspector.
  • Use docs/deployment.md para implantação HTTP em produção, Docker, variáveis de ambiente e verificação.
  • O CodeAudit suporta conexões MCP locais stdio e Streamable HTTP. Implantações HTTP podem ser protegidas com API key ou token Bearer.

Distribuição Pública Gratuita

  • Pacote público npm: @priyanshuchawda/codeaudit
  • Versão npm atual: 0.1.5
  • Pacotes públicos npm são gratuitos para publicar com npm publish --access public.
  • A publicação de releases é configurada por meio de .github/workflows/publish-npm.yml.
  • Para publicar, adicione um token npm granular de escrita com bypass de 2FA habilitado como o segredo do GitHub NPM_TOKEN, depois crie um release no GitHub.
  • Usuários podem instalar e executar sem clonar o GitHub usando npx -y @priyanshuchawda/codeaudit.

CLI de Habilidades

Instale a habilidade pública do CodeAudit sem clonar este repositório:

npx skills add priyanshuchawda/codeaudit --skill codeaudit

Liste habilidades públicas disponíveis:

npx skills add priyanshuchawda/codeaudit --list

O formato do catálogo público expõe intencionalmente uma habilidade, codeaudit. Fluxos de trabalho especializados sob skills/ são marcados como metadata.internal: true para que o CodeAudit possa manter seu vocabulário interno de roteamento sem duplicar habilidades públicas no skills.sh.

Modelo de Segurança

  • Ferramentas são registradas com anotações somente leitura.
  • O acesso ao sistema de arquivos é limitado à raiz do projeto fornecida.
  • Implantações HTTP hospedadas restringem projectPath a CODEAUDIT_ALLOWED_ROOTS; quando não definido no modo HTTP, o servidor usa como padrão process.cwd().
  • Formatos comuns de segredos são redigidos antes da saída.
  • A execução de comandos não é exposta como ferramenta MCP.
  • O executor de comandos interno suporta apenas uma pequena allowlist.
  • Arquivos de habilidades são tratados como entrada não confiável e podem ser auditados antes do uso.
  • Documentação externa é tratada como dados de referência não confiáveis.
  • Relatórios gerados são retornados como strings markdown; este servidor não os escreve em repositórios de destino.

Pacote de Habilidades

Habilidades personalizadas ficam em skills/:

  • codeaudit habilidade guarda-chuva 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 são escritas para que clientes que não podem ativar habilidades literalmente ainda possam usar route_skills como um manifesto de habilidades recomendadas, fases de fluxo de trabalho ordenadas, sequência de ferramentas, saídas e guardrails.

Exemplo de Fluxo de Trabalho

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

Depois, roteie:

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

Para um projeto existente, execute auditorias antes de refatorações:

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

Exemplo de Saída

Quando executado em um projeto Next.js existente, o CodeAudit retorna stack detectado e notas de risco, listas de arquivos importantes/risco/docs/teste/config, descobertas de qualidade de código, afirmações de documentação com evidências encontradas ou ausentes, um plano de issue recomendado e um plano 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"]
  }
}

O Que o CodeAudit Não É

  • Não é um substituto para Semgrep, CodeQL ou SAST.
  • Não é um scanner de vulnerabilidades.
  • Não é um bot autônomo de mutação no GitHub.
  • Ainda não é um analisador profundo de AST.
  • Melhor usado como uma camada de planejamento e coleta de evidências somente leitura para agentes de codificação de IA.

Trabalho Futuro

  • Mais detectores de linguagem/framework.
  • Verificações baseadas em AST usando a API do compilador TypeScript ou ts-morph.
  • Formatos de relatório JSON e SARIF.
  • Análise mais profunda de duplicação e complexidade baseada em AST.
  • Ferramenta opcional de escrita de relatórios controlada por aprovação explícita.
  • Criação opcional de issues/PRs no GitHub controlada por aprovação explícita.
  • Pacotes de políticas de segurança mais amplos para Firebase, Azure e agentes de IA.
  • Integração opcional de provedor OAuth para implantações hospedadas multi-usuário.