Servidor GIT MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona herramientas para interactuar con repositorios Git. Este servidor permite a los asistentes de IA y agentes LLM gestionar repositorios, ramas, confirmaciones y archivos mediante una interfaz estandarizada sin necesidad de acceso directo al sistema de archivos ni a la línea de comandos. Expone las operaciones Git como recursos y herramientas MCP, aprovechando la biblioteca simple-git para la funcionalidad principal, manteniendo al mismo tiempo los límites de seguridad adecuados.

Tabla de contenido

Descripción general
- Arquitectura y componentes
Características
- Acceso a recursos
- Operaciones de Git
Instalación
Uso
Estructura del proyecto
Herramientas
Recursos
- Recursos del repositorio
Desarrollo
- Construir y probar
Licencia

Descripción general

Capacidades clave:

Gestión de repositorios : inicializar, clonar y comprobar el estado del repositorio
Operaciones de sucursal : crear, enumerar, retirar, eliminar y fusionar sucursales
Directorio de trabajo : preparar archivos, confirmar cambios, crear diferencias
Operaciones remotas : agregar controles remotos, buscar, extraer, enviar
Comandos avanzados de Git : administrar etiquetas, almacenar cambios, seleccionar elementos, reorganizar

Arquitectura y componentes

Arquitectura del sistema central:

Componentes principales:

Servidor MCP ( server.ts ) : utiliza @modelcontextprotocol/sdk para crear un servidor que expone recursos y herramientas.
Servicio Git ( services/git-service.ts ) : capa de abstracción sobre la biblioteca simple-git que proporciona interfaces limpias para las operaciones de Git.
Recursos ( resources/ ) : expone datos de Git (como estado, registros, contenido de archivos) a través de recursos MCP con plantillas de URI consistentes.
Herramientas ( tools/ ) : Exponer acciones de Git (como confirmar, enviar, extraer) a través de herramientas MCP con esquemas de entrada bien definidos (validados usando Zod).
Manejo de errores ( services/error-service.ts ) : manejo y generación de informes de errores estandarizados para operaciones de Git y MCP.
Punto de entrada ( index.ts ) : inicializa e inicia el servidor, conectándolo al transporte de E/S estándar.

Características

Acceso a recursos

Exponer información del repositorio de Git a través de recursos MCP:

Información del repositorio : acceda a información básica del repositorio Git, incluida la rama actual, el estado y los detalles de referencia
Ramas del repositorio : enumera todas las ramas del repositorio con el indicador de rama actual
Repositorios remotos : enumera todos los repositorios remotos configurados con sus URL
Etiquetas del repositorio : enumera todas las etiquetas del repositorio con sus referencias
Contenido del archivo : acceder al contenido de archivos específicos en una referencia de Git determinada
Listado de directorios : vea listas de archivos y directorios en una ruta específica y referencia
Diffs : Obtenga diferencias entre referencias, cambios no preparados o cambios preparados
Historial de confirmaciones : vea registros de confirmaciones detallados con información del autor, la fecha y el mensaje
Archivo Blame : vea la atribución línea por línea que muestra qué confirmación modificó por última vez cada línea
Detalles de confirmación : acceda a información detallada sobre confirmaciones específicas, incluidos cambios de diferencias

Operaciones de Git

Ejecutar comandos Git a través de herramientas MCP:

Operaciones del repositorio : inicializar repositorios, clonar desde remotos, verificar el estado del repositorio
Operaciones de sucursal : crear sucursales, listar sucursales, retirar, eliminar sucursales, fusionar
Operaciones del directorio de trabajo : preparar archivos, retirar archivos del escenario, confirmar cambios, crear diferencias
Operaciones remotas : agregar controles remotos, enumerar controles remotos, buscar, extraer, enviar
Operaciones avanzadas : administrar etiquetas, guardar cambios, seleccionar confirmaciones, reorganizar ramas, restablecer, limpiar

Instalación

Prerrequisitos

Node.js 16 o superior
Git instalado y disponible en PATH

Instalar desde NPM

npm install -g @cyanheads/git-mcp-server

Instalar desde la fuente

git clone https://github.com/cyanheads/git-mcp-server.git
cd git-mcp-server
npm install
npm run build

Uso

Ejecución del servidor

Si se instala globalmente a través de NPM:

git-mcp-server

Si se ejecuta desde la fuente:

node build/index.js

El servidor se comunica a través de stdin/stdout utilizando el Protocolo de Contexto de Modelo, lo que lo hace compatible con cualquier cliente MCP.

Integración con Claude

Agregue a su archivo de configuración de Claude (por ejemplo, cline_mcp_settings.json o claude_desktop_config.json ):

{
  "mcpServers": {
    "git": {
      "command": "git-mcp-server", // Or the full path to build/index.js if not installed globally
      "args": [],
      "env": {},
      "disabled": false,
      "autoApprove": [] // Configure auto-approval rules if desired
    }
  }
}

Integración con otros clientes MCP

Utilice el inspector MCP para probar el servidor:

# If installed globally
npx @modelcontextprotocol/inspector git-mcp-server

# If running from source
npx @modelcontextprotocol/inspector build/index.js

Estructura del proyecto

El código base sigue una estructura modular:

git-mcp-server/
├── src/
│   ├── index.ts           # Entry point: Initializes and starts the server
│   ├── server.ts          # Core MCP server implementation and setup
│   ├── resources/         # MCP Resource implementations
│   │   ├── descriptors.ts # Resource URI templates and descriptions
│   │   ├── diff.ts        # Diff-related resources (staged, unstaged, commit)
│   │   ├── file.ts        # File content and directory listing resources
│   │   ├── history.ts     # Commit history and blame resources
│   │   ├── index.ts       # Aggregates and registers all resources
│   │   └── repository.ts  # Repository info, branches, remotes, tags resources
│   ├── services/          # Core logic and external integrations
│   │   ├── error-service.ts # Centralized error handling utilities
│   │   └── git-service.ts   # Abstraction layer for simple-git operations
│   ├── tools/             # MCP Tool implementations
│   │   ├── advanced.ts    # Advanced Git tools (tag, stash, cherry-pick, rebase, log, show)
│   │   ├── branch.ts      # Branch management tools (list, create, checkout, delete, merge)
│   │   ├── index.ts       # Aggregates and registers all tools
│   │   ├── remote.ts      # Remote interaction tools (add, list, fetch, pull, push)
│   │   ├── repository.ts  # Repository level tools (init, clone, status)
│   │   └── workdir.ts     # Working directory tools (add, reset, commit, diff, reset-commit, clean)
│   ├── types/             # TypeScript type definitions
│   │   └── git.ts         # Custom types related to Git operations
│   └── utils/             # Shared utility functions
│       ├── global-settings.ts # Manages global working directory setting
│       └── validation.ts  # Input validation schemas (Zod) and helpers
├── build/                 # Compiled JavaScript output
├── docs/                  # Documentation files
├── logs/                  # Log files (if any)
├── scripts/               # Helper scripts for development (e.g., clean, tree)
├── .env.example           # Example environment variables
├── .gitignore             # Git ignore rules
├── LICENSE                # Project license file
├── package.json           # Project metadata and dependencies
├── package-lock.json      # Lockfile for dependencies
├── README.md              # This file
└── tsconfig.json          # TypeScript compiler configuration

Herramientas

Git MCP Server proporciona un conjunto completo de herramientas para operaciones de Git:

Operaciones del repositorio

Herramienta	Descripción
`git_init`	Inicializa un nuevo repositorio Git en la ruta especificada con opciones para repositorios vacíos.
`git_clone`	Clonar un repositorio Git desde una URL remota a una ruta local con opciones de rama y profundidad.
`git_status`	Obtenga el estado actual de un repositorio Git, incluidos los cambios en el directorio de trabajo y el área de almacenamiento temporal.

Operaciones de sucursal

Herramienta	Descripción
`git_branch_list`	Enumere todas las ramas en un repositorio con opciones para incluir ramas remotas.
`git_branch_create`	Crea una nueva rama con opciones para especificar el punto de inicio y el pago automático.
`git_checkout`	Extraiga una rama, etiqueta o confirmación con opciones para crear una nueva rama durante el proceso de pago.
`git_branch_delete`	Eliminar una rama con opciones para forzar la eliminación de ramas no fusionadas.
`git_merge`	Fusiona una rama en la rama actual con mensajes de confirmación personalizables y estrategias de fusión.

Operaciones del directorio de trabajo

