dockerhub-mcp-server

Abhi151433/dockerhub-mcp-server

3.1

If you are the rightful owner of dockerhub-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This project is a Model Context Protocol (MCP) server designed to interact with Docker Hub and OCI registries, providing an AI-accessible interface for various Docker-related operations.

Tools
4
Resources
0
Prompts
0

🐳 DockerHub MCP Server

📌 Overview

This project is a Model Context Protocol (MCP) server that integrates with Docker Hub and OCI registries to provide an AI-accessible interface for:

  • Searching images
  • Fetching metadata
  • Listing tags
  • Analyzing layers
  • Comparing images
  • Retrieving manifests
  • And more...

The AI (via MCP) can call these tools in real-time to interact with Docker Hub programmatically.

🎯 Assignment Goal

The assignment asked us to:

  1. Build an MCP server that can interact with Docker Hub.
  2. Implement a set of tools:
    • Core tools like docker_search_images, docker_get_image_details, docker_list_tags, etc.
    • Bonus tools like vulnerability scanning, build history, base image tracking.
  3. Use TypeScript with strict validation.
  4. Add clear logging, caching, and rate limiting.
  5. Provide a clear README for setup and usage.

We implemented all required tools + all bonus tools ✅.

⚙️ How the Project Works

📡 High-Level Flow

  1. Client / AI Agent sends an MCP request:
    Example: Search for nginx images.

  2. MCP Server (index.ts):

    • Receives request.
    • Validates input with Zod schemas.
    • Maps tool name → matching handler function in implementations.ts.

  3. Tool Implementation (implementations.ts):

    • Calls DockerHubClient functions.
    • Handles any transformation of data (like layer size totals).

  4. DockerHubClient (dockerhub/client.ts):

    • Makes HTTP calls to Docker Hub API and OCI Registry API.
    • Uses:
      • Rate limiter (rateLimiter.ts) → prevents exceeding API limits.
      • Cache (cache.ts) → speeds up repeat calls.
      • Auth handler (dockerhub/auth.ts) → fetches registry tokens.

  5. Response:

    • Sent back as structured JSON.
    • AI can now process and display to the user.

📂 Project Structure

├── dist
│   ├── cache.js                     # Compiled JS for caching utilities
│   ├── dockerhub
│   │   ├── auth.js                  # Compiled JS for Docker Hub authentication
│   │   └── client.js                # Compiled JS for Docker Hub API client
│   ├── index.js                      # Compiled JS entry point for MCP server
│   ├── logger.js                     # Compiled JS logger utilities
│   ├── rateLimiter.js                # Compiled JS rate limiter logic
│   ├── tools
│   │   ├── common.js                 # Compiled JS for Zod schemas (SearchInput, ImageInput, etc.)
│   │   └── implementations.js       # Compiled JS tool implementations (searchImages, getImageDetails, etc.)
│   └── types.js                      # Compiled JS type definitions
├── docker-compose.yml                # Docker Compose configuration for local environment
├── Dockerfile                        # Dockerfile to build the MCP server image
├── package-lock.json                  # NPM lock file
├── package.json                       # NPM project configuration and dependencies
├── README.md                          # Project documentation
├── responses                          # Folder to store output of each tool
│   ├── docker_analyze_layers_response.json
│   ├── docker_compare_images_response.json
│   ├── docker_estimate_pull_size_response.json
│   ├── docker_get_dockerfile_response.json
│   ├── docker_get_image_details_response.json
│   ├── docker_get_image_history_response.json
│   ├── docker_get_manifest_response.json
│   ├── docker_get_stats_response.json
│   ├── docker_get_vulnerabilities_response.json
│   ├── docker_list_tags_response.json
│   ├── docker_search_images_response.json
│   └── docker_track_base_updates_response.json
├── src
│   ├── cache.ts                       # TypeScript code for caching utilities
│   ├── dockerhub
│   │   ├── auth.ts                     # TypeScript code for Docker Hub authentication
│   │   └── client.ts                   # TypeScript Docker Hub API client
│   ├── index.ts                        # MCP server entry point with tool request handlers
│   ├── logger.ts                        # Logger setup for development and production
│   ├── rateLimiter.ts                   # Rate limiter logic
│   ├── testRunner.ts                    # Test runner for tools; can call each tool and store results
│   ├── tools
│   │   ├── common.ts                    # Zod schemas for input validation
│   │   └── implementations.ts          # Tool implementations (functions that interact with DockerHub)
│   └── types.ts                         # Type definitions (interfaces, types)
├── tests
│   └── client.spec.ts                   # Unit tests for DockerHub client or other tools
└── tsconfig.json                        # TypeScript configuration

📜 File-by-File Explanation

1. index.ts

  • Registers all tools in the tools object.
  • Validates inputs using schemas from tools/common.ts.
  • Maps requests to handlers in tools/implementations.ts.
  • Starts the MCP server over stdio.

2. tools/common.ts

  • Contains Zod schemas:
    • ImageInput
    • ImageTagInput
    • SearchInput
  • Ensures tools only receive valid parameters.

3. tools/implementations.ts

  • Actual logic for each tool.
  • Example: docker_compare_images:
    1. Calls analyzeLayers on both images.
    2. Finds common/unique layers.
    3. Returns comparison results.

4. dockerhub/client.ts

  • Talks directly to Docker Hub API & OCI registry.
  • Handles search, repo details, tags, manifests, vulnerabilities.
  • Uses cache.ts to store responses.
  • Uses rateLimiter.ts to throttle requests.

5. dockerhub/auth.ts

  • Gets JWT tokens from Docker Hub for private/registry API access.

6. cache.ts

  • Uses LRU Cache.
  • Stores responses to reduce API calls.

7. rateLimiter.ts

  • Uses Bottleneck to limit requests/sec.

8. logger.ts

  • Uses Winston for structured logs.

9. testRunner.ts

  • Test runner for all tools.
  • Can run tools directly and save responses to responses/ folder.

🧪 Testing & Saving Responses

  1. Run all tools and automatically save responses:
# Run test runner (default saves to responses/)
npm run test:tools

🧠 AI Integration

This project integrates with Model Context Protocol (MCP) to enable AI-powered agents (such as ChatGPT with MCP plugin support) to execute Docker Hub operations in a structured, validated, and secure way.

How AI Works Here

  1. MCP Server Role

    • The MCP server acts as a bridge between the AI agent and Docker Hub APIs.
    • The AI agent sends structured requests containing:
      • The tool name (e.g., docker_search_images)
      • The parameters (e.g., query, pageSize, page)
    • This ensures predictable execution and reduces the risk of malformed or malicious requests.

  2. Structured Request → Validation

    • All incoming requests are validated using Zod schemas in src/tools/common.ts.
    • Validation ensures:
      • Required parameters are present
      • Data types are correct
      • Invalid input is rejected before any API calls happen.

  3. Handler Execution

    • Each tool has a corresponding handler function inside src/tools/implementations.ts.
    • These handlers:
      • Extract validated parameters
      • Call the DockerHubClient methods to interact with Docker Hub
      • Format and return the results

  4. Response Back to AI

    • The results are returned to the AI in a clean JSON format
    • This enables the AI to:
      • Generate human-readable responses
      • Process the data for further reasoning
      • Chain multiple tool calls together when needed

⚙️ Tool Execution Flow

  1. Incoming MCP Request
    Example request format: 
    {
  "method": "tools/execute",
  "params": {
    "name": "docker_search_images",
    "arguments": { "query": "nginx", "pageSize": 10, "page": 1 }
  }
}

⚠️ Error Handling

  • Validation errors → descriptive messages.
  • API errors → caught and returned.
  • Handler errors → structured JSON.
{
  "error": "InvalidInput",
  "message": "pageSize must be a number between 1 and 100."
}

🛠 Extending Tools

  1. Define Zod schema in tools/common.ts.
  2. Write handler in tools/implementations.ts.
  3. Register the tool in index.ts tools map.

🔧 Troubleshooting

  • Server not starting: Ensure Node 18+ is installed and .env variables are set.
  • Rate limit errors: Adjust configuration in rateLimiter.ts.
  • Cache issues: Clear LRU cache or restart the server.
  • Authentication errors: Verify dockerhub/auth.ts is fetching tokens correctly.

🚀 Quick Start

# Clone repository
git clone https://github.com/Abhi151433/dockerhub-mcp-server.git
cd dockerhub-mcp-server

# Install dependencies
npm install

# Copy & edit environment variables
cp .env.example .env
# Fill in Docker Hub credentials if needed

# Run MCP server directly
npm run start

# Or run test runner to save tool responses
npm run test:tools

📚 References

✅ Summary

  • Fully functional MCP server for Docker Hub.
  • Implements core + bonus tools.
  • Supports AI integration with validated requests.
  • Structured logging, caching, rate-limiting, and error handling.
  • Extensible framework for new Docker tools.