Servidor MCP de Gitea

Un servidor del Protocolo de Contexto de Modelo (MCP) listo para producción para una integración fluida con plataformas Gitea autohospedadas. 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.

Related MCP server: Gitea MCP Tool

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 confirmaciones 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

• Limitación de tasa: Respeta los límites de tasa de la API por instancia

• Procesamiento por lotes: Subida eficiente de archivos con tamaños de lote configurables

• Registro completo: Registro estructurado con salida segura para la seguridad

• Manejo de errores: Manejo robusto de errores con lógica de reintento

• TypeScript: Seguridad de tipos completa 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 la autenticación

Instalación

1. Clona el repositorio:

git clone <repository-url>
cd gitea-mcp

2. Instala las dependencias:

npm install

3. Configura las variables de entorno:

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

4. Construye el proyecto:

npm run build

5. 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 construcción. El script de construcción predeterminado utiliza el comando chmod, que no está disponible en Windows. El archivo package.json ha sido actualizado para usar un script de construcción compatible con Windows.

Configuración de registro

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

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 el registro de depuración habilitado, utiliza el script start:mcp:

npm run start:mcp

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

Configuración de desarrollo

Para el desarrollo con recarga en caliente:

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 la instancia de Gitea

Cada instancia de Gitea requiere:

• id: Identificador único para la instancia

• name: Nombre legible por humanos para el registro

• baseUrl: URL base de tu instancia de Gitea

• token: Token de acceso personal con los permisos adecuados

• timeout: Tiempo de espera de la solicitud en milisegundos (opcional)

• rateLimit: Configuración de limitación de tasa (opcional)

Configuración del token de acceso personal

1. Inicia sesión en tu instancia de Gitea

2. Ve a Configuración → Aplicaciones → Tokens de acceso personal

3. 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

Añade 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 obtener 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 que el repositorio sea 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 confirmación

• branch (cadena, predeterminado: "main"): Rama de destino

• 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 confirmaciones iniciales

Descubre y sincroniza automáticamente un directorio de proyecto completo con 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, utiliza 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 confirmación para la sincronización

• branch (cadena, predeterminado: "main"): Rama de destino

• projectPath (cadena, predeterminado: "."): Ruta al directorio del proyecto a sincronizar

• dryRun (booleano, predeterminado: false): Previsualiza lo que se subiría sin subirlo 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 ignorar 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 prueba (dry run) para previsualizar cambios

• Informes detallados de archivos descubiertos, filtrados, subidos y fallidos

Casos de uso:

• Configuración inicial del proyecto y primera confirmación

• 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 un 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 inclinadas hacia adelante)

• 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 actual del archivo (detectado automáticamente si no se proporciona)

• message (cadena, requerido): Mensaje de confirmación para todas las operaciones

• branch (cadena, predeterminado: "main"): Rama de destino

• 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): Previsualizar operaciones sin realizar cambios

Características clave:

• Uso inteligente de la API: Utiliza PUT para actualizaciones, POST para creaciones, DELETE para eliminaciones

• Detección de cambios: Compara el contenido local frente al remoto para omitir actualizaciones innecesarias

• Resolución automática de SHA: Obtiene automáticamente los valores SHA requeridos para las operaciones de actualización

• Múltiples estrategias: Auto, lote (confirmación única) o individual (confirmaciones separadas)

• Resolución de conflictos: Maneja casos donde los archivos remotos han cambiado desde la última sincronización

• Operaciones mixtas: Puede manejar operaciones de creación, actualización y eliminación en una sola llamada

• Modo de prueba (dry run): Previsualiza qué operaciones se realizarían sin hacer cambios

Tipos de operación:

• add: Crear nuevos archivos (equivalente a la API POST)

• modify: Actualizar archivos existentes (utiliza la API PUT con SHA para la resolución de conflictos)

• delete: Eliminar archivos existentes (utiliza la API DELETE con SHA)

Opciones de estrategia:

• auto: Elige inteligentemente el mejor enfoque basado en el recuento de archivos y los tipos de operación

• batch: Realiza todas las operaciones en una sola confirmación utilizando la API de lotes de Gitea

• individual: Realiza cada operación como una confirmación separada

Casos de uso:

• Actualizar archivos de proyecto existentes

• Modificaciones selectivas de archivos

• Operaciones masivas de archivos (crear, actualizar, eliminar)

• Actualizaciones incrementales del proyecto

• 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 prueba (dry run):

{
  "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:

1. create_repository: Crear nuevos repositorios

2. sync_project: Subida inicial del proyecto a repositorios vacíos/nuevos

3. upload_files: Subir archivos específicos con control total sobre el proceso

4. 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 - Construir para producción

• npm run dev - Desarrollo con recarga en caliente

• npm start - Iniciar servidor de producción

• npm test - Ejecutar pruebas

• npm run lint - Analizar código (lint)

• 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

Añadir nuevas herramientas

1. Crea la implementación de la herramienta en src/tools/

2. Añade la validación de esquema en src/tools/schemas.ts

3. Registra la herramienta en src/tools/index.ts

4. Añade pruebas en tests/unit/tools/

Despliegue

Docker

Construye 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

• Utiliza variables de entorno o gestión de secretos para los tokens

• Configura niveles de registro adecuados

• Configura monitoreo y comprobaciones de salud

• Utiliza gestores de procesos como PM2 para aplicaciones Node.js

• Considera usar Docker o Kubernetes para la orquestación

Seguridad

Mejores prácticas

• Almacena los tokens de forma segura utilizando variables de entorno o gestión de secretos

• Utiliza los permisos mínimos requeridos para los tokens de acceso

• Valida todos los parámetros de entrada

• Registra eventos de seguridad sin exponer datos confidenciales

• Utiliza HTTPS para todas las comunicaciones de la API de Gitea

• Rota regularmente los tokens de acceso

Limitación de tasa

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

• Predeterminado: 100 solicitudes por minuto por instancia

• Configurable mediante rateLimit en la configuración de la 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 caducado

• Asegúrate de que la URL base sea correcta

Límite de tasa alcanzado

• Reduce el tamaño del lote para las subidas de archivos

• Ajusta la configuración de límite de tasa

• Espera antes de reintentar las solicitudes

Fallos en la subida de archivos

• Comprueba que el contenido del archivo sea válido

• Verifica que las rutas de los archivos no contengan caracteres ilegales

• Asegúrate de que el repositorio exista y tengas permisos de escritura

Registro

Habilita el registro de depuración para la resolución de problemas:

LOG_LEVEL=debug npm start

Comprobaciones de salud

Comprueba el estado del servidor:

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

Contribución

1. Haz un fork del repositorio

2. Crea una rama de características

3. Realiza cambios con pruebas

4. Ejecuta linting y verificación de tipos

5. Envía una solicitud de extracción (pull request)

Licencia

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

Soporte

• Problemas de GitHub: Informa de errores y solicitudes de características

• Documentación: Consulta el directorio docs/

• Ejemplos: Consulta el directorio examples/

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

Ver también

• [TranscriptionTools