Herramienta	Descripción
`git_add`	Archivos de preparación para confirmación con soporte para archivos individuales o directorios completos.
`git_reset`	Quitar archivos del área de preparación con opciones para archivos específicos o todos los cambios preparados.
`git_commit`	Confirme los cambios programados con mensajes de confirmación personalizables, información del autor y opciones de modificación.
`git_diff_unstaged`	Obtenga una diferencia de todos los cambios no preparados en el directorio de trabajo con opciones para archivos específicos.
`git_diff_staged`	Obtenga una diferencia de todos los cambios realizados en el índice con opciones para archivos específicos.
`git_reset_commit`	Restablecer el repositorio a una referencia específica con opciones para modo duro, suave o mixto.
`git_clean`	Elimina archivos no rastreados del árbol de trabajo con opciones para directorios y limpieza forzada.

Operaciones remotas

Herramienta	Descripción
`git_remote_add`	Agregue un nuevo repositorio remoto con un nombre y una URL.
`git_remote_list`	Enumere todos los repositorios remotos configurados y sus URL.
`git_fetch`	Obtenga actualizaciones de un repositorio remoto con opciones para ramas específicas.
`git_pull`	Extraer cambios de un repositorio remoto con opciones para la estrategia de rebase.
`git_push`	Envíe los cambios locales a un repositorio remoto con opciones de envío forzado y seguimiento ascendente.

Operaciones avanzadas

Herramienta	Descripción
`git_tag_create`	Crea una nueva etiqueta con opciones para etiquetas anotadas con mensajes.
`git_tag_list`	Enumere todas las etiquetas en el repositorio con sus referencias.
`git_stash_create`	Guarde los cambios en el directorio de trabajo con opciones para archivos no rastreados y descripciones.
`git_stash_list`	Enumere todos los escondites en el repositorio con sus descripciones.
`git_stash_apply`	Aplicar un cambio guardado sin eliminarlo de la lista de guardado.
`git_stash_pop`	Aplicar un cambio almacenado y eliminarlo de la lista de almacenamiento.
`git_cherry_pick`	Aplicar cambios de confirmaciones específicas a la rama actual.
`git_rebase`	Rebase la rama actual en otra rama con opciones de modo interactivo.
`git_log`	Obtenga el historial de confirmaciones con formato de salida y profundidad personalizables.
`git_show`	Muestra información detallada sobre una confirmación específica, incluidos los cambios diferenciales.

Recursos

El servidor Git MCP expone datos de Git a través de recursos MCP estándar:

Recursos del repositorio

Recurso	Descripción
`git://repo/{repoPath}/info`	Información básica del repositorio Git, incluida la rama actual, el estado y los detalles de referencia
`git://repo/{repoPath}/branches`	Lista de todas las ramas del repositorio con indicador de rama actual
`git://repo/{repoPath}/remotes`	Lista de todos los repositorios remotos configurados con sus URL
`git://repo/{repoPath}/tags`	Lista de todas las etiquetas en el repositorio con sus referencias
`git://repo/{repoPath}/file/{filePath}?ref={ref}`	Devuelve el contenido de un archivo específico en una referencia de Git determinada
`git://repo/{repoPath}/ls/{dirPath}?ref={ref}`	Devuelve una lista de archivos y directorios en una ruta y referencia específicas
`git://repo/{repoPath}/diff/{fromRef}/{toRef}?path={path}`	Devuelve una diferencia entre dos referencias de Git (confirmaciones, ramas, etiquetas)
`git://repo/{repoPath}/diff-unstaged?path={path}`	Devuelve una diferencia de todos los cambios no preparados en el directorio de trabajo
`git://repo/{repoPath}/diff-staged?path={path}`	Devuelve una diferencia de todos los cambios realizados en el índice
`git://repo/{repoPath}/log?maxCount={maxCount}&file={file}`	Devuelve el registro del historial de confirmaciones con el autor, la fecha y los detalles del mensaje.
`git://repo/{repoPath}/blame/{filePath}`	Devuelve la atribución línea por línea mostrando qué confirmación modificó por última vez cada línea
`git://repo/{repoPath}/commit/{commitHash}`	Devuelve información detallada sobre una confirmación específica, incluidos los cambios de diferencia.

Desarrollo

Construir y probar

# Build the project
npm run build

# Watch for changes and rebuild automatically
npm run watch

# Test the server locally using the MCP inspector tool
npm run inspector

# Clean build artifacts
npm run clean

# Generate a file tree representation for documentation
npm run tree

# Clean and rebuild the project completely
npm run rebuild

Licencia

Licencia Apache 2.0 - Consulte LICENCIA para obtener más detalles.

Git MCP Server

Integrations