使用说明

🐳 DockerHub MCP服务器

📌 概述

这个项目是 模型上下文协议（MCP） 与集成的服务器 Docker Hub 和 OCI 注册 提供一个AI可访问的界面，用于：

搜索图像
正在获取元数据
列表标签
分析图层
比较图像
检索清单
还有更多。..

人工智能（通过MCP）可以调用这些工具 实时的 以编程方式与Docker Hub交互。

🎯 作业目标

任务要求我们：

构建一个可以与Docker Hub交互的MCP服务器。
实施一套工具：
- 核心工具 喜欢 docker_search_images, docker_get_image_details, docker_list_tags等等。
- 奖励工具 比如漏洞扫描、构建历史、基础图像跟踪。
使用 TypeScript 随着 严格验证.
添加 清除日志记录、缓存和速率限制.
提供a 清除README 用于设置和使用。

我们实施 所有必需的工具 + 所有奖励工具 ✅.

⚙️ 项目如何运作

📡 高水位流量

客户端/AI代理 发送MCP请求：
示例：搜索 nginx 图像。
MCP服务器(index.ts):
- 接收请求。
- 使用验证输入 Zod模式.
- 地图工具名称→ 匹配中的处理函数 implementations.ts.
工具实施(implementations.ts):
- 呼叫 DockerHub客户端 功能。
- 处理任何数据转换（如图层大小总计）。
DockerHub客户端(dockerhub/client.ts):
- 对以下对象进行HTTP调用 Docker Hub API 和 OCI注册表API.
- 使用：
  - 速率限制器 (rateLimiter.ts) → 防止超过API限值。
  - 缓存 (cache.ts) → 加快重复呼叫。
  - 身份验证处理程序 (dockerhub/auth.ts) → 获取注册表令牌。
响应:
- 以结构化JSON格式发回。
- AI现在可以处理并向用户显示。

📂 项目结构

├── 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

📜 逐个文件说明

1.index.ts

注册所有工具 在 tools 对象。
验证输入 使用来自的模式 tools/common.ts.
地图请求 处理程序在 tools/implementations.ts.
启动MCP服务器 超过stdio。

2.工具/通用工具

包含 Zod模式:
- ImageInput
- ImageTagInput
- SearchInput
确保工具只接收有效参数。

3.工具/实施

实际 每个工具的逻辑.
例子： docker_compare_images:
1. 呼叫 analyzeLayers 在两幅图像上。
2. 查找通用/唯一图层。
3. 返回比较结果。

4.码头/客户

直接与 Docker Hub API & OCI 注册.
处理搜索、仓库详细信息、标签、清单、漏洞。
用途 cache.ts 以存储响应。
用途 rateLimiter.ts 以限制请求。

5.码头代理/授权

得到 JWT代币 来自Docker Hub，用于私有/注册表API访问。

6.cache.ts

用途 LRU缓存.
存储响应以减少API调用。

7.rateLimiter.ts

用途瓶颈限制请求/秒。

8.logger.ts

用途 温斯顿 对于结构化日志。

9.testRunner.ts

所有工具的测试流道。
可以直接运行工具并将响应保存到响应/文件夹。

🧪 测试和保存响应

运行所有工具并自动保存响应：

# Run test runner (default saves to responses/)
npm run test:tools

🧠 人工智能集成

该项目与 模型上下文协议（MCP） 使AI驱动的代理（如支持MCP插件的ChatGPT）能够在 结构化的, 已验证，以及安全方式。

人工智能在这里是如何工作的

MCP服务器角色
- MCP服务器充当桥在AI代理和Docker Hub API之间。
- AI代理发送 结构化请求 包含：
  - 这 工具名称 （例如。， docker_search_images)
  - 这参数（例如。， query, pageSize, page)
- 这确保了可预测的执行，并降低了格式错误或恶意请求的风险。
结构化请求→ 验证
- 所有传入请求都使用验证 Zod模式 在……里面 src/tools/common.ts.
- 验证确保：
  - 所需参数已存在
  - 数据类型正确
  - 无效输入被拒绝之前任何API调用都会发生。
处理程序执行
- 每个工具都有相应的 处理程序函数 内部 src/tools/implementations.ts.
- 这些处理程序：
  - 提取验证参数
  - 打电话给 DockerHubClient 与Docker Hub交互的方法
  - 格式化并返回结果
回复AI
- 结果以某种方式返回给AI 干净的JSON格式
- 这使AI能够：
  - 生成人类可读的响应
  - 处理数据以进行进一步推理
  - 在需要时将多个工具调用链接在一起

⚙️ 工具执行流程

传入MCP请求
请求格式示例：

{
  "method": "tools/execute",
  "params": {
    "name": "docker_search_images",
    "arguments": { "query": "nginx", "pageSize": 10, "page": 1 }
  }
}

⚠️ 错误处理

验证错误→ 描述性信息。
API错误→ 抓住并返回。
处理程序错误→ 结构化JSON。

{
  "error": "InvalidInput",
  "message": "pageSize must be a number between 1 and 100."
}

🛠 扩展工具

定义 Zod模式 在……里面 tools/common.ts.
写 处理器 在……里面 tools/implementations.ts.
在中注册该工具 index.ts tools 地图。

🔧 故障排除

服务器未启动：确保节点18+已安装 .env 变量已设置。
速率限制错误：调整配置 rateLimiter.ts.
缓存问题：清除LRU缓存或重新启动服务器。
身份验证错误：验证 dockerhub/auth.ts 正在正确获取令牌。

🚀 快速开始

# 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

📚 参考文献

✅ 总结

功能完备的 MCP服务器 Docker Hub。
实现 核心+奖励工具.
支持 人工智能集成 通过验证请求。
结构化日志记录、缓存、速率限制和错误处理。
新Docker工具的可扩展框架。