GitPilot MCP

GitPilot es un plano de control de ingeniería de IA con estado para GitHub. Conecta incidencias, código local aprobado, memoria de proyecto duradera y ejecuciones de verificación auditables a través de herramientas MCP y un panel web.

Capacidades

• Enumera los repositorios propios, de colaboradores y de organizaciones disponibles para la identidad de GitHub conectada.

• Crea, actualiza, etiqueta, comenta, cierra y reabre incidencias.

• Recupera el conocimiento del repositorio entre sesiones de IA.

• Recupera fragmentos de código clasificados dentro de presupuestos de tokens fijos.

• Lee rangos de archivos acotados y aplica ediciones de coincidencia exacta.

• Ejecuta únicamente comandos de verificación derivados del manifiesto.

• Exige una verificación correcta antes de completar una ejecución de corrección de IA.

• Mantiene un historial de solo añadidura de contexto, lecturas, ediciones, comprobaciones y finalización.

• Conecta el proveedor de IA propio de un repositorio y genera una propuesta de parche estructurada, la aplica solo con aprobación explícita, la verifica y la publica como solicitud de extracción en borrador — nunca en una rama protegida, nunca sin una segunda aprobación explícita para publicar.

• Opcionalmente, permite que GitPilot reintente automáticamente tras una verificación fallida (hasta un número acotado de intentos), arrastrando solo el fallo, no todo el repositorio — y aun así se detiene para revisión humana ante una propuesta de alto riesgo o baja confianza, y nunca publica por su cuenta.

• Selecciona un modo manual sin IA con ámbito de repositorio que bloquea las llamadas al proveedor conservando evidencia acotada, ediciones exactas, ramas aisladas, verificación en lista de permitidos, historial de auditoría y publicación de PR en borrador — siempre a un clic de distancia, incluso tras un fallo de facturación, cuota o credencial en la ruta de IA.

Related MCP server: Agentic CI/CD MCP Orchestrator

Configuración

cd /d "C:\Projects - Building\GithubPilotMCP"
.venv\Scripts\activate.bat
pip install -r requirements.txt
copy .env.example .env

Inicia el panel y pega un token de acceso personal de GitHub en Connect repository & brain. En una instalación local solo de bucle de retorno, GitPilot crea una clave de bóveda persistente privada en data/.gitpilot-master-key, valida el token, lo cifra en reposo y nunca lo devuelve al navegador. Las implementaciones de producción, ensayo y expuestas a la red deben establecer GITPILOT_MASTER_KEY mediante almacenamiento seguro de secretos. Como alternativa de arranque, establece GITHUB_TOKEN en .env.

Prefiere un token de grano fino con acceso solo a los repositorios previstos. Usa Metadata read, Contents read/write, Issues read/write y Pull requests read/write cuando quieras el flujo de trabajo completo de diagnóstico, parche y PR en borrador. GitHub puede exigir que el propietario del repositorio o el administrador de la organización aprueben el acceso; GitPilot no puede eludir esa aprobación.

Asigna los repositorios locales aprobados para operaciones de código:

GITPILOT_CODE_ROOTS=my-repo=C:\path\to\my-repo

Separa varias asignaciones con punto y coma. GitPilot enumera todos los repositorios disponibles para el token, pero solo puede leer o editar código en espacios de trabajo asignados explícitamente.

Setup Doctor

Antes de registrar GitPilot con Claude, comprueba que todo esté configurado correctamente:

python setup_doctor.py

Cada comprobación imprime un estado en lenguaje sencillo, un paso de recuperación exacto si algo falla y detalles legibles por máquina. Nunca imprime un valor de token. El doctor reconoce tanto las conexiones cifradas del panel como GITHUB_TOKEN, y luego verifica Python, dependencias, autenticación de GitHub, acceso a repositorios, SQLite, espacios de trabajo de código, preparación de MCP, el puerto del panel y la preparación del registro de la CLI de Claude.

Panel

python dashboard.py

Abre http://127.0.0.1:8765. Mantén esta interfaz en localhost o colócala detrás de TLS autenticado.

El control Log in proporciona cuentas nativas de correo electrónico/contraseña sin requerir Google. La creación de cuentas solicita el nombre de perfil de GitHub, no un repositorio. Cada cuenta recibe un ID de cliente único. Las contraseñas se salan y se aplica un hash unidireccional con scrypt; las credenciales de GitHub e IA continúan cifradas con GITPILOT_MASTER_KEY y tienen ámbito de ese ID de cliente. Los clientes también pueden crear claves de API de GitPilot revocables gp_live_... desde Account & API access. La clave de API en texto plano se muestra una sola vez y solo se almacena su hash SHA-256.

