From 798b047d1a82d4abcb8f6b44eb1ceb4f62bc0205 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 8 Aug 2025 07:20:44 +0000 Subject: [PATCH] Update ToolHive reference docs for v0.2.5 --- docs/toolhive/reference/cli/thv_build.md | 6 +- docs/toolhive/reference/cli/thv_proxy.md | 19 +- docs/toolhive/reference/cli/thv_restart.md | 5 +- docs/toolhive/reference/cli/thv_run.md | 4 +- docs/toolhive/reference/cli/thv_serve.md | 21 +- static/api-specs/toolhive-api.yaml | 259 ++++++++++++++++----- 6 files changed, 233 insertions(+), 81 deletions(-) diff --git a/docs/toolhive/reference/cli/thv_build.md b/docs/toolhive/reference/cli/thv_build.md index a1fde7b..5316e77 100644 --- a/docs/toolhive/reference/cli/thv_build.md +++ b/docs/toolhive/reference/cli/thv_build.md @@ -44,8 +44,10 @@ thv build [flags] PROTOCOL ### Options ``` - -h, --help help for build - -t, --tag string Name and optionally a tag in the 'name:tag' format for the built image + --dry-run Generate Dockerfile without building (stdout output unless -o is set) + -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 ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/cli/thv_proxy.md b/docs/toolhive/reference/cli/thv_proxy.md index 2bd0d44..2f86c3a 100644 --- a/docs/toolhive/reference/cli/thv_proxy.md +++ b/docs/toolhive/reference/cli/thv_proxy.md @@ -48,13 +48,22 @@ Basic transparent proxy: thv proxy my-server --target-uri http://localhost:8080 -Proxy with OAuth authentication to remote server: +Proxy with OIDC authentication to remote server: thv proxy my-server --target-uri https://api.example.com \ --remote-auth --remote-auth-issuer https://auth.example.com \ --remote-auth-client-id my-client-id \ --remote-auth-client-secret-file /path/to/secret +Proxy with non-OIDC OAuth authentication to remote server: + + thv proxy my-server --target-uri https://api.example.com \ + --remote-auth \ + --remote-auth-authorize-url https://auth.example.com/oauth/authorize \ + --remote-auth-token-url https://auth.example.com/oauth/token \ + --remote-auth-client-id my-client-id \ + --remote-auth-client-secret-file /path/to/secret + Proxy with OIDC protection for incoming requests: thv proxy my-server --target-uri http://localhost:8080 \ @@ -77,19 +86,23 @@ thv proxy [flags] SERVER_NAME --host string Host for the HTTP proxy to listen on (IP or hostname) (default "127.0.0.1") --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-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-skip-opaque-token-validation Allow skipping validation of opaque tokens --port int Port for the HTTP proxy to listen on (host port) --remote-auth Enable OAuth authentication to remote MCP server + --remote-auth-authorize-url string OAuth authorization endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth) --remote-auth-callback-port int Port for OAuth callback server during remote authentication (default: 8666) (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-issuer string OAuth/OIDC issuer URL for remote server authentication (e.g., https://accounts.google.com) - --remote-auth-scopes strings OAuth scopes to request for remote server authentication (default [openid,profile,email]) + --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-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) --target-uri string URI for the target MCP server (e.g., http://localhost:8080) (required) ``` diff --git a/docs/toolhive/reference/cli/thv_restart.md b/docs/toolhive/reference/cli/thv_restart.md index c2c4280..332cb47 100644 --- a/docs/toolhive/reference/cli/thv_restart.md +++ b/docs/toolhive/reference/cli/thv_restart.md @@ -24,8 +24,9 @@ thv restart [workload-name] [flags] ### Options ``` - -a, --all Restart all MCP servers - -h, --help help for restart + -a, --all Restart all MCP servers + -f, --foreground Run the restarted workload in foreground mode + -h, --help help for restart ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/cli/thv_run.md b/docs/toolhive/reference/cli/thv_run.md index 89e1ece..49448e9 100644 --- a/docs/toolhive/reference/cli/thv_run.md +++ b/docs/toolhive/reference/cli/thv_run.md @@ -78,9 +78,10 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...] --name string Name of the MCP server (auto-generated from image if not provided) --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-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-skip-opaque-token-validation Allow skipping validation of opaque tokens --otel-enable-prometheus-metrics-path Enable Prometheus-style /metrics endpoint on the main transport port --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) @@ -92,6 +93,7 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...] --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") --proxy-port int Port for the HTTP proxy to listen on (host port) + --resource-url string Explicit resource URL for OAuth discovery endpoint (RFC 9728) --secret stringArray Specify a secret to be fetched from the secrets manager and set as an environment variable (format: NAME,target=TARGET) --target-host string Host to forward traffic to (only applicable to SSE or Streamable HTTP transport) (default "127.0.0.1") --target-port int Port for the container to expose (only applicable to SSE or Streamable HTTP transport) diff --git a/docs/toolhive/reference/cli/thv_serve.md b/docs/toolhive/reference/cli/thv_serve.md index ef0d525..cbdee01 100644 --- a/docs/toolhive/reference/cli/thv_serve.md +++ b/docs/toolhive/reference/cli/thv_serve.md @@ -24,16 +24,17 @@ thv serve [flags] ### Options ``` - -h, --help help for serve - --host string Host address to bind the server to (default "127.0.0.1") - --oidc-audience string Expected audience for the token - --oidc-client-id string OIDC client ID - --oidc-issuer string OIDC issuer URL (e.g., https://accounts.google.com) - --oidc-jwks-url string URL to fetch the JWKS from - --oidc-skip-opaque-token-validation Allow skipping validation of opaque tokens - --openapi Enable OpenAPI documentation endpoints (/api/openapi.json and /api/doc) - --port int Port to bind the server to (default 8080) - --socket string UNIX socket path to bind the server to (overrides host and port if provided) + -h, --help help for serve + --host string Host address to bind the server to (default "127.0.0.1") + --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-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 + --openapi Enable OpenAPI documentation endpoints (/api/openapi.json and /api/doc) + --port int Port to bind the server to (default 8080) + --socket string UNIX socket path to bind the server to (overrides host and port if provided) ``` ### Options inherited from parent commands diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml index 14acc2b..9345abc 100644 --- a/static/api-specs/toolhive-api.yaml +++ b/static/api-specs/toolhive-api.yaml @@ -41,10 +41,6 @@ components: auth.TokenValidatorConfig: description: OIDCConfig contains OIDC configuration properties: - allowOpaqueTokens: - description: AllowOpaqueTokens indicates whether to allow opaque tokens - (non-JWT) - type: boolean allowPrivateIP: description: AllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses type: boolean @@ -62,12 +58,23 @@ components: clientID: description: ClientID is the OIDC client ID type: string + clientSecret: + description: ClientSecret is the optional OIDC client secret for introspection + type: string + introspectionURL: + description: IntrospectionURL is the optional introspection endpoint for + validating tokens + type: string issuer: description: Issuer is the OIDC issuer URL (e.g., https://accounts.google.com) type: string jwksurl: description: JWKSURL is the URL to fetch the JWKS from type: string + resourceURL: + description: ResourceURL is the explicit resource URL for OAuth discovery + (RFC 9728) + type: string type: object authz.CedarConfig: description: |- @@ -149,6 +156,59 @@ components: ToolHive configuration type: boolean type: object + core.Workload: + properties: + created_at: + description: CreatedAt is the timestamp when the workload was created. + type: string + group: + description: Group is the name of the group this workload belongs to, if + any. + type: string + labels: + additionalProperties: + type: string + description: Labels are the container labels (excluding standard ToolHive + labels) + type: object + name: + description: |- + Name is the name of the workload. + It is used as a unique identifier. + type: string + package: + description: Package specifies the Workload Package used to create this + Workload. + type: string + port: + description: |- + Port is the port on which the workload is exposed. + This is embedded in the URL. + type: integer + status: + $ref: '#/components/schemas/runtime.WorkloadStatus' + status_context: + description: |- + StatusContext provides additional context about the workload's status. + The exact meaning is determined by the status and the underlying runtime. + type: string + tool_type: + description: |- + ToolType is the type of tool this workload represents. + For now, it will always be "mcp" - representing an MCP server. + type: string + tools: + description: ToolsFilter is the filter on tools applied to the workload. + items: + type: string + type: array + uniqueItems: false + transport_type: + $ref: '#/components/schemas/types.TransportType' + url: + description: URL is the URL of the workload exposed by the ToolHive proxy. + type: string + type: object groups.Group: properties: name: @@ -253,7 +313,8 @@ components: args: description: |- Args are the default command-line arguments to pass to the MCP server container. - These arguments will be prepended to any command-line arguments provided by the user. + These arguments will be used only if no command-line arguments are provided by the user. + If the user provides arguments, they will override these defaults. items: type: string type: array @@ -452,6 +513,14 @@ components: K8sPodTemplatePatch is a JSON string to patch the Kubernetes pod template Only applicable when using Kubernetes runtime type: string + middleware_configs: + description: |- + MiddlewareConfigs contains the list of middleware to apply to the transport + and the configuration for each middleware. + items: + $ref: '#/components/schemas/types.MiddlewareConfig' + type: array + uniqueItems: false name: description: Name is the name of the MCP server type: string @@ -572,6 +641,17 @@ components: description: ServiceVersion is the service version for telemetry type: string type: object + types.MiddlewareConfig: + properties: + parameters: + description: |- + Parameters is a JSON object containing the middleware parameters. + It is stored as a raw message to allow flexible parameter types. + type: object + type: + description: Type is a string representing the middleware type. + type: string + type: object types.ProxyMode: description: ProxyMode is the proxy mode for stdio transport ("sse" or "streamable-http") type: string @@ -586,8 +666,44 @@ components: - TransportTypeSSE - TransportTypeStreamableHTTP - TransportTypeInspector + v1.RegistryType: + description: Type of registry (file, url, or default) + type: string + x-enum-varnames: + - RegistryTypeFile + - RegistryTypeURL + - RegistryTypeDefault + v1.UpdateRegistryRequest: + description: Request containing registry configuration updates + properties: + allow_private_ip: + description: Allow private IP addresses for registry URL + type: boolean + local_path: + description: Local registry file path + type: string + url: + description: Registry URL (for remote registries) + type: string + type: object + v1.UpdateRegistryResponse: + description: Response containing update result + properties: + message: + description: Status message + type: string + type: + description: Registry type after update + type: string + type: object v1.bulkClientRequest: properties: + groups: + description: Groups is the list of groups configured on the client. + items: + type: string + type: array + uniqueItems: false names: description: Names is the list of client names to operate on. items: @@ -631,6 +747,12 @@ components: type: object v1.createClientRequest: properties: + groups: + description: Groups is the list of groups configured on the client. + items: + type: string + type: array + uniqueItems: false name: description: Name is the type of the client to register. type: string @@ -651,6 +773,12 @@ components: type: object v1.createClientResponse: properties: + groups: + description: Groups is the list of groups configured on the client. + items: + type: string + type: array + uniqueItems: false name: description: Name is the type of the client that was registered. type: string @@ -788,6 +916,17 @@ components: server_count: description: Number of servers in the registry type: integer + source: + description: Source of the registry (URL, file path, or empty string for + built-in) + type: string + type: + description: Type of registry (file, url, or default) + type: string + x-enum-varnames: + - RegistryTypeFile + - RegistryTypeURL + - RegistryTypeDefault version: description: Version of the registry schema type: string @@ -842,15 +981,18 @@ components: v1.oidcOptions: description: OIDC configuration options properties: - allow_opaque_tokens: - description: Allow opaque tokens (non-JWT) for OIDC validation - type: boolean audience: description: Expected audience type: string client_id: description: OAuth2 client ID type: string + client_secret: + description: OAuth2 client secret + type: string + introspection_url: + description: Token introspection URL for OIDC + type: string issuer: description: OIDC issuer URL type: string @@ -889,6 +1031,12 @@ components: server_count: description: Number of servers in the registry type: integer + source: + description: Source of the registry (URL, file path, or empty string for + built-in) + type: string + type: + $ref: '#/components/schemas/v1.RegistryType' version: description: Version of the registry schema type: string @@ -963,62 +1111,9 @@ components: workloads: description: List of container information for each workload items: - $ref: '#/components/schemas/workloads.Workload' - type: array - uniqueItems: false - type: object - workloads.Workload: - properties: - created_at: - description: CreatedAt is the timestamp when the workload was created. - type: string - group: - description: Group is the name of the group this workload belongs to, if - any. - type: string - labels: - additionalProperties: - type: string - description: Labels are the container labels (excluding standard ToolHive - labels) - type: object - name: - description: |- - Name is the name of the workload. - It is used as a unique identifier. - type: string - package: - description: Package specifies the Workload Package used to create this - Workload. - type: string - port: - description: |- - Port is the port on which the workload is exposed. - This is embedded in the URL. - type: integer - status: - $ref: '#/components/schemas/runtime.WorkloadStatus' - status_context: - description: |- - StatusContext provides additional context about the workload's status. - The exact meaning is determined by the status and the underlying runtime. - type: string - tool_type: - description: |- - ToolType is the type of tool this workload represents. - For now, it will always be "mcp" - representing an MCP server. - type: string - tools: - description: ToolsFilter is the filter on tools applied to the workload. - items: - type: string + $ref: '#/components/schemas/core.Workload' type: array uniqueItems: false - transport_type: - $ref: '#/components/schemas/types.TransportType' - url: - description: URL is the URL of the workload exposed by the ToolHive proxy. - type: string type: object externalDocs: description: "" @@ -1373,6 +1468,44 @@ paths: summary: Get a registry tags: - registry + put: + description: Update registry URL or local path for the default registry + parameters: + - description: Registry name (must be 'default') + in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/v1.UpdateRegistryRequest' + description: Registry configuration + required: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/v1.UpdateRegistryResponse' + description: OK + "400": + content: + application/json: + schema: + type: string + description: Bad Request + "404": + content: + application/json: + schema: + type: string + description: Not Found + summary: Update registry configuration + tags: + - registry /api/v1beta/registry/{name}/servers: get: description: Get a list of servers in a specific registry @@ -1778,7 +1911,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/workloads.Workload' + $ref: '#/components/schemas/core.Workload' description: OK "404": content: