diff --git a/src/.vuepress/sidebar/en.ts b/src/.vuepress/sidebar/en.ts index 0ffdd190..db34fdb3 100644 --- a/src/.vuepress/sidebar/en.ts +++ b/src/.vuepress/sidebar/en.ts @@ -124,6 +124,34 @@ export const enSidebar = sidebar({ collapsible: true, children: "structure", }, + { + text: "MCP-Kafka", + icon: "fa-solid fa-robot", + prefix: "mcp-kafka", + collapsible: true, + children: "structure", + }, + { + text: "MCP-Kafka-Connect", + icon: "fa-solid fa-robot", + prefix: "mcp-kafka-connect", + collapsible: true, + children: "structure", + }, + { + text: "MCP-OpenAPI", + icon: "fa-solid fa-robot", + prefix: "mcp-openapi", + collapsible: true, + children: "structure", + }, + { + text: "MCP-Schema-Registry", + icon: "fa-solid fa-robot", + prefix: "mcp-schema-registry", + collapsible: true, + children: "structure", + }, { text: "MQTT", icon: "fa-solid fa-wifi", diff --git a/src/reference/config/bindings/mcp-http/.partials/options.md b/src/reference/config/bindings/mcp-http/.partials/options.md index 0e935ba3..112df75f 100644 --- a/src/reference/config/bindings/mcp-http/.partials/options.md +++ b/src/reference/config/bindings/mcp-http/.partials/options.md @@ -2,7 +2,7 @@ > `object` -The `mcp_http` specific options. +The `mcp-http` specific options. ```yaml options: @@ -40,23 +40,13 @@ options: my_catalog: - subject: order_result version: latest - prompts: - summarize: - description: Summarize a document about a topic - arguments: - - name: topic - description: The topic to summarize - required: true - messages: - - role: user - text: "Please summarize the document about ${args.topic}." ``` #### options.authorization > `object` as map of named `object` -Guard credentials to inject into the upstream `http` request. The named key references a [guard](../../../guards/README.md) defined elsewhere in the configuration. At most one guard may be referenced. +Guard credentials to inject into the upstream `http` request. The named key references a [`guard`](../../../../config/overview.md#guards) defined elsewhere in the configuration. At most one guard may be referenced. #### authorization.credentials @@ -137,19 +127,19 @@ Converter validating and projecting the upstream `http` response, surfaced as th > `object` as map of named `object` -MCP resources terminated by this binding and expanded into `http` requests. The named key is the resource name surfaced to MCP clients by `resources/list` and matched by `resources/read`. +MCP resources terminated by this binding and expanded into `http` requests. The named key is the resource name surfaced to MCP clients by `resources/list` or `resources/templates/list`, and matched by `resources/read`. #### resources.uri\* > `string` -Resource URI template surfaced by `resources/list`, with optional embedded capture names, such as `order://{orderId}`. Captured values are referenced from a route as `${params.x}`. +Resource URI, with optional embedded capture names, such as `order://{orderId}`. A URI with no captures is a concrete resource surfaced by `resources/list`; a URI with one or more captures is a resource template surfaced by `resources/templates/list` instead. Captured values are referenced from a route as `${params.x}`. #### resources.description > `string` -Resource description surfaced to MCP clients by `resources/list`. +Resource description surfaced to MCP clients by `resources/list` or `resources/templates/list`. #### resources.mimeType @@ -170,57 +160,3 @@ JSON schema converter for the resource. Converter validating and projecting the upstream `http` response, surfaced as the resource `contents`. Uses the same shape as [`schemas.input`](#schemas-input). - -#### options.prompts - -> `object` as map of named `object` - -MCP prompts served locally by this binding. The named key is the prompt name surfaced to MCP clients by `prompts/list` and matched by `prompts/get`. A `prompts/get` request renders the messages locally with no upstream `http` request. - -#### prompts.description - -> `string` - -Prompt description surfaced to MCP clients by `prompts/list`. - -#### prompts.arguments - -> `array` of `object` - -Arguments accepted by the prompt, surfaced to MCP clients by `prompts/list` and supplied on `prompts/get`. - -#### arguments[].name\* - -> `string` - -Argument name, referenced from a message template as `${args.name}`. - -#### arguments[].description - -> `string` - -Argument description surfaced to MCP clients. - -#### arguments[].required - -> `boolean` | Default: `false` - -Whether the argument must be supplied on `prompts/get`. - -#### prompts.messages\* - -> `array` of `object` - -Message templates rendered and returned by `prompts/get`. - -#### messages[].role\* - -> `enum` [ `user`, `assistant` ] - -Role of the rendered message. - -#### messages[].text\* - -> `string` - -Message text template. Supports `${args.x}` interpolation, where `x` references a prompt argument supplied on `prompts/get`. diff --git a/src/reference/config/bindings/mcp-http/.partials/proxy.yaml b/src/reference/config/bindings/mcp-http/.partials/proxy.yaml index 2fb8e2e7..b48c3376 100644 --- a/src/reference/config/bindings/mcp-http/.partials/proxy.yaml +++ b/src/reference/config/bindings/mcp-http/.partials/proxy.yaml @@ -1,5 +1,5 @@ mcp_http_proxy: - type: mcp_http + type: mcp-http kind: proxy options: authorization: @@ -36,16 +36,6 @@ mcp_http_proxy: my_catalog: - subject: order_result version: latest - prompts: - summarize: - description: Summarize a document about a topic - arguments: - - name: topic - description: The topic to summarize - required: true - messages: - - role: user - text: "Please summarize the document about ${args.topic}." routes: - when: - tool: create_pr diff --git a/src/reference/config/bindings/mcp-http/.partials/routes.md b/src/reference/config/bindings/mcp-http/.partials/routes.md index 7d2e7638..9d970811 100644 --- a/src/reference/config/bindings/mcp-http/.partials/routes.md +++ b/src/reference/config/bindings/mcp-http/.partials/routes.md @@ -2,7 +2,7 @@ > `array` of `object` -Conditional `mcp_http` specific routes, resolving the upstream `http` request for a matched `tools/call` or `resources/read`. +Conditional `mcp-http` specific routes, resolving the upstream `http` request for a matched `tools/call` or `resources/read`. ```yaml routes: @@ -36,29 +36,44 @@ routes: > `object` as map of named `array` of `string` -Roles required by the named guard. When a guarded route matches, the MCP session must be authorized for the listed roles, otherwise the stream is rejected. +Roles required by the named guard. When a route with [`with`](#routes-with) matches, the MCP session must be authorized for the listed roles on every applicable route, otherwise the stream is rejected. + +A route may omit both [`when`](#routes-when) and `with` to act as a guard-only layer, applying its `guarded` roles globally across every tool and resource rather than mapping to an upstream request. Combine a global guard-only layer with a route-specific one by giving the guard-only layer a single `when` condition instead of omitting `when`. Roles from every applicable layer — the matched mapping route plus any global or scoped guard-only layers — must all authorize. ```yaml routes: - guarded: + my_guard: + - read + - when: + - tool: create_pr + exit: http_client + guarded: my_guard: - pr:write + with: + headers: + ":method": POST + ":scheme": https + ":authority": api.github.com + ":path": /repos/${args.owner}/${args.repo}/pulls ``` #### routes[].when > `array` of `object` -List of conditions (any match) to match this route. +At most one condition to match this route. A route with [`with`](#routes-with) requires exactly one `when` condition, mapping one tool or resource to an upstream request; a route without `with` may omit `when` entirely to guard every tool and resource, or give exactly one condition to scope the guard to a single tool or resource. Read more: [When a route matches](/concepts/protocol/README.md#route-matches) ```yaml routes: - when: - tool: create_pr - - resource: order ``` +Each condition specifies exactly one of `tool` or `resource`, never both. + #### when[].tool > `string` @@ -98,9 +113,35 @@ with: HTTP request headers for the upstream request, including the pseudo-headers `:method`, `:scheme`, `:authority`, and `:path`. Values support interpolation. -- `${args.x}` Replaced with property `x` of the `tools/call` arguments. +- `${args.x}` Replaced with property `x` of the `tools/call` arguments. `x` may be dotted to reference a nested property, such as `${args.repository.owner}`. - `${params.x}` Replaced with capture `x` from the matched resource [`uri`](#resources-uri). +Every header other than `:path` is omitted from the upstream request entirely when a referenced property or capture is absent, rather than being sent with an empty value. + +The `:path` pseudo-header resolves differently: a referenced property or capture that is absent resolves to an empty string rather than omitting the header, since `:path` is always required. To omit an individual query parameter instead, mark its fragment as optional with `${?args.x=name}` (or `${?params.x=name}`) in place of a literal `name=${args.x}` pair — the whole `name=value` fragment, including its separator, is dropped when `x` is absent. + +```yaml +with: + headers: + ":method": GET + ":scheme": https + ":authority": api.github.com + ":path": /items?q=${args.q}&${?args.limit=limit} +``` + +#### with.cookies + +> `object` as map of named `string` + +Cookie name/value pairs aggregated into a single `Cookie` header on the upstream request. Values support the same `${args.x}` and `${params.x}` interpolation as [`with.headers`](#with-headers). A cookie whose referenced property or capture is absent is dropped from the aggregate on its own; the `Cookie` header itself is omitted only when every configured cookie is absent. + +```yaml +with: + cookies: + session: ${args.sessionId} + locale: ${params.locale} +``` + #### with.query > `object` @@ -129,7 +170,7 @@ with: > `object` as map of named `string` -Explicit request body, mapping each body property to an interpolated value. Supports `${args.x}` interpolation, where `x` references a property of the `tools/call` arguments. Use a template to rename or restructure arguments before dispatch. +Explicit request body, mapping each body property to an interpolated value. Supports `${args.x}` interpolation, where `x` references a property of the `tools/call` arguments; `x` may be dotted to reference a nested property, such as `${args.pr.branch}`. Use a template to rename or restructure arguments, including flattening nested arguments, before dispatch. ```yaml with: diff --git a/src/reference/config/bindings/mcp-http/README.md b/src/reference/config/bindings/mcp-http/README.md index abf84f53..f1ce518d 100644 --- a/src/reference/config/bindings/mcp-http/README.md +++ b/src/reference/config/bindings/mcp-http/README.md @@ -9,13 +9,13 @@ tag: # mcp-http Binding -The `proxy` kind `mcp_http` binding accepts `mcp` streams and produces `http` streams. It terminates `tools/list`, `resources/list`, and `prompts/list` from configuration, expands `tools/call` and `resources/read` into upstream `http` requests, and renders `prompts/get` from configured message templates. +The `proxy` kind `mcp-http` binding accepts `mcp` streams and produces `http` streams. It terminates `tools/list`, `resources/list`, and `resources/templates/list` from configuration, and expands `tools/call` and `resources/read` into upstream `http` requests. ## proxy > [Full config](./proxy.md) -Behave as an `mcp_http` `proxy`. +Behave as an `mcp-http` `proxy`. ```yaml {3} diff --git a/src/reference/config/bindings/mcp-http/proxy.md b/src/reference/config/bindings/mcp-http/proxy.md index d383b5d1..d3345886 100644 --- a/src/reference/config/bindings/mcp-http/proxy.md +++ b/src/reference/config/bindings/mcp-http/proxy.md @@ -4,7 +4,7 @@ shortTitle: proxy # mcp-http proxy -The `mcp_http` proxy binding accepts `mcp` streams and produces `http` streams, terminating `tools/list`, `resources/list`, and `prompts/list` from configuration, expanding `tools/call` and `resources/read` into upstream `http` requests, and rendering `prompts/get` from configured message templates. +The `mcp-http` proxy binding accepts `mcp` streams and produces `http` streams, terminating `tools/list`, `resources/list`, and `resources/templates/list` from configuration, and expanding `tools/call` and `resources/read` into upstream `http` requests. ```yaml {3} diff --git a/src/reference/config/bindings/mcp-kafka-connect/.partials/client.yaml b/src/reference/config/bindings/mcp-kafka-connect/.partials/client.yaml new file mode 100644 index 00000000..6cae985c --- /dev/null +++ b/src/reference/config/bindings/mcp-kafka-connect/.partials/client.yaml @@ -0,0 +1,22 @@ +mcp_kafka_connect_client: + type: mcp-kafka-connect + kind: client + options: + server: http://kafka-connect.examples.dev:8083 + routes: + - when: + - tool: create_connector + - tool: delete_connector + - tool: update_connector_config + - tool: restart_connector + - tool: pause_connector + - tool: resume_connector + - tool: stop_connector + - tool: restart_connector_task + - tool: alter_connector_offsets + - tool: reset_connector_offsets + guarded: + my_guard: + - kafka-connect:admin + - when: + - tool: "*" diff --git a/src/reference/config/bindings/mcp-kafka-connect/.partials/options.md b/src/reference/config/bindings/mcp-kafka-connect/.partials/options.md new file mode 100644 index 00000000..58839406 --- /dev/null +++ b/src/reference/config/bindings/mcp-kafka-connect/.partials/options.md @@ -0,0 +1,16 @@ +### options\* + +> `object` + +The `client` specific options. + +```yaml +options: + server: http://kafka-connect.examples.dev:8083 +``` + +#### options.server\* + +> `string` + +Base URL of the Kafka Connect REST API this binding proxies to. diff --git a/src/reference/config/bindings/mcp-kafka-connect/.partials/routes.md b/src/reference/config/bindings/mcp-kafka-connect/.partials/routes.md new file mode 100644 index 00000000..959b6086 --- /dev/null +++ b/src/reference/config/bindings/mcp-kafka-connect/.partials/routes.md @@ -0,0 +1,50 @@ +### routes\* + +> `array` of `object` + +Conditional `mcp-kafka-connect` specific routes, matching by tool name or glob pattern. At least one route is required. Routes are evaluated in order; the first matching route wins. + +```yaml +routes: + - when: + - tool: delete_connector + guarded: + my_guard: + - kafka-connect:admin + - when: + - tool: "*" +``` + +#### routes[].when\* + +> `array` of `object` + +List of conditions (any match) restricting this route to particular tools. Required. + +```yaml +routes: + - when: + - tool: create_connector + - tool: delete_connector +``` + +#### when[].tool\* + +> `string` or `array` of `string` + +Tool name matched by `tools/call`, or a `*` glob pattern matching many tool names in bulk (such as `list_*`). Required. + +#### routes[].guarded + +> `object` as map of named `array` of `string` + +Roles required by the named guard for a `tools/call` against this route. Roles for the same guard are unioned into one entry; roles naming a different guard add a separate entry that must also authorize. + +```yaml +routes: + - when: + - tool: delete_connector + guarded: + my_guard: + - kafka-connect:admin +``` diff --git a/src/reference/config/bindings/mcp-kafka-connect/.partials/tools.md b/src/reference/config/bindings/mcp-kafka-connect/.partials/tools.md new file mode 100644 index 00000000..0f139cb7 --- /dev/null +++ b/src/reference/config/bindings/mcp-kafka-connect/.partials/tools.md @@ -0,0 +1,222 @@ +The `mcp-kafka-connect` client exposes a fixed set of intrinsic tools, derived from a bundled Kafka Connect REST API specification — there is no `options.tools` to author, and no upstream server or spec to select. Each tool's `inputSchema` validates `tools/call` `arguments` before Zilla dispatches the matching request to `options.server`. Every tool's `structuredContent` carries the upstream JSON response — validated and pruned to a declared `outputSchema` where one exists, or the raw body unchanged where none is declared — and `content` carries the tool's `summary` text, which may itself interpolate fields out of that same response via `${result.x}`. + +### list_connectors + +> Read-only, idempotent + +Lists the names of every connector on the worker. + +No arguments. + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response — an array of connector names — with no fixed property list. + +### create_connector + +> Not destructive, not idempotent + +Creates a new connector. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `name` | `string` | Yes | Connector name. | +| `config` | `object` as map of named `string` | Yes | Connector configuration properties. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. The summary interpolates `${result.name}`. + +### describe_connector + +> Read-only, idempotent + +Reads one connector's configuration and task list by name. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector to describe. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. The summary interpolates `${result.name}`. + +### delete_connector + +> Destructive, idempotent + +Deletes a connector. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector to delete. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. The summary interpolates `${result.name}`. + +### describe_connector_config + +> Read-only, idempotent + +Reads the effective configuration of a connector. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector to read the configuration of. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. + +### update_connector_config + +> Not destructive, idempotent + +Creates or updates a connector by setting its full configuration. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector to configure. | +| `connector.class` | `string` | Yes | Connector class to instantiate. | +| `tasks.max` | `string` | Yes | Maximum number of tasks to run. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. The summary interpolates `${result.name}`. + +### validate_connector_config + +> Read-only, idempotent + +Validates a connector configuration against a plugin's configuration definition, without creating or updating any connector. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `pluginName` | `string` | Yes | Connector plugin to validate against. | +| `connector.class` | `string` | Yes | Connector class to validate. | +| `tasks.max` | `string` | Yes | Maximum number of tasks to validate. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. The summary interpolates `${result.error_count}`, such as `Validated connector config with 0 errors`. + +### describe_connector_status + +> Read-only, idempotent + +Reads a connector's current state and the state of each of its tasks. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector to check the status of. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. The summary interpolates `${result.name}` and `${result.connector.state}`, such as `Connector my-connector is RUNNING`. + +### restart_connector + +> Not destructive, not idempotent + +Restarts a connector. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector to restart. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. The summary interpolates `${result.name}`. + +### pause_connector + +> Not destructive, idempotent + +Pauses a connector and all of its tasks. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector to pause. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. The summary interpolates `${result.name}`. + +### resume_connector + +> Not destructive, idempotent + +Resumes a paused connector and all of its tasks. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector to resume. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. The summary interpolates `${result.name}`. + +### stop_connector + +> Not destructive, idempotent + +Stops a connector and shuts down all of its tasks, without deleting the connector. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector to stop. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. The summary interpolates `${result.name}`. + +### list_connector_tasks + +> Read-only, idempotent + +Lists every task belonging to a connector. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector whose tasks to list. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. + +### restart_connector_task + +> Not destructive, not idempotent + +Restarts a single task belonging to a connector. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector owning the task. | +| `task` | `integer` | Yes | Task id to restart. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. + +### describe_connector_offsets + +> Read-only, idempotent + +Reads a connector's current source or sink offsets. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector whose offsets to read. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. + +### alter_connector_offsets + +> Destructive, idempotent + +Overwrites a connector's source or sink offsets. The connector must be stopped first. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector whose offsets to alter. | +| `offsets` | `array` of `object` | Yes | Offsets to write. | +| `offsets[].partition` | `object` | Yes | Source partition or sink topic-partition identifying the offset. | +| `offsets[].offset` | `object` | Yes | New offset value for the identified partition. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. The summary interpolates `${result.message}`. + +### reset_connector_offsets + +> Destructive, idempotent + +Resets a connector's source or sink offsets to their initial state. The connector must be stopped first. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `connector` | `string` | Yes | Connector whose offsets to reset. | + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response, with no fixed property list. The summary interpolates `${result.message}`. + +### list_connector_plugins + +> Read-only, idempotent + +Lists every connector plugin installed on the worker. + +No arguments. + +No fixed `outputSchema` is declared; the result's `structuredContent` mirrors the raw upstream JSON response — an array of installed plugins — with no fixed property list. diff --git a/src/reference/config/bindings/mcp-kafka-connect/README.md b/src/reference/config/bindings/mcp-kafka-connect/README.md new file mode 100644 index 00000000..c28fd396 --- /dev/null +++ b/src/reference/config/bindings/mcp-kafka-connect/README.md @@ -0,0 +1,22 @@ +--- +shortTitle: mcp-kafka-connect +category: + - Binding +tag: + - mcp-kafka-connect + - client +--- + +# mcp-kafka-connect Binding + +The `client` kind `mcp-kafka-connect` binding exposes the Kafka Connect REST API — connectors, tasks, offsets, and plugins — as a fixed set of intrinsic MCP tools, connecting directly to the Kafka Connect worker named by `options.server`, with no upstream MCP server, OpenAPI spec, or per-tool schema authoring. + +## client + +> [Full config](./client.md) + +Behave as an `mcp-kafka-connect` `client`. + +```yaml {3} + +``` diff --git a/src/reference/config/bindings/mcp-kafka-connect/client.md b/src/reference/config/bindings/mcp-kafka-connect/client.md new file mode 100644 index 00000000..b3434735 --- /dev/null +++ b/src/reference/config/bindings/mcp-kafka-connect/client.md @@ -0,0 +1,21 @@ +--- +shortTitle: client +--- + +# mcp-kafka-connect client + +The `mcp-kafka-connect` client binding exposes the Kafka Connect REST API as a fixed set of intrinsic MCP tools, connecting directly to the Kafka Connect worker named by `options.server` — unlike [`mcp-openapi`](../mcp-openapi/client.md), there is no upstream spec or per-tool schema to author. [`mcp-kafka`](../mcp-kafka/client.md) and [`mcp-schema-registry`](../mcp-schema-registry/client.md) follow the same fixed-tool pattern for the Kafka broker and schema registry APIs. + +```yaml {3} + +``` + +## Configuration (\* required) + + + + + +## Tools + + diff --git a/src/reference/config/bindings/mcp-kafka/.partials/client.yaml b/src/reference/config/bindings/mcp-kafka/.partials/client.yaml new file mode 100644 index 00000000..489adbb2 --- /dev/null +++ b/src/reference/config/bindings/mcp-kafka/.partials/client.yaml @@ -0,0 +1,33 @@ +mcp_kafka_client: + type: mcp-kafka + kind: client + options: + servers: + - kafka.examples.dev:9092 + routes: + - when: + - tool: create_topics + - tool: delete_topics + - tool: alter_configs + - tool: reset_offsets + guarded: + my_guard: + - kafka:admin + - when: + - tool: produce_message + topics: [ orders ] + guarded: + my_guard: + - kafka:write + - when: + - tool: consume_messages + topics: [ orders ] + - when: + - tool: describe_configs + - tool: list_topics + - tool: describe_topic + - tool: cluster_overview + - tool: list_brokers + - tool: describe_cluster + - tool: list_consumer_groups + - tool: describe_consumer_group diff --git a/src/reference/config/bindings/mcp-kafka/.partials/options.md b/src/reference/config/bindings/mcp-kafka/.partials/options.md new file mode 100644 index 00000000..7a10687f --- /dev/null +++ b/src/reference/config/bindings/mcp-kafka/.partials/options.md @@ -0,0 +1,74 @@ +### options\* + +> `object` + +The `client` specific options. + +```yaml +options: + servers: + - kafka.examples.dev:9092 + authorization: + my_auth: + credentials: + mechanism: plain + username: my_username + password: my_password + topics: + - name: orders +``` + +#### options.servers\* + +> `array` of `string` + +Bootstrap servers to use when connecting to the `kafka` cluster. + +#### options.authorization + +> `object` as map of named `object` + +Credentials used to authenticate this binding's own connection to the `kafka` cluster, keyed by an arbitrary name. At most one entry is allowed. + +#### authorization.credentials\* + +> `object` + +```yaml +credentials: + mechanism: plain + username: my_username + password: my_password +``` + +#### credentials.mechanism\* + +> `enum` [ `plain`, `scram-sha-1`, `scram-sha-256`, `scram-sha-512`, `oauthbearer` ] + +SASL mechanism used to authenticate with the broker. + +#### credentials.username\* + +> `string` + +SASL username. Required when `mechanism` is `plain` or a `scram-sha-*` variant; not allowed with `oauthbearer`. + +#### credentials.password\* + +> `string` + +SASL password. Required when `mechanism` is `plain` or a `scram-sha-*` variant; not allowed with `oauthbearer`. + +#### credentials.token\* + +> `string` + +SASL token. Required when `mechanism` is `oauthbearer`; not allowed with any other mechanism. + +#### options.topics + +> `array` of `object` + +Per-topic key and value validation, applied to `produce_message` calls and to records read back by `consume_messages`. + + diff --git a/src/reference/config/bindings/mcp-kafka/.partials/routes.md b/src/reference/config/bindings/mcp-kafka/.partials/routes.md new file mode 100644 index 00000000..0d7aae8d --- /dev/null +++ b/src/reference/config/bindings/mcp-kafka/.partials/routes.md @@ -0,0 +1,58 @@ +### routes\* + +> `array` of `object` + +Conditional `mcp-kafka` specific routes, matching by tool name and, for `produce_message` and `consume_messages`, by topic. At least one route is required. Routes are evaluated in order; the first matching route wins. + +```yaml +routes: + - when: + - tool: produce_message + topics: [ orders ] + guarded: + my_guard: + - kafka:write + - when: + - tool: consume_messages + topics: [ orders ] +``` + +#### routes[].when + +> `array` of `object` + +List of conditions (any match) restricting this route to particular tools. + +```yaml +routes: + - when: + - tool: create_topics + - tool: delete_topics +``` + +#### when[].tool + +> `string` + +Tool name matched by `tools/call`. Omit to match every tool not already claimed by an earlier route. + +#### when[].topics + +> `array` of `string` + +Topic name allow-list (exact names or `*` glob patterns) restricting this route to matching topics. Only enforced for [`produce_message`](../client.md#produce_message) and [`consume_messages`](../client.md#consume_messages), the only two tools that name a single topic as a routing key — every other tool either takes no topic or names one as a `tools/call` argument rather than a route match, so this list has no effect on them. + +#### routes[].guarded + +> `object` as map of named `array` of `string` + +Roles required by the named guard for a `tools/call` against this route. Roles for the same guard are unioned into one entry; roles naming a different guard add a separate entry that must also authorize. + +```yaml +routes: + - when: + - tool: alter_configs + guarded: + my_guard: + - kafka:admin +``` diff --git a/src/reference/config/bindings/mcp-kafka/.partials/tools.md b/src/reference/config/bindings/mcp-kafka/.partials/tools.md new file mode 100644 index 00000000..77d65647 --- /dev/null +++ b/src/reference/config/bindings/mcp-kafka/.partials/tools.md @@ -0,0 +1,272 @@ +The `mcp-kafka` client exposes a fixed set of intrinsic tools — there is no `options.tools` to author, and no upstream server or spec to derive them from. Each tool's `inputSchema` validates `tools/call` `arguments` before Zilla dispatches the matching Kafka request; a tool with no declared `outputSchema` still returns a result, either as `structuredContent` or as `content` text only. + +### produce_message + +> Not read-only, not idempotent + +Appends one record to a topic. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `topic` | `string` | Yes | Topic to write to. | +| `value` | `string` | Yes | Record value. | +| `key` | `string` | No | Record key. | +| `partition` | `integer` | No | Explicit partition, chosen automatically when omitted. | + +No `outputSchema` is declared; the result is a `content` text summary only. + +### consume_messages + +> Read-only, idempotent + +Reads records from a topic starting at an offset, streaming each record to the reply as it arrives. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `topic` | `string` | Yes | Topic to read from. | +| `partition` | `integer` | No | Specific partition to read, every partition when omitted. | +| `offset` | `integer` | No | Starting offset, the earliest available record when omitted. | +| `limit` | `integer` | No | Maximum records to return (1-100, default 10). | + +No `outputSchema` is declared, though the result's `structuredContent` follows this shape: + +```json +{ + "topic": "orders", + "messages": [ + { "key": null, "headers": [], "value": "hello from mcp-kafka" } + ], + "count": 1 +} +``` + +### create_topics + +> Not destructive + +Creates one or more topics. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `topics` | `array` of `object` | Yes | Topics to create. | +| `topics[].name` | `string` | Yes | Topic name. | +| `topics[].partitions` | `integer` | Yes | Partition count. | +| `topics[].replicas` | `integer` | Yes | Replication factor. | +| `topics[].assignments` | `array` | No | Explicit partition-to-broker placement. | +| `topics[].configs` | `object` | No | Per-topic config overrides. | +| `timeout` | `integer` | No | Request timeout, in milliseconds. | +| `validate_only` | `boolean` | No | Validate the request without creating any topic. | + +`outputSchema`: + +| Property | Type | Required | Description | +| --- | --- | --- | --- | +| `topics` | `array` of `object` | Yes | One entry per requested topic. | +| `topics[].name` | `string` | Yes | Topic name. | +| `topics[].error` | `integer` | Yes | Kafka error code, `0` on success. | +| `topics[].error_message` | `string` | No | Kafka error message, present only on failure. | + +### delete_topics + +> Not read-only, not idempotent + +Deletes one or more topics by name. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `topics` | `array` of `string` | Yes | Topic names to delete. | +| `timeout` | `integer` | No | Request timeout, in milliseconds. | + +`outputSchema` — same shape as [`create_topics`](#create-topics): + +| Property | Type | Required | Description | +| --- | --- | --- | --- | +| `topics` | `array` of `object` | Yes | One entry per requested topic. | +| `topics[].name` | `string` | Yes | Topic name. | +| `topics[].error` | `integer` | Yes | Kafka error code, `0` on success. | +| `topics[].error_message` | `string` | No | Kafka error message, present only on failure. | + +### describe_configs + +> Read-only, idempotent + +Reads the effective configuration of a topic or broker, including values Kafka set by default. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `resource_type` | `enum` [ `topic`, `broker` ] | Yes | Resource kind to describe. | +| `resource_name` | `string` | Yes | Resource name — a topic name, or a broker id. | + +`outputSchema`: + +| Property | Type | Required | Description | +| --- | --- | --- | --- | +| `configs` | `array` of `object` | Yes | Every config Kafka reports for the resource. | +| `configs[].name` | `string` | Yes | Config key. | +| `configs[].value` | `string` | No | Config value. | +| `configs[].is_default` | `boolean` | Yes | Whether the value is a broker default rather than an explicit override. | +| `configs[].is_sensitive` | `boolean` | Yes | Whether Kafka redacted the value. | + +### alter_configs + +> Not destructive + +Sets configs on a topic or broker. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `resource_type` | `enum` [ `topic`, `broker` ] | Yes | Resource kind to alter. | +| `resource_name` | `string` | Yes | Resource name — a topic name, or a broker id. | +| `configs` | `object` as map of named `string` | Yes | Config keys and their new values. | + +`outputSchema`: + +| Property | Type | Required | Description | +| --- | --- | --- | --- | +| `resource_type` | `enum` [ `topic`, `broker` ] | Yes | Resource kind altered. | +| `resource_name` | `string` | Yes | Resource name altered. | +| `updated` | `boolean` | Yes | Whether the change was applied. | + +### list_topics + +> Read-only, idempotent + +Lists every topic on the broker, with each entry's own partition count and replication factor. + +No arguments. + +`outputSchema`: + +| Property | Type | Required | Description | +| --- | --- | --- | --- | +| `topics` | `array` of `object` | Yes | One entry per topic on the broker. | +| `topics[].name` | `string` | Yes | Topic name. | +| `topics[].partition_count` | `integer` | Yes | Partition count. | +| `topics[].replication_factor` | `integer` | Yes | Replication factor. | + +### describe_topic + +> Read-only, idempotent + +Describes one topic by name, reporting each partition's leader, replica set, and in-sync replica (ISR) set. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `topic` | `string` | Yes | Topic to describe. | + +`outputSchema`: + +| Property | Type | Required | Description | +| --- | --- | --- | --- | +| `name` | `string` | Yes | Topic name. | +| `partitions` | `array` of `object` | Yes | One entry per partition. | +| `partitions[].partition_id` | `integer` | Yes | Partition id. | +| `partitions[].leader` | `integer` | Yes | Broker id of the current leader. | +| `partitions[].replicas` | `array` of `integer` | Yes | Broker ids holding a replica. | +| `partitions[].isr` | `array` of `integer` | Yes | Broker ids currently in sync. | + +### cluster_overview + +> Read-only, idempotent + +Summarizes the whole cluster — broker count, controller broker id, and under-replicated and offline partition counts — as a single health check across every topic at once. + +No arguments. + +`outputSchema`: + +| Property | Type | Required | Description | +| --- | --- | --- | --- | +| `broker_count` | `integer` | Yes | Number of brokers in the cluster. | +| `controller_id` | `integer` | Yes | Broker id of the current controller. | +| `under_replicated_partitions` | `integer` | Yes | Partitions with fewer in-sync replicas than configured. | +| `offline_partitions` | `integer` | Yes | Partitions with no available leader. | +| `topic_count` | `integer` | Yes | Number of topics in the cluster. | + +### list_brokers + +> Read-only, idempotent + +Lists every broker in the cluster. + +No arguments. + +`outputSchema`: + +| Property | Type | Required | Description | +| --- | --- | --- | --- | +| `brokers` | `array` of `object` | Yes | One entry per broker. | +| `brokers[].broker_id` | `integer` | Yes | Broker id. | +| `brokers[].host` | `string` | Yes | Broker host. | +| `brokers[].port` | `integer` | Yes | Broker port. | +| `brokers[].rack` | `string` | No | Broker rack id, when configured. | + +### describe_cluster + +> Read-only, idempotent + +Reports the cluster id and the controller broker's id. + +No arguments. + +`outputSchema`: + +| Property | Type | Required | Description | +| --- | --- | --- | --- | +| `cluster_id` | `string` | No | KRaft-generated cluster identifier. | +| `controller_id` | `integer` | Yes | Broker id of the current controller. | +| `authorized_operations` | `integer` | Yes | Bitfield of operations the connection is authorized to perform on the cluster. | + +### list_consumer_groups + +> Read-only, idempotent + +Lists every consumer group known to the cluster. + +No arguments. + +`outputSchema`: + +| Property | Type | Required | Description | +| --- | --- | --- | --- | +| `groups` | `array` of `object` | Yes | One entry per consumer group. | +| `groups[].group_id` | `string` | Yes | Consumer group id. | +| `groups[].state` | `string` | Yes | Group state, such as `Stable` or `Dead`. | + +### describe_consumer_group + +> Read-only, idempotent + +Describes one consumer group by id, including its current members and their partition assignments. A group id that has never committed an offset reports state `Dead` — Kafka's actual behavior for a group that does not yet exist, not an error. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `group_id` | `string` | Yes | Consumer group to describe. | + +`outputSchema`: + +| Property | Type | Required | Description | +| --- | --- | --- | --- | +| `group_id` | `string` | Yes | Consumer group id. | +| `state` | `string` | Yes | Group state, such as `Stable` or `Dead`. | +| `members` | `array` of `object` | Yes | One entry per group member. | +| `members[].member_id` | `string` | Yes | Member id. | +| `members[].client_id` | `string` | Yes | Client id reported by the member. | +| `members[].assignments` | `array` of `object` | No | Partitions assigned to this member. | +| `members[].assignments[].topic` | `string` | Yes | Assigned topic. | +| `members[].assignments[].partition` | `integer` | Yes | Assigned partition. | + +### reset_offsets + +> Not read-only, not idempotent + +Commits an explicit offset for a consumer group on one topic-partition, overwriting whatever the group last committed. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `group` | `string` | Yes | Consumer group to commit for. | +| `topic` | `string` | Yes | Topic of the partition to commit. | +| `partition` | `integer` | Yes | Partition to commit. | +| `offset` | `integer` | Yes | Offset to commit. | + +No `outputSchema` is declared; the result is a `content` text summary only. diff --git a/src/reference/config/bindings/mcp-kafka/README.md b/src/reference/config/bindings/mcp-kafka/README.md new file mode 100644 index 00000000..e16eb466 --- /dev/null +++ b/src/reference/config/bindings/mcp-kafka/README.md @@ -0,0 +1,22 @@ +--- +shortTitle: mcp-kafka +category: + - Binding +tag: + - mcp-kafka + - client +--- + +# mcp-kafka Binding + +The `client` kind `mcp-kafka` binding exposes a fixed set of Kafka broker operations — producing and consuming records, managing topics and their configs, and inspecting brokers and consumer groups — as intrinsic MCP tools, connecting directly to the Kafka cluster named by `options.servers`, with no upstream MCP or REST server and no per-tool schema authoring. + +## client + +> [Full config](./client.md) + +Behave as an `mcp-kafka` `client`. + +```yaml {3} + +``` diff --git a/src/reference/config/bindings/mcp-kafka/client.md b/src/reference/config/bindings/mcp-kafka/client.md new file mode 100644 index 00000000..19a0b583 --- /dev/null +++ b/src/reference/config/bindings/mcp-kafka/client.md @@ -0,0 +1,22 @@ +--- +shortTitle: client +--- + +# mcp-kafka client + +The `mcp-kafka` client binding exposes a fixed set of Kafka broker operations as intrinsic MCP tools, connecting directly to the Kafka cluster named by `options.servers` — unlike [`mcp-openapi`](../mcp-openapi/client.md), there is no upstream server, spec, or per-tool schema to author. [`mcp-kafka-connect`](../mcp-kafka-connect/client.md) and [`mcp-schema-registry`](../mcp-schema-registry/client.md) follow the same fixed-tool pattern for the Kafka Connect and schema registry REST APIs. + +```yaml {3} + +``` + +## Configuration (\* required) + + + + + + +## Tools + + diff --git a/src/reference/config/bindings/mcp-openapi/.partials/client.yaml b/src/reference/config/bindings/mcp-openapi/.partials/client.yaml new file mode 100644 index 00000000..c3536955 --- /dev/null +++ b/src/reference/config/bindings/mcp-openapi/.partials/client.yaml @@ -0,0 +1,29 @@ +mcp_openapi_client: + type: mcp-openapi + kind: client + options: + specs: + github: + catalog: + my_catalog: + subject: github + version: latest + security: + bearerAuth: my_guard + tools: + create_pr: + description: Create a pull request to merge one branch into another. + routes: + - when: + - tool: create_pr + with: + spec: github + operation: create_pr + - when: + - resource: read_order + with: + spec: github + operation: read_order + - with: + spec: github + tag: issues diff --git a/src/reference/config/bindings/mcp-openapi/.partials/options.md b/src/reference/config/bindings/mcp-openapi/.partials/options.md new file mode 100644 index 00000000..75d36bcd --- /dev/null +++ b/src/reference/config/bindings/mcp-openapi/.partials/options.md @@ -0,0 +1,197 @@ +### options + +> `object` + +The `mcp-openapi` specific options. + +```yaml +options: + authorization: + my_guard: + credentials: + headers: + authorization: Bearer {credentials} + specs: + github: + server: https://api.github.com + catalog: + my_catalog: + subject: github + version: latest + overlay: + my_catalog: + subject: github-overlay + version: latest + security: + bearerAuth: my_guard + tools: + create_pr: + description: Create a pull request to merge one branch into another. + summary: "Created pull request #${result.number}" + input: + model: json + catalog: + my_catalog: + - subject: create_pr_input + version: latest + output: + model: json + catalog: + my_catalog: + - subject: create_pr_result + version: latest + resources: + read_order: + description: Read a customer order by id. + mimeType: application/json +``` + +#### options.authorization + +> `object` as map of named `object` + +Guard credentials to inject into every upstream `http` request generated by this binding. At most one guard may be referenced. + +#### authorization.credentials + +> `object` + +Credentials derived from the named guard. + +#### credentials.headers + +> `object` as map of named `string` + +HTTP request headers added to the upstream request, with values resolved from the guarded session. + +- `{credentials}` Replaced with the raw credentials presented to the named guard. +- `{identity}` Replaced with the authorized identity resolved by the named guard. + +#### options.specs + +> `object` as map of named `object` + +OpenAPI specifications available to routed operations. The named key is the spec label referenced by a route's [`with.spec`](#with-spec). + +#### specs.server + +> `string` + +Overrides the server URL declared by the OpenAPI specification, used to resolve the `:scheme`, `:authority`, and base path of the generated upstream `http` request. + +#### specs.catalog + +> `object` as map of named `object` + +Catalog reference resolving the OpenAPI document. The named key references a catalog defined elsewhere in the configuration. + +#### catalog.subject\* + +> `string` + +Subject name identifying the OpenAPI document in the named catalog. + +#### catalog.version + +> `string` | Default: `latest` + +Specific version of the registered OpenAPI document. + +#### specs.overlay + +> `object` as map of named `object` + +Catalog reference resolving an [OpenAPI Overlay](https://github.com/OAI/Overlay-Specification) document, applied to the OpenAPI document before it is parsed. Overlay actions can patch or extend the base document — for example, to add a `security` requirement or `servers` entry — without duplicating it. Uses the same shape as [`specs.catalog`](#specs-catalog). + +#### specs.security + +> `object` as map of named `string` + +Maps each OpenAPI `securityScheme` name declared by the specification to the named guard that authorizes it. Resolution is best-effort: a security requirement naming a scheme absent from this map is simply not enforced, rather than rejecting the operation. A route is only rejected outright when the operation declares multiple OR-alternative security requirements, or when a single alternative requires more than one distinct guard at once — Zilla routes can reference only one guard. + +#### options.tools + +> `object` as map of named `object` + +Overrides for MCP tools generated from routed OpenAPI operations. The named key is the tool name — either an explicit route's [`when[].tool`](#when-tool), or the automatic name assigned to a bulk-selected operation (see [`routes`](#routes)). + +#### tools.description + +> `string` + +Tool description surfaced to MCP clients by `tools/list`, overriding the OpenAPI operation's own `description`, which is itself the fallback before the operation id. + +#### tools.summary + +> `string` + +Result summary template surfaced as the tool-call text result, overriding the OpenAPI operation's own `summary`, which is itself the fallback before a generic literal naming the operation. Supports `${result.x}` interpolation, where `x` references a property of the upstream JSON response. + +#### tools.input + +> `object` + +Model overriding the schema generated from the OpenAPI operation's parameters and request body, used to validate the `tools/call` `arguments` before the upstream `http` request is dispatched. + +```yaml +input: + model: json + catalog: + my_catalog: + - subject: create_pr_input + version: latest +``` + +#### input.model\* + +> `string` + +Model name used to convert and validate the value, such as `json`. + +#### input.catalog + +> `object` as map of named `array` + +Catalog subjects resolving the schema used for validation. + +#### catalog[].subject\* + +> `string` + +Subject name identifying the schema in the named catalog. + +#### catalog[].version + +> `string` | Default: `latest` + +Specific version of the registered schema. + +#### tools.output + +> `object` + +Model overriding the schema generated from the OpenAPI operation's success response, surfaced as the tool-call `structuredContent`. Uses the same shape as [`tools.input`](#tools-input). + +#### options.resources + +> `object` as map of named `object` + +Overrides for MCP resources generated from routed OpenAPI operations. The named key is the resource identifier used by a route's [`when[].resource`](#when-resource) — not the URI ultimately surfaced by `resources/list`, which is derived from the OpenAPI path. + +#### resources.description + +> `string` + +Resource description surfaced to MCP clients by `resources/list`, overriding the OpenAPI operation's own `description`, which is itself the fallback before the operation id. + +#### resources.mimeType + +> `string` + +MIME type of the resource contents surfaced to MCP clients, overriding the MIME type derived from the OpenAPI operation's success response content. + +#### resources.output + +> `object` + +Model overriding the schema generated from the OpenAPI operation's success response, surfaced as the resource `contents`. Uses the same shape as [`tools.input`](#tools-input). diff --git a/src/reference/config/bindings/mcp-openapi/.partials/routes.md b/src/reference/config/bindings/mcp-openapi/.partials/routes.md new file mode 100644 index 00000000..7c27e665 --- /dev/null +++ b/src/reference/config/bindings/mcp-openapi/.partials/routes.md @@ -0,0 +1,148 @@ +### routes\* + +> `array` of `object` + +Conditional `mcp-openapi` specific routes, compiling matched OpenAPI operations into the generated `mcp-http` proxy as MCP tools or resources. At least one route is required. + +A route either names a single operation explicitly, or bulk-selects many operations at once: + +- **Explicit** — [`with.operation`](#with-operation) names one exact `operationId`. May pair with [`when[].tool`](#when-tool) or [`when[].resource`](#when-resource) to name and shape the generated MCP primitive. +- **Bulk** — [`with.spec`](#with-spec) alone selects every operation in the spec, [`with.tag`](#with-tag) selects every operation carrying the named OpenAPI tag, or [`with.operation`](#with-operation) containing a `*` selects every operation whose id matches the glob pattern. Bulk-selected operations always become tools, never resources, and cannot be named with `when[].tool` or `when[].resource` — each is named automatically. [`when[].capability`](#when-capability) can still restrict a bulk route to only `tool` or only `resource`. + +```yaml +routes: + - when: + - tool: create_pr + with: + spec: github + operation: create_pr + - with: + spec: github + tag: issues + - with: + spec: github + operation: "search_*" +``` + +::: info Route precedence and default tool naming +Routes are evaluated in order, and the first route to claim an operation removes it from consideration by every later route. A bulk-selected operation not given an explicit name is named after its `operationId` converted to `snake_case`, falling back to a slug of its method and path when the id is absent or already taken, then a numeric suffix on any further collision. +::: + +#### routes[].guarded + +> `object` as map of named `array` of `string` + +Additional roles required by the named guard, independent of any guard already resolved from the OpenAPI operation's own `security` requirement (see [`specs.security`](#specs-security)). Roles for the same guard are unioned into one entry; roles naming a different guard add a separate entry that must also authorize. + +```yaml +routes: + - guarded: + my_guard: + - pr:write +``` + +#### routes[].when + +> `array` of `object` + +List of conditions (any match) to name or filter the tool or resource generated for the matched route. +Read more: [When a route matches](/concepts/protocol/README.md#route-matches) + +```yaml +routes: + - when: + - tool: create_pr + - resource: read_order +``` + +#### when[].tool + +> `string` + +Tool name surfaced to MCP clients by `tools/list` and matched by `tools/call`, naming the explicit OpenAPI operation routed by [`with.operation`](#with-operation). Not allowed on a bulk route. + +#### when[].resource + +> `string` + +Resource identifier matched by `resources/read`, naming the explicit OpenAPI operation routed by [`with.operation`](#with-operation). Not allowed on a bulk route. + +::: info Resource vs. resource template +An operation whose OpenAPI path contains a `{param}` capture is surfaced as a resource template through `resources/templates/list`. Otherwise it is a concrete resource surfaced through `resources/list`, with any query parameters appended to its URI as an RFC 6570 `{?name1,name2}` suffix rather than disqualifying it from being concrete. +::: + +#### when[].capability + +> `array` of `enum` [ `tool`, `resource` ] + +Restricts a bulk route to only the listed primitive kinds. An explicit route naming [`when[].tool`](#when-tool) or [`when[].resource`](#when-resource) is filtered accordingly whether or not `capability` is also listed. + +```yaml +routes: + - when: + - capability: [ tool ] + with: + spec: github + tag: issues +``` + +#### routes[].with\* + +> `object` + +Resolves the OpenAPI operation or operations compiled into the generated `mcp-http` proxy for this route. + +```yaml +with: + spec: github + operation: create_pr +``` + +#### with.spec\* + +> `string` + +Spec label to route to, referencing an entry in [`options.specs`](#options-specs). + +#### with.operation + +> `string` + +Exact OpenAPI `operationId` to route, or a `*` glob pattern matching many operation ids in bulk, within the named [`spec`](#with-spec). Cannot be combined with [`tag`](#with-tag). + +#### with.tag + +> `string` + +OpenAPI tag to bulk-select every operation carrying it, within the named [`spec`](#with-spec). Cannot be combined with [`operation`](#with-operation). + +#### with.params + +> `object` as map of named `string` + +Rebinds an OpenAPI path, query, header, or cookie parameter to a different expression than its default `${args.name}` (tool) or `${params.name}` (resource) passthrough. The named key is the OpenAPI parameter name; the value is the replacement expression, with or without the surrounding `${ }`. Applies to every operation matched by the route, so it works the same on a bulk route as on an explicit one. + +```yaml +with: + spec: github + operation: create_pr + params: + owner: ${args.repository.owner} + repo: ${args.repository.name} +``` + +#### with.body + +> `object` as map of named `string` + +Explicit upstream request body, mapping each body property to an interpolated value, in place of the schema generated from the OpenAPI operation's request body. Supports `${args.x}` interpolation, where `x` references a property of the `tools/call` arguments. Use a template to rename or restructure arguments before dispatch. + +```yaml +with: + spec: github + operation: create_pr + body: + title: ${args.title} + head: ${args.pr.branch} + base: ${args.pr.target} +``` diff --git a/src/reference/config/bindings/mcp-openapi/README.md b/src/reference/config/bindings/mcp-openapi/README.md new file mode 100644 index 00000000..300bbbfe --- /dev/null +++ b/src/reference/config/bindings/mcp-openapi/README.md @@ -0,0 +1,22 @@ +--- +shortTitle: mcp-openapi +category: + - Binding +tag: + - mcp-openapi + - client +--- + +# mcp-openapi Binding + +The `client` kind `mcp-openapi` binding reads OpenAPI specifications from a catalog and compiles routed operations — named individually or bulk-selected by spec, tag, or glob pattern — into a generated `mcp-http` proxy, exposing them as MCP tools and resources with a single spec parse and no protocol-specific code. + +## client + +> [Full config](./client.md) + +Behave as an `mcp-openapi` `client`. + +```yaml {3} + +``` diff --git a/src/reference/config/bindings/mcp-openapi/client.md b/src/reference/config/bindings/mcp-openapi/client.md new file mode 100644 index 00000000..4473b5ff --- /dev/null +++ b/src/reference/config/bindings/mcp-openapi/client.md @@ -0,0 +1,17 @@ +--- +shortTitle: client +--- + +# mcp-openapi client + +The `mcp-openapi` client binding parses OpenAPI specifications from a catalog and compiles routed operations — named individually or bulk-selected by spec, tag, or glob pattern — into a generated composite `mcp-http` proxy binding, exposing them as MCP tools and resources with a single spec parse. + +```yaml {3} + +``` + +## Configuration (\* required) + + + + diff --git a/src/reference/config/bindings/mcp-schema-registry/.partials/client.yaml b/src/reference/config/bindings/mcp-schema-registry/.partials/client.yaml new file mode 100644 index 00000000..dcc24465 --- /dev/null +++ b/src/reference/config/bindings/mcp-schema-registry/.partials/client.yaml @@ -0,0 +1,13 @@ +mcp_schema_registry_client: + type: mcp-schema-registry + kind: client + options: + server: http://karapace-registry.examples.dev:8081 + routes: + - when: + - tool: register_schema + guarded: + my_guard: + - kafka-sr:write + - when: + - tool: "*" diff --git a/src/reference/config/bindings/mcp-schema-registry/.partials/options.md b/src/reference/config/bindings/mcp-schema-registry/.partials/options.md new file mode 100644 index 00000000..7d6e6b13 --- /dev/null +++ b/src/reference/config/bindings/mcp-schema-registry/.partials/options.md @@ -0,0 +1,16 @@ +### options\* + +> `object` + +The `client` specific options. + +```yaml +options: + server: http://karapace-registry.examples.dev:8081 +``` + +#### options.server\* + +> `string` + +Base URL of the schema registry this binding proxies to. diff --git a/src/reference/config/bindings/mcp-schema-registry/.partials/routes.md b/src/reference/config/bindings/mcp-schema-registry/.partials/routes.md new file mode 100644 index 00000000..3920b6ad --- /dev/null +++ b/src/reference/config/bindings/mcp-schema-registry/.partials/routes.md @@ -0,0 +1,50 @@ +### routes\* + +> `array` of `object` + +Conditional `mcp-schema-registry` specific routes, matching by tool name or glob pattern. At least one route is required. Routes are evaluated in order; the first matching route wins. + +```yaml +routes: + - when: + - tool: register_schema + guarded: + my_guard: + - kafka-sr:write + - when: + - tool: "*" +``` + +#### routes[].when\* + +> `array` of `object` + +List of conditions (any match) restricting this route to particular tools. Required. + +```yaml +routes: + - when: + - tool: register_schema + - tool: set_compatibility +``` + +#### when[].tool\* + +> `string` or `array` of `string` + +Tool name matched by `tools/call`, or a `*` glob pattern matching many tool names in bulk (such as `list_*`). Required. + +#### routes[].guarded + +> `object` as map of named `array` of `string` + +Roles required by the named guard for a `tools/call` against this route. Roles for the same guard are unioned into one entry; roles naming a different guard add a separate entry that must also authorize. + +```yaml +routes: + - when: + - tool: register_schema + guarded: + my_guard: + - kafka-sr:write +``` diff --git a/src/reference/config/bindings/mcp-schema-registry/.partials/tools.md b/src/reference/config/bindings/mcp-schema-registry/.partials/tools.md new file mode 100644 index 00000000..2073a549 --- /dev/null +++ b/src/reference/config/bindings/mcp-schema-registry/.partials/tools.md @@ -0,0 +1,113 @@ +The `mcp-schema-registry` client exposes a fixed set of intrinsic tools, derived from a bundled schema registry API specification — there is no `options.tools` to author, and no upstream server or spec to select. Each tool's `inputSchema` validates `tools/call` `arguments` before Zilla dispatches the matching request to `options.server`. None of these tools declare a fixed `outputSchema`, so each tool's `structuredContent` mirrors the raw upstream JSON response with no fixed property list, and its `summary` text may interpolate fields out of that same response, such as `${result.id}`. + +### list_subjects + +> Read-only, idempotent + +Lists every subject registered in the schema registry. + +No arguments. + +The result's `structuredContent` mirrors the raw upstream JSON response — an array of subject names. + +### describe_subject + +> Read-only, idempotent + +Lists the schema version numbers registered for a subject. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `subject` | `string` | Yes | Subject to list versions for. | + +The result's `structuredContent` mirrors the raw upstream JSON response — an array of version numbers. + +### register_schema + +> Not destructive, not idempotent + +Registers a new schema version under a subject. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `subject` | `string` | Yes | Subject to register the schema under. | +| `schema` | `string` | Yes | Schema document to register. | +| `schemaType` | `string` | No | Schema format, such as `AVRO`, `JSON`, or `PROTOBUF`. Defaults to `AVRO` when omitted. | + +The summary interpolates `${result.id}`, such as `Registered schema with id 1`. + +### get_schema + +> Read-only, idempotent + +Retrieves a specific registered schema version for a subject. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `subject` | `string` | Yes | Subject to read from. | +| `version` | `string` | Yes | Schema version number, or `latest`. | + +The summary interpolates `${result.id}` and `${result.version}`, such as `Retrieved schema id 1, version 1`. + +### delete_schema_version + +> Destructive, idempotent + +Deletes a specific registered schema version for a subject. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `subject` | `string` | Yes | Subject to delete from. | +| `version` | `string` | Yes | Schema version number, or `latest`. | + +### delete_subject + +> Destructive, idempotent + +Deletes a subject and every schema version registered under it. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `subject` | `string` | Yes | Subject to delete. | + +The result's `structuredContent` mirrors the raw upstream JSON response — an array of the deleted subject's version numbers. + +### check_compatibility + +> Read-only, idempotent + +Checks whether a schema is compatible with a specific already-registered version of a subject. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `subject` | `string` | Yes | Subject to check compatibility against. | +| `version` | `string` | Yes | Schema version number, or `latest`, to check compatibility against. | +| `schema` | `string` | Yes | Schema document to check. | +| `schemaType` | `string` | No | Schema format, such as `AVRO`, `JSON`, or `PROTOBUF`. Defaults to `AVRO` when omitted. | + +The summary interpolates `${result.is_compatible}`, such as `Compatibility check result: true`. + +### get_compatibility + +> Read-only, idempotent + +Reads the compatibility level configured for a subject. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `subject` | `string` | Yes | Subject to read the compatibility level of. | + +The summary interpolates `${result.compatibilityLevel}`, such as `Compatibility level is FULL`. + +### set_compatibility + +> Not destructive, idempotent + +Sets the compatibility level for a subject. + +| Argument | Type | Required | Description | +| --- | --- | --- | --- | +| `subject` | `string` | Yes | Subject to set the compatibility level of. | +| `compatibility` | `string` | Yes | Compatibility level, such as `BACKWARD`, `FORWARD`, `FULL`, or `NONE`. | + +The summary interpolates `${result.compatibility}`, such as `Compatibility level set to FULL`. diff --git a/src/reference/config/bindings/mcp-schema-registry/README.md b/src/reference/config/bindings/mcp-schema-registry/README.md new file mode 100644 index 00000000..50029e0a --- /dev/null +++ b/src/reference/config/bindings/mcp-schema-registry/README.md @@ -0,0 +1,22 @@ +--- +shortTitle: mcp-schema-registry +category: + - Binding +tag: + - mcp-schema-registry + - client +--- + +# mcp-schema-registry Binding + +The `client` kind `mcp-schema-registry` binding exposes a Karapace-compatible schema registry's subject, schema, and compatibility operations as a fixed set of intrinsic MCP tools, connecting directly to the registry named by `options.server`, with no upstream MCP server, OpenAPI spec, or per-tool schema authoring. + +## client + +> [Full config](./client.md) + +Behave as an `mcp-schema-registry` `client`. + +```yaml {3} + +``` diff --git a/src/reference/config/bindings/mcp-schema-registry/client.md b/src/reference/config/bindings/mcp-schema-registry/client.md new file mode 100644 index 00000000..1eea2b10 --- /dev/null +++ b/src/reference/config/bindings/mcp-schema-registry/client.md @@ -0,0 +1,21 @@ +--- +shortTitle: client +--- + +# mcp-schema-registry client + +The `mcp-schema-registry` client binding exposes a Karapace-compatible schema registry's subject, schema, and compatibility operations as a fixed set of intrinsic MCP tools, connecting directly to the registry named by `options.server` — unlike [`mcp-openapi`](../mcp-openapi/client.md), there is no upstream spec or per-tool schema to author. [`mcp-kafka`](../mcp-kafka/client.md) and [`mcp-kafka-connect`](../mcp-kafka-connect/client.md) follow the same fixed-tool pattern for the Kafka broker and Kafka Connect REST APIs. + +```yaml {3} + +``` + +## Configuration (\* required) + + + + + +## Tools + + diff --git a/src/reference/config/bindings/mcp/.partials/options-authorization-client.md b/src/reference/config/bindings/mcp/.partials/options-authorization-client.md new file mode 100644 index 00000000..bf58407a --- /dev/null +++ b/src/reference/config/bindings/mcp/.partials/options-authorization-client.md @@ -0,0 +1,17 @@ +#### options.authorization + +> `object` as map of named `object` properties + +Authorization by a named guard, used to authorize outbound requests to the upstream MCP server. + +```yaml +authorization: + my_jwt_guard: + credentials: "Bearer {credentials}" +``` + +#### authorization.credentials + +> `string` | Default: `Bearer {credentials}` + +Template used to build the outbound `Authorization` header. When it contains the `{credentials}` placeholder, the placeholder is replaced with the value returned by the named guard. When omitted from the template, the header is sent as the literal template value regardless of the guard outcome. diff --git a/src/reference/config/bindings/mcp/.partials/options-authorization-server.md b/src/reference/config/bindings/mcp/.partials/options-authorization-server.md new file mode 100644 index 00000000..0eeab827 --- /dev/null +++ b/src/reference/config/bindings/mcp/.partials/options-authorization-server.md @@ -0,0 +1,17 @@ +#### options.authorization + +> `object` as map of named `object` properties + +Authorization by a named guard, used to validate inbound MCP requests. A request with no `Authorization` header is admitted as unauthorized, matching how an unauthenticated request reaches an unguarded route elsewhere in Zilla; a request whose `Authorization` header is present but does not match the [`credentials`](#authorization-credentials) template, or whose extracted credentials the guard rejects, is rejected outright with a `401` response and a `WWW-Authenticate` challenge. + +```yaml +authorization: + my_jwt_guard: + credentials: "Bearer {credentials}" +``` + +#### authorization.credentials + +> `string` | Default: `Bearer {credentials}` + +Template matched against the inbound `Authorization` header, extracting the captured value in place of the required `{credentials}` placeholder and passing it to the named guard to authorize the session. diff --git a/src/reference/config/bindings/mcp/.partials/options-authorization.md b/src/reference/config/bindings/mcp/.partials/options-authorization.md deleted file mode 100644 index ca75e531..00000000 --- a/src/reference/config/bindings/mcp/.partials/options-authorization.md +++ /dev/null @@ -1,17 +0,0 @@ -#### options.authorization - -> `object` as map of named `object` properties - -Authorization by a named guard. - -```yaml -authorization: - my_jwt_guard: - credentials: scope -``` - -#### authorization.credentials - -> `string` - -Credentials used by the named guard to authorize the MCP session. diff --git a/src/reference/config/bindings/mcp/.partials/options-proxy.md b/src/reference/config/bindings/mcp/.partials/options-proxy.md index 1f9ed273..a2be816c 100644 --- a/src/reference/config/bindings/mcp/.partials/options-proxy.md +++ b/src/reference/config/bindings/mcp/.partials/options-proxy.md @@ -41,6 +41,110 @@ Authorization by a named guard used when refreshing cached entries. Credentials used by the named guard when refreshing cached entries. +#### cache.tools + +> `object` + +Tool-related cache configuration. + +#### tools.search + +> `object` + +Agent-callable tool search over cached tools. Injects three synthetic tools into `tools/list` responses, each answering its `tools/call` requests directly from the cache instead of routing to an upstream MCP server: + +- `search_tools` ranks cached tools by relevance to a natural-language `query` argument and returns name and description matches. +- `describe_tool` resolves the full cached definition, including input and output schema, of a tool named exactly as returned by `search_tools`. +- `execute_tool` invokes a tool by name exactly as `tools/call` would, once its schema is known via `describe_tool`. + +```yaml +tools: + search: + toolkit: zilla +``` + +#### search.toolkit + +> `string` + +Optional `toolkit__` prefix applied to the three synthetic tool names (`search_tools`, `describe_tool`, `execute_tool`), matching the naming convention used for proxied tools. When omitted, the tools are exposed unprefixed. + +#### search.limit + +> `integer` | Default: `5` + +Maximum number of matching tools returned, further capped by any `max_results` argument in the request. + +#### search.fields + +> `array` of `enum` [ `name`, `description`, `output-schema` ] | Default: `[ name, description ]` + +Tool fields indexed for ranking. + +#### search.weights + +> `object` as map of named `number` + +Per-field weight multiplier applied to term frequency during ranking. Keys reference entries in [`fields`](#search-fields). + +#### search.type + +> `enum` [ `keyword` ] + +Shorthand for a single ranking backend with no backend-specific fields. Mutually exclusive with [`index`](#search-index). + +```yaml +search: + toolkit: zilla + type: keyword +``` + +#### search.index + +> `array` of `object` + +One or more ranking backends, fused by reciprocal rank when more than one is configured. Mutually exclusive with [`type`](#search-type). + +```yaml +search: + toolkit: zilla + index: + - type: keyword +``` + +#### index[].type\* + +> `enum` [ `keyword` ] + +Ranking backend. Only `keyword` (BM25 ranking over the configured fields) is available. + +#### tools.eager + +> `object` + +Eager/cold partitioning of cached tools in `tools/list` responses, applied after per-session scope filtering. Cold tools are annotated `defer_loading: true` when no [tool search](#tools-search) is configured, or omitted from `tools/list` entirely — reachable only through search results — when one is. + +```yaml +tools: + eager: + policy: explicit + match: + - github__list_repos + - "slack__*" +``` + +#### eager.policy + +> `enum` [ `none`, `all`, `explicit` ] | Default: `none` + +Which cached tools are eager. `none` marks every tool cold, `all` marks every tool eager, and `explicit` marks only tools matching [`match`](#eager-match) eager. + +#### eager.match + +> `array` of `string` + +Glob patterns of tool names admitted to the eager set, where `*` matches any sequence of characters. Required when `policy` is `explicit`; not allowed for any other policy. + #### options.tools > `enum` [ `avro`, `boolean`, `double`, `float`, `int32`, `int64`, `json`, `string` ], `object` diff --git a/src/reference/config/bindings/mcp/.partials/options-server.md b/src/reference/config/bindings/mcp/.partials/options-server.md index e1f0fc76..0eae76b6 100644 --- a/src/reference/config/bindings/mcp/.partials/options-server.md +++ b/src/reference/config/bindings/mcp/.partials/options-server.md @@ -25,6 +25,6 @@ Path on which the binding receives the authorization callback during elicitation #### elicitation.timeout -> `string` | Default: `PT0S` +> `string` -Maximum time to wait for the client to complete elicitation before the request fails. +Maximum time to wait for the client to complete elicitation before the request fails. When omitted, no timeout is enforced and the binding waits indefinitely for elicitation to complete. diff --git a/src/reference/config/bindings/mcp/.partials/proxy.yaml b/src/reference/config/bindings/mcp/.partials/proxy.yaml index 699e2cbc..8591836b 100644 --- a/src/reference/config/bindings/mcp/.partials/proxy.yaml +++ b/src/reference/config/bindings/mcp/.partials/proxy.yaml @@ -9,9 +9,7 @@ mcp_proxy: - exit: app1 when: - toolkit: bluesky - capability: - - tools - tools: + tool: - post_* - exit: app2 when: diff --git a/src/reference/config/bindings/mcp/.partials/routes-client.md b/src/reference/config/bindings/mcp/.partials/routes-client.md new file mode 100644 index 00000000..eeaca2c4 --- /dev/null +++ b/src/reference/config/bindings/mcp/.partials/routes-client.md @@ -0,0 +1,64 @@ +### routes + +> `array` of `object` + +Conditional `mcp` specific routes, resolved per matched tool, prompt, or resource, used to authorize individual `tools/call`, `prompts/get`, and `resources/read` requests against the upstream MCP server. + +```yaml +routes: + - exit: net_client + when: + - tool: + - get_weather + - exit: net_client + when: + - tool: + - get_status + guarded: + my_jwt_guard: + - read +``` + +#### routes[].guarded + +> `object` as map of named `array` of `string` + +Roles required by the named guard. When a guarded route matches a requested tool, prompt, or resource, the session must be authorized for the listed roles, otherwise the request is rejected. Also drives which entries are stamped with `securitySchemes` in `tools/list` responses. + +```yaml +routes: + - guarded: + my_jwt_guard: + - read +``` + +#### routes[].when + +> `array` of `object` + +List of conditions (any match) to match this route. +Read more: [When a route matches](/concepts/protocol/README.md#route-matches) + +#### when[].tool + +> `string` or `array` of `string` + +Glob patterns of tool names to match, where `*` matches any sequence of characters. A bare string is shorthand for a single-element array. When omitted, all tools are admitted. + +#### when[].prompt + +> `string` or `array` of `string` + +Glob patterns of prompt names to match, where `*` matches any sequence of characters. A bare string is shorthand for a single-element array. When omitted, all prompts are admitted. + +#### when[].resource + +> `string` or `array` of `string` + +Glob patterns of resource URIs to match, where `*` matches any sequence of characters. A bare string is shorthand for a single-element array. When omitted, all resources are admitted. + +#### routes[].exit + +> `string` + +Next binding when following this route. diff --git a/src/reference/config/bindings/mcp/.partials/routes-proxy.md b/src/reference/config/bindings/mcp/.partials/routes-proxy.md index ad543d43..961a4d45 100644 --- a/src/reference/config/bindings/mcp/.partials/routes-proxy.md +++ b/src/reference/config/bindings/mcp/.partials/routes-proxy.md @@ -4,6 +4,19 @@ Conditional `mcp` specific routes. +#### routes[].guarded + +> `object` as map of named `array` of `string` + +Roles required by the named guard. When a guarded route matches, drives scope-based filtering of `tools/list`, `prompts/list`, and `resources/list` responses, admitting only the entries the caller's roles allow. + +```yaml +routes: + - guarded: + my_jwt_guard: + - read +``` + #### routes[].when > `array` of `object` @@ -17,29 +30,23 @@ Read more: [When a route matches](/concepts/protocol/README.md#route-matches) Toolkit name to match. -#### when[].capability - -> `array` of `enum` [ `tools`, `prompts`, `resources` ] - -MCP capabilities to match. - -#### when[].tools +#### when[].tool -> `array` of `string` +> `string` or `array` of `string` -Glob patterns of tool names to expose, where `*` matches any sequence of characters. Only tools whose name matches a pattern are routed. Valid when the `tools` capability is enabled. When omitted, all tools are admitted. +Glob patterns of tool names to expose, where `*` matches any sequence of characters. Only tools whose name matches a pattern are routed. A bare string is shorthand for a single-element array. Presence of `tool` activates the tools capability for this condition; when none of `tool`, `prompt`, or `resource` are given, every capability is admitted. -#### when[].prompts +#### when[].prompt -> `array` of `string` +> `string` or `array` of `string` -Glob patterns of prompt names to expose, where `*` matches any sequence of characters. Only prompts whose name matches a pattern are routed. Valid when the `prompts` capability is enabled. When omitted, all prompts are admitted. +Glob patterns of prompt names to expose, where `*` matches any sequence of characters. Only prompts whose name matches a pattern are routed. A bare string is shorthand for a single-element array. Presence of `prompt` activates the prompts capability for this condition. -#### when[].resources +#### when[].resource -> `array` of `string` +> `string` or `array` of `string` -Glob patterns of resource URIs to expose, where `*` matches any sequence of characters. Only resources whose URI matches a pattern are routed. Valid when the `resources` capability is enabled. When omitted, all resources are admitted. +Glob patterns of resource URIs to expose, where `*` matches any sequence of characters. Only resources whose URI matches a pattern are routed. A bare string is shorthand for a single-element array. Presence of `resource` activates the resources capability for this condition. Applies to both `resources/list` and `resources/templates/list`. #### routes[].with @@ -57,7 +64,7 @@ Cache override configuration for this route. > `string` -Credentials used by the named guard when populating the cache for this route. +Credentials used by the named guard when populating the cache for this route. When omitted, falls back to [`options.cache.authorization`](#cache-authorization)'s credentials. #### routes[].exit @@ -70,10 +77,11 @@ routes: - exit: app1 when: - toolkit: bluesky - capability: - - tools - tools: + tool: - post_* + guarded: + my_jwt_guard: + - read - exit: app2 when: - toolkit: quartz diff --git a/src/reference/config/bindings/mcp/.partials/server.yaml b/src/reference/config/bindings/mcp/.partials/server.yaml index 2b8b4bd1..600b9276 100644 --- a/src/reference/config/bindings/mcp/.partials/server.yaml +++ b/src/reference/config/bindings/mcp/.partials/server.yaml @@ -6,5 +6,5 @@ mcp_server: callback: auth/callback authorization: my_jwt_guard: - credentials: scope + credentials: "Bearer {credentials}" exit: mcp_client diff --git a/src/reference/config/bindings/mcp/README.md b/src/reference/config/bindings/mcp/README.md index 9ff0ec67..ff60e46e 100644 --- a/src/reference/config/bindings/mcp/README.md +++ b/src/reference/config/bindings/mcp/README.md @@ -36,7 +36,7 @@ The `client` kind `mcp` binding forwards outbound MCP requests to the upstream M > [Full config](./proxy.md) -The `proxy` kind `mcp` binding routes inbound MCP requests to upstream MCP servers based on toolkit, capability, and per-route tool, prompt, and resource filters. +The `proxy` kind `mcp` binding routes inbound MCP requests to upstream MCP servers based on toolkit and per-route tool, prompt, and resource filters. ```yaml {3} diff --git a/src/reference/config/bindings/mcp/client.md b/src/reference/config/bindings/mcp/client.md index 4e2000fe..9cc4b215 100644 --- a/src/reference/config/bindings/mcp/client.md +++ b/src/reference/config/bindings/mcp/client.md @@ -13,6 +13,7 @@ The mcp client binding forwards outbound MCP requests to an upstream MCP server. ## Configuration (\* required) - + + diff --git a/src/reference/config/bindings/mcp/proxy.md b/src/reference/config/bindings/mcp/proxy.md index 459c43db..42bbfa7c 100644 --- a/src/reference/config/bindings/mcp/proxy.md +++ b/src/reference/config/bindings/mcp/proxy.md @@ -4,7 +4,7 @@ shortTitle: proxy # mcp proxy -The mcp proxy binding routes inbound MCP requests to upstream MCP servers based on toolkit, capability, and per-route tool, prompt, and resource filters. +The mcp proxy binding routes inbound MCP requests to upstream MCP servers based on toolkit and per-route tool, prompt, and resource filters. ```yaml {3} diff --git a/src/reference/config/bindings/mcp/server.md b/src/reference/config/bindings/mcp/server.md index 934f6e60..e0dc1fa3 100644 --- a/src/reference/config/bindings/mcp/server.md +++ b/src/reference/config/bindings/mcp/server.md @@ -13,6 +13,6 @@ The mcp server binding accepts inbound MCP client connections, handling authoriz ## Configuration (\* required) - +