diff --git a/docs/toolhive/reference/cli/thv.md b/docs/toolhive/reference/cli/thv.md index 60b33bc2..eb8ca4e3 100644 --- a/docs/toolhive/reference/cli/thv.md +++ b/docs/toolhive/reference/cli/thv.md @@ -18,7 +18,7 @@ ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers ToolHive (thv) is a lightweight, secure, and fast manager for MCP (Model Context Protocol) servers. It is written in Go and has extensive test coverage—including input validation—to ensure reliability and security. -Under the hood, ToolHive acts as a very thin client for the Docker/Podman Unix socket API. +Under the hood, ToolHive acts as a very thin client for the Docker/Podman/Colima Unix socket API. This design choice allows it to remain both efficient and lightweight while still providing powerful, container-based isolation for running MCP servers. @@ -47,12 +47,12 @@ thv [flags] * [thv proxy](thv_proxy.md) - Create a transparent proxy for an MCP server with authentication support * [thv registry](thv_registry.md) - Manage MCP server registry * [thv restart](thv_restart.md) - Restart a tooling server -* [thv rm](thv_rm.md) - Remove an MCP server +* [thv rm](thv_rm.md) - Remove one or more MCP servers * [thv run](thv_run.md) - Run an MCP server * [thv runtime](thv_runtime.md) - Commands related to the container runtime * [thv search](thv_search.md) - Search for MCP servers * [thv secret](thv_secret.md) - Manage secrets * [thv serve](thv_serve.md) - Start the ToolHive API server -* [thv stop](thv_stop.md) - Stop an MCP server +* [thv stop](thv_stop.md) - Stop one or more MCP servers * [thv version](thv_version.md) - Show the version of ToolHive diff --git a/docs/toolhive/reference/cli/thv_rm.md b/docs/toolhive/reference/cli/thv_rm.md index ceefd84c..3ec7b59a 100644 --- a/docs/toolhive/reference/cli/thv_rm.md +++ b/docs/toolhive/reference/cli/thv_rm.md @@ -11,19 +11,20 @@ mdx: ## thv rm -Remove an MCP server +Remove one or more MCP servers ### Synopsis -Remove an MCP server managed by ToolHive. +Remove one or more MCP servers managed by ToolHive. ``` -thv rm [workload-name] [flags] +thv rm [workload-name...] [flags] ``` ### Options ``` + --all Delete all workloads --group string Delete all workloads in the specified group -h, --help help for rm ``` diff --git a/docs/toolhive/reference/cli/thv_run.md b/docs/toolhive/reference/cli/thv_run.md index 6d9e5428..981e07f2 100644 --- a/docs/toolhive/reference/cli/thv_run.md +++ b/docs/toolhive/reference/cli/thv_run.md @@ -107,10 +107,10 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...] --otel-env-vars stringArray Environment variable names to include in OpenTelemetry spans (comma-separated: ENV1,ENV2) --otel-headers stringArray OpenTelemetry OTLP headers in key=value format (e.g., x-honeycomb-team=your-api-key) --otel-insecure Connect to the OpenTelemetry endpoint using HTTP instead of HTTPS - --otel-metrics-enabled Enable OTLP metrics export (when OTLP endpoint is configured) + --otel-metrics-enabled Enable OTLP metrics export (when OTLP endpoint is configured) (default true) --otel-sampling-rate float OpenTelemetry trace sampling rate (0.0-1.0) (default 0.1) --otel-service-name string OpenTelemetry service name (defaults to toolhive-mcp-proxy) - --otel-tracing-enabled Enable distributed tracing (when OTLP endpoint is configured) + --otel-tracing-enabled Enable distributed tracing (when OTLP endpoint is configured) (default true) --permission-profile string Permission profile to use (none, network, or path to JSON file) --print-resolved-overlays Debug: show resolved container paths for tmpfs overlays --proxy-mode string Proxy mode for stdio transport (sse or streamable-http) (default "sse") @@ -132,6 +132,7 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...] --target-port int Port for the container to expose (only applicable to SSE or Streamable HTTP transport) --thv-ca-bundle string Path to CA certificate bundle for ToolHive HTTP operations (JWKS, OIDC discovery, etc.) --tools stringArray Filter MCP server tools (comma-separated list of tool names) + --tools-override string Path to a JSON file containing overrides for MCP server tools names and descriptions --transport string Transport mode (sse, streamable-http or stdio) -v, --volume stringArray Mount a volume into the container (format: host-path:container-path[:ro]) ``` diff --git a/docs/toolhive/reference/cli/thv_stop.md b/docs/toolhive/reference/cli/thv_stop.md index 7345648a..050f318c 100644 --- a/docs/toolhive/reference/cli/thv_stop.md +++ b/docs/toolhive/reference/cli/thv_stop.md @@ -11,14 +11,14 @@ mdx: ## thv stop -Stop an MCP server +Stop one or more MCP servers ### Synopsis -Stop a running MCP server managed by ToolHive. +Stop one or more running MCP servers managed by ToolHive. ``` -thv stop [workload-name] [flags] +thv stop [workload-name...] [flags] ``` ### Options diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml index be9e0f43..fdb044d1 100644 --- a/static/api-specs/toolhive-api.yaml +++ b/static/api-specs/toolhive-api.yaml @@ -194,6 +194,9 @@ components: Port is the port on which the workload is exposed. This is embedded in the URL. type: integer + proxy_mode: + description: ProxyMode is the proxy mode for stdio transport (sse or streamable-http). + type: string remote: description: Remote indicates whether this is a remote workload (true) or a container workload (false). @@ -326,6 +329,29 @@ components: If true, the value will be stored as a secret rather than as a plain environment variable type: boolean type: object + registry.Group: + properties: + description: + description: Description is a human-readable description of the group's + purpose and functionality + type: string + name: + description: Name is the identifier for the group, used when referencing + the group in commands + type: string + remote_servers: + additionalProperties: + $ref: '#/components/schemas/registry.RemoteServerMetadata' + description: RemoteServers is a map of server names to their corresponding + remote server definitions within this group + type: object + servers: + additionalProperties: + $ref: '#/components/schemas/registry.ImageMetadata' + description: Servers is a map of server names to their corresponding server + definitions within this group + type: object + type: object registry.Header: properties: choices: @@ -527,6 +553,13 @@ components: registry.Registry: description: Full registry data properties: + groups: + description: Groups is a slice of group definitions containing related MCP + servers + items: + $ref: '#/components/schemas/registry.Group' + type: array + uniqueItems: false last_updated: description: LastUpdated is the timestamp when the registry was last updated, in RFC3339 format @@ -785,24 +818,18 @@ components: description: ThvCABundle is the path to the CA certificate bundle for ToolHive HTTP operations type: string - tool_override: - additionalProperties: - $ref: '#/components/schemas/runner.ToolOverride' - description: |- - ToolOverride is the map of tool names to override. Tools to override are - specified as ToolOverride structs. - type: object - tool_override_file: - description: |- - ToolOverrideFile is the path to a file containing tool overrides. - The file is a JSON struct mapping actual names to ToolOverride structs. - type: string tools_filter: description: ToolsFilter is the list of tools to filter items: type: string type: array uniqueItems: false + tools_override: + additionalProperties: + $ref: '#/components/schemas/runner.ToolOverride' + description: ToolsOverride is a map from an actual tool to its overridden + name and/or description + type: object transport: description: Transport is the transport mode (stdio, sse, or streamable-http) type: string @@ -869,6 +896,7 @@ components: items: type: string type: array + uniqueItems: false headers: additionalProperties: type: string @@ -1137,6 +1165,11 @@ components: type: string type: array uniqueItems: false + tools_override: + additionalProperties: + $ref: '#/components/schemas/v1.toolOverride' + description: Tools override + type: object transport: description: Transport configuration type: string @@ -1413,6 +1446,16 @@ components: description: Type of the secrets provider that was setup type: string type: object + v1.toolOverride: + description: Tool override + properties: + description: + description: Description of the tool + type: string + name: + description: Name of the tool + type: string + type: object v1.updateRequest: description: Request to update an existing workload (name cannot be changed) properties: @@ -1472,6 +1515,11 @@ components: type: string type: array uniqueItems: false + tools_override: + additionalProperties: + $ref: '#/components/schemas/v1.toolOverride' + description: Tools override + type: object transport: description: Transport configuration type: string diff --git a/static/api-specs/toolhive-registry-schema.json b/static/api-specs/toolhive-registry-schema.json index 0b6e2a8d..31390498 100644 --- a/static/api-specs/toolhive-registry-schema.json +++ b/static/api-specs/toolhive-registry-schema.json @@ -31,6 +31,13 @@ }, "additionalProperties": false }, + "groups": { + "type": "array", + "description": "Collection of group definitions containing related MCP servers", + "items": { + "$ref": "#/definitions/group" + } + }, "version": { "type": "string", "description": "Registry schema version", @@ -546,6 +553,47 @@ } }, "additionalProperties": false + }, + "group": { + "type": "object", + "description": "Group definition containing related MCP servers that can be deployed together", + "required": ["name", "description"], + "properties": { + "name": { + "type": "string", + "description": "Identifier for the group, used when referencing the group in commands", + "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "description": "Human-readable description of the group's purpose and functionality", + "minLength": 10, + "maxLength": 500 + }, + "servers": { + "type": "object", + "description": "Collection of MCP server entries within this group indexed by server name", + "patternProperties": { + "^[a-z0-9][a-z0-9-]+[a-z0-9]$": { + "$ref": "#/definitions/server" + } + }, + "additionalProperties": false + }, + "remote_servers": { + "type": "object", + "description": "Collection of remote MCP server entries within this group indexed by server name", + "patternProperties": { + "^[a-z0-9][a-z0-9-]+[a-z0-9]$": { + "$ref": "#/definitions/remote_server" + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false } } }