OCI Registry MCP Server

OCI Registry MCP 服务

一个 MCP（Model Context Protocol）服务，提供用于查询 OCI 注册表和镜像引用的工具。

概述

本项目实现了一个基于 SSE 的 MCP 服务，允许由大模型驱动的应用与 OCI 注册表交互。它提供用于检索容器镜像信息、列出标签等的工具。

功能

• 获取 OCI 镜像信息
• 列出仓库的标签
• 获取镜像清单
• 获取镜像配置

MCP 工具

该服务提供以下 MCP 工具：

get_image_info

获取 OCI 镜像信息。

输入：

• image_ref：镜像引用（例如，docker.io/library/alpine:latest）

输出：

• 镜像信息，包括摘要、大小、架构、操作系统、创建日期和层数

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 Registry MCP 服务最简单的方式是使用 ToolHive，它为 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

该服务将可供兼容 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 标头中包含 bearer token：

   • Authorization: Bearer <your-token>
   • 此方式的优先级高于所有其他身份验证方式
   • 使用此方式时，将忽略环境变量和 Docker 配置

2. Bearer Token 环境变量：设置以下环境变量：

   • OCI_TOKEN：用于注册表身份验证的 bearer token

3. 用户名和密码：设置以下环境变量：

   • OCI_USERNAME：用于注册表身份验证的用户名
   • OCI_PASSWORD：用于注册表身份验证的密码

4. Docker 配置（最低优先级）：如果未提供其他身份验证信息，该服务将使用默认 Docker 密钥链，从 ~/.docker/config.json 读取凭据。

示例：

# 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 服务贡献代码！如果您想参与贡献，请查看 贡献指南，了解如何开始。

如果您遇到 Bug 或有功能请求，请在仓库中 提交 issue，或加入我们的 社区 Discord 服务中的 #mcp-servers 频道。

许可证

本项目采用 Apache v2 许可证授权，详情请参阅 LICENSE 文件。