@aws-cdk/aws-bedrock-agentcore-alpha 2.238.0-alpha.0 → 2.239.0-alpha.0

package/lib/gateway/targets/target-configuration.d.ts

@@ -1,3 +1,4 @@
+import type { IRestApi } from 'aws-cdk-lib/aws-apigateway';
 import type { IFunction } from 'aws-cdk-lib/aws-lambda';
 import type { Construct } from 'constructs';
 import type { IGateway } from '../gateway-base';
@@ -228,3 +229,248 @@ export declare class McpServerTargetConfiguration extends McpTargetConfiguration
      */
     private validateEndpoint;
 }
+/******************************************************************************
+ *                     API Gateway Target Configuration
+ *****************************************************************************/
+/**
+ * HTTP methods supported by API Gateway
+ */
+export declare enum ApiGatewayHttpMethod {
+    /** GET method */
+    GET = "GET",
+    /** POST method */
+    POST = "POST",
+    /** PUT method */
+    PUT = "PUT",
+    /** DELETE method */
+    DELETE = "DELETE",
+    /** PATCH method */
+    PATCH = "PATCH",
+    /** HEAD method */
+    HEAD = "HEAD",
+    /** OPTIONS method */
+    OPTIONS = "OPTIONS"
+}
+/**
+ * Configuration for filtering API Gateway tools
+ *
+ * Tool filters allow you to select REST API operations using path and method combinations.
+ * Each filter supports two path matching strategies:
+ * - **Explicit paths**: Matches a single specific path, such as `/pets/{petId}`
+ * - **Wildcard paths**: Matches all paths starting with the specified prefix, such as `/pets/*`
+ */
+export interface ApiGatewayToolFilter {
+    /**
+     * The resource path to filter
+     * Can be an explicit path (e.g., `/pets/{petId}`) or a wildcard path (e.g., `/pets/*`)
+     * Must start with a forward slash
+     */
+    readonly filterPath: string;
+    /**
+     * List of HTTP methods to include for this path
+     * Each filter specifies both a path and a list of HTTP methods
+     * Multiple filters can overlap and duplicates are automatically de-duplicated
+     */
+    readonly methods: ApiGatewayHttpMethod[];
+}
+/**
+ * Configuration for overriding API Gateway tool metadata
+ *
+ * Tool overrides allow you to customize the tool name or description for specific operations
+ * after filtering. Each override must specify an explicit path and a single HTTP method.
+ * The override must match an operation that exists in your API and must correspond to one
+ * of the operations resolved by your filters.
+ */
+export interface ApiGatewayToolOverride {
+    /**
+     * The explicit resource path (no wildcards)
+     * Must match an operation that exists in your API
+     */
+    readonly path: string;
+    /**
+     * The HTTP method for this override
+     * Must be a single method (no wildcards)
+     */
+    readonly method: ApiGatewayHttpMethod;
+    /**
+     * The custom tool name
+     * If not provided, the operationId from the OpenAPI definition will be used
+     */
+    readonly name: string;
+    /**
+     * Optional custom description for the tool
+     * @default - No custom description
+     */
+    readonly description?: string;
+}
+/**
+ * Configuration for passing metadata (headers and query parameters) to the API Gateway target
+ */
+export interface MetadataConfiguration {
+    /**
+     * List of query parameter names to pass through to the target
+     *
+     * Constraints:
+     * - Array must contain 1-10 items
+     * - Each parameter name must be 1-40 characters
+     * - Cannot be an empty array
+     *
+     * @default - No query parameters are passed through
+     */
+    readonly allowedQueryParameters?: string[];
+    /**
+     * List of request header names to pass through to the target
+     *
+     * Constraints:
+     * - Array must contain 1-10 items
+     * - Each header name must be 1-100 characters
+     * - Cannot be an empty array
+     *
+     * @default - No request headers are passed through
+     */
+    readonly allowedRequestHeaders?: string[];
+    /**
+     * List of response header names to pass through from the target
+     *
+     * Constraints:
+     * - Array must contain 1-10 items
+     * - Each header name must be 1-100 characters
+     * - Cannot be an empty array
+     *
+     * @default - No response headers are passed through
+     */
+    readonly allowedResponseHeaders?: string[];
+}
+/**
+ * Configuration for API Gateway tools
+ *
+ * The API Gateway tool configuration defines which operations from your REST API
+ * are exposed as tools. It requires a list of tool filters to select operations
+ * to expose, and optionally accepts tool overrides to customize tool metadata.
+ */
+export interface ApiGatewayToolConfiguration {
+    /**
+     * List of tool filters to select operations
+     * At least one filter is required
+     */
+    readonly toolFilters: ApiGatewayToolFilter[];
+    /**
+     * Optional list of tool overrides to customize tool metadata
+     * Each override must correspond to an operation selected by the filters
+     * @default - No tool overrides
+     */
+    readonly toolOverrides?: ApiGatewayToolOverride[];
+}
+/**
+ * Properties for creating an API Gateway target configuration
+ */
+export interface ApiGatewayTargetConfigurationProps {
+    /**
+     * The REST API to integrate with
+     * Must be in the same account and region as the gateway
+     */
+    readonly restApi: IRestApi;
+    /**
+     * The stage name of the REST API
+     * @default - Uses the deployment stage from the RestApi (restApi.deploymentStage.stageName)
+     */
+    readonly stage?: string;
+    /**
+     * Tool configuration defining which operations to expose
+     */
+    readonly apiGatewayToolConfiguration: ApiGatewayToolConfiguration;
+    /**
+     * Metadata configuration for passing headers and query parameters
+     * Allows you to pass additional context through headers and query parameters
+     * @default - No metadata configuration
+     */
+    readonly metadataConfiguration?: MetadataConfiguration;
+}
+/**
+ * Configuration for API Gateway-based MCP targets
+ *
+ * This configuration connects your gateway to an Amazon API Gateway REST API stage.
+ * The gateway translates incoming MCP requests into HTTP requests to your REST API
+ * and handles response formatting.
+ *
+ * Key considerations:
+ * - API must be in the same account and region as the gateway
+ * - Only REST APIs are supported (no HTTP or WebSocket APIs)
+ * - API must use a public endpoint type
+ * - Methods with both AWS_IAM authorization and API key requirements are not supported
+ * - Proxy resources (e.g., `/pets/{proxy+}`) are not supported
+ */
+export declare class ApiGatewayTargetConfiguration extends McpTargetConfiguration {
+    /**
+     * Create an API Gateway target configuration
+     *
+     * @param props The configuration properties
+     * @returns A new ApiGatewayTargetConfiguration instance
+     */
+    static create(props: ApiGatewayTargetConfigurationProps): ApiGatewayTargetConfiguration;
+    readonly targetType = McpTargetType.API_GATEWAY;
+    /**
+     * The REST API reference
+     */
+    private readonly _restApi;
+    /**
+     * The ID of the REST API
+     */
+    readonly restApiId: string;
+    /**
+     * The stage name of the REST API
+     */
+    readonly stage: string;
+    /**
+     * Tool configuration for the API Gateway target
+     */
+    readonly apiGatewayToolConfiguration: ApiGatewayToolConfiguration;
+    /**
+     * Metadata configuration for the API Gateway target
+     */
+    readonly metadataConfiguration?: MetadataConfiguration;
+    constructor(props: ApiGatewayTargetConfigurationProps);
+    /**
+     * Binds this configuration to a construct scope
+     * Sets up necessary permissions for the gateway to access the API Gateway
+     *
+     * @param _scope The construct scope
+     * @param gateway The gateway that will use this target
+     */
+    bind(_scope: Construct, gateway: IGateway): TargetConfigurationConfig;
+    /**
+     * Renders the MCP-specific configuration
+     */
+    protected renderMcpConfiguration(): any;
+    /**
+     * Validates the configuration
+     * @internal
+     */
+    private validateConfiguration;
+    /**
+     * Validates metadata configuration
+     * @internal
+     */
+    private validateMetadataConfiguration;
+    /**
+     * Validates a metadata configuration array (query parameters or headers)
+     * @param array The array to validate
+     * @param fieldName The name of the field for error messages
+     * @param minItems Minimum number of items allowed in the array
+     * @param maxItems Maximum number of items allowed in the array
+     * @param minStringLength Minimum length for each string in the array
+     * @param maxStringLength Maximum length for each string in the array
+     * @internal
+     */
+    private validateMetadataArray;
+    /**
+     * Validates a tool filter
+     * @internal
+     */
+    private validateToolFilter;
+    /**
+     * Validates a tool override
+     * @internal
+     */
+    private validateToolOverride;
+}