MCP Server Dockerhub

DockerHub MCP服务器

用于Docker Hub集成的全面模型上下文协议（MCP）服务器，为AI助手提供强大的Docker镜像搜索、分析和管理功能。

🚀 快速开始

先决条件

• Node.js 18+
• npm或纱线
• Docker Hub帐户（可选，用于身份验证）

安装和设置

1. 克隆并安装：

git clone 
cd dockerhub-mcp-server
npm install
npm run build

1. 配置环境（可选）：

cp .env.example .env
# Edit .env with your Docker Hub credentials

1. 启动服务器：

npm start

🛠️ 发展

npm run build               # Build project
npm test                    # Run tests
npm run lint               # Run linting
npm start                  # Start server

MCP检查器（Web界面）

npm run inspect
# Opens at: http://localhost:6274

🔧 特性

12工具

• 搜索图像、图像详细信息、列表标签、获取清单
• 分析图层，比较图像，估计拉取大小
• 获取Dockerfile信息、统计数据、漏洞、图像历史记录、跟踪库更新

关键能力

• ✅ 使用TTL和简单的逐出进行缓存
• ✅ 可选的身份验证和私有注册表支持
• ✅ 全面的错误处理
• ✅ 具有强大安全检查的TypeScript
• ✅ Docker容器化支持
• ✅ 符合MCP协议
• ✅ 核心和客户端模块的单元测试

📚 Claude桌面设置

要与Claude Desktop集成，请执行以下操作：

1. 构建项目：

npm run build

1. 添加到Claude桌面配置 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "dockerhub": {
      "command": "node",
      "args": ["/path/to/your/project/dist/index.js"],
      "env": {
        "CACHE_TTL_SECONDS": "300",
        "CACHE_MAX_SIZE": "1000",
        "REQUEST_TIMEOUT_MS": "10000",
        "DOCKERHUB_USERNAME": "",
        "DOCKERHUB_PASSWORD": "",
        "PRIVATE_REGISTRY_URL": "",
        "PRIVATE_REGISTRY_USERNAME": "",
        "PRIVATE_REGISTRY_PASSWORD": "",
        "LOG_LEVEL": "info"
      }
    }
  }
}

1. 重新启动克劳德桌面 并用以下方法进行测试： *“你能在Docker Hub上搜索nginx镜像吗？”*

🐳 Docker部署

docker build -t dockerhub-mcp-server .
docker run -d --name dockerhub-mcp dockerhub-mcp-server

⚙️ 配置

环境变量

DOCKERHUB_USERNAME=your_username           # Optional
DOCKERHUB_PASSWORD=your_token              # Optional
PRIVATE_REGISTRY_URL=                      # Optional, overrides Docker Hub
PRIVATE_REGISTRY_USERNAME=                 # Optional
PRIVATE_REGISTRY_PASSWORD=                 # Optional
CACHE_TTL_SECONDS=300                      # Cache TTL
CACHE_MAX_SIZE=1000                        # Cache max entries
REQUEST_TIMEOUT_MS=10000                   # HTTP request timeout
RATE_LIMIT_REQUESTS_PER_MINUTE=100         # Global token bucket rate limit
LOG_LEVEL=info                             # error|warn|info|debug

速率限制

• MCP CallTool处理程序中强制的全局令牌桶
• 超过此值时，服务器将返回MCP错误响应内容 { "error": "Rate limit exceeded" }

结构化日志记录

• JSON格式的行，带字段：ts、level、msg、可选上下文（reqId、tool、message）
• 通过LOGLEVEL控制
• 记录的重要事件：auth_start/success/failed、call_tool_start/failure/error、rate_limit_exceeded、server_connected

🧪 测试

npm test                    # Run all tests
npm run inspect            # Interactive web testing

📖 API示例

搜索图像

{
  "tool": "docker_search_images",
  "arguments": {
    "query": "nginx",
    "limit": 10,
    "filters": { "is_official": true }
  }
}

比较图像

{
  "tool": "docker_compare_images", 
  "arguments": {
    "image1": "nginx:alpine",
    "image2": "nginx:latest"
  }
}

🏗️ 建筑

• DockerHub客户端 -具有授权和速率限制的API客户端
• 缓存管理器 -带TTL和LRU的智能缓存
• RateLimiter -请求节流和监控
• 配置管理器 -基于环境的配置
• 日志记录器 -带级别的结构化日志记录

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🆘 支持

• 🐛 为bug或问题创建问题
• 📧 检查存储库中的更新
• 🔧 使用MCP检查器进行调试