diff --git a/static/api-specs/toolhive-crd-api.md b/static/api-specs/toolhive-crd-api.md index b4d6f99c..a8df4ecc 100644 --- a/static/api-specs/toolhive-crd-api.md +++ b/static/api-specs/toolhive-crd-api.md @@ -8,11 +8,29 @@ Package v1alpha1 contains API Schema definitions for the toolhive v1alpha1 API group ### Resource Types +- [MCPRegistry](#mcpregistry) +- [MCPRegistryList](#mcpregistrylist) - [MCPServer](#mcpserver) - [MCPServerList](#mcpserverlist) +#### AuditConfig + + + +AuditConfig defines audit logging configuration for the MCP server + + + +_Appears in:_ +- [MCPServerSpec](#mcpserverspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `enabled` _boolean_ | Enabled controls whether audit logging is enabled
When true, enables audit logging with default configuration | false | | + + #### AuthzConfigRef @@ -65,6 +83,23 @@ _Appears in:_ | `key` _string_ | Key is the key in the ConfigMap that contains the OIDC configuration | oidc.json | | +#### ConfigMapSource + + + +ConfigMapSource defines ConfigMap source configuration + + + +_Appears in:_ +- [MCPRegistrySource](#mcpregistrysource) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name is the name of the ConfigMap | | MinLength: 1
Required: \{\}
| +| `key` _string_ | Key is the key in the ConfigMap that contains the registry data | registry.json | MinLength: 1
| + + #### EnvVar @@ -146,6 +181,132 @@ _Appears in:_ | `useClusterAuth` _boolean_ | UseClusterAuth enables using the Kubernetes cluster's CA bundle and service account token
When true, uses /var/run/secrets/kubernetes.io/serviceaccount/ca.crt for TLS verification
and /var/run/secrets/kubernetes.io/serviceaccount/token for bearer token authentication
Defaults to true if not specified | | | +#### MCPRegistry + + + +MCPRegistry is the Schema for the mcpregistries API +⚠️ Experimental API (v1alpha1) — subject to change. + + + +_Appears in:_ +- [MCPRegistryList](#mcpregistrylist) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `toolhive.stacklok.dev/v1alpha1` | | | +| `kind` _string_ | `MCPRegistry` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[MCPRegistrySpec](#mcpregistryspec)_ | | | | +| `status` _[MCPRegistryStatus](#mcpregistrystatus)_ | | | | + + +#### MCPRegistryList + + + +MCPRegistryList contains a list of MCPRegistry + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `toolhive.stacklok.dev/v1alpha1` | | | +| `kind` _string_ | `MCPRegistryList` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `items` _[MCPRegistry](#mcpregistry) array_ | | | | + + +#### MCPRegistryPhase + +_Underlying type:_ _string_ + +MCPRegistryPhase represents the phase of the MCPRegistry + +_Validation:_ +- Enum: [Pending Ready Failed Syncing Terminating] + +_Appears in:_ +- [MCPRegistryStatus](#mcpregistrystatus) + +| Field | Description | +| --- | --- | +| `Pending` | MCPRegistryPhasePending means the MCPRegistry is being initialized
| +| `Ready` | MCPRegistryPhaseReady means the MCPRegistry is ready and operational
| +| `Failed` | MCPRegistryPhaseFailed means the MCPRegistry has failed
| +| `Syncing` | MCPRegistryPhaseSyncing means the MCPRegistry is currently syncing data
| +| `Terminating` | MCPRegistryPhaseTerminating means the MCPRegistry is being deleted
| + + +#### MCPRegistrySource + + + +MCPRegistrySource defines the source configuration for registry data + + + +_Appears in:_ +- [MCPRegistrySpec](#mcpregistryspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _string_ | Type is the type of source (configmap) | configmap | Enum: [configmap]
| +| `format` _string_ | Format is the data format (toolhive, upstream) | toolhive | Enum: [toolhive upstream]
| +| `configmap` _[ConfigMapSource](#configmapsource)_ | ConfigMap defines the ConfigMap source configuration
Only used when Type is "configmap" | | | + + +#### MCPRegistrySpec + + + +MCPRegistrySpec defines the desired state of MCPRegistry + + + +_Appears in:_ +- [MCPRegistry](#mcpregistry) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `displayName` _string_ | DisplayName is a human-readable name for the registry | | | +| `source` _[MCPRegistrySource](#mcpregistrysource)_ | Source defines the configuration for the registry data source | | Required: \{\}
| +| `syncPolicy` _[SyncPolicy](#syncpolicy)_ | SyncPolicy defines the automatic synchronization behavior for the registry.
If specified, enables automatic synchronization at the given interval.
Manual synchronization is always supported via annotation-based triggers
regardless of this setting. | | | +| `filter` _[RegistryFilter](#registryfilter)_ | Filter defines include/exclude patterns for registry content | | | + + +#### MCPRegistryStatus + + + +MCPRegistryStatus defines the observed state of MCPRegistry + + + +_Appears in:_ +- [MCPRegistry](#mcpregistry) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `phase` _[MCPRegistryPhase](#mcpregistryphase)_ | Phase represents the current phase of the MCPRegistry | | Enum: [Pending Ready Failed Syncing Terminating]
| +| `message` _string_ | Message provides additional information about the current phase | | | +| `lastSyncTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#time-v1-meta)_ | LastSyncTime is the timestamp of the last successful sync | | | +| `lastSyncHash` _string_ | LastSyncHash is the hash of the last successfully synced data
Used to detect changes in source data | | | +| `serverCount` _integer_ | ServerCount is the total number of servers in the registry | | Minimum: 0
| +| `deployedServerCount` _integer_ | DeployedServerCount is the number of deployed servers with matching labels | | Minimum: 0
| +| `syncAttempts` _integer_ | SyncAttempts is the number of sync attempts since last success | | Minimum: 0
| +| `apiEndpoint` _string_ | APIEndpoint is the URL of the registry API service | | | +| `storageRef` _[StorageReference](#storagereference)_ | StorageRef is a reference to the internal storage location | | | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#condition-v1-meta) array_ | Conditions represent the latest available observations of the MCPRegistry's state | | | + + #### MCPServer @@ -236,6 +397,7 @@ _Appears in:_ | `resourceOverrides` _[ResourceOverrides](#resourceoverrides)_ | ResourceOverrides allows overriding annotations and labels for resources created by the operator | | | | `oidcConfig` _[OIDCConfigRef](#oidcconfigref)_ | OIDCConfig defines OIDC authentication configuration for the MCP server | | | | `authzConfig` _[AuthzConfigRef](#authzconfigref)_ | AuthzConfig defines authorization policy configuration for the MCP server | | | +| `audit` _[AuditConfig](#auditconfig)_ | Audit defines audit logging configuration for the MCP server | | | | `tools` _string array_ | ToolsFilter is the filter on tools applied to the MCP server | | | | `telemetry` _[TelemetryConfig](#telemetryconfig)_ | Telemetry defines observability configuration for the MCP server | | | @@ -259,6 +421,23 @@ _Appears in:_ | `message` _string_ | Message provides additional information about the current phase | | | +#### NameFilter + + + +NameFilter defines name-based filtering + + + +_Appears in:_ +- [RegistryFilter](#registryfilter) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `include` _string array_ | Include is a list of glob patterns to include | | | +| `exclude` _string array_ | Exclude is a list of glob patterns to exclude | | | + + #### NetworkPermissions @@ -314,6 +493,7 @@ _Appears in:_ | `headers` _string array_ | Headers contains authentication headers for the OTLP endpoint
Specified as key=value pairs | | | | `insecure` _boolean_ | Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint | false | | | `metrics` _[OpenTelemetryMetricsConfig](#opentelemetrymetricsconfig)_ | Metrics defines OpenTelemetry metrics-specific configuration | | | +| `tracing` _[OpenTelemetryTracingConfig](#opentelemetrytracingconfig)_ | Tracing defines OpenTelemetry tracing configuration | | | #### OpenTelemetryMetricsConfig @@ -329,7 +509,24 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `enabled` _boolean_ | Enabled controls whether OTLP metrics are sent | true | | +| `enabled` _boolean_ | Enabled controls whether OTLP metrics are sent | false | | + + +#### OpenTelemetryTracingConfig + + + +OpenTelemetryTracingConfig defines OpenTelemetry tracing configuration + + + +_Appears in:_ +- [OpenTelemetryConfig](#opentelemetryconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `enabled` _boolean_ | Enabled controls whether OTLP tracing is sent | false | | +| `samplingRate` _string_ | SamplingRate is the trace sampling rate (0.0-1.0) | 0.05 | | #### OutboundNetworkPermissions @@ -405,6 +602,23 @@ _Appears in:_ | `env` _[EnvVar](#envvar) array_ | Env are environment variables to set in the proxy container (thv run process)
These affect the toolhive proxy itself, not the MCP server it manages | | | +#### RegistryFilter + + + +RegistryFilter defines include/exclude patterns for registry content + + + +_Appears in:_ +- [MCPRegistrySpec](#mcpregistryspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `names` _[NameFilter](#namefilter)_ | NameFilters defines name-based filtering | | | +| `tags` _[TagFilter](#tagfilter)_ | Tags defines tag-based filtering | | | + + #### ResourceList @@ -492,6 +706,59 @@ _Appears in:_ | `targetEnvName` _string_ | TargetEnvName is the environment variable to be used when setting up the secret in the MCP server
If left unspecified, it defaults to the key | | | +#### StorageReference + + + +StorageReference defines a reference to internal storage + + + +_Appears in:_ +- [MCPRegistryStatus](#mcpregistrystatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _string_ | Type is the storage type (configmap) | | Enum: [configmap]
| +| `configMapRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#localobjectreference-v1-core)_ | ConfigMapRef is a reference to a ConfigMap storage
Only used when Type is "configmap" | | | + + +#### SyncPolicy + + + +SyncPolicy defines automatic synchronization behavior. +When specified, enables automatic synchronization at the given interval. +Manual synchronization via annotation-based triggers is always available +regardless of this policy setting. + + + +_Appears in:_ +- [MCPRegistrySpec](#mcpregistryspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `interval` _string_ | Interval is the sync interval for automatic synchronization (Go duration format)
Examples: "1h", "30m", "24h" | | Pattern: `^([0-9]+(\.[0-9]+)?(ns\|us\|µs\|ms\|s\|m\|h))+$`
Required: \{\}
| + + +#### TagFilter + + + +TagFilter defines tag-based filtering + + + +_Appears in:_ +- [RegistryFilter](#registryfilter) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `include` _string array_ | Include is a list of tags to include | | | +| `exclude` _string array_ | Exclude is a list of tags to exclude | | | + + #### TelemetryConfig