From dc413ab6b094da2205724059676950732baccae9 Mon Sep 17 00:00:00 2001 From: Juan Antonio Osorio Date: Wed, 8 Jul 2026 08:14:56 +0300 Subject: [PATCH 1/3] Point agent entry files at the architecture docs The CLAUDE.md entry point mentioned docs/arch/ only as inline text near the bottom, so the architecture documentation was easy for a reader (or agent) to miss. Add a prominent, clickable pointer to the architecture index at the top, and make AGENTS.md a symlink to CLAUDE.md so tools that read the AGENTS.md convention get the same canonical guidance. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 1 + CLAUDE.md | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) create mode 120000 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 0000000000..681311eb9c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CLAUDE.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index e566d11bc0..4390e2b1d9 100644 --- a/CLAUDE.md +++ b/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 From e8402198563bd3690c1f26e7b4daef5fd2a01eee Mon Sep 17 00:00:00 2001 From: Juan Antonio Osorio Date: Wed, 8 Jul 2026 08:15:09 +0300 Subject: [PATCH 2/3] Cross-link related architecture documents The numbered architecture docs linked up to the index but rarely to each other, so moving between closely related topics (deployment modes and groups, runconfig and registry, transport and operator) meant routing back through the index. Add the missing lateral 'Related Documentation' links between strongly related docs, and give 14-plugins-system.md the Related section it was missing. Co-Authored-By: Claude Opus 4.8 --- docs/arch/01-deployment-modes.md | 2 ++ docs/arch/03-transport-architecture.md | 1 + docs/arch/05-runconfig-and-permissions.md | 1 + docs/arch/06-registry-system.md | 1 + docs/arch/07-groups.md | 1 + docs/arch/09-operator-architecture.md | 1 + docs/arch/10-virtual-mcp-architecture.md | 1 + docs/arch/12-skills-system.md | 1 + docs/arch/14-plugins-system.md | 7 +++++++ 9 files changed, 16 insertions(+) diff --git a/docs/arch/01-deployment-modes.md b/docs/arch/01-deployment-modes.md index 56d5ca98fd..cd66c3ecc4 100644 --- a/docs/arch/01-deployment-modes.md +++ b/docs/arch/01-deployment-modes.md @@ -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 diff --git a/docs/arch/03-transport-architecture.md b/docs/arch/03-transport-architecture.md index 7f881531c1..1b944cc836 100644 --- a/docs/arch/03-transport-architecture.md +++ b/docs/arch/03-transport-architecture.md @@ -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 diff --git a/docs/arch/05-runconfig-and-permissions.md b/docs/arch/05-runconfig-and-permissions.md index 11a85f2e7e..2ea393b280 100644 --- a/docs/arch/05-runconfig-and-permissions.md +++ b/docs/arch/05-runconfig-and-permissions.md @@ -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 diff --git a/docs/arch/06-registry-system.md b/docs/arch/06-registry-system.md index 491f5331bd..ba8dd1699f 100644 --- a/docs/arch/06-registry-system.md +++ b/docs/arch/06-registry-system.md @@ -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 diff --git a/docs/arch/07-groups.md b/docs/arch/07-groups.md index 9ac6bc2e1b..d862439ed3 100644 --- a/docs/arch/07-groups.md +++ b/docs/arch/07-groups.md @@ -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 diff --git a/docs/arch/09-operator-architecture.md b/docs/arch/09-operator-architecture.md index 38ce8001fc..525c41e457 100644 --- a/docs/arch/09-operator-architecture.md +++ b/docs/arch/09-operator-architecture.md @@ -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` diff --git a/docs/arch/10-virtual-mcp-architecture.md b/docs/arch/10-virtual-mcp-architecture.md index 891dffc3ed..cc03ec710c 100644 --- a/docs/arch/10-virtual-mcp-architecture.md +++ b/docs/arch/10-virtual-mcp-architecture.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 diff --git a/docs/arch/12-skills-system.md b/docs/arch/12-skills-system.md index e0021eb346..83e16b8409 100644 --- a/docs/arch/12-skills-system.md +++ b/docs/arch/12-skills-system.md @@ -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) diff --git a/docs/arch/14-plugins-system.md b/docs/arch/14-plugins-system.md index 2583fcf9ef..82c3d9a1ae 100644 --- a/docs/arch/14-plugins-system.md +++ b/docs/arch/14-plugins-system.md @@ -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 From 5de208015ce48dded5e2d6ab68ba00cbc111052a Mon Sep 17 00:00:00 2001 From: Juan Antonio Osorio Date: Wed, 8 Jul 2026 08:15:09 +0300 Subject: [PATCH 3/3] Link standalone READMEs from the developer guides Several READMEs were not linked from any hub, so a reader browsing the docs could not discover them: the generated CLI reference, the server API docs, the e2e test guide, the local Keycloak and OpenTelemetry setups, and the Helm chart docs. Link each from the most relevant guide, and add a Contributing section to the chart README templates so their CONTRIBUTING guides are reachable. Co-Authored-By: Claude Opus 4.8 --- cmd/thv-operator/README.md | 4 ++++ deploy/charts/operator-crds/README.md | 4 ++++ deploy/charts/operator-crds/README.md.gotmpl | 4 ++++ deploy/charts/operator/README.md | 4 ++++ deploy/charts/operator/README.md.gotmpl | 4 ++++ docs/README.md | 8 ++++++++ docs/observability.md | 4 ++++ test/e2e/README.md | 4 ++++ 8 files changed, 36 insertions(+) diff --git a/cmd/thv-operator/README.md b/cmd/thv-operator/README.md index 22b58773a2..2fac701a33 100644 --- a/cmd/thv-operator/README.md +++ b/cmd/thv-operator/README.md @@ -129,6 +129,10 @@ helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive- helm upgrade -i oci://ghcr.io/stacklok/toolhive/toolhive-operator --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 diff --git a/deploy/charts/operator-crds/README.md b/deploy/charts/operator-crds/README.md index 29440e9bf5..6b42b1ade6 100644 --- a/deploy/charts/operator-crds/README.md +++ b/deploy/charts/operator-crds/README.md @@ -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. + diff --git a/deploy/charts/operator-crds/README.md.gotmpl b/deploy/charts/operator-crds/README.md.gotmpl index 4239f894d7..0c3a333605 100644 --- a/deploy/charts/operator-crds/README.md.gotmpl +++ b/deploy/charts/operator-crds/README.md.gotmpl @@ -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. + diff --git a/deploy/charts/operator/README.md b/deploy/charts/operator/README.md index 1c99996229..d6a8c47487 100644 --- a/deploy/charts/operator/README.md +++ b/deploy/charts/operator/README.md @@ -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. + diff --git a/deploy/charts/operator/README.md.gotmpl b/deploy/charts/operator/README.md.gotmpl index fed616e595..de8d55cbc9 100644 --- a/deploy/charts/operator/README.md.gotmpl +++ b/deploy/charts/operator/README.md.gotmpl @@ -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. + diff --git a/docs/README.md b/docs/README.md index ae11753018..3a2ee6e7d0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/observability.md b/docs/observability.md index 3a11cd3d48..79dcc0dc69 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -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). diff --git a/test/e2e/README.md b/test/e2e/README.md index a03c68e8da..03867c3995 100644 --- a/test/e2e/README.md +++ b/test/e2e/README.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: