convez.ai
MCP Server
Knuckles-Team

dockerhub-api

Knuckles-Team/dockerhub-api

Ver no GitHub
InicialPluginScore · de 0 a 100

Docker Hub API client + MCP server + A2A agent — repos, tokens, orgs, teams, audit, SCIM

Instalação

$npx convez-ai Knuckles-Team/dockerhub-api

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 5 dias
Versão
v1.5.0
Issues abertas
1
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Dockerhub Api

CLI or API | MCP | Agent

PyPI - Version MCP Server PyPI - Downloads GitHub Repo stars PyPI - License GitHub last commit (by committer) GitHub issues GitHub top language GitHub repo size PyPI - Wheel PyPI - Implementation

Version: 0.5.0

Documentation — Installation, deployment, usage across the API, CLI, and MCP interfaces, the integrated A2A agent server, and guidance on the backing Docker Hub platform are maintained in docs/.


Table of Contents


Overview

Dockerhub Api is a production-grade Agent and Model Context Protocol (MCP) server that wraps the official Docker Hub API v2 (https://hub.docker.com): repositories and tags, immutable tags, personal and organization access tokens, organization members/settings/invites, teams, audit logs, and SCIM 2.0 provisioning — plus the Registry HTTP API v2 (registry-1.docker.io: manifests, blobs, digests, multi-arch inspection, OCI referrers, and gated push/delete) and Docker Scout (api.scout.docker.com: CVE/SBOM/policy intelligence).


Key Features

  • Consolidated Action-Routed MCP Tools: Nine togglable tool modules (hub_auth, hub_repos, hub_org, hub_teams, hub_audit, hub_scim, hub_admin, hub_registry, hub_scout) minimize token overhead in LLM contexts.
  • Three API surfaces, one package: the Hub management API, the Registry v2 image API (its own host + per-repository scoped-token auth), and Docker Scout — each with the same uniform envelope, redaction, and gating.
  • JWT Auth Lifecycle: Short-lived bearer minted from POST /v2/auth/token (password, PAT dckr_pat_*, or org access token), cached and refreshed before expiry, with one transparent re-mint on 401.
  • Rate-Limit Telemetry: X-RateLimit-* headers surfaced in every result; HTTP 429 retried with bounded Retry-After backoff.
  • Safety by Default: Deletes and org-settings writes are gated behind DOCKERHUB_ALLOW_DESTRUCTIVE (default False); secrets are redacted from tool results (plaintext tokens appear exactly once — on creation). Repository creation stays enabled: it is the primary release-provisioning use case.
  • Integrated Graph Agent: Built-in Pydantic AI agent (dockerhub-agent) with A2A and AG-UI web interfaces.
  • Native Telemetry & Tracing: Out-of-the-box OpenTelemetry exports and Langfuse tracing via agent-utilities.

Installation

pip install dockerhub-api            # API client only
pip install "dockerhub-api[mcp]"     # + MCP server
pip install "dockerhub-api[agent]"   # + A2A agent server
pip install "dockerhub-api[all]"     # everything
ExtraAdds
mcpFastMCP server (dockerhub-mcp) via agent-utilities[mcp]
agentPydantic-AI A2A agent (dockerhub-agent) + Logfire via agent-utilities[agent,logfire]
allmcp + agent
testpytest toolchain for development

Or pull the published image:

docker pull knucklessg1/dockerhub-api:latest

Usage

Python API / CLI

from dockerhub_api.auth import get_client

api = get_client()   # reads DOCKERHUB_URL / DOCKER_HUB_USER / DOCKER_HUB_TOKEN

repos = api.get_repositories(namespace="acme", ordering="-last_updated")
api.create_repository(namespace="acme", name="release-images", is_private=True)
tags = api.get_repository_tags(namespace="acme", repository="release-images")
print(api.rate_limit)   # latest X-RateLimit-* snapshot

Every client method returns a uniform envelope: {"status_code": int, "data": ..., "rate_limit": {"limit", "remaining", "reset"}}.

MCP

Available MCP Tools

Tool ModuleToggle Env VarEnabled by DefaultDescription & Nested Actions
hub_authAUTHTOOLTrueToken lifecycle: create_token, login (deprecated), two_factor_login, list_pats, create_pat, get_pat, update_pat, delete_pat, list_oats, create_oat, get_oat, update_oat, delete_oat
hub_reposREPOSTOOLTrueRepositories & tags: list, create, get, check, list_tags, check_tags, get_tag, check_tag, set_immutable_tags, verify_immutable_tags, assign_group
hub_orgORGTOOLTrueOrg admin: get_settings, update_settings, list_members, export_members, update_member, remove_member, list_invites, delete_invite, resend_invite, bulk_invite
hub_teamsTEAMSTOOLTrueTeams: list, create, get, update, patch, delete, list_members, add_member, remove_member
hub_auditAUDITTOOLTrueAudit trail: logs, actions
hub_scimSCIMTOOLTrueSCIM 2.0: service_provider_config, resource_types, resource_type, schemas, schema, list_users, get_user, create_user, update_user
hub_adminADMINTOOLTrueDiagnostics: rate_limit, whoami (local JWT introspection)
hub_registryREGISTRYTOOLTrueRegistry v2 (registry-1.docker.io): api_version, list_tags, get_manifest, check_manifest, resolve_digest, list_platforms, get_config, inspect, get_blob, check_blob, list_referrers, delete_manifest†, delete_blob†, start_upload†, upload_chunk†, complete_upload†, mount_blob†, put_manifest†
hub_scoutSCOUTTOOLTrueDocker Scout (api.scout.docker.com): summary, cves, vulnerabilities, sbom, compare, policies, policy_evaluation

† Gated by DOCKERHUB_ALLOW_DESTRUCTIVE (push and delete are destructive).

Registry v2 vs. the Hub management API

hub_registry targets a different host and auth model than the other tools. The Hub management API (hub.docker.com) uses one JWT from /v2/auth/token; the Registry v2 API (registry-1.docker.io) authorizes each call with a per-repository, per-action bearer obtained from a token service via a 401 WWW-Authenticate challenge. Both reuse the same DOCKER_HUB_USER / DOCKER_HUB_TOKEN credentials (anonymous works for public pulls). Single-segment repository names (e.g. nginx) are normalized to their official library/ path.

_catalog (registry-wide repository listing) is intentionally not implemented: Docker Hub does not issue the registry-scoped token it requires. The chunked push buffers each chunk in memory — it is intended for manifests, config, and attestation blobs, not as a replacement for docker push of large layers.

from dockerhub_api.auth import get_registry_client, get_scout_client

reg = get_registry_client()
print(reg.inspect("nginx", "latest")["data"]["platforms"])      # multi-arch list
digest = reg.resolve_digest("nginx", "latest")["data"]["digest"]
print(reg.list_referrers("nginx", digest)["data"])              # SBOM/attestations

scout = get_scout_client()
print(scout.get_cves("myorg/app", reference="v1")["data"])      # CVE listing

Run the server:

export DOCKER_HUB_USER=youruser
export DOCKER_HUB_TOKEN=dckr_pat_xxx
dockerhub-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Agent (A2A)

dockerhub-agent --mcp-url http://localhost:8000/mcp --web

Environment Variables

VariableDefaultPurpose
DOCKERHUB_URLhttps://hub.docker.comDocker Hub API base URL
DOCKER_HUB_USER—Account identifier (official hub-tool name, primary)
DOCKER_HUB_TOKEN—Password, PAT dckr_pat_*, or org access token (primary)
DOCKERHUB_USERNAME / DOCKERHUB_TOKEN—Legacy fallback aliases for the two above
DOCKERHUB_JWT—Optional pre-minted bearer (overrides credential exchange)
DOCKERHUB_SSL_VERIFYTrueTLS certificate verification
DOCKERHUB_ALLOW_DESTRUCTIVEFalseEnable deletes and org-settings writes
AUTHTOOL … ADMINTOOLTruePer-module MCP tool toggles (see table above)
HOST / PORT / TRANSPORT0.0.0.0 / 8000 / stdioMCP server bind & transport (stdio, streamable-http, sse)
AUTH_TYPEnoneMCP server auth mode (Docker image)
MCP_URL—MCP endpoint the A2A agent connects to
ENABLE_OTELTrueOpenTelemetry / Langfuse export via agent-utilities
EUNOMIA_TYPE / EUNOMIA_POLICY_FILE / EUNOMIA_REMOTE_URLnone / mcp_policies.json / —Eunomia access-governance middleware
FASTMCP_LOG_LEVEL / NO_COLOR—FastMCP logging controls

A complete annotated template lives in .env.example.


Deployment

Docker Compose definitions ship in docker/:

cp .env.example .env       # fill in DOCKER_HUB_USER / DOCKER_HUB_TOKEN
docker compose -f docker/mcp.compose.yml up -d     # MCP server only
docker compose -f docker/agent.compose.yml up -d   # MCP server + A2A agent (port 9018)

Both services expose /health endpoints; see docs/deployment.md for transports, Caddy ingress, and Technitium DNS guidance.


Additional Deployment Options

dockerhub-api can also run as a local container (Docker / Podman / uv) or be consumed from a remote deployment. The Deployment guide has full, copy-paste mcp_config.json for all four transports — stdio, streamable-http, local container / uv, and remote URL:

  • Local container / uv — launch the server from mcp_config.json via uvx, docker run, or podman run, or point at a local streamable-http container by url.
  • Remote URL — connect to a server deployed behind Caddy at http://dockerhub-mcp.arpa/mcp using the "url" key.

Safety Model

Operation classDefaultOverride
Reads (repos, tags, members, logs, SCIM)allowed—
Repository create / immutable-tag config / invites / role updatesallowed—
Deletes (PATs, OATs, groups, members, invites)blockedDOCKERHUB_ALLOW_DESTRUCTIVE=True
Org-settings writes (PUT /v2/orgs/{org}/settings)blockedDOCKERHUB_ALLOW_DESTRUCTIVE=True

Concepts

The concept registry (CONCEPT:HUB-1.x) is documented in docs/concepts.md.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados