OCI Repository Model Context Protocol Server

This implementation establishes an MCP (Model Context Protocol) service endpoint facilitating queries against OCI (Open Container Initiative) artifact registries and image references.

Core Functionality

This project furnishes an SSE (Server-Sent Events) driven MCP gateway enabling language model-backed agents to interrogate OCI registries. It offers specialized endpoints for extracting container image specifics, enumerating available tags, and fetching detailed image specifications.

Capabilities

• Fetch metadata for specified OCI images
• Retrieve a complete listing of tags associated with a repository
• Acquire the raw image manifest document
• Download the image configuration blob

Exposed MCP Utilities

The server exposes the following specialized functions for LLM consumption:

get_image_info

Retrieves comprehensive data pertaining to a single OCI image identifier.

Input Parameters:

• image_ref: The fully qualified image locator (e.g., "docker.io/library/alpine:latest")

Return Value:

• Structured data including the image digest hash, byte size, platform architecture, operating system, creation timestamp, and layer count.

list_tags

Generates a sequence of all known tags for a designated container repository.

Input Parameters:

• repository: The repository's canonical path (e.g., "docker.io/library/alpine")

Return Value:

• A collection (list) of string tags.

get_image_manifest

Returns the raw OCI image manifest associated with a specific image reference.

Input Parameters:

• image_ref: The identifier for the image (e.g., "docker.io/library/alpine:latest")

Return Value:

• The raw image manifest content.

get_image_config

Fetches the configuration document embedded within an OCI image manifest.

Input Parameters:

• image_ref: The target image reference (e.g., "docker.io/library/alpine:latest")

Return Value:

• The image's configuration object.

Deployment Strategy

Integration with ToolHive (Recommended Pathway)

The simplest method for operationalizing the OCI Registry MCP service involves utilizing the ToolHive orchestration layer, which facilitates secure, containerized hosting of MCP intermediaries:

# Provision ToolHive if absent
# Refer to: https://docs.stacklok.com/toolhive/guides-cli/install

# Configure necessary client integrations for environment setup
thv client setup
# Deploy and launch the OCI Registry MCP server (packaged under 'oci-registry' in ToolHive)
thv run oci-registry

# Review currently active servers
thv list

# Query operational details for the deployed server instance
thv registry info oci-registry

The service will then be accessible to MCP-aware clients for querying OCI registry data.

Secure Credential Handling via ToolHive

For access to private registries, authentication material can be injected using ToolHive's built-in secret management:

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

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

# For standard user/pass authentication
thv secret set oci-username
thv secret set oci-password
# Input credentials upon request

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

Development Guidelines

Prerequisites for Building

• Go language compiler version 1.21 or newer
• Network access to target OCI registries

Registry Authentication Mechanisms

The server is engineered to support several methods for authenticating against restricted OCI repositories:

1. Bearer Token: Defined via the OCI_TOKEN environment variable.

2. OCI_TOKEN: The requisite bearer token for registry access

3. Username and Password Credentials: Specified through environment variables.

4. OCI_USERNAME: The credential for user identity

5. OCI_PASSWORD: The associated secret credential

6. Docker Configuration File: If neither token nor U/P is configured, the service defaults to utilizing the standard Docker credential helper chain, reading from ~/.docker/config.json.

Example Environment Variable Setup:

# Token Example
export OCI_TOKEN=your-secret-token-here

# User/Password Example
export OCI_USERNAME=registry_user
export OCI_PASSWORD=registry_password

Network Port Specification

The listening interface port can be dictated using one of two primary configuration sources:

1. Environment Variable:

2. MCP_PORT: Specifies the numeric listening port (must be in the range 0-65535).

3. Default is 8080 if unset or invalid.

4. Command-line Argument:

5. -port: Takes precedence over the environment variable (must be a valid port number).
6. Invalid argument values revert to the 8080 default.
7. Execution illustration: ./ocireg-mcp -port 9090

Quality Assurance Testing

Run the integrated test suite:

go test ./...

Code Linting

Execute the static analysis tool:

golangci-lint run

Collaboration

We encourage community involvement in the maintenance and enhancement of this MCP service! Please consult the CONTRIBUTING guide for contribution instructions.

Should you discover a fault or propose a new capability, kindly report an issue on the repository or engage with our team in the #mcp-servers channel on our community Discord server.

Licensing

This software is distributed under the terms of the Apache v2 License; review the LICENSE file for complete terms.