GitPilot nunca recopila una combinación de nombre de usuario/contraseña de GitHub ni un OTP de GitHub. Con una GitHub App configurada, la creación de cuentas continúa en la pantalla de instalación de GitHub para que el cliente elija los repositorios y permisos exactos. Con OAuth configurado, GitPilot redirige al flujo de código de autorización de GitHub con validación de estado y PKCE; GitHub gestiona el inicio de sesión y la autenticación de dos factores en github.com, y luego devuelve un token de autorización. Un token de acceso personal validado sigue siendo la alternativa local. La identidad de GitHub verificada reemplaza cualquier error tipográfico de perfil escrito, y GitPilot enumera solo los repositorios que GitHub indica que la conexión puede acceder.

La selección de repositorios ocurre después de verificar la conexión. El cliente puede ejecutar Select repositories de nuevo más tarde tras crear un repositorio, aceptar una invitación o ampliar una instalación de token/App. Los repositorios de propietario separado y de organizaciones siguen sujetos a las reglas de aprobación de GitHub.

La vista previa local de invitado sigue disponible de forma predeterminada. Para un servicio de cliente implementado, establece GITPILOT_REQUIRE_ACCOUNT_LOGIN=true, configura un GITPILOT_SESSION_SECRET persistente, establece GITPILOT_HTTPS_ONLY=true y termina el tráfico mediante HTTPS. No crees archivos de Python o de configuración que contengan los secretos de un cliente; los registros de credenciales pertenecen a la bóveda de base de datos cifrada con ámbito del propietario.

Para una presentación fiable sin depender de la conectividad del lugar ni de una cuenta de GitHub en vivo, abre http://127.0.0.1:8765/?demo=1. El modo demo está claramente etiquetado y usa datos simulados de repositorio, incidencia, recuperación, memoria, modelo, costo, conexión de GitHub, conexión de proveedor de IA y Brain Profile. La URL normal siempre usa servicios reales configurados.

Conecta el repositorio y selecciona tu cerebro

Haz clic en Connect repository & brain para abrir el asistente de configuración: pega y valida un token de GitHub, selecciona cualquier repositorio accesible propio/de colaborador/de organización, elige DeepSeek, Anthropic, OpenAI-compatible/local, Google Gemini o xAI Grok, conecta la clave de proveedor propia del cliente, elige un modelo, establece límites de tokens y costos, y revisa todo antes de activar. Esto es BYOK (trae tu propia clave): GitPilot nunca suministra una clave de desarrollador compartida, nunca recurre a la clave del operador y nunca comparte la credencial de un cliente con otro cliente. El uso y los cargos del proveedor pertenecen a la cuenta de cliente que emitió la clave. El comprobador de acceso explica cuándo un propietario separado o una organización debe aprobar el acceso, y el asistente puede aceptar una invitación de repositorio pendiente después de que GitHub la emita. Una GitHub App configurada sigue siendo un modo de conexión adicional opcional. Consulta docs/BRAIN.md para conocer la arquitectura completa, el modelo de datos y el modelo de amenazas.

En la selección del flujo de trabajo, elige Manual / no AI para operar sin credencial de IA ni llamada al proveedor. Esta elección se almacena de forma independiente para cada repositorio y la aplica el backend. Volver a la IA requiere activar explícitamente un Brain Profile de repositorio válido.

El acceso a IA alojada y las suscripciones de chat son productos separados. El acceso a ChatGPT Plus/Pro o Codex no proporciona automáticamente facturación de la API de OpenAI Platform para las llamadas realizadas por GitPilot, y una suscripción de chat de DeepSeek no financia la API de DeepSeek. El asistente hace explícita esta distinción. Para no incurrir en cargos de modelo alojado, usa Manual / no AI o conecta un servidor local estilo Ollama/vLLM mediante OpenAI-compatible / local. DeepSeek V4 Flash es la opción alojada de menor costo en el catálogo integrado, pero aun así requiere una clave de API de DeepSeek Platform y saldo disponible.

Los usuarios sin clave de API pueden elegir Use external chat (copy/paste). Esta es una alternativa manual separada, no una conexión de cuenta de ChatGPT/Claude: GitPilot no puede iniciar sesión ni operar la suscripción del usuario. Construye un prompt acotado y listo para copiar que contiene solo la evidencia de la incidencia seleccionada y los comandos de verificación en lista de permitidos. El usuario pega ese prompt en un asistente externo y luego pega la propuesta JSON devuelta de nuevo en GitPilot. El resultado importado no es de confianza: debe pasar los mismos controles de ámbito de archivo, coincidencia exacta, tamaño de parche, comando de verificación, hash de propuesta, aprobación humana, rama aislada y pruebas que una propuesta generada por API. GitPilot no realiza ninguna llamada al proveedor y registra cero costo de modelo para esta transferencia.

Una vez que el cerebro de un repositorio está activo, iniciar una corrección guiada desde una incidencia la recorre a través de evidence → diagnosis → patch proposal → approve & apply (isolated branch) → verify → approve & publish (draft PR) — cada etapa se muestra en el panel de canalización del panel, y cada escritura en el sistema de archivos/GitHub está controlada por su propia aprobación humana explícita. Consulta docs/BRAIN.md §16 para saber exactamente qué puede y qué no puede hacer la IA en cada etapa.

