How stacklok/toolhive works
Project type and purpose
• ToolHive is a multi-component Go-based system that provides a CLI, a local container runner (“proxyrunner”), an HTTP/gRPC API server, and a Kubernetes Operator to deploy and manage Model Context Protocol (MCP) servers in secure containers.
• It supports local (Docker) and cluster (Kubernetes) deployment, secrets management, telemetry, and pluggable registries/auth.
High-level components
a. CLI client (“thv” binary under cmd/thv)
b. Local runner (“proxyrunner” binary under cmd/thv-proxyrunner)
c. API server (pkg/api exposing HTTP/JSON endpoints)
d. Kubernetes Operator (cmd/thv-operator + deploy/charts/operator)
e. Container runtime interfaces (pkg/container/docker, pkg/container/kubernetes)
f. Secrets & config backends (pkg/secrets, pkg/config, pkg/state)
g. Registry providers (pkg/registry/provider_{local,remote})
h. Authn/Authz middleware (pkg/auth, pkg/authz)
i. Telemetry & audit (pkg/telemetry, pkg/audit)
j. External services: Docker/K8s API, container registries, OIDC providers (Keycloak/GitHub), telemetry backends (Prometheus/OTLP/Jaeger)
Relationships and data flows
• CLI “thv” → API server (HTTP/gRPC) for registry discovery, group management, and remote control
• CLI “thv” → direct container runtime calls (Docker or K8s) via pkg/container for local mode
• API server → registry providers to fetch available MCP tool definitions
• CLI/Operator → secrets manager for fetching credentials (1Password, keyring, env)
• CLI → proxyrunner via STDIO/SSE/streamable proxy for bidirectional tunnel to MCP server process
• Operator watches CRDs (MCPServer, MCPRegistry, ToolConfig) using controllers → creates Kubernetes Deployments (mcpserver + proxyrunner sidecar) via Helm chart
• Telemetry middleware intercepts HTTP and SSE traffic → pushes metrics/traces to OTLP or Prometheus
• Audit middleware logs events to audit sink
Architectural patterns and design principles
• Modular Go packages following “pkg/…” for domain separation (auth, audit, registry, container, transport, secrets, telemetry)
• Adapter/factory patterns for pluggable implementations (registry providers, secrets stores, transport layers)
• Operator pattern for Kubernetes CRD reconciliation (controller-runtime)
• Middleware chaining (HTTP handlers for auth, audit, telemetry)
• State abstraction (local file vs. Kubernetes API)