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 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/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 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: