diff --git a/docs/toolhive/reference/cli/thv.md b/docs/toolhive/reference/cli/thv.md index f630f869..dc043452 100644 --- a/docs/toolhive/reference/cli/thv.md +++ b/docs/toolhive/reference/cli/thv.md @@ -53,6 +53,7 @@ thv [flags] * [thv secret](thv_secret.md) - Manage secrets * [thv serve](thv_serve.md) - Start the ToolHive API server * [thv start](thv_start.md) - Start (resume) a tooling server +* [thv status](thv_status.md) - Show detailed status of 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_build.md b/docs/toolhive/reference/cli/thv_build.md index 23dfd87b..90b23bf4 100644 --- a/docs/toolhive/reference/cli/thv_build.md +++ b/docs/toolhive/reference/cli/thv_build.md @@ -53,10 +53,10 @@ thv build [flags] PROTOCOL [-- ARGS...] ### Options ``` - --dry-run Generate Dockerfile without building (stdout output unless -o is set) + --dry-run Generate Dockerfile without building (stdout output unless -o is set) (default false) -h, --help help for build - -o, --output string Write the Dockerfile to the specified file instead of building - -t, --tag string Name and optionally a tag in the 'name:tag' format for the built image + -o, --output string Write the Dockerfile to the specified file instead of building (default builds an image instead of generating a Dockerfile) + -t, --tag string Name and optionally a tag in the 'name:tag' format for the built image (default generates a unique image name based on the package and transport type) ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/cli/thv_config_get-build-auth-file.md b/docs/toolhive/reference/cli/thv_config_get-build-auth-file.md index 7c72d8db..978776c3 100644 --- a/docs/toolhive/reference/cli/thv_config_get-build-auth-file.md +++ b/docs/toolhive/reference/cli/thv_config_get-build-auth-file.md @@ -35,7 +35,7 @@ thv config get-build-auth-file [name] [flags] ``` -h, --help help for get-build-auth-file - --show-content Show the actual file content (contains credentials) + --show-content Show the actual file content (contains credentials) (default false) ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/cli/thv_config_set-build-auth-file.md b/docs/toolhive/reference/cli/thv_config_set-build-auth-file.md index 287eb15a..0165a978 100644 --- a/docs/toolhive/reference/cli/thv_config_set-build-auth-file.md +++ b/docs/toolhive/reference/cli/thv_config_set-build-auth-file.md @@ -48,7 +48,7 @@ thv config set-build-auth-file [content] [flags] ``` -h, --help help for set-build-auth-file - --stdin Read file content from stdin instead of command line argument + --stdin Read file content from stdin instead of command line argument (default false) ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/cli/thv_config_set-registry.md b/docs/toolhive/reference/cli/thv_config_set-registry.md index 0a6725be..c25292c9 100644 --- a/docs/toolhive/reference/cli/thv_config_set-registry.md +++ b/docs/toolhive/reference/cli/thv_config_set-registry.md @@ -34,7 +34,7 @@ thv config set-registry [flags] ### Options ``` - -p, --allow-private-ip Allow setting the registry URL or API endpoint, even if it references a private IP address + -p, --allow-private-ip Allow setting the registry URL or API endpoint, even if it references a private IP address (default false) -h, --help help for set-registry ``` diff --git a/docs/toolhive/reference/cli/thv_group_rm.md b/docs/toolhive/reference/cli/thv_group_rm.md index dededfe3..42cac4b8 100644 --- a/docs/toolhive/reference/cli/thv_group_rm.md +++ b/docs/toolhive/reference/cli/thv_group_rm.md @@ -25,7 +25,7 @@ thv group rm [group-name] [flags] ``` -h, --help help for rm - --with-workloads Delete all workloads in the group along with the group + --with-workloads Delete all workloads in the group along with the group (default false) ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/cli/thv_logs.md b/docs/toolhive/reference/cli/thv_logs.md index a055299a..e3503bb2 100644 --- a/docs/toolhive/reference/cli/thv_logs.md +++ b/docs/toolhive/reference/cli/thv_logs.md @@ -40,9 +40,9 @@ thv logs [workload-name|prune] [flags] ### Options ``` - -f, --follow Follow log output (only for workload logs) + -f, --follow Follow log output (only for workload logs) (default false) -h, --help help for logs - -p, --proxy Show proxy logs instead of container logs + -p, --proxy Show proxy logs instead of container logs (default false) ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/cli/thv_proxy.md b/docs/toolhive/reference/cli/thv_proxy.md index d7385e6e..20c1216c 100644 --- a/docs/toolhive/reference/cli/thv_proxy.md +++ b/docs/toolhive/reference/cli/thv_proxy.md @@ -107,18 +107,18 @@ thv proxy [flags] SERVER_NAME --oidc-jwks-url string URL to fetch the JWKS from --oidc-scopes strings OAuth scopes to advertise in the well-known endpoint (RFC 9728, defaults to 'openid' if not specified) --port int Port for the HTTP proxy to listen on (host port) - --remote-auth Enable OAuth/OIDC authentication to remote MCP server + --remote-auth Enable OAuth/OIDC authentication to remote MCP server (default false) --remote-auth-authorize-url string OAuth authorization endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth) --remote-auth-bearer-token string Bearer token for remote server authentication (alternative to OAuth) --remote-auth-bearer-token-file string Path to file containing bearer token (alternative to --remote-auth-bearer-token) --remote-auth-callback-port int Port for OAuth callback server during remote authentication (default 8666) - --remote-auth-client-id string OAuth client ID for remote server authentication - --remote-auth-client-secret string OAuth client secret for remote server authentication (optional for PKCE) - --remote-auth-client-secret-file string Path to file containing OAuth client secret (alternative to --remote-auth-client-secret) + --remote-auth-client-id string OAuth client ID for remote server authentication (optional if the authorization server supports dynamic client registration (RFC 7591)) + --remote-auth-client-secret string OAuth client secret for remote server authentication (optional if the authorization server supports dynamic client registration (RFC 7591) or if using PKCE) + --remote-auth-client-secret-file string Path to file containing OAuth client secret (alternative to --remote-auth-client-secret) (optional if the authorization server supports dynamic client registration (RFC 7591) or if using PKCE) --remote-auth-issuer string OAuth/OIDC issuer URL for remote server authentication (e.g., https://accounts.google.com) --remote-auth-resource string OAuth 2.0 resource indicator (RFC 8707) --remote-auth-scopes strings OAuth scopes to request for remote server authentication (defaults: OIDC uses 'openid,profile,email') - --remote-auth-skip-browser Skip opening browser for remote server OAuth flow + --remote-auth-skip-browser Skip opening browser for remote server OAuth flow (default false) --remote-auth-timeout duration Timeout for OAuth authentication flow (e.g., 30s, 1m, 2m30s) (default 30s) --remote-auth-token-url string OAuth token endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth) --resource-url string Explicit resource URL for OAuth discovery endpoint (RFC 9728) diff --git a/docs/toolhive/reference/cli/thv_run.md b/docs/toolhive/reference/cli/thv_run.md index 42840dce..c13ade28 100644 --- a/docs/toolhive/reference/cli/thv_run.md +++ b/docs/toolhive/reference/cli/thv_run.md @@ -114,58 +114,58 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...] --audit-config string Path to the audit configuration file --authz-config string Path to the authorization configuration file --ca-cert string Path to a custom CA certificate file to use for container builds - --enable-audit Enable audit logging with default configuration + --enable-audit Enable audit logging with default configuration (default false) --endpoint-prefix string Path prefix to prepend to SSE endpoint URLs (e.g., /playwright) -e, --env stringArray Environment variables to pass to the MCP server (format: KEY=VALUE) --env-file string Load environment variables from a single file --env-file-dir string Load environment variables from all files in a directory - -f, --foreground Run in foreground mode (block until container exits) + -f, --foreground Run in foreground mode (block until container exits) (default false) --from-config string Load configuration from exported file - --group string Name of the group this workload belongs to (defaults to 'default' if not specified) (default "default") + --group string Name of the group this workload should belong to (default "default") -h, --help help for run --host string Host for the HTTP proxy to listen on (IP or hostname) (default "127.0.0.1") --ignore-globally Load global ignore patterns from ~/.config/toolhive/thvignore (default true) --image-verification string Set image verification mode (warn, enabled, disabled) (default "warn") - --isolate-network Isolate the container network from the host (default: false) - --jwks-allow-private-ip Allow JWKS/OIDC endpoints on private IP addresses (use with caution) + --isolate-network Isolate the container network from the host (default false) + --jwks-allow-private-ip Allow JWKS/OIDC endpoints on private IP addresses (use with caution) (default false) --jwks-auth-token-file string Path to file containing bearer token for authenticating JWKS/OIDC requests -l, --label stringArray Set labels on the container (format: key=value) - --name string Name of the MCP server (auto-generated from image if not provided) + --name string Name of the MCP server (default to auto-generated from image) --network string Connect the container to a network (e.g., 'host' for host networking) --oidc-audience string Expected audience for the token --oidc-client-id string OIDC client ID --oidc-client-secret string OIDC client secret (optional, for introspection) - --oidc-insecure-allow-http Allow HTTP (non-HTTPS) OIDC issuers for local development/testing (WARNING: Insecure!) + --oidc-insecure-allow-http Allow HTTP (non-HTTPS) OIDC issuers for local development/testing (WARNING: Insecure!) (default false) --oidc-introspection-url string URL for token introspection endpoint --oidc-issuer string OIDC issuer URL (e.g., https://accounts.google.com) --oidc-jwks-url string URL to fetch the JWKS from --oidc-scopes strings OAuth scopes to advertise in the well-known endpoint (RFC 9728, defaults to 'openid' if not specified) --otel-custom-attributes string Custom resource attributes for OpenTelemetry in key=value format (e.g., server_type=prod,region=us-east-1,team=platform) - --otel-enable-prometheus-metrics-path Enable Prometheus-style /metrics endpoint on the main transport port + --otel-enable-prometheus-metrics-path Enable Prometheus-style /metrics endpoint on the main transport port (default false) --otel-endpoint string OpenTelemetry OTLP endpoint URL (e.g., https://api.honeycomb.io) --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-insecure Connect to the OpenTelemetry endpoint using HTTP instead of HTTPS (default false) --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) (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 + --permission-profile string Permission profile to use (none, network, or path to JSON file) (default is to use the permission profile from the registry or "network" if not part of the registry) + --print-resolved-overlays Debug: show resolved container paths for tmpfs overlays (default false) --proxy-mode string Proxy mode for stdio (streamable-http or sse (deprecated, will be removed)) (default "streamable-http") --proxy-port int Port for the HTTP proxy to listen on (host port) - --remote-auth Enable OAuth/OIDC authentication to remote MCP server + --remote-auth Enable OAuth/OIDC authentication to remote MCP server (default false) --remote-auth-authorize-url string OAuth authorization endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth) --remote-auth-bearer-token string Bearer token for remote server authentication (alternative to OAuth) --remote-auth-bearer-token-file string Path to file containing bearer token (alternative to --remote-auth-bearer-token) --remote-auth-callback-port int Port for OAuth callback server during remote authentication (default 8666) - --remote-auth-client-id string OAuth client ID for remote server authentication - --remote-auth-client-secret string OAuth client secret for remote server authentication (optional for PKCE) - --remote-auth-client-secret-file string Path to file containing OAuth client secret (alternative to --remote-auth-client-secret) + --remote-auth-client-id string OAuth client ID for remote server authentication (optional if the authorization server supports dynamic client registration (RFC 7591)) + --remote-auth-client-secret string OAuth client secret for remote server authentication (optional if the authorization server supports dynamic client registration (RFC 7591) or if using PKCE) + --remote-auth-client-secret-file string Path to file containing OAuth client secret (alternative to --remote-auth-client-secret) (optional if the authorization server supports dynamic client registration (RFC 7591) or if using PKCE) --remote-auth-issuer string OAuth/OIDC issuer URL for remote server authentication (e.g., https://accounts.google.com) --remote-auth-resource string OAuth 2.0 resource indicator (RFC 8707) --remote-auth-scopes strings OAuth scopes to request for remote server authentication (defaults: OIDC uses 'openid,profile,email') - --remote-auth-skip-browser Skip opening browser for remote server OAuth flow + --remote-auth-skip-browser Skip opening browser for remote server OAuth flow (default false) --remote-auth-timeout duration Timeout for OAuth authentication flow (e.g., 30s, 1m, 2m30s) (default 30s) --remote-auth-token-url string OAuth token endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth) --resource-url string Explicit resource URL for OAuth discovery endpoint (RFC 9728) @@ -184,7 +184,7 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...] --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) - --trust-proxy-headers Trust X-Forwarded-* headers from reverse proxies (X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Prefix) + --trust-proxy-headers Trust X-Forwarded-* headers from reverse proxies (X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Prefix) (default false) -v, --volume stringArray Mount a volume into the container (format: host-path:container-path[:ro]) ``` diff --git a/docs/toolhive/reference/cli/thv_secret_provider.md b/docs/toolhive/reference/cli/thv_secret_provider.md index 868617ca..e4ea85a6 100644 --- a/docs/toolhive/reference/cli/thv_secret_provider.md +++ b/docs/toolhive/reference/cli/thv_secret_provider.md @@ -22,10 +22,10 @@ Note: The "thv secret setup" command is recommended for interactive configuratio Use this command to set the secrets provider directly without interactive prompts, making it suitable for scripted deployments and automation. -Valid secrets providers: - - encrypted: Full read-write secrets provider using AES-256-GCM encryption - - 1password: Read-only secrets provider (requires OP_SERVICE_ACCOUNT_TOKEN) - - none: Disables secrets functionality + Valid secrets providers: + - encrypted: Full read-write secrets provider using AES-256-GCM encryption + - 1password: Read-only secrets provider (requires OP_SERVICE_ACCOUNT_TOKEN) + - environment: Read-only secrets provider from TOOLHIVE_SECRET_* env vars ``` thv secret provider [flags] diff --git a/docs/toolhive/reference/cli/thv_secret_setup.md b/docs/toolhive/reference/cli/thv_secret_setup.md index b51fc81d..fab40515 100644 --- a/docs/toolhive/reference/cli/thv_secret_setup.md +++ b/docs/toolhive/reference/cli/thv_secret_setup.md @@ -21,10 +21,10 @@ This command guides you through selecting and configuring a secrets provider for storing and retrieving secrets. The setup process validates your configuration and ensures the selected provider initializes properly. -Available providers: - - encrypted: Stores secrets in an encrypted file using AES-256-GCM using the OS keyring - - 1password: Read-only access to 1Password secrets (requires OP_SERVICE_ACCOUNT_TOKEN environment variable) - - none: Disables secrets functionality + Available providers: + - encrypted: Stores secrets in an encrypted file using AES-256-GCM using the OS keyring + - 1password: Read-only access to 1Password secrets (requires OP_SERVICE_ACCOUNT_TOKEN environment variable) + - environment: Read-only access to secrets from TOOLHIVE_SECRET_* env vars Run this command before using any other secrets functionality. diff --git a/docs/toolhive/reference/cli/thv_start.md b/docs/toolhive/reference/cli/thv_start.md index 848eeb4c..70d58926 100644 --- a/docs/toolhive/reference/cli/thv_start.md +++ b/docs/toolhive/reference/cli/thv_start.md @@ -28,7 +28,7 @@ thv start [workload-name] [flags] ``` -a, --all Restart all MCP servers - -f, --foreground Run the restarted workload in foreground mode + -f, --foreground Run the restarted workload in foreground mode (default false) -g, --group string Filter by group -h, --help help for start ``` diff --git a/docs/toolhive/reference/cli/thv_status.md b/docs/toolhive/reference/cli/thv_status.md new file mode 100644 index 00000000..84575ca3 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_status.md @@ -0,0 +1,40 @@ +--- +title: thv status +hide_title: true +description: Reference for ToolHive CLI command `thv status` +last_update: + author: autogenerated +slug: thv_status +mdx: + format: md +--- + +## thv status + +Show detailed status of an MCP server + +### Synopsis + +Display detailed status information for a specific MCP server managed by ToolHive. + +``` +thv status [workload-name] [flags] +``` + +### Options + +``` + --format string Output format (json or text) (default "text") + -h, --help help for status +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv](thv.md) - ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers + diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml index 7c30be0a..0d0c1932 100644 --- a/static/api-specs/toolhive-api.yaml +++ b/static/api-specs/toolhive-api.yaml @@ -231,6 +231,10 @@ components: description: Remote indicates whether this is a remote workload (true) or a container workload (false). type: boolean + started_at: + description: StartedAt is when the container was last started (changes on + restart) + type: string status: $ref: '#/components/schemas/runtime.WorkloadStatus' status_context: @@ -437,6 +441,14 @@ components: type: string type: array uniqueItems: false + custom_metadata: + additionalProperties: {} + description: CustomMetadata allows for additional user-defined metadata + type: object + description: + description: Description is a human-readable description of the server's + purpose and functionality + type: string docker_tags: description: DockerTags lists the available Docker tags for this server image @@ -454,14 +466,73 @@ components: image: description: Image is the Docker image reference for the MCP server type: string + metadata: + $ref: '#/components/schemas/registry.Metadata' + name: + description: |- + Name is the identifier for the MCP server, used when referencing the server in commands + If not provided, it will be auto-generated from the registry key + type: string permissions: $ref: '#/components/schemas/permissions.Profile' provenance: $ref: '#/components/schemas/registry.Provenance' + proxy_port: + description: |- + ProxyPort is the port for the HTTP proxy to listen on (host port) + If not specified, a random available port will be assigned + type: integer + repository_url: + description: RepositoryURL is the URL to the source code repository for + the server + type: string + status: + description: Status indicates whether the server is currently active or + deprecated + type: string + tags: + description: Tags are categorization labels for the server to aid in discovery + and filtering + items: + type: string + type: array + uniqueItems: false target_port: description: TargetPort is the port for the container to expose (only applicable to SSE and Streamable HTTP transports) type: integer + tier: + description: Tier represents the tier classification level of the server, + e.g., "Official" or "Community" + type: string + tools: + description: Tools is a list of tool names provided by this MCP server + items: + type: string + type: array + uniqueItems: false + transport: + description: |- + Transport defines the communication protocol for the server + For containers: stdio, sse, or streamable-http + For remote servers: sse or streamable-http (stdio not supported) + type: string + type: object + registry.Metadata: + description: Metadata contains additional information about the server such + as popularity metrics + properties: + last_updated: + description: LastUpdated is the timestamp when the server was last updated, + in RFC3339 format + type: string + pulls: + description: Pulls indicates how many times the server image has been downloaded + type: integer + stars: + description: Stars represents the popularity rating or number of stars for + the server + type: integer type: object registry.OAuthConfig: description: |- @@ -567,6 +638,14 @@ components: registry.RemoteServerMetadata: description: Remote server details (if it's a remote server) properties: + custom_metadata: + additionalProperties: {} + description: CustomMetadata allows for additional user-defined metadata + type: object + description: + description: Description is a human-readable description of the server's + purpose and functionality + type: string env_vars: description: |- EnvVars defines environment variables that can be passed to configure the client @@ -583,8 +662,46 @@ components: $ref: '#/components/schemas/registry.Header' type: array uniqueItems: false + metadata: + $ref: '#/components/schemas/registry.Metadata' + name: + description: |- + Name is the identifier for the MCP server, used when referencing the server in commands + If not provided, it will be auto-generated from the registry key + type: string oauth_config: $ref: '#/components/schemas/registry.OAuthConfig' + repository_url: + description: RepositoryURL is the URL to the source code repository for + the server + type: string + status: + description: Status indicates whether the server is currently active or + deprecated + type: string + tags: + description: Tags are categorization labels for the server to aid in discovery + and filtering + items: + type: string + type: array + uniqueItems: false + tier: + description: Tier represents the tier classification level of the server, + e.g., "Official" or "Community" + type: string + tools: + description: Tools is a list of tool names provided by this MCP server + items: + type: string + type: array + uniqueItems: false + transport: + description: |- + Transport defines the communication protocol for the server + For containers: stdio, sse, or streamable-http + For remote servers: sse or streamable-http (stdio not supported) + type: string url: description: URL is the endpoint URL for the remote MCP server (e.g., https://api.example.com/mcp) type: string @@ -1465,7 +1582,7 @@ components: TODO Review environment variable for this type: string provider_type: - description: Type of the secrets provider (encrypted, 1password, none) + description: Type of the secrets provider (encrypted, 1password, environment) type: string type: object v1.setupSecretsResponse: @@ -2557,7 +2674,8 @@ paths: - workloads /api/v1beta/workloads/{name}/logs: get: - description: Retrieve at most 100 lines of logs for a specific workload by name. + description: Retrieve at most 1000 lines of logs for a specific workload by + name. parameters: - description: Workload name in: path @@ -2589,8 +2707,8 @@ paths: - logs /api/v1beta/workloads/{name}/proxy-logs: get: - description: Retrieve proxy logs for a specific workload by name from the file - system. + description: Retrieve at most 1000 lines of proxy logs for a specific workload + by name from the file system. parameters: - description: Workload name in: path diff --git a/static/api-specs/toolhive-legacy-registry.schema.json b/static/api-specs/toolhive-legacy-registry.schema.json index 341076cc..10fe6eae 100644 --- a/static/api-specs/toolhive-legacy-registry.schema.json +++ b/static/api-specs/toolhive-legacy-registry.schema.json @@ -144,6 +144,12 @@ "minimum": 1, "maximum": 65535 }, + "proxy_port": { + "type": "integer", + "description": "Port for the HTTP proxy to listen on (host port). If not specified, a random available port will be assigned", + "minimum": 1, + "maximum": 65535 + }, "tier": { "type": "string", "description": "Tier classification of the server, (Official or Community)",