quay-mcp-server by quay - MCP Server

Quay MCP Server

A Model Context Protocol (MCP) server that provides access to Quay container registry APIs. This server automatically discovers Quay API endpoints from the OpenAPI specification and generates MCP tools for interacting with Quay registries.

Project Structure

This project follows Go best practices with a clean, modular architecture:

quay-mcp-server/
├── cmd/
│   └── quay-mcp/           # Main application
│       └── main.go
├── internal/               # Private application code
│   ├── client/            # Quay API client
│   │   └── quay_client.go
│   ├── server/            # MCP server implementation
│   │   └── mcp_server.go
│   └── types/             # Common data types
│       └── types.go
├── examples/              # Example code and demonstrations
│   └── example.go
├── test/                  # Test files
│   └── main_test.go
├── testing/               # Test data and fixtures
├── bin/                   # Built binaries (created by build)
├── go.mod                 # Go module definition
├── go.sum                 # Go module checksums
├── Makefile              # Build automation
├── README.md             # This file
└── .gitignore            # Git ignore rules

Features

Automatic API Discovery: Fetches and parses Quay's OpenAPI specification
Dynamic Tool Generation: Creates MCP tools from API endpoints
Smart Parameter Handling: Supports both path and query parameters
Comprehensive Logging: Detailed request/response logging with security features
Tag-based Filtering: Only exposes relevant API endpoints (manifest, organization, repository, robot, tag)
Authentication Support: OAuth token authentication for protected resources

Installation

Prerequisites

Go 1.23 or later
Access to a Quay registry (e.g., quay.io)

Building from Source

# Clone the repository
git clone https://github.com/quay/quay-mcp-server.git
cd quay-mcp-server

# Install dependencies
make deps

# Build the application
make build

# The binary will be available at ./bin/quay-mcp

Using Make Commands

# Build the application
make build

# Run tests
make test

# Run example mode
make run-example

# Clean build artifacts
make clean

# Format code
make fmt

# Install to GOPATH/bin
make install

# Show all available commands
make help

Usage

Basic Usage

# Start MCP server for quay.io
./bin/quay-mcp -url https://quay.io

# Start with OAuth token for authenticated access
./bin/quay-mcp -url https://quay.io -token your-oauth-token

# Run in example mode to see available tools
./bin/quay-mcp -url https://quay.io -example

Command Line Options

-url <registry-url>: Quay registry URL (required)
-token <oauth-token>: OAuth token for authentication (optional)
-example: Run in example mode to demonstrate functionality

Integration with Claude Desktop

Add the following to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "quay": {
      "command": "/path/to/bin/quay-mcp",
      "args": ["-url", "https://quay.io"],
      "env": {
        "QUAY_OAUTH_TOKEN": "your-oauth-token-here"
      }
    }
  }
}

Integration with MCPHost

MCPHost is a powerful CLI host application that enables Large Language Models (LLMs) to interact with MCP servers. You can use it to interact with your Quay registry through various LLM providers.

Installation

Install MCPHost using one of these methods:

# Using Go
go install github.com/mark3labs/mcphost@latest

# Using npm
npm install -g @mark3labs/mcphost

# Or download from releases
# https://github.com/mark3labs/mcphost/releases

Configuration

Create or update your MCPHost configuration file at ~/.mcphost.yml:

# MCP Servers configuration
mcpServers:
  quay:
    command: "/path/to/bin/quay-mcp"
    args: ["-url", "https://quay.io"]
    env:
      QUAY_OAUTH_TOKEN: "your-oauth-token-here"

# Application settings
model: "anthropic:claude-3-5-sonnet-latest"  # or openai:gpt-4, ollama:qwen2.5:3b, etc.
max-steps: 20
debug: false

# Model generation parameters
max-tokens: 4096
temperature: 0.7
top-p: 0.95

Usage Examples

Interactive Mode:

# Start interactive session with Claude
mcphost

# Use with different LLM providers
mcphost -m openai:gpt-4
mcphost -m ollama:qwen2.5:3b
mcphost -m google:gemini-2.0-flash

Non-Interactive Mode (Perfect for Automation):

