Gitea MCP Server

Um servidor para integração perfeita com plataformas Gitea auto-hospedadas, permitindo o gerenciamento de repositórios e outros recursos.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP Gitea

Um servidor Model Context Protocol (MCP) pronto para produção para integração perfeita com plataformas Gitea auto-hospedadas. Este servidor fornece ferramentas para criar repositórios e enviar arquivos, preservando a estrutura de diretórios.

Guia de Instalação e Configuração

Este guia fornece instruções passo a passo para instalar e configurar o servidor MCP Gitea, incluindo a solução de problemas comuns.

Recursos

Criação de Repositórios: Crie novos repositórios em qualquer instância Gitea configurada
Envio de Arquivos: Envie arquivos e pastas preservando a estrutura de diretórios
Sincronização de Projetos: Sincronize automaticamente projetos inteiros para commits iniciais (somente novos arquivos)
Atualizações Avançadas de Arquivos: Ferramenta de atualização inteligente com resolução de conflitos para modificar arquivos existentes
Suporte a Múltiplas Instâncias: Conecte-se a várias instâncias Gitea simultaneamente
Limitação de Taxa: Respeite os limites de taxa da API por instância
Processamento em Lote: Envio eficiente de arquivos com tamanhos de lote configuráveis
Registro Abrangente: Registro estruturado com saída segura para segurança
Tratamento de Erros: Tratamento robusto de erros com lógica de repetição
TypeScript: Segurança total de tipos e recursos modernos de JavaScript

Início Rápido

Pré-requisitos

Node.js 18.0.0 ou superior
Acesso a uma ou mais instâncias Gitea
Tokens de acesso pessoal para autenticação

Instalação

Clone o repositório:

git clone <repository-url>
cd gitea-mcp

Instale as dependências:

npm install

Configure as variáveis de ambiente:

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

Compile o projeto:

npm run build

Inicie o servidor:

npm run start:mcp

Solução de Problemas Comuns

Compatibilidade com Windows

Se você estiver usando Windows, poderá encontrar problemas com o script de compilação. O script de compilação padrão usa o comando chmod, que não está disponível no Windows. O package.json foi atualizado para usar um script de compilação compatível com Windows.

Configuração de Registro

Se você encontrar problemas com a configuração de registro, certifique-se de ter o pacote pino-pretty instalado:

npm install --save-dev pino-pretty

Variáveis de Ambiente

O arquivo .env deve conter a seguinte configuração:

# 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

Certifique-se de substituir "https://your-gitea-instance.com" pela URL real da sua instância Gitea e "your-personal-access-token" pelo seu token de acesso pessoal Gitea.

Executando com Registro de Depuração

Para executar o servidor com registro de depuração habilitado, use o script start:mcp:

npm run start:mcp

Este script define NODE_ENV como development e LOG_LEVEL como debug antes de iniciar o servidor.

Configuração de Desenvolvimento

Para desenvolvimento com recarga automática:

npm run dev

Configuração

Variáveis de Ambiente

Crie um arquivo .env com base em .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

Configuração da Instância Gitea

Cada instância Gitea requer:

id: Identificador único para a instância
name: Nome legível para registro
baseUrl: URL base da sua instância Gitea
token: Token de acesso pessoal com as permissões apropriadas
timeout: Tempo limite de solicitação em milissegundos (opcional)
rateLimit: Configuração de limitação de taxa (opcional)

Configuração do Token de Acesso Pessoal

Faça login na sua instância Gitea
Vá para Configurações → Aplicativos → Tokens de Acesso Pessoal
Crie um novo token com estas permissões:
- repo: Acesso total ao repositório
- write:repository: Criar repositórios
- read:user: Ler informações do usuário

Configuração do Cliente MCP

Claude Desktop

Adicione à sua configuração do Claude Desktop:

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

Outros Clientes MCP

O servidor se comunica via stdio e segue a especificação do protocolo MCP. Consulte a documentação do seu cliente para obter detalhes de configuração.

Ferramentas Disponíveis

create_repository

Crie um novo repositório em uma instância Gitea especificada.

Parâmetros:

instanceId (string, obrigatório): Identificador da instância Gitea
name (string, obrigatório): Nome do repositório
description (string, opcional): Descrição do repositório
private (booleano, padrão: true): Tornar o repositório privado
autoInit (booleano, padrão: true): Inicializar com README
defaultBranch (string, padrão: "main"): Nome do branch padrão

