ocireg MCP Server

Servidor MCP de Registro OCI

Um servidor MCP (Model Context Protocol) que fornece ferramentas para consultar registros OCI e referências de imagens.

Visão Geral

Este projeto implementa um servidor MCP baseado em SSE que permite que aplicações baseadas em LLM interajam com registros OCI. Ele fornece ferramentas para recuperar informações sobre imagens de contêiner, listar tags e muito mais.

Funcionalidades

• Obter informações sobre imagens OCI
• Listar tags de repositórios
• Obter manifestos de imagem
• Obter configurações de imagem

Ferramentas MCP

O servidor fornece as seguintes ferramentas MCP:

get_image_info

Obtém informações sobre uma imagem OCI.

Entrada:

• image_ref: A referência da imagem (ex.: docker.io/library/alpine:latest)

Saída:

• Informações da imagem, incluindo digest, tamanho, arquitetura, SO, data de criação e número de camadas

list_tags

Lista tags de um repositório.

Entrada:

• repository: O nome do repositório (ex.: docker.io/library/alpine)

Saída:

• Lista de tags do repositório

get_image_manifest

Obtém o manifesto de uma imagem OCI.

Entrada:

• image_ref: A referência da imagem (ex.: docker.io/library/alpine:latest)

Saída:

• O manifesto da imagem

get_image_config

Obtém a configuração de uma imagem OCI.

Entrada:

• image_ref: A referência da imagem (ex.: docker.io/library/alpine:latest)

Saída:

• A configuração da imagem

Uso

Executando com ToolHive (Recomendado)

A maneira mais fácil de executar o servidor MCP de Registro OCI é usando o ToolHive, que fornece implantação segura e conteinerizada de servidores MCP:

# Install ToolHive (if not already installed)
# See: https://docs.stacklok.com/toolhive/guides-cli/install

# Register a supported client so ToolHive can auto-configure your environment
thv client setup
# Run the OCI Registry MCP server (packaged as 'oci-registry' in ToolHive)
thv run oci-registry

# List running servers
thv list

# Get detailed information about the server
thv registry info oci-registry

O servidor estará disponível para seus clientes compatíveis com MCP e poderá consultar registros OCI para obter informações de imagem.

Autenticação com ToolHive

Se você precisar acessar registros privados, pode fornecer credenciais de autenticação usando o gerenciamento de segredos do ToolHive:

# For bearer token authentication
thv secret set oci-token
# Enter your bearer token when prompted

thv run --secret oci-token,target=OCI_TOKEN oci-registry

# For username/password authentication
thv secret set oci-username
thv secret set oci-password
# Enter your credentials when prompted

thv run --secret oci-username,target=OCI_USERNAME --secret oci-password,target=OCI_PASSWORD oci-registry

Desenvolvimento

Pré-requisitos

• Go 1.21 ou posterior
• Acesso a registros OCI

Autenticação

O servidor suporta os seguintes métodos de autenticação para acessar registros OCI privados (em ordem de prioridade):

1. Cabeçalho HTTP Authorization (Prioridade Mais Alta): Inclua um token bearer no cabeçalho Authorization da requisição HTTP:

   • Authorization: Bearer <your-token>
   • Este método tem precedência sobre todos os outros métodos de autenticação
   • Quando presente, variáveis de ambiente e configuração do Docker são ignoradas

2. Variável de Ambiente de Token Bearer: Defina a seguinte variável de ambiente:

   • OCI_TOKEN: Token bearer para autenticação no registro

3. Nome de Usuário e Senha: Defina as seguintes variáveis de ambiente:

   • OCI_USERNAME: Nome de usuário para autenticação no registro
   • OCI_PASSWORD: Senha para autenticação no registro

4. Configuração do Docker (Prioridade Mais Baixa): Se nenhuma outra autenticação for fornecida, o servidor usará o chaveiro padrão do Docker, que lê credenciais de ~/.docker/config.json.

Exemplos:

# HTTP Authorization header (for per-request authentication)
# This is handled automatically by the MCP client when making requests
# Example: curl -H "Authorization: Bearer mytoken" http://localhost:8080/...

# Bearer token authentication via environment variable
export OCI_TOKEN=mytoken

# Username/password authentication via environment variables
export OCI_USERNAME=myuser
export OCI_PASSWORD=mypassword

Configuração de Porta

O servidor pode ser configurado para escutar em uma porta específica usando:

1. Variável de Ambiente:

   • MCP_PORT: O número da porta para escutar (deve estar entre 0 e 65535)
   • Se não definida ou inválida, o padrão é a porta 8080

2. Flag de Linha de Comando:

   • -port: Sobrescreve a configuração da variável de ambiente (deve estar entre 0 e 65535)
   • Se uma porta inválida for fornecida, o padrão é a porta 8080
   • Exemplo: ./ocireg-mcp -port 9090

Testes

go test ./...

Linting

golangci-lint run

Contribuindo

Aceitamos contribuições para este servidor MCP! Se você deseja contribuir, revise o guia CONTRIBUTING para obter detalhes sobre como começar.

Se você encontrar um bug ou tiver uma solicitação de funcionalidade, por favor abra uma issue no repositório ou junte-se a nós no canal #mcp-servers em nosso servidor Discord da comunidade.

Licença

Este projeto está licenciado sob a Licença Apache v2 - veja o arquivo LICENSE para detalhes.