# Single query with full UI
mcphost -p "List all repositories in the redhat namespace"

# Quiet mode for scripting (only AI response)
mcphost -p "Show manifest details for redhat/ubi8" --quiet

# Use in shell scripts
REPOS=$(mcphost -p "Get public repositories from quay.io/redhat" --quiet)
echo "Found repositories: $REPOS"

Advanced Usage:

# Custom parameters for more focused responses
mcphost -p "Analyze repository security tags" --temperature 0.3 --max-tokens 2000

# With custom stop sequences
mcphost -p "Generate automation script" --stop-sequences "```","END"

Interactive Commands

Once in MCPHost interactive mode, you can use:

/tools - List all available Quay tools
/servers - Show configured MCP servers
/help - Show available commands
/history - Display conversation history
/quit - Exit the application

Example Interactions

$ mcphost
🤖 MCPHost Interactive Mode
📡 Connected to Quay MCP Server

You: List repositories in the redhat namespace that are public

🤖 I'll help you list the public repositories in the redhat namespace using the Quay API.

[Uses quay_listRepos tool with namespace=redhat, public=true]

Here are the public repositories in the redhat namespace:
- redhat/ubi8: Red Hat Universal Base Image 8
- redhat/ubi9: Red Hat Universal Base Image 9  
- redhat/3scale-toolbox: 3scale toolbox container
...

You: Show me the manifest details for redhat/ubi8:latest

🤖 I'll retrieve the manifest details for the redhat/ubi8:latest image.

[Uses quay_getRepoManifest tool]

Here are the manifest details for redhat/ubi8:latest:
- Architecture: amd64
- Size: 234MB
- Layers: 3
- Digest: sha256:abc123...
...

Automation & Scripting

MCPHost's non-interactive mode makes it perfect for DevOps automation:

#!/bin/bash
# Repository monitoring script
REPOS=$(mcphost -p "List all repositories in namespace 'myorg' that haven't been updated in 30 days" --quiet)

# Security scanning
VULNS=$(mcphost -p "Check for security vulnerabilities in myorg/myapp:latest" --quiet)

# Automated reporting
mcphost -p "Generate a weekly report of repository activity for myorg namespace" --quiet > weekly-report.md

API Coverage

The server automatically filters and exposes Quay API endpoints with the following tags:

manifest: Container manifest operations
organization: Organization management
repository: Repository operations
robot: Robot account management
tag: Container tag operations

Architecture

Internal Packages

internal/client: Quay API client with comprehensive HTTP handling, parameter processing, and authentication
internal/server: MCP server implementation with tool registration and request handling
internal/types: Common data structures used across packages

Key Components

Swagger Spec Discovery: Automatically fetches OpenAPI specification from Quay
Endpoint Discovery: Parses specification to identify relevant API endpoints
Tool Generation: Creates MCP tools with proper parameter schemas
Request Processing: Handles both path parameters and query parameters
Response Formatting: Returns JSON responses with proper formatting

Development

Project Layout

The project follows the Standard Go Project Layout:

cmd/: Main applications
internal/: Private application and library code
examples/: Examples and demonstrations
test/: Additional external test apps and test data

Adding New Features

Client Features: Add to internal/client/quay_client.go
Server Features: Add to internal/server/mcp_server.go
Types: Add common types to internal/types/types.go

Testing

# Run all tests
make test

# Run tests with verbose output
go test -v ./...

Logging

The server provides comprehensive logging including:

API request/response details
Parameter processing
Authentication (with token masking for security)
Error handling
Performance metrics

Security

OAuth tokens are masked in logs for security
Response bodies are truncated to prevent log overflow
Internal packages are not exposed to external consumers

Contributing

Fork the repository
Create a feature branch
Make your changes following Go best practices
Add tests for new functionality
Run make fmt and make lint
Submit a pull request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

For issues and questions:

Check the existing issues on GitHub
Create a new issue with detailed information
Include logs and reproduction steps

Changelog

v1.0.0

Initial release with refactored architecture
Proper Go project structure
Comprehensive API coverage
Full parameter support (path and query)
Authentication and logging features