Exemplo:

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

upload_files

Envie vários arquivos para um repositório preservando a estrutura de diretórios.

Parâmetros:

instanceId (string, obrigatório): Identificador da instância Gitea
owner (string, obrigatório): Nome de usuário do proprietário do repositório
repository (string, obrigatório): Nome do repositório
files (array, obrigatório): Matriz de objetos de arquivo com path e content
message (string, obrigatório): Mensagem de commit
branch (string, padrão: "main"): Branch de destino
batchSize (número, padrão: 10): Arquivos por lote

Exemplo:

{
  "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 ⚠️ Somente Commits Iniciais

Descubra e sincronize automaticamente um diretório de projeto inteiro para um repositório Gitea, respeitando as regras de .gitignore.

Importante: Esta ferramenta foi projetada para envios iniciais de projetos e só pode criar novos arquivos. Ela não pode atualizar arquivos que já existem no repositório. Para atualizar arquivos existentes, use a ferramenta sync_update.

Parâmetros:

instanceId (string, obrigatório): Identificador da instância Gitea
owner (string, obrigatório): Nome de usuário do proprietário do repositório
repository (string, obrigatório): Nome do repositório
message (string, obrigatório): Mensagem de commit para a sincronização
branch (string, padrão: "main"): Branch de destino
projectPath (string, padrão: "."): Caminho para o diretório do projeto a ser sincronizado
dryRun (booleano, padrão: false): Visualizar o que seria enviado sem realmente enviar
includeHidden (booleano, padrão: false): Incluir arquivos ocultos (começando com .)
maxFileSize (número, padrão: 1048576): Tamanho máximo do arquivo em bytes (1MB)
textOnly (booleano, padrão: true): Enviar apenas arquivos de texto (pular arquivos binários)

Recursos:

Lê e aplica automaticamente as regras de .gitignore
Inclui padrões sensatos para padrões de ignorância comuns (node_modules/, .git/, etc.)
Verifica recursivamente o diretório do projeto em busca de arquivos elegíveis
Heurística simples para detectar e opcionalmente pular arquivos binários
Filtragem de tamanho para arquivos grandes
Modo de execução simulada para visualizar alterações
Relatórios detalhados de arquivos descobertos, filtrados, enviados e com falha

Casos de Uso:

Configuração inicial do projeto e primeiro commit
Envio de novos projetos para repositórios vazios
Envio em massa de arquivos para novos repositórios

Exemplo:

{
  "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 ✨ Atualizações Avançadas de Arquivos

Ferramenta avançada para atualizar arquivos existentes no repositório Gitea com resolução inteligente de conflitos e detecção de alterações.

Parâmetros:

instanceId (string, obrigatório): Identificador da instância Gitea
owner (string, obrigatório): Nome de usuário do proprietário do repositório
repository (string, obrigatório): Nome do repositório
files (array, obrigatório): Matriz de objetos de operação de arquivo
files[].path (string, obrigatório): Caminho do arquivo no repositório (barras normais)
files[].content (string, condicional): Conteúdo do arquivo (obrigatório para operações de adicionar/modificar)
files[].operation (string, obrigatório): Tipo de operação: 'add', 'modify' ou 'delete'
files[].sha (string, opcional): SHA atual do arquivo (detectado automaticamente se não fornecido)
message (string, obrigatório): Mensagem de commit para todas as operações
branch (string, padrão: "main"): Branch de destino
strategy (string, padrão: "auto"): Estratégia de atualização: 'auto', 'batch' ou 'individual'
conflictResolution (string, padrão: "fail"): Tratamento de conflitos: 'fail', 'overwrite' ou 'skip'
detectChanges (booleano, padrão: true): Comparar com arquivos remotos para evitar atualizações desnecessárias
dryRun (booleano, padrão: false): Visualizar operações sem fazer alterações

Recursos Principais:

Uso Inteligente da API: Usa PUT para atualizações, POST para criações, DELETE para remoções
Detecção de Alterações: Compara conteúdo local vs. remoto para pular atualizações desnecessárias
Resolução Automática de SHA: Busca automaticamente os valores SHA necessários para operações de atualização
Múltiplas Estratégias: Auto, lote (commit único) ou individual (commits separados)
Resolução de Conflitos: Trata casos em que arquivos remotos foram alterados desde a última sincronização
Operações Mistas: Pode lidar com operações de criação, atualização e exclusão em uma única chamada
Modo de Execução Simulada: Visualize quais operações seriam executadas sem fazer alterações

Tipos de Operação:

add: Criar novos arquivos (equivalente à API POST)
modify: Atualizar arquivos existentes (usa API PUT com SHA para resolução de conflitos)
delete: Remover arquivos existentes (usa API DELETE com SHA)

Opções de Estratégia:

auto: Escolhe inteligentemente a melhor abordagem com base na contagem de arquivos e tipos de operação
batch: Executa todas as operações em um único commit usando a API de lote do Gitea
individual: Executa cada operação como um commit separado

Casos de Uso:

Atualização de arquivos de projeto existentes
Modificações seletivas de arquivos
Operações em massa de arquivos (criar, atualizar, excluir)
Atualizações incrementais de projetos
Manutenção automatizada de arquivos

Exemplo:

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

Exemplo de Resposta de Execução Simulada:

{
  "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
    }
  ]
}

Guia de Seleção de Ferramentas

Quando usar cada ferramenta:

create_repository: Criar novos repositórios
sync_project: Envio inicial de projetos para repositórios vazios/novos
upload_files: Enviar arquivos específicos com controle total sobre o processo
sync_update: Atualizar arquivos existentes, criar novos arquivos ou excluir arquivos em repositórios existentes

Exemplo de Fluxo de Trabalho:

# 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

Desenvolvimento

Scripts

npm run build - Compilar para produção
npm run dev - Desenvolvimento com recarga automática
npm start - Iniciar servidor de produção
npm test - Executar testes
npm run lint - Verificar código (lint)
npm run format - Formatar código
npm run type-check - Verificação de tipos TypeScript

Estrutura do Projeto

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

Adicionando Novas Ferramentas

Crie a implementação da ferramenta em src/tools/
Adicione a validação de esquema em src/tools/schemas.ts
Registre a ferramenta em src/tools/index.ts
Adicione testes em tests/unit/tools/

Implantação

Docker

Compile e execute com Docker:

# Build image
docker build -t gitea-mcp .

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

Considerações de Produção

Use variáveis de ambiente ou gerenciamento de segredos para tokens
Configure níveis de registro apropriados
Configure monitoramento e verificações de integridade
Use gerenciadores de processos como PM2 para aplicações Node.js
Considere usar Docker ou Kubernetes para orquestração

Segurança

Melhores Práticas

Armazene tokens com segurança usando variáveis de ambiente ou gerenciamento de segredos
Use as permissões mínimas necessárias para tokens de acesso
Valide todos os parâmetros de entrada
Registre eventos de segurança sem expor dados sensíveis
Use HTTPS para todas as comunicações com a API Gitea
Alterne regularmente os tokens de acesso

Limitação de Taxa

O servidor implementa limitação de taxa por instância Gitea para respeitar os limites da API:

Padrão: 100 solicitações por minuto por instância
Configurável via rateLimit na configuração da instância
Repetição automática com backoff exponencial

Solução de Problemas

Problemas Comuns

Falha de Autenticação

Verifique se o token de acesso está correto e tem as permissões necessárias
Verifique se o token não expirou
Certifique-se de que a URL base está correta

Limite de Taxa Atingido

Reduza o tamanho do lote para envio de arquivos
Ajuste a configuração de limitação de taxa
Aguarde antes de repetir as solicitações

Falhas no Envio de Arquivos

Verifique se o conteúdo do arquivo é válido
Verifique se os caminhos dos arquivos não contêm caracteres ilegais
Garanta que o repositório exista e que você tenha permissões de escrita

Registro de Logs

Ative o registro de logs de depuração para solução de problemas:

LOG_LEVEL=debug npm start

Verificações de Saúde

Verifique o status do servidor:

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

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça alterações com testes
Execute linting e verificação de tipos
Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Suporte

GitHub Issues: Relate bugs e solicitações de recursos
Documentação: Consulte o diretório docs/
Exemplos: Veja o diretório examples/

Feito com ❤️ para as comunidades Gitea e MCP.

Veja Também

TranscriptionTools-MCP — Processamento de transcrições
DeepLucid3D-MCP — Processamento cognitivo
UNO-MCP — Aprimoramento narrativo
gitea-mcp — Integração com Gitea
zero-vector-MCP — Geração procedural