{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://caplets.dev/config.schema.json", "title": "Caplets config", "description": "Configuration file for the Caplets progressive MCP disclosure gateway.", "type": "object", "properties": { "$schema": { "description": "Optional JSON Schema URL for editor validation.", "type": "string", "format": "uri" }, "version": { "default": 1, "description": "Caplets config schema version.", "type": "number", "const": 1 }, "defaultSearchLimit": { "default": 20, "description": "Default maximum number of same-server search results.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxSearchLimit": { "default": 50, "description": "Maximum accepted search_tools limit.", "type": "integer", "exclusiveMinimum": 0, "maximum": 50 }, "completion": { "default": { "discoveryTimeoutMs": 750, "overallTimeoutMs": 1500, "cacheTtlMs": 300000, "negativeCacheTtlMs": 30000 }, "description": "Shell completion discovery timeout and cache settings.", "type": "object", "properties": { "discoveryTimeoutMs": { "default": 750, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "overallTimeoutMs": { "default": 1500, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "cacheTtlMs": { "default": 300000, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "negativeCacheTtlMs": { "default": 30000, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "options": { "default": { "exposure": "code_mode", "exposureDiscoveryTimeoutMs": 15000, "exposureDiscoveryConcurrency": 4 }, "description": "Global Caplets runtime options.", "type": "object", "properties": { "exposure": { "default": "code_mode", "type": "string", "enum": [ "direct", "progressive", "code_mode", "direct_and_code_mode", "progressive_and_code_mode" ], "description": "How this Caplet is exposed to agents." }, "exposureDiscoveryTimeoutMs": { "default": 15000, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "exposureDiscoveryConcurrency": { "default": 4, "type": "integer", "exclusiveMinimum": 0, "maximum": 32 } }, "additionalProperties": false }, "mcpServers": { "default": {}, "description": "Downstream MCP servers keyed by stable server ID.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Human-readable server display name." }, "description": { "type": "string", "description": "Capability description shown to agents before downstream tools are disclosed." }, "transport": { "description": "Downstream MCP transport. Defaults to stdio when command is present.", "type": "string", "enum": ["stdio", "http", "sse"] }, "command": { "description": "Executable command for stdio servers.", "type": "string", "minLength": 1 }, "args": { "description": "Arguments passed to the stdio command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Environment variables for stdio servers. Supports ${VAR} and $env:VAR.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for stdio servers.", "type": "string", "minLength": 1 }, "url": { "description": "Remote MCP server URL for http or sse transport.", "type": "string", "format": "uri" }, "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "none" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "bearer" }, "token": { "type": "string", "minLength": 1 } }, "required": ["type", "token"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "headers" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } } }, "required": ["type", "headers"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "oauth2" }, "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "issuer": { "type": "string", "format": "uri" }, "resourceMetadataUrl": { "type": "string", "format": "uri" }, "authorizationServerMetadataUrl": { "type": "string", "format": "uri" }, "openidConfigurationUrl": { "type": "string", "format": "uri" }, "clientMetadataUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string", "minLength": 1 }, "clientSecret": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "redirectUri": { "type": "string", "format": "uri" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "oidc" }, "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "issuer": { "type": "string", "format": "uri" }, "resourceMetadataUrl": { "type": "string", "format": "uri" }, "authorizationServerMetadataUrl": { "type": "string", "format": "uri" }, "openidConfigurationUrl": { "type": "string", "format": "uri" }, "clientMetadataUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string", "minLength": 1 }, "clientSecret": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "redirectUri": { "type": "string", "format": "uri" } }, "required": ["type"], "additionalProperties": false } ], "description": "Authentication settings for a remote MCP server." }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "exposure": { "type": "string", "enum": [ "direct", "progressive", "code_mode", "direct_and_code_mode", "progressive_and_code_mode" ], "description": "How this Caplet is exposed to agents." }, "shadowing": { "default": "forbid", "description": "Whether attached local Caplets may shadow this remote Caplet ID.", "type": "string", "enum": ["forbid", "allow"] }, "useWhen": { "description": "When agents should prefer this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "avoidWhen": { "description": "When agents should avoid this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "setup": { "type": "object", "properties": { "commands": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "description": "Human-readable setup or verification step label." }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this command.", "type": "string", "minLength": 1 }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["label", "command"], "additionalProperties": false } }, "verify": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "description": "Human-readable setup or verification step label." }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this command.", "type": "string", "minLength": 1 }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["label", "command"], "additionalProperties": false } } }, "additionalProperties": false }, "projectBinding": { "type": "object", "properties": { "required": { "type": "boolean", "const": true, "description": "Requires Project Binding before this Caplet can run." } }, "required": ["required"], "additionalProperties": false, "description": "Project Binding requirements for Caplets that need an attached project." }, "runtime": { "type": "object", "properties": { "features": { "type": "array", "items": { "type": "string", "enum": ["docker", "browser"] }, "description": "Runtime features required by this Caplet." }, "resources": { "description": "Hosted sandbox resource requirements.", "type": "object", "properties": { "class": { "description": "Requested hosted sandbox resource class.", "type": "string", "enum": ["standard", "large", "heavy"] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Runtime feature and resource requirements for hosted execution." }, "startupTimeoutMs": { "default": 10000, "description": "Timeout in milliseconds for starting or checking a downstream server.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "callTimeoutMs": { "default": 60000, "description": "Timeout in milliseconds for downstream tool calls.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "toolCacheTtlMs": { "default": 30000, "description": "Milliseconds downstream tool metadata stays fresh. Set 0 to refresh every time.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "disabled": { "default": false, "description": "When true, omit this server from Caplets discovery and do not start it.", "type": "boolean" } }, "required": ["name", "description"], "additionalProperties": false } }, "openapiEndpoints": { "default": {}, "description": "OpenAPI endpoints keyed by stable Caplet ID.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Human-readable OpenAPI display name." }, "description": { "type": "string", "description": "Capability description shown to agents before OpenAPI operations are disclosed." }, "specPath": { "description": "Local OpenAPI specification path.", "type": "string", "minLength": 1 }, "specUrl": { "description": "Remote OpenAPI specification URL.", "type": "string", "format": "uri" }, "baseUrl": { "description": "Override base URL for OpenAPI requests.", "type": "string", "format": "uri" }, "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "none" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "bearer" }, "token": { "type": "string", "minLength": 1 } }, "required": ["type", "token"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "headers" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } } }, "required": ["type", "headers"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "oauth2" }, "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "issuer": { "type": "string", "format": "uri" }, "resourceMetadataUrl": { "type": "string", "format": "uri" }, "authorizationServerMetadataUrl": { "type": "string", "format": "uri" }, "openidConfigurationUrl": { "type": "string", "format": "uri" }, "clientMetadataUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string", "minLength": 1 }, "clientSecret": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "redirectUri": { "type": "string", "format": "uri" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "oidc" }, "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "issuer": { "type": "string", "format": "uri" }, "resourceMetadataUrl": { "type": "string", "format": "uri" }, "authorizationServerMetadataUrl": { "type": "string", "format": "uri" }, "openidConfigurationUrl": { "type": "string", "format": "uri" }, "clientMetadataUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string", "minLength": 1 }, "clientSecret": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "redirectUri": { "type": "string", "format": "uri" } }, "required": ["type"], "additionalProperties": false } ], "description": "Explicit OpenAPI request auth config. Use {\"type\":\"none\"} for public APIs." }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "exposure": { "type": "string", "enum": [ "direct", "progressive", "code_mode", "direct_and_code_mode", "progressive_and_code_mode" ], "description": "How this Caplet is exposed to agents." }, "shadowing": { "default": "forbid", "description": "Whether attached local Caplets may shadow this remote Caplet ID.", "type": "string", "enum": ["forbid", "allow"] }, "useWhen": { "description": "When agents should prefer this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "avoidWhen": { "description": "When agents should avoid this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "setup": { "type": "object", "properties": { "commands": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "description": "Human-readable setup or verification step label." }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this command.", "type": "string", "minLength": 1 }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["label", "command"], "additionalProperties": false } }, "verify": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "description": "Human-readable setup or verification step label." }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this command.", "type": "string", "minLength": 1 }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["label", "command"], "additionalProperties": false } } }, "additionalProperties": false }, "projectBinding": { "type": "object", "properties": { "required": { "type": "boolean", "const": true, "description": "Requires Project Binding before this Caplet can run." } }, "required": ["required"], "additionalProperties": false, "description": "Project Binding requirements for Caplets that need an attached project." }, "runtime": { "type": "object", "properties": { "features": { "type": "array", "items": { "type": "string", "enum": ["docker", "browser"] }, "description": "Runtime features required by this Caplet." }, "resources": { "description": "Hosted sandbox resource requirements.", "type": "object", "properties": { "class": { "description": "Requested hosted sandbox resource class.", "type": "string", "enum": ["standard", "large", "heavy"] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Runtime feature and resource requirements for hosted execution." }, "requestTimeoutMs": { "default": 60000, "description": "Timeout in milliseconds for OpenAPI HTTP requests.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "operationCacheTtlMs": { "default": 30000, "description": "Milliseconds OpenAPI operation metadata stays fresh. Set 0 to refresh every time.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "disabled": { "default": false, "description": "When true, omit this OpenAPI Caplet from discovery.", "type": "boolean" } }, "required": ["name", "description", "auth"], "additionalProperties": false } }, "graphqlEndpoints": { "default": {}, "description": "GraphQL endpoints keyed by stable Caplet ID.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Human-readable GraphQL display name." }, "description": { "type": "string", "description": "Capability description shown to agents before GraphQL operations are disclosed." }, "endpointUrl": { "type": "string", "format": "uri", "description": "GraphQL HTTP endpoint URL." }, "schemaPath": { "description": "Local GraphQL SDL or introspection path.", "type": "string", "minLength": 1 }, "schemaUrl": { "description": "Remote GraphQL SDL or introspection URL.", "type": "string", "format": "uri" }, "introspection": { "description": "Load schema through endpoint introspection.", "type": "boolean", "const": true }, "operations": { "description": "Configured GraphQL operations keyed by stable tool name.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "document": { "description": "Inline GraphQL operation document.", "type": "string", "minLength": 1 }, "documentPath": { "description": "Path to a GraphQL operation document.", "type": "string", "minLength": 1 }, "operationName": { "description": "Operation name to execute.", "type": "string", "minLength": 1 }, "description": { "description": "Operation capability description.", "type": "string", "minLength": 1 }, "useWhen": { "description": "When agents should prefer this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "avoidWhen": { "description": "When agents should avoid this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false } }, "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "none" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "bearer" }, "token": { "type": "string", "minLength": 1 } }, "required": ["type", "token"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "headers" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } } }, "required": ["type", "headers"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "oauth2" }, "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "issuer": { "type": "string", "format": "uri" }, "resourceMetadataUrl": { "type": "string", "format": "uri" }, "authorizationServerMetadataUrl": { "type": "string", "format": "uri" }, "openidConfigurationUrl": { "type": "string", "format": "uri" }, "clientMetadataUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string", "minLength": 1 }, "clientSecret": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "redirectUri": { "type": "string", "format": "uri" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "oidc" }, "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "issuer": { "type": "string", "format": "uri" }, "resourceMetadataUrl": { "type": "string", "format": "uri" }, "authorizationServerMetadataUrl": { "type": "string", "format": "uri" }, "openidConfigurationUrl": { "type": "string", "format": "uri" }, "clientMetadataUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string", "minLength": 1 }, "clientSecret": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "redirectUri": { "type": "string", "format": "uri" } }, "required": ["type"], "additionalProperties": false } ], "description": "Explicit GraphQL request auth config. Use {\"type\":\"none\"} for public APIs." }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "exposure": { "type": "string", "enum": [ "direct", "progressive", "code_mode", "direct_and_code_mode", "progressive_and_code_mode" ], "description": "How this Caplet is exposed to agents." }, "shadowing": { "default": "forbid", "description": "Whether attached local Caplets may shadow this remote Caplet ID.", "type": "string", "enum": ["forbid", "allow"] }, "useWhen": { "description": "When agents should prefer this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "avoidWhen": { "description": "When agents should avoid this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "setup": { "type": "object", "properties": { "commands": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "description": "Human-readable setup or verification step label." }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this command.", "type": "string", "minLength": 1 }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["label", "command"], "additionalProperties": false } }, "verify": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "description": "Human-readable setup or verification step label." }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this command.", "type": "string", "minLength": 1 }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["label", "command"], "additionalProperties": false } } }, "additionalProperties": false }, "projectBinding": { "type": "object", "properties": { "required": { "type": "boolean", "const": true, "description": "Requires Project Binding before this Caplet can run." } }, "required": ["required"], "additionalProperties": false, "description": "Project Binding requirements for Caplets that need an attached project." }, "runtime": { "type": "object", "properties": { "features": { "type": "array", "items": { "type": "string", "enum": ["docker", "browser"] }, "description": "Runtime features required by this Caplet." }, "resources": { "description": "Hosted sandbox resource requirements.", "type": "object", "properties": { "class": { "description": "Requested hosted sandbox resource class.", "type": "string", "enum": ["standard", "large", "heavy"] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Runtime feature and resource requirements for hosted execution." }, "requestTimeoutMs": { "default": 60000, "description": "Timeout in milliseconds for GraphQL HTTP requests.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "operationCacheTtlMs": { "default": 30000, "description": "Milliseconds GraphQL operation metadata stays fresh. Set 0 to refresh every time.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "selectionDepth": { "default": 2, "description": "Maximum depth for auto-generated GraphQL selection sets.", "type": "integer", "exclusiveMinimum": 0, "maximum": 5 }, "disabled": { "default": false, "description": "When true, omit this GraphQL Caplet.", "type": "boolean" } }, "required": ["name", "description", "endpointUrl", "auth"], "additionalProperties": false } }, "httpApis": { "default": {}, "description": "HTTP APIs keyed by stable Caplet ID.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Human-readable HTTP API display name." }, "description": { "type": "string", "description": "Capability description shown to agents before HTTP actions are disclosed." }, "baseUrl": { "type": "string", "pattern": "^(?![a-zA-Z][a-zA-Z0-9+.-]*:\\/\\/[^/?#]*@)[^?#]*$", "description": "Base URL for HTTP action requests.", "format": "uri" }, "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "none" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "bearer" }, "token": { "type": "string", "minLength": 1 } }, "required": ["type", "token"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "headers" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } } }, "required": ["type", "headers"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "oauth2" }, "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "issuer": { "type": "string", "format": "uri" }, "resourceMetadataUrl": { "type": "string", "format": "uri" }, "authorizationServerMetadataUrl": { "type": "string", "format": "uri" }, "openidConfigurationUrl": { "type": "string", "format": "uri" }, "clientMetadataUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string", "minLength": 1 }, "clientSecret": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "redirectUri": { "type": "string", "format": "uri" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "oidc" }, "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "issuer": { "type": "string", "format": "uri" }, "resourceMetadataUrl": { "type": "string", "format": "uri" }, "authorizationServerMetadataUrl": { "type": "string", "format": "uri" }, "openidConfigurationUrl": { "type": "string", "format": "uri" }, "clientMetadataUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string", "minLength": 1 }, "clientSecret": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "redirectUri": { "type": "string", "format": "uri" } }, "required": ["type"], "additionalProperties": false } ], "description": "Explicit HTTP API request auth config. Use {\"type\":\"none\"} for public APIs." }, "actions": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "method": { "type": "string", "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"], "description": "HTTP method used for this action." }, "path": { "type": "string", "minLength": 1, "pattern": "^\\/", "description": "URL path appended to the HTTP API baseUrl." }, "description": { "description": "Action capability description.", "type": "string", "minLength": 1 }, "useWhen": { "description": "When agents should prefer this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "avoidWhen": { "description": "When agents should avoid this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "inputSchema": { "description": "JSON Schema for call_tool arguments.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "description": "JSON Schema for structuredContent returned by this action.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "query": { "description": "Query parameter mapping.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "headers": { "description": "Request header mapping.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "jsonBody": { "description": "JSON request body mapping." } }, "required": ["method", "path"], "additionalProperties": false }, "description": "Configured HTTP actions keyed by stable tool name.", "minProperties": 1 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "exposure": { "type": "string", "enum": [ "direct", "progressive", "code_mode", "direct_and_code_mode", "progressive_and_code_mode" ], "description": "How this Caplet is exposed to agents." }, "shadowing": { "default": "forbid", "description": "Whether attached local Caplets may shadow this remote Caplet ID.", "type": "string", "enum": ["forbid", "allow"] }, "useWhen": { "description": "When agents should prefer this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "avoidWhen": { "description": "When agents should avoid this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "setup": { "type": "object", "properties": { "commands": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "description": "Human-readable setup or verification step label." }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this command.", "type": "string", "minLength": 1 }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["label", "command"], "additionalProperties": false } }, "verify": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "description": "Human-readable setup or verification step label." }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this command.", "type": "string", "minLength": 1 }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["label", "command"], "additionalProperties": false } } }, "additionalProperties": false }, "projectBinding": { "type": "object", "properties": { "required": { "type": "boolean", "const": true, "description": "Requires Project Binding before this Caplet can run." } }, "required": ["required"], "additionalProperties": false, "description": "Project Binding requirements for Caplets that need an attached project." }, "runtime": { "type": "object", "properties": { "features": { "type": "array", "items": { "type": "string", "enum": ["docker", "browser"] }, "description": "Runtime features required by this Caplet." }, "resources": { "description": "Hosted sandbox resource requirements.", "type": "object", "properties": { "class": { "description": "Requested hosted sandbox resource class.", "type": "string", "enum": ["standard", "large", "heavy"] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Runtime feature and resource requirements for hosted execution." }, "requestTimeoutMs": { "default": 60000, "description": "Timeout in milliseconds for HTTP action requests.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxResponseBytes": { "default": 200000, "description": "Maximum HTTP action response body bytes to read.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "disabled": { "default": false, "description": "When true, omit this HTTP API Caplet.", "type": "boolean" } }, "required": ["name", "description", "baseUrl", "auth", "actions"], "additionalProperties": false } }, "cliTools": { "default": {}, "description": "CLI tools keyed by stable Caplet ID.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Human-readable CLI tools display name." }, "description": { "type": "string", "description": "Capability description shown to agents before CLI actions are disclosed." }, "actions": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "description": { "description": "Action capability description.", "type": "string", "minLength": 1 }, "useWhen": { "description": "When agents should prefer this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "avoidWhen": { "description": "When agents should avoid this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "inputSchema": { "description": "JSON Schema for call_tool arguments.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "description": "JSON Schema for structuredContent returned by this action.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables for the command.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this action.", "type": "string", "minLength": 1 }, "timeoutMs": { "description": "Command timeout in milliseconds.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "description": "Maximum combined stdout and stderr bytes to keep.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "output": { "type": "object", "properties": { "type": { "default": "text", "description": "How stdout should be represented in structuredContent.", "type": "string", "enum": ["text", "json"] } }, "additionalProperties": false }, "annotations": { "type": "object", "properties": { "readOnlyHint": { "type": "boolean" }, "destructiveHint": { "type": "boolean" }, "idempotentHint": { "type": "boolean" }, "openWorldHint": { "type": "boolean" } }, "additionalProperties": false } }, "required": ["command"], "additionalProperties": false }, "description": "Configured CLI actions keyed by stable tool name.", "minProperties": 1 }, "cwd": { "description": "Default working directory for CLI actions.", "type": "string", "minLength": 1 }, "env": { "description": "Default environment variables for CLI actions.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "exposure": { "type": "string", "enum": [ "direct", "progressive", "code_mode", "direct_and_code_mode", "progressive_and_code_mode" ], "description": "How this Caplet is exposed to agents." }, "shadowing": { "default": "forbid", "description": "Whether attached local Caplets may shadow this remote Caplet ID.", "type": "string", "enum": ["forbid", "allow"] }, "useWhen": { "description": "When agents should prefer this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "avoidWhen": { "description": "When agents should avoid this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "setup": { "type": "object", "properties": { "commands": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "description": "Human-readable setup or verification step label." }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this command.", "type": "string", "minLength": 1 }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["label", "command"], "additionalProperties": false } }, "verify": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "description": "Human-readable setup or verification step label." }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this command.", "type": "string", "minLength": 1 }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["label", "command"], "additionalProperties": false } } }, "additionalProperties": false }, "projectBinding": { "type": "object", "properties": { "required": { "type": "boolean", "const": true, "description": "Requires Project Binding before this Caplet can run." } }, "required": ["required"], "additionalProperties": false, "description": "Project Binding requirements for Caplets that need an attached project." }, "runtime": { "type": "object", "properties": { "features": { "type": "array", "items": { "type": "string", "enum": ["docker", "browser"] }, "description": "Runtime features required by this Caplet." }, "resources": { "description": "Hosted sandbox resource requirements.", "type": "object", "properties": { "class": { "description": "Requested hosted sandbox resource class.", "type": "string", "enum": ["standard", "large", "heavy"] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Runtime feature and resource requirements for hosted execution." }, "timeoutMs": { "default": 60000, "description": "Default timeout in milliseconds for CLI actions.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "default": 200000, "description": "Default maximum combined stdout and stderr bytes to keep.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "disabled": { "default": false, "description": "When true, omit this CLI tools Caplet.", "type": "boolean" } }, "required": ["name", "description", "actions"], "additionalProperties": false } }, "capletSets": { "default": {}, "description": "Nested Caplet collections keyed by stable Caplet ID.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Human-readable Caplet set display name." }, "description": { "type": "string", "description": "Capability description shown before child Caplets are disclosed." }, "configPath": { "description": "Child Caplets config.json path.", "type": "string", "minLength": 1 }, "capletsRoot": { "description": "Child Markdown Caplets root directory.", "type": "string", "minLength": 1 }, "defaultSearchLimit": { "default": 20, "description": "Default maximum number of child Caplet search results.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxSearchLimit": { "default": 50, "description": "Maximum accepted child Caplet search result limit.", "type": "integer", "exclusiveMinimum": 0, "maximum": 50 }, "toolCacheTtlMs": { "default": 30000, "description": "Milliseconds child Caplet metadata stays fresh. Set 0 to refresh every time.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "exposure": { "type": "string", "enum": [ "direct", "progressive", "code_mode", "direct_and_code_mode", "progressive_and_code_mode" ], "description": "How this Caplet is exposed to agents." }, "shadowing": { "default": "forbid", "description": "Whether attached local Caplets may shadow this remote Caplet ID.", "type": "string", "enum": ["forbid", "allow"] }, "useWhen": { "description": "When agents should prefer this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "avoidWhen": { "description": "When agents should avoid this Caplet or configured action.", "type": "string", "minLength": 1, "maxLength": 500 }, "setup": { "type": "object", "properties": { "commands": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "description": "Human-readable setup or verification step label." }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this command.", "type": "string", "minLength": 1 }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["label", "command"], "additionalProperties": false } }, "verify": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "description": "Human-readable setup or verification step label." }, "command": { "type": "string", "minLength": 1, "description": "Executable command to spawn without a shell." }, "args": { "description": "Arguments passed to the command.", "type": "array", "items": { "type": "string" } }, "env": { "description": "Additional environment variables.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cwd": { "description": "Working directory for this command.", "type": "string", "minLength": 1 }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxOutputBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["label", "command"], "additionalProperties": false } } }, "additionalProperties": false }, "projectBinding": { "type": "object", "properties": { "required": { "type": "boolean", "const": true, "description": "Requires Project Binding before this Caplet can run." } }, "required": ["required"], "additionalProperties": false, "description": "Project Binding requirements for Caplets that need an attached project." }, "runtime": { "type": "object", "properties": { "features": { "type": "array", "items": { "type": "string", "enum": ["docker", "browser"] }, "description": "Runtime features required by this Caplet." }, "resources": { "description": "Hosted sandbox resource requirements.", "type": "object", "properties": { "class": { "description": "Requested hosted sandbox resource class.", "type": "string", "enum": ["standard", "large", "heavy"] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Runtime feature and resource requirements for hosted execution." }, "disabled": { "default": false, "description": "When true, omit this Caplet set.", "type": "boolean" } }, "required": ["name", "description"], "additionalProperties": false } } }, "additionalProperties": false }