Inicio de sesión multiinquilino alojado (opcional, beta)

De forma predeterminada, el panel se ejecuta en modo local de propietario único — sin inicio de sesión, idéntico al actual. Para permitir que varias personas inicien sesión con su propia cuenta de GitHub:

1. Crea una GitHub OAuth App en https://github.com/settings/developers. Establece su URL de devolución de llamada de autorización en http://<your-host>/auth/callback.

2. Establece GITHUB_OAUTH_CLIENT_ID y GITHUB_OAUTH_CLIENT_SECRET en .env desde esa app.

3. Genera una GITPILOT_MASTER_KEY (consulta .env.example) — esto cifra el token de GitHub de cada usuario con sesión iniciada en reposo. Nunca la confirmes ni la compartas fuera del almacenamiento de secretos de tu implementación.

4. Reinicia el panel. Los visitantes ahora ven una pantalla de "Log in with GitHub".

La memoria del proyecto y el historial de ejecuciones de corrección tienen ámbito del usuario con sesión iniciada en modo alojado. La edición de código local sigue deliberadamente no disponible para los usuarios alojados porque un servicio alojado no puede acceder de forma segura al disco de un cliente; ejecuta el cliente MCP localmente para operaciones de código.

Las cuentas nativas de GitPilot son independientes del flujo opcional de OAuth de GitHub. Un cliente puede crear primero un espacio de trabajo de correo electrónico/contraseña y luego pegar un token de acceso personal de GitHub de grano fino en el asistente de repositorios. OAuth puede permanecer deshabilitado para una implementación solo local.

Para la incorporación de clientes más sólida, configura una GitHub App pública y establece GITHUB_APP_ID, GITHUB_APP_SLUG y GITHUB_APP_PRIVATE_KEY_PATH. Las GitHub Apps son preferibles porque los clientes eligen repositorios específicos y la app recibe permisos de grano fino y tokens de instalación de corta duración. OAuth sigue siendo una alternativa compatible. Un token de acceso personal de grano fino cifrado sigue disponible para el desarrollo local donde no está configurada ninguna de las dos integraciones.

Los valores opcionales GITPILOT_INPUT_USD_PER_MTOK y GITPILOT_OUTPUT_USD_PER_MTOK controlan la estimación de planificación neutral respecto al proveedor que se muestra antes de una ejecución. La facturación real del proveedor sigue siendo la autoritativa.

Claude MCP

Regístrate una vez:

claude mcp add gitpilot -- "C:\Projects - Building\GithubPilotMCP\.venv\Scripts\python.exe" "C:\Projects - Building\GithubPilotMCP\server.py"

Ejemplo de prompt:

Start an AI fix run for issue #12 in atlas-library-ai. Recall project memory, inspect only the ranked files, make the smallest safe edit, verify it, save the resolution, and only then close the issue.

El flujo manual usa ai_start_issue_fix, ai_read_file, ai_edit_file, ai_verify_fix y ai_complete_issue_fix. Cuando un repositorio tiene un Brain Profile activo, el flujo de corrección guiada (ai_generate_patch_proposal, ai_approve_and_apply_patch, ai_verify_fix, ai_publish_fix) impulsa los mismos límites de recopilación de evidencia y aprobación humana mediante un parche redactado por IA en lugar de ediciones manuales. Nunca se aceptan comandos de shell arbitrarios.

Las ediciones exactas manuales se someten a hash para auditoría, se aplican solo en una rama dedicada gitpilot/fix-* y pueden usar el mismo publicador verificado de solicitudes de extracción en borrador. Los parches generados por IA requieren el hash exacto de la propuesta revisada; omitirlo falla de forma segura.

Docker

docker compose up --build

La imagen se ejecuta como un usuario no root con un sistema de archivos de solo lectura. SQLite persiste en data/ y el código aprobado se monta por separado.

Pruebas

python -m pytest -q

Esto ejecuta solo la suite completa sin conexión — cada prueba de credenciales en vivo es opcional y se omite de forma predeterminada (tests/test_live_integration.py, tests/test_live_guided_fix_integration.py). Consulta sus cadenas de documentación de módulo para obtener instrucciones de configuración exactas si quieres ejercitar una instalación real de GitHub App y un proveedor de IA real de extremo a extremo.

Consulta docs/ARCHITECTURE.md para el modelo de memoria, la máquina de estados, los límites de proveedor y la guía de producción, y docs/BRAIN.md para la conexión de GitHub App, la bóveda de proveedores de IA, Repository Brain Profile y el pipeline de parches de corrección guiada. Nunca hagas commit de .env ni expongas tokens en registros o capturas de pantalla.