cerngitlab-mcp

Servidor MCP do CERN GitLab

Um servidor MCP que conecta LLMs ao CERN GitLab para descobrir código de HEP, documentação e exemplos de análise.

Recursos

15 ferramentas MCP para pesquisar, navegar e analisar repositórios do CERN GitLab
Operação em modo duplo — modos stdio (usuário único) e HTTP (multi-usuário)
Ferramenta CLI (cerngitlab-cli) para uso direto via linha de comando
Acesso público — funciona sem autenticação para repositórios públicos
Modo HTTP multi-usuário — autenticação CERN SSO + GitLab OAuth para implantações centralizadas; o GitLab aplica todas as permissões de acesso nativamente
Focado em HEP — análise de dependências para ecossistemas Python e C++, detecção binária para arquivos .root, pesquisa de issues
Robusto — limite de taxa, novas tentativas com backoff exponencial, tratamento elegante de erros

Instalação

Requer Python 3.10+.

Início rápido (recomendado)

Nenhuma instalação necessária — basta usar uvx para executar diretamente:

uvx cerngitlab-mcp

Via PyPI

pip install cerngitlab-mcp

A partir do código-fonte

git clone https://github.com/MohamedElashri/cerngitlab-mcp
cd cerngitlab-mcp
uv sync

Configuração

Todas as configurações são definidas por meio de variáveis de ambiente com o prefixo CERNGITLAB_:

Variável	Padrão	Descrição
`CERNGITLAB_GITLAB_URL`	`https://gitlab.cern.ch`	URL da instância do GitLab
`CERNGITLAB_TOKEN`	(vazio)	Token de acesso pessoal (opcional, para modo stdio)
`CERNGITLAB_TIMEOUT`	`30`	Tempo limite de HTTP em segundos
`CERNGITLAB_MAX_RETRIES`	`3`	Máximo de novas tentativas para solicitações com falha
`CERNGITLAB_RATE_LIMIT_PER_MINUTE`	`300`	Limite de taxa da API
`CERNGITLAB_LOG_LEVEL`	`INFO`	Nível de registro (logging)
`CERNGITLAB_DEFAULT_REF`	(vazio)	Branch ou tag padrão do Git para pesquisa de código. Vazio usa o comportamento de referência padrão do GitLab.
`CERNGITLAB_HTTP_MODE`	(vazio)	Defina qualquer valor para detectar automaticamente o modo HTTP
`CERNGITLAB_HOST`	`0.0.0.0`	Endereço de bind do servidor HTTP
`CERNGITLAB_PORT`	`8000`	Porta de bind do servidor HTTP
`CERNGITLAB_CERN_CLIENT_ID`	(vazio)	Modo HTTP — ID do cliente OAuth do CERN SSO
`CERNGITLAB_GITLAB_OAUTH_CLIENT_ID`	(vazio)	Modo HTTP — ID do cliente do aplicativo OAuth do GitLab
`CERNGITLAB_GITLAB_OAUTH_CLIENT_SECRET`	(vazio)	Modo HTTP — Segredo do cliente do aplicativo OAuth do GitLab
`CERNGITLAB_SERVER_BASE_URL`	`http://localhost:8000`	Modo HTTP — URL base pública (usada para o callback do OAuth)
`CERNGITLAB_SESSION_STORAGE_PATH`	`/tmp/cerngitlab/sessions`	Modo HTTP — Diretório para persistir arquivos de sessão OAuth

Autenticação

O servidor funciona em dois modos:

Sem token — Acesso a todos os repositórios públicos. Suficiente para a maioria das descobertas de código HEP.
Com token — Acesso adicional a projetos internos/privados, pesquisa de código e páginas wiki.

Para criar um token:

Vá para https://gitlab.cern.ch/-/user_settings/personal_access_tokens
Crie um token com o escopo read_api
Defina CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx

Nota: A pesquisa de código (search_code), pesquisa de issues (search_issues) e wiki (get_wiki_pages) exigem autenticação no CERN GitLab.

