Gitea MCP Server

Un servidor para la integración fluida con plataformas Gitea autoalojadas, que permite la gestión de repositorios y otros recursos.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de Gitea

Un servidor de Model Context Protocol (MCP) listo para producción para una integración perfecta con plataformas Gitea autoalojadas. Este servidor proporciona herramientas para crear repositorios y subir archivos preservando la estructura de directorios.

Guía de Instalación y Configuración

Esta guía proporciona instrucciones paso a paso para instalar y configurar el servidor MCP de Gitea, incluyendo la resolución de problemas comunes.

Características

Creación de Repositorios: Crea nuevos repositorios en cualquier instancia de Gitea configurada
Subida de Archivos: Sube archivos y carpetas preservando la estructura de directorios
Sincronización de Proyectos: Sincroniza automáticamente proyectos completos para commits iniciales (solo archivos nuevos)
Actualizaciones Avanzadas de Archivos: Herramienta de actualización inteligente con resolución de conflictos para modificar archivos existentes
Soporte Multi-Instancia: Conéctate a múltiples instancias de Gitea simultáneamente
Límite de Tasa: Respeta los límites de tasa de API por instancia
Procesamiento por Lotes: Subida eficiente de archivos con tamaños de lote configurables
Registro Integral: Registro estructurado con salida segura para seguridad
Manejo de Errores: Manejo robusto de errores con lógica de reintentos
TypeScript: Seguridad total de tipos y características modernas de JavaScript

Inicio Rápido

Requisitos Previos

Node.js 18.0.0 o superior
Acceso a una o más instancias de Gitea
Tokens de acceso personal para autenticación

Instalación

Clona el repositorio:

git clone <repository-url>
cd gitea-mcp

Instala las dependencias:

npm install

Configura las variables de entorno:

cp .env.example .env
# Edit .env with your Gitea instance details

Compila el proyecto:

npm run build

Inicia el servidor:

npm run start:mcp

Resolución de Problemas Comunes

Compatibilidad con Windows

Si estás ejecutando en Windows, podrías encontrar problemas con el script de compilación. El script de compilación predeterminado usa el comando chmod, que no está disponible en Windows. El package.json se ha actualizado para usar un script de compilación compatible con Windows.

Configuración de Registro

Si encuentras problemas con la configuración de registro, asegúrate de tener el paquete pino-pretty instalado:

npm install --save-dev pino-pretty

Variables de Entorno

El archivo .env debe contener la siguiente configuración:

# Server Configuration
NODE_ENV=development
LOG_LEVEL=debug

# Gitea Configuration
# Replace with your Gitea instance URL and token
GITEA_INSTANCES=[{"id":"main","name":"Main Gitea Instance","baseUrl":"https://your-gitea-instance.com","token":"your-personal-access-token","timeout":30000,"rateLimit":{"requests":100,"windowMs":60000}}]

# Upload Configuration
MAX_FILE_SIZE=10485760
MAX_FILES=100
BATCH_SIZE=10

# Gitea API Configuration
GITEA_TIMEOUT=30000
GITEA_MAX_RETRIES=3

Asegúrate de reemplazar "https://your-gitea-instance.com" con la URL real de tu instancia de Gitea y "your-personal-access-token" con tu token de acceso personal de Gitea.

Ejecución con Registro de Depuración

Para ejecutar el servidor con registro de depuración habilitado, usa el script start:mcp:

npm run start:mcp

Este script establece NODE_ENV a development y LOG_LEVEL a debug antes de iniciar el servidor.

Configuración de Desarrollo

Para desarrollo con recarga automática:

npm run dev

Configuración

Variables de Entorno

Crea un archivo .env basado en .env.example:

# Server Configuration
NODE_ENV=development
LOG_LEVEL=info

# Gitea Configuration
GITEA_INSTANCES='[
  {
    "id": "main",
    "name": "Main Gitea Instance", 
    "baseUrl": "https://gitea.example.com",
    "token": "your-personal-access-token",
    "timeout": 30000,
    "rateLimit": {
      "requests": 100,
      "windowMs": 60000
    }
  }
]'

# Upload Configuration
MAX_FILE_SIZE=10485760  # 10MB
MAX_FILES=100
BATCH_SIZE=10

# API Configuration
GITEA_TIMEOUT=30000
GITEA_MAX_RETRIES=3

Configuración de Instancia de Gitea

Cada instancia de Gitea requiere:

id: Identificador único para la instancia
name: Nombre legible para registro
baseUrl: URL base de tu instancia de Gitea
token: Token de acceso personal con permisos apropiados
timeout: Tiempo de espera de solicitud en milisegundos (opcional)
rateLimit: Configuración de límite de tasa (opcional)

Configuración del Token de Acceso Personal

Inicia sesión en tu instancia de Gitea
Ve a Configuración → Aplicaciones → Tokens de Acceso Personal
Crea un nuevo token con estos permisos:
- repo: Acceso completo al repositorio
- write:repository: Crear repositorios
- read:user: Leer información del usuario

Configuración del Cliente MCP

Claude Desktop

Agrega a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "gitea-mcp": {
      "command": "node",
      "args": ["./build/index.js"],
      "cwd": "/path/to/gitea-mcp",
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Otros Clientes MCP

El servidor se comunica a través de stdio y sigue la especificación del protocolo MCP. Consulta la documentación de tu cliente para detalles de configuración.

Herramientas Disponibles

create_repository

Crea un nuevo repositorio en una instancia de Gitea especificada.

Parámetros:

instanceId (cadena, requerido): Identificador de la instancia de Gitea
name (cadena, requerido): Nombre del repositorio
description (cadena, opcional): Descripción del repositorio
private (booleano, predeterminado: true): Hacer el repositorio privado
autoInit (booleano, predeterminado: true): Inicializar con README
defaultBranch (cadena, predeterminado: "main"): Nombre de la rama predeterminada

Ejemplo:

{
  "instanceId": "main",
  "name": "my-new-repo",
  "description": "A test repository",
  "private": true,
  "autoInit": true,
  "defaultBranch": "main"
}

upload_files

Sube múltiples archivos a un repositorio preservando la estructura de directorios.

Parámetros:

instanceId (cadena, requerido): Identificador de la instancia de Gitea
owner (cadena, requerido): Nombre de usuario del propietario del repositorio
repository (cadena, requerido): Nombre del repositorio
files (matriz, requerido): Matriz de objetos de archivo con path y content
message (cadena, requerido): Mensaje de commit
branch (cadena, predeterminado: "main"): Rama objetivo
batchSize (número, predeterminado: 10): Archivos por lote

Ejemplo:

{
  "instanceId": "main",
  "owner": "username",
  "repository": "my-repo",
  "files": [
    {
      "path": "README.md",
      "content": "# My Project\n\nProject description here."
    },
    {
      "path": "src/index.js", 
      "content": "console.log('Hello, World!');"
    }
  ],
  "message": "Initial commit",
  "branch": "main",
  "batchSize": 5
}

sync_project ⚠️ Solo Commits Iniciales

Descubre y sincroniza automáticamente un directorio de proyecto completo a un repositorio de Gitea respetando las reglas de .gitignore.

Importante: Esta herramienta está diseñada para subidas iniciales de proyectos y solo puede crear archivos nuevos. No puede actualizar archivos que ya existen en el repositorio. Para actualizar archivos existentes, usa la herramienta sync_update en su lugar.

Parámetros:

instanceId (cadena, requerido): Identificador de la instancia de Gitea
owner (cadena, requerido): Nombre de usuario del propietario del repositorio
repository (cadena, requerido): Nombre del repositorio
message (cadena, requerido): Mensaje de commit para la sincronización
branch (cadena, predeterminado: "main"): Rama objetivo
projectPath (cadena, predeterminado: "."): Ruta al directorio del proyecto a sincronizar
dryRun (booleano, predeterminado: false): Vista previa de lo que se subiría sin subir realmente
includeHidden (booleano, predeterminado: false): Incluir archivos ocultos (que comienzan con .)
maxFileSize (número, predeterminado: 1048576): Tamaño máximo de archivo en bytes (1MB)
textOnly (booleano, predeterminado: true): Solo subir archivos de texto (omitir archivos binarios)

Características:

Lee y aplica automáticamente las reglas de .gitignore
Incluye valores predeterminados sensatos para patrones de ignorados comunes (node_modules/, .git/, etc.)
Escanea recursivamente el directorio del proyecto en busca de archivos elegibles
Heurística simple para detectar y opcionalmente omitir archivos binarios
Filtrado de tamaño para archivos grandes
Modo de ejecución en seco para previsualizar cambios
Informes detallados de archivos descubiertos, filtrados, subidos y fallidos

Casos de Uso:

Configuración inicial del proyecto y primer commit
Subir nuevos proyectos a repositorios vacíos
Subida masiva de archivos a nuevos repositorios

Ejemplo:

{
  "instanceId": "main",
  "owner": "username",
  "repository": "my-project",
  "message": "Initial project sync",
  "branch": "main",
  "projectPath": "./my-app",
  "dryRun": false,
  "includeHidden": false,
  "maxFileSize": 2097152,
  "textOnly": true
}

sync_update ✨ Actualizaciones Avanzadas de Archivos

Herramienta avanzada para actualizar archivos existentes en el repositorio de Gitea con resolución inteligente de conflictos y detección de cambios.

Parámetros:

instanceId (cadena, requerido): Identificador de la instancia de Gitea
owner (cadena, requerido): Nombre de usuario del propietario del repositorio
repository (cadena, requerido): Nombre del repositorio
files (matriz, requerido): Matriz de objetos de operación de archivo
files[].path (cadena, requerido): Ruta del archivo en el repositorio (barras diagonales)
files[].content (cadena, condicional): Contenido del archivo (requerido para operaciones de agregar/modificar)
files[].operation (cadena, requerido): Tipo de operación: 'add', 'modify' o 'delete'
files[].sha (cadena, opcional): SHA del archivo actual (auto-detectado si no se proporciona)
message (cadena, requerido): Mensaje de commit para todas las operaciones
branch (cadena, predeterminado: "main"): Rama objetivo
strategy (cadena, predeterminado: "auto"): Estrategia de actualización: 'auto', 'batch' o 'individual'
conflictResolution (cadena, predeterminado: "fail"): Manejo de conflictos: 'fail', 'overwrite' o 'skip'
detectChanges (booleano, predeterminado: true): Comparar con archivos remotos para evitar actualizaciones innecesarias
dryRun (booleano, predeterminado: false): Vista previa de operaciones sin hacer cambios

Características Clave:

Uso Inteligente de API: Usa PUT para actualizaciones, POST para creaciones, DELETE para eliminaciones
Detección de Cambios: Compara contenido local vs remoto para omitir actualizaciones innecesarias
Resolución Automática de SHA: Obtiene automáticamente los valores SHA requeridos para operaciones de actualización
Múltiples Estrategias: Auto, lote (commit único) o individual (commits separados)
Resolución de Conflictos: Maneja casos donde los archivos remotos han cambiado desde la última sincronización
Operaciones Mixtas: Puede manejar operaciones de crear, actualizar y eliminar en una sola llamada
Modo de Ejecución en Seco: Vista previa de qué operaciones se realizarían sin hacer cambios

Tipos de Operación:

add: Crear archivos nuevos (equivalente a API POST)
modify: Actualizar archivos existentes (usa API PUT con SHA para resolución de conflictos)
delete: Eliminar archivos existentes (usa API DELETE con SHA)

Opciones de Estrategia:

auto: Elige inteligentemente el mejor enfoque según el recuento de archivos y los tipos de operación
batch: Realiza todas las operaciones en un solo commit usando la API de lote de Gitea
individual: Realiza cada operación como un commit separado

Casos de Uso:

Actualizar archivos de proyecto existentes
Modificaciones selectivas de archivos
Operaciones masivas de archivos (crear, actualizar, eliminar)
Actualizaciones incrementales de proyectos
Mantenimiento automatizado de archivos

Ejemplo:

{
  "instanceId": "main",
  "owner": "username",
  "repository": "my-project",
  "files": [
    {
      "path": "README.md",
      "content": "# Updated Project\n\nThis is an updated version of the project.",
      "operation": "modify"
    },
    {
      "path": "src/new-feature.js",
      "content": "// New feature implementation\nfunction newFeature() {\n  return 'Hello, World!';\n}",
      "operation": "add"
    },
    {
      "path": "old-file.txt",
      "operation": "delete"
    }
  ],
  "message": "Update documentation and add new feature",
  "branch": "main",
  "strategy": "auto",
  "detectChanges": true,
  "dryRun": false
}

Ejemplo de Respuesta de Ejecución en Seco:

{
  "dryRun": true,
  "strategy": "individual",
  "summary": {
    "discovered": 3,
    "analyzed": 3,
    "needsUpdate": 2,
    "processed": 0,
    "succeeded": 0,
    "failed": 0,
    "skipped": 0
  },
  "filesNeedingUpdate": [
    {
      "path": "README.md",
      "operation": "modify",
      "hasRemoteSha": true
    },
    {
      "path": "src/new-feature.js",
      "operation": "add",
      "hasRemoteSha": false
    }
  ]
}

Guía de Selección de Herramientas

Cuándo usar cada herramienta:

create_repository: Crear nuevos repositorios
sync_project: Subida inicial de proyectos a repositorios vacíos/nuevos
upload_files: Subir archivos específicos con control total sobre el proceso
sync_update: Actualizar archivos existentes, crear archivos nuevos o eliminar archivos en repositorios existentes

Ejemplo de Flujo de Trabajo:

# 1. Create a new repository
create_repository → "my-new-project"

# 2. Initial upload of all project files
sync_project → Upload entire project structure

# 3. Later updates to specific files
sync_update → Modify README.md, add new features, delete old files

Desarrollo

Scripts

npm run build - Compilar para producción
npm run dev - Desarrollo con recarga automática
npm start - Iniciar servidor de producción
npm test - Ejecutar pruebas
npm run lint - Verificar código con linter
npm run format - Formatear código
npm run type-check - Verificación de tipos de TypeScript

Estructura del Proyecto

gitea-mcp/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── config/               # Configuration management
│   ├── gitea/                # Gitea API client
│   ├── tools/                # MCP tool implementations
│   ├── services/             # Business logic services
│   ├── utils/                # Utilities (logging, errors, etc.)
│   └── types/                # TypeScript type definitions
├── build/                    # Compiled JavaScript
├── docs/                     # Documentation
└── package.json

Agregar Nuevas Herramientas

Crea la implementación de la herramienta en src/tools/
Agrega validación de esquema en src/tools/schemas.ts
Registra la herramienta en src/tools/index.ts
Agrega pruebas en tests/unit/tools/

Despliegue

Docker

Compila y ejecuta con Docker:

# Build image
docker build -t gitea-mcp .

# Run container
docker run -d \
  --name gitea-mcp \
  --env-file .env \
  gitea-mcp

Consideraciones de Producción

Usa variables de entorno o gestión de secretos para tokens
Configura niveles de registro apropiados
Configura monitoreo y verificaciones de salud
Usa gestores de procesos como PM2 para aplicaciones Node.js
Considera usar Docker o Kubernetes para orquestación

Seguridad

Mejores Prácticas

Almacena tokens de forma segura usando variables de entorno o gestión de secretos
Usa permisos mínimos requeridos para tokens de acceso
Valida todos los parámetros de entrada
Registra eventos de seguridad sin exponer datos sensibles
Usa HTTPS para todas las comunicaciones de API de Gitea
Rota regularmente los tokens de acceso

Límite de Tasa

El servidor implementa límites de tasa por instancia de Gitea para respetar los límites de API:

Predeterminado: 100 solicitudes por minuto por instancia
Configurable a través de rateLimit en la configuración de instancia
Reintento automático con retroceso exponencial

Resolución de Problemas

Problemas Comunes

Autenticación Fallida

Verifica que el token de acceso sea correcto y tenga los permisos requeridos
Comprueba que el token no haya expirado
Asegúrate de que la URL base sea correcta

Límite de Tasa Alcanzado

Reduce el tamaño del lote para subidas de archivos
Ajusta la configuración del límite de tasa
Espera antes de reintentar solicitudes

Fallos en la Subida de Archivos

Comprueba que el contenido del archivo sea válido
Verifica que las rutas de archivo no contengan caracteres ilegales
Asegúrate de que el repositorio exista y tengas permisos de escritura

Registro (Logging)

Habilita el registro de depuración para solucionar problemas:

LOG_LEVEL=debug npm start

Verificaciones de salud

Comprueba el estado del servidor:

curl -f http://localhost:8080/health || exit 1

Contribuciones

Haz un fork del repositorio
Crea una rama de características
Realiza cambios con pruebas
Ejecuta el linting y la verificación de tipos
Envía una solicitud de extracción (pull request)

Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

Soporte

Problemas de GitHub: reporta errores y solicitudes de funciones
Documentación: consulta el directorio docs/
Ejemplos: consulta el directorio examples/

Hecho con ❤️ para las comunidades de Gitea y MCP.

Ver También

TranscriptionTools-MCP — Procesamiento de transcripciones
DeepLucid3D-MCP — Procesamiento cognitivo
UNO-MCP — Mejora narrativa
gitea-mcp — Integración con Gitea
zero-vector-MCP — Generación procedural