🐳 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 在两幅图像上。 1. 查找通用/唯一图层。 1. 返回比较结果。
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.tstools地图。
______________________________________________________________________
🔧 故障排除
- 服务器未启动：确保节点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工具的可扩展框架。