ocireg MCP Server

공식

SSE 기반 MCP 서버로, LLM 기반 애플리케이션이 OCI 레지스트리와 상호작용할 수 있도록 합니다. 컨테이너 이미지 정보 조회, 태그 목록 확인 등을 위한 도구를 제공합니다.

GitHub
12

문서

OCI 레지스트리 MCP 서버

Trust Score OCI 레지스트리 및 이미지 참조를 쿼리하기 위한 도구를 제공하는 MCP(Model Context Protocol) 서버입니다.

개요

이 프로젝트는 LLM 기반 애플리케이션이 OCI 레지스트리와 상호 작용할 수 있도록 하는 SSE 기반 MCP 서버를 구현합니다. 컨테이너 이미지에 대한 정보 검색, 태그 목록 조회 등을 위한 도구를 제공합니다.

기능

  • OCI 이미지 정보 조회
  • 리포지토리의 태그 목록 조회
  • 이미지 매니페스트 조회
  • 이미지 구성 조회

MCP 도구

서버는 다음 MCP 도구를 제공합니다:

get_image_info

OCI 이미지에 대한 정보를 가져옵니다.

입력:

  • image_ref: 이미지 참조 (예: docker.io/library/alpine:latest)

출력:

  • 다이제스트, 크기, 아키텍처, OS, 생성 날짜, 레이어 수를 포함한 이미지 정보

list_tags

리포지토리의 태그를 나열합니다.

입력:

  • repository: 리포지토리 이름 (예: docker.io/library/alpine)

출력:

  • 리포지토리의 태그 목록

get_image_manifest

OCI 이미지의 매니페스트를 가져옵니다.

입력:

  • image_ref: 이미지 참조 (예: docker.io/library/alpine:latest)

출력:

  • 이미지 매니페스트

get_image_config

OCI 이미지의 구성을 가져옵니다.

입력:

  • image_ref: 이미지 참조 (예: docker.io/library/alpine:latest)

출력:

  • 이미지 구성

사용법

ToolHive로 실행하기 (권장)

OCI 레지스트리 MCP 서버를 실행하는 가장 쉬운 방법은 MCP 서버의 안전한 컨테이너화된 배포를 제공하는 ToolHive를 사용하는 것입니다:

# 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

서버는 MCP 호환 클라이언트에서 사용할 수 있으며 이미지 정보를 위해 OCI 레지스트리를 쿼리할 수 있습니다.

ToolHive를 통한 인증

비공개 레지스트리에 접근해야 하는 경우 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

개발

사전 요구 사항

  • Go 1.21 이상
  • OCI 레지스트리에 대한 접근 권한

인증

서버는 비공개 OCI 레지스트리에 접근하기 위해 다음 인증 방법을 지원합니다 (우선순위 순):

  1. HTTP Authorization 헤더 (최우선): HTTP 요청의 Authorization 헤더에 베어러 토큰을 포함합니다:

    • Authorization: Bearer <your-token>
    • 이 방법은 다른 모든 인증 방법보다 우선합니다
    • 이 방법이 사용되면 환경 변수 및 Docker 구성은 무시됩니다

  2. 베어러 토큰 환경 변수: 다음 환경 변수를 설정합니다:

    • OCI_TOKEN: 레지스트리 인증을 위한 베어러 토큰

  3. 사용자 이름 및 비밀번호: 다음 환경 변수를 설정합니다:

    • OCI_USERNAME: 레지스트리 인증을 위한 사용자 이름
    • OCI_PASSWORD: 레지스트리 인증을 위한 비밀번호

  4. Docker 구성 (최하위): 다른 인증이 제공되지 않으면 서버는 ~/.docker/config.json에서 자격 증명을 읽는 기본 Docker 키체인을 사용합니다.

예시:

# 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

포트 구성

서버는 다음 중 하나를 사용하여 특정 포트에서 수신 대기하도록 구성할 수 있습니다:

  1. 환경 변수:

    • MCP_PORT: 수신 대기할 포트 번호 (0에서 65535 사이여야 함)
    • 설정되지 않았거나 유효하지 않은 경우 기본값은 8080 포트입니다

  2. 명령줄 플래그:

    • -port: 환경 변수 설정을 재정의합니다 (0에서 65535 사이여야 함)
    • 유효하지 않은 포트가 제공되면 기본값은 8080 포트입니다
    • 예시: ./ocireg-mcp -port 9090

테스트

go test ./...

린팅

golangci-lint run

기여

이 MCP 서버에 대한 기여를 환영합니다! 기여하고 싶으시다면 시작하는 방법에 대한 자세한 내용은 CONTRIBUTING 가이드를 검토해 주세요.

버그를 발견하거나 기능 요청이 있으시면 리포지토리에 이슈를 등록하거나 커뮤니티 Discord 서버의 #mcp-servers 채널에 참여해 주세요.

라이선스

이 프로젝트는 Apache v2 라이선스에 따라 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.