Uso

Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "cerngitlab": {
      "command": "uvx",
      "args": ["cerngitlab-mcp"],
      "env": {
        "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  }
}

Nota para usuários de macOS: Se você vir um erro sobre uvx não encontrado, talvez seja necessário fornecer o caminho absoluto. O Claude Desktop não suporta expansão de ~ ou $HOME.

Execute which uvx no seu terminal para encontrar o caminho (por exemplo, /Users/yourusername/.local/bin/uvx).

Use esse caminho absoluto no campo command:
"command": "/Users/seunome/.local/bin/uvx"

Claude Code

Específico do projeto (padrão) — instala na configuração do diretório atual:

claude mcp add cerngitlab-mcp -- uvx cerngitlab-mcp

Global — instala para a sua conta de usuário (funciona em todos os projetos):

claude mcp add --scope user cerngitlab-mcp -- uvx cerngitlab-mcp

Para incluir autenticação, adicione -e CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx antes do --:

# Example: Global installation with token
claude mcp add --scope user -e CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx cerngitlab-mcp -- uvx cerngitlab-mcp

Configuração manual — você também pode editar manualmente sua configuração global em ~/.claude.json (no Linux/macOS) ou %APPDATA%\Claude\claude.json (no Windows):

{
  "mcpServers": {
    "cerngitlab": {
      "command": "uvx",
      "args": ["cerngitlab-mcp"],
      "env": {
        "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  }
}

GitHub Copilot

Adicione ao seu settings.json do VS Code:

{
  "mcp": {
    "servers": {
      "cerngitlab": {
        "command": "uvx",
        "args": ["cerngitlab-mcp"],
        "env": {
          "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
        }
      }
    }
  }
}

Ou adicione um .vscode/mcp.json ao seu projeto:

{
  "servers": {
    "cerngitlab": {
      "command": "uvx",
      "args": ["cerngitlab-mcp"],
      "env": {
        "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  }
}

Gemini CLI

Adicione ao seu ~/.gemini/settings.json:

{
  "mcpServers": {
    "cerngitlab": {
      "command": "uvx",
      "args": ["cerngitlab-mcp"],
      "env": {
        "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  }
}

Uso direto

Modo Stdio (Usuário Único, Padrão)

# Run with uvx (no install needed)
uvx cerngitlab-mcp

# Or if installed from PyPI
cerngitlab-mcp

# Explicit stdio mode
cerngitlab-mcp --mode stdio

# Or from source
uv run cerngitlab-mcp

# With authentication
CERNGITLAB_TOKEN=glpat-xxx uvx cerngitlab-mcp

Modo HTTP (Multi-Usuário)

# HTTP mode for multi-user deployment
cerngitlab-mcp --mode http --host 0.0.0.0 --port 8080

# Or use environment variables
CERNGITLAB_HTTP_MODE=true CERNGITLAB_HOST=0.0.0.0 CERNGITLAB_PORT=8080 cerngitlab-mcp

# Dedicated HTTP entry point
cerngitlab-mcp-http

Seleção de Modo

--mode stdio - Modo de usuário único usando stdin/stdout (padrão)
--mode http - Modo multi-usuário usando API HTTP
--mode auto - Detecção automática com base em variáveis de ambiente

O servidor detecta automaticamente o modo HTTP se as variáveis de ambiente CERNGITLAB_HTTP_MODE, CERNGITLAB_HOST ou CERNGITLAB_PORT estiverem definidas.

Ferramentas

Ferramenta	Descrição	Autenticação necessária
`search_projects`	Pesquisar projetos públicos do CERN GitLab (repositórios) por palavra-chave, tópico ou linguagem	Não
`get_project_info`	Obter metadados detalhados do projeto (estrelas, descrição, linguagens, estatísticas)	Não
`list_branches`	Listar ou pesquisar branches do projeto e seus metadados de commit	Não
`list_project_files`	Listar arquivos e diretórios no repositório de um projeto	Não
`get_file_content`	Buscar o conteúdo de um arquivo específico (inclui detecção binária)	Não
`get_project_readme`	Obter o conteúdo do README de um projeto	Não
`search_code`	Pesquisar código dentro de um projeto específico ou globalmente	Sim*
`search_lhcb_stack`	Pesquisar código dentro de uma stack de software LHCb (por exemplo, 'sim11'), com resolução automática de referência Git	Sim*
`search_issues`	Pesquisar issues em um projeto	Sim
`get_wiki_pages`	Listar páginas wiki de um projeto	Sim
`inspect_project`	Analisar estrutura do projeto, sistema de build, dependências e CI/CD	Não
`list_releases`	Listar releases de um projeto	Não
`get_release`	Obter detalhes de um release específico	Não
`list_tags`	Listar tags de um projeto	Não
`test_connectivity`	Testar conexão com a instância do GitLab	Não

Para documentação detalhada de parâmetros, consulte docs/dev.md.

Exemplos de Prompts

Pesquisar repositórios

"Pesquise no CERN GitLab por repositórios Python relacionados à análise ROOT e mostre-me os mais estrelados"

Entender um projeto

"Obtenha o README e a estrutura de arquivos do projeto lhcb/DaVinci no CERN GitLab"

Explorar uma branch

"Encontre branches contendo 'release' em lhcb/DaVinci e, em seguida, pesquise na branch selecionada pela configuração do Scheduler"

Encontrar exemplos adequados

"Pesquise repositórios no CERN GitLab que usam RooFit e mostre-me exemplos de código de ajuste"

Visualizar código da stack de software LHCb

"Pesquise na stack sim11 do LHCb pelas rotinas de inicialização no projeto Boole"

Analisar a estrutura de um projeto

"Inspecione o projeto lhcb/allen para entender seu sistema de build, dependências e configuração do pipeline de CI"

Encontrar contexto de uso

"Pesquise issues relacionadas a 'falha de segmentação' no projeto atlas/athena para ver se outros encontraram isso"

Acompanhar releases

"Liste os releases recentes de lhcb/DaVinci e mostre-me as notas de release da versão mais recente"

Encontrar configurações de framework

"Pesquise arquivos de configuração do framework Gaudi no CERN GitLab e mostre-me exemplos"

Desenvolvimento

Consulte docs/dev.md para configuração de desenvolvimento, estrutura do projeto, testes e instruções de release.

Implantação HTTP Multi-Usuário

O modo HTTP fornece um servidor centralizado para vários usuários. Ele usa CERN SSO + GitLab OAuth para autenticação; os usuários autenticam com sua identidade CERN existente, e o sistema de permissões do próprio GitLab aplica todos os controles de acesso.

Pré-requisitos

Cliente CERN SSO — Registre um cliente no Serviço de Autorização do CERN. Anote o ID do cliente.
Aplicativo OAuth do GitLab — Crie um em https://gitlab.cern.ch/-/profile/applications.
- Defina o URI de redirecionamento para https://gitlabmcp.cern.ch/oauth/callback (substitua pela URL real)
- Habilite os escopos read_api read_repository read_user
- Anote o ID e o segredo do aplicativo.

Configuração

export CERNGITLAB_CERN_CLIENT_ID=your-cern-sso-client-id
export CERNGITLAB_GITLAB_OAUTH_CLIENT_ID=your-gitlab-oauth-app-id
export CERNGITLAB_GITLAB_OAUTH_CLIENT_SECRET=your-gitlab-oauth-secret
export CERNGITLAB_SERVER_BASE_URL=https://gitlabmcp.cern.ch
export CERNGITLAB_SESSION_STORAGE_PATH=/var/lib/cerngitlab/sessions  # optional

# Start the server
cerngitlab-mcp --mode http --host 0.0.0.0 --port 8000

Consulte examples/oauth_server.py no repositório para um script de referência autônomo.

Fluxo de Autenticação

O cliente envia uma solicitação com o cabeçalho Authorization: Bearer <cern-sso-token>.
O servidor valida o token CERN SSO por meio do endpoint JWKS do CERN.
Se o usuário não tiver uma sessão OAuth ativa do GitLab, o servidor retorna HTTP 202 com um campo authorization_url.
O usuário visita essa URL, autoriza o aplicativo OAuth do GitLab e é redirecionado de volta para /oauth/callback.
As solicitações subsequentes são atendidas usando o token OAuth do GitLab armazenado. As sessões expiram após 2 horas.

Endpoints da API

Método	Caminho	Autenticação	Descrição
`GET`	`/`	—	Informações do servidor
`GET`	`/health`	—	Verificação de integridade
`GET`	`/oauth/authorize`	CERN SSO	Iniciar ou verificar o fluxo de autorização OAuth
`GET`	`/oauth/callback`	—	Receber o código OAuth do GitLab (redirecionamento do navegador)
`GET`	`/tools`	CERN SSO	Listar ferramentas MCP disponíveis
`POST`	`/tools/{tool_name}`	CERN SSO	Executar uma ferramenta específica
`DELETE`	`/session`	CERN SSO	Revogar a sessão OAuth do usuário atual
`GET`	`/admin/sessions`	—	Listar todas as sessões ativas (uso administrativo)

Exemplo de Uso

Supondo que o servidor esteja em execução em https://gitlabmcp.cern.ch e a variável de ambiente CERN_SSO_TOKEN esteja definida com um token CERN SSO válido:

# Step 1 – check authorization status
curl -H "Authorization: Bearer $CERN_SSO_TOKEN" \
     https://gitlabmcp.cern.ch/oauth/authorize
# If 202, visit the returned authorization_url in a browser and authorize.

# Step 2 – list available tools (once authorized)
curl -H "Authorization: Bearer $CERN_SSO_TOKEN" \
     https://gitlabmcp.cern.ch/tools

# Step 3 – execute a tool
curl -X POST -H "Authorization: Bearer $CERN_SSO_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"arguments": {"query": "ROOT"}}' \
     https://gitlabmcp.cern.ch/tools/search_projects

# Revoke session
curl -X DELETE -H "Authorization: Bearer $CERN_SSO_TOKEN" \
     https://gitlabmcp.cern.ch/session

Ferramenta CLI

Uma interface de linha de comando também está disponível para uso direto sem o servidor MCP:

# Install or use with uvx
uvx cerngitlab-cli

# Test connectivity
cerngitlab-cli test-connection

# Search for projects
cerngitlab-cli search-projects --query "ROOT analysis" --language python

# Get project info
cerngitlab-cli get-project-info --project lhcb/DaVinci

# Search code
cerngitlab-cli search-code --search-term "RooFit" --per-page 10

# Inspect project structure
cerngitlab-cli inspect-project --project lhcb/allen

Todos os comandos geram JSON na saída padrão para facilitar o encadeamento e a composição. Consulte cerngitlab-cli --help para a lista completa de comandos.

Arquivo de Skill

Um arquivo de skill detalhado (SKILL.md) está disponível com:

Documentação completa de todas as 15 ferramentas
Especificações de entrada/saída
Exemplos de uso
Requisitos de autenticação

Isso pode ser usado por LLMs ou agentes para entender as ferramentas disponíveis e como usá-las.

Licença

Este software é fornecido sob a licença AGPL-3.0.

cerngitlab-mcp

Documentação

Servidor MCP do CERN GitLab

Recursos

Instalação

Início rápido (recomendado)

Via PyPI

A partir do código-fonte

Configuração

Autenticação

Uso

Claude Desktop

Claude Code

GitHub Copilot

Gemini CLI

Uso direto

Modo Stdio (Usuário Único, Padrão)

Modo HTTP (Multi-Usuário)

Seleção de Modo

Ferramentas

Exemplos de Prompts

Pesquisar repositórios

Entender um projeto

Explorar uma branch

Encontrar exemplos adequados

Visualizar código da stack de software LHCb

Analisar a estrutura de um projeto

Encontrar contexto de uso

Acompanhar releases

Encontrar configurações de framework

Desenvolvimento

Implantação HTTP Multi-Usuário

Pré-requisitos

Configuração

Fluxo de Autenticação

Endpoints da API

Exemplo de Uso

Ferramenta CLI

Arquivo de Skill

Licença