stacklok · JAORMX · Jul 8, 2026 · Jul 8, 2026 · Jul 8, 2026 · Jul 8, 2026
@@ -0,0 +1 @@
+CLAUDE.md
@@ -6,6 +6,8 @@ This file provides guidance to Claude Code when working with this repository.
 
 ToolHive is a lightweight, secure manager for MCP (Model Context Protocol: https://modelcontextprotocol.io) servers written in Go. It provides a CLI (`thv`), a Kubernetes operator (`thv-operator`), and a proxy runner (`thv-proxyrunner`) for container-based MCP server isolation.
 
+**To understand the system, start with the [Architecture Documentation](docs/arch/README.md).** Begin at the [Architecture Overview](docs/arch/00-overview.md) and [Core Concepts](docs/arch/02-core-concepts.md), then read the component deep-dives relevant to your task — [Deployment Modes](docs/arch/01-deployment-modes.md), [Transport Architecture](docs/arch/03-transport-architecture.md), [Kubernetes Operator](docs/arch/09-operator-architecture.md), [Virtual MCP](docs/arch/10-virtual-mcp-architecture.md), and more. The [architecture index](docs/arch/README.md) has a full map and by-topic navigation.
+
 ## Build and Development Commands
 
 ```bash
@@ -84,7 +86,7 @@ Detailed rules are in `.claude/rules/` (loaded automatically when matching files
 
 ## Architecture Documentation
 
-When making changes that affect architecture, update relevant docs in `docs/arch/`. See `docs/arch/README.md` for structure.
+When making changes that affect architecture, update relevant docs in `docs/arch/`. See the [architecture documentation index](docs/arch/README.md) for structure and the per-component documents.
 
 ## Things That Will Bite You
 

@@ -129,6 +129,10 @@ helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-
 helm upgrade -i <release_name> oci://ghcr.io/stacklok/toolhive/toolhive-operator --version=<version> -n toolhive-system --create-namespace
 ```
 
+For the full list of configurable values, see the
+[operator chart](../../deploy/charts/operator/README.md) and
+[operator CRDs chart](../../deploy/charts/operator-crds/README.md) documentation.
+
 ## Usage
 
 ### Creating an MCP Server

@@ -85,3 +85,7 @@ This is a one-time operation. After patching, future upgrades will work as long
 | crds.install | bool | `true` | Whether to install the CRDs in this chart |
 | crds.keep | bool | `true` | Whether to add the "helm.sh/resource-policy: keep" annotation to CRDs When true, CRDs will not be deleted when the Helm release is uninstalled |
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing to this chart.
+
@@ -89,3 +89,7 @@ This is a one-time operation. After patching, future upgrades will work as long
 
 {{ template "chart.valuesSection" . }}
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing to this chart.
+
@@ -99,3 +99,7 @@ The command removes all the Kubernetes components associated with the chart and
 | registryAPI | object | `{"image":"ghcr.io/stacklok/thv-registry-api:v1.3.0"}` | All values for the registry API deployment and associated resources |
 | registryAPI.image | string | `"ghcr.io/stacklok/thv-registry-api:v1.3.0"` | Container image for the registry API |
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing to this chart.
+
@@ -52,3 +52,7 @@ The command removes all the Kubernetes components associated with the chart and
 
 {{ template "chart.valuesSection" . }}
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing to this chart.
+
@@ -28,6 +28,7 @@ For information on the ToolHive Operator, see the
 
 ### Development Guidelines
 
+- **[CLI Command Reference](cli/thv.md)** - Generated reference for every `thv` command and subcommand
 - **[CLI Best Practices](cli-best-practices.md)** - Guidelines for adding and maintaining CLI commands with focus on usability and consistency
 - **[Logging Practices](logging.md)** - Logging levels, when to use them, and how to structure log messages
 - **[Error Handling](error-handling.md)** - Error construction, wrapping, and handling patterns for CLI and API
@@ -37,6 +38,7 @@ For information on the ToolHive Operator, see the
 - **[Runtime Implementation Guide](runtime-implementation-guide.md)** - Guide for implementing new container runtime support
 - **[Runtime Version Customization](runtime-version-customization.md)** - Customizing base images and packages for protocol-scheme builds
 - **[Remote MCP Authentication](remote-mcp-authentication.md)** - How ToolHive authenticates to remote MCP servers
+- **[Server API Documentation](server/README.md)** - How the OpenAPI docs for the `thv serve` REST API are generated and served
 
 ### Operator Documentation
 
@@ -111,6 +113,9 @@ ToolHive also includes comprehensive end-to-end tests that can be run using:
 task test-e2e
 ```
 
+See the [end-to-end test guide](../test/e2e/README.md) for the test structure,
+Ginkgo labels, and how to run specific suites.
+
 ### Other development tasks
 
 To see a list of all available development tasks, run:
@@ -119,6 +124,9 @@ To see a list of all available development tasks, run:
 task --list
 ```
 
+To spin up a local Keycloak instance for testing authentication flows, see the
+[Keycloak development setup](../deploy/keycloak/README.md).
+
 ## Note on EXPERIMENTAL features
 
 From time to time, ToolHive may include features marked as EXPERIMENTAL. These

@@ -519,3 +519,5 @@ This allows the same codebase to behave appropriately in different environments.
 - [Transport Architecture](03-transport-architecture.md) - How proxying works
 - [RunConfig and Permissions](05-runconfig-and-permissions.md) - Configuration format
 - [Operator Architecture](09-operator-architecture.md) - Kubernetes operator details
+- [Groups](07-groups.md) - Logical grouping of servers across deployment modes
+- [Virtual MCP Server Architecture](10-virtual-mcp-architecture.md) - Aggregating backends as a deployment pattern
@@ -655,3 +655,4 @@ func (*Factory) Create(config types.Config) (types.Transport, error) {
 - [Deployment Modes](01-deployment-modes.md) - How transports work in each mode
 - [RunConfig and Permissions](05-runconfig-and-permissions.md) - Transport configuration
 - [Core Concepts](02-core-concepts.md) - Transport concepts and terminology
+- [Operator Architecture](09-operator-architecture.md) - How the operator and proxy-runner set up transports in Kubernetes
@@ -747,3 +747,4 @@ Custom permission profiles can be defined in JSON files for reusable security po
 - [Deployment Modes](01-deployment-modes.md) - RunConfig portability
 - [Transport Architecture](03-transport-architecture.md) - Transport configuration
 - [Operator Architecture](09-operator-architecture.md) - K8s-specific configuration
+- [Registry System](06-registry-system.md) - Registry metadata that seeds RunConfig for a server
@@ -971,6 +971,7 @@ re-sync, modify `configYAML` (or restart the registry API pod).
 - [Deployment Modes](01-deployment-modes.md) - Registry usage per mode
 - [Groups](07-groups.md) - Groups in registry
 - [Operator Architecture](09-operator-architecture.md) - MCPRegistry CRD
+- [RunConfig and Permissions](05-runconfig-and-permissions.md) - How registry metadata feeds a server's RunConfig
 - [Skills System](12-skills-system.md) - Skills discovery and distribution via registry
 
 ### External Documentation

@@ -141,3 +141,4 @@ Groups may serve as the foundation for additional features:
 - [Workloads Lifecycle](08-workloads-lifecycle.md) - Group operations
 - [Virtual MCP Server Architecture](10-virtual-mcp-architecture.md) - Group-based aggregation
 - [Skills System](12-skills-system.md) - Skills organized in groups
+- [Deployment Modes](01-deployment-modes.md) - How groups apply per deployment mode
@@ -729,4 +729,5 @@ spec:
 - [Core Concepts](02-core-concepts.md) - Operator concepts
 - [Registry System](06-registry-system.md) - MCPRegistry CRD
 - [Virtual MCP Server Architecture](10-virtual-mcp-architecture.md) - VirtualMCPServer details
+- [Transport Architecture](03-transport-architecture.md) - Transport and proxy setup the proxy-runner performs in-cluster
 - Operator Design: `cmd/thv-operator/DESIGN.md`
@@ -364,3 +364,4 @@ Status reporting enables vMCP runtime to report operational status directly inst
 - [Local vMCP CLI Mode](vmcp-local.md) - `thv vmcp` CLI surface, optimizer tiers, and TEI lifecycle
 - [vMCP Library Embedding](vmcp-library.md) - Embedding `pkg/vmcp/` in downstream Go projects
 - [vMCP Scalability Limits and Constraints](13-vmcp-scalability.md) - Per-pod session cap, TTL mechanics, Redis sizing, and pod restart behaviour
+- [Deployment Modes](01-deployment-modes.md) - Where vMCP fits among local and Kubernetes deployment patterns
@@ -462,3 +462,4 @@ ToolHive owns the installation lifecycle, scoping model, CLI/API interfaces, and
 - [Registry System](06-registry-system.md) - Registry architecture shared by skills and servers
 - [Groups](07-groups.md) - Group concept used to organize skills and workloads
 - [Architecture Overview](00-overview.md) - Platform overview
+- [Plugins System](14-plugins-system.md) - Sibling distribution system (OCI artifacts, multi-client install)
@@ -270,3 +270,10 @@ The OCI plugin layer (`ociplugins.Store`, `PluginPackager`, `RegistryClient`,
 | `pkg/storage/sqlite/plugin_store.go` | SQLite store |
 | `pkg/groups/plugins.go` | group membership |
 | `pkg/client/plugins.go` | client metadata + path resolution |
+
+## Related Documentation
+
+- [Skills System](12-skills-system.md) - Sibling distribution system (OCI artifacts, multi-client install, build/publish/install lifecycle)
+- [Registry System](06-registry-system.md) - Registry-name resolution in the install dispatch chain
+- [Groups](07-groups.md) - Plugin group membership (`pkg/groups/plugins.go`)
+- [Core Concepts](02-core-concepts.md) - Platform terminology
@@ -13,6 +13,10 @@ setting up and using these features, see the ToolHive documentation:
 - [CLI guide](https://docs.stacklok.com/toolhive/guides-cli/telemetry-and-metrics),
   including how to enable and configure telemetry and send to common backends
 
+To run a complete local observability stack (Prometheus, Grafana, and the
+OpenTelemetry Collector) for testing this instrumentation, see the
+[OpenTelemetry example stack](../examples/otel/README.md).
+
 For migrating from legacy attribute names to the new OTEL MCP semantic
 conventions, see the [Telemetry Migration Guide](./telemetry-migration-guide.md).
 

@@ -22,6 +22,10 @@ These tests validate ToolHive functionality by exercising the full application s
 - `oidc_mock.go` - Mock OIDC server for authentication tests
 - `run_tests.sh` - Test runner script
 
+Operator-specific end-to-end tests live in subdirectories, such as the
+[VirtualMCPServer E2E tests](thv-operator/virtualmcp/README.md) that run against
+a real Kubernetes cluster.
+
 ### Test Categories
 
 Tests are organized using Ginkgo labels for parallelization and filtering:
Original file line number	Diff line number	Diff line change
Expand Up		@@ -89,3 +89,7 @@ This is a one-time operation. After patching, future upgrades will work as long

		{{ template "chart.valuesSection" . }}

		## Contributing

		See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing to this chart.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -52,3 +52,7 @@ The command removes all the Kubernetes components associated with the chart and

		{{ template "chart.valuesSection" . }}

		## Contributing

		See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing to this chart.