aws-cdk-lib/aws-bedrockagentcore/lib/gateway/targets/target-configuration.d.ts

Version 2 of the AWS Cloud Development Kit library

import type { Construct } from 'constructs';
import type { ApiSchema } from './schema/api-schema';
import type { ToolSchema } from './schema/tool-schema';
import { McpTargetType } from './target-base';
import type { IRestApi } from '../../../../aws-apigateway';
import type { IFunction } from '../../../../aws-lambda';
import type { IGateway } from '../gateway-base';
/******************************************************************************
 *                          Interface
 *****************************************************************************/
/**
 * Configuration returned by binding a target configuration
 */
export interface TargetConfigurationConfig {
    /**
     * Indicates that the configuration has been successfully bound
     */
    readonly bound: boolean;
}
/**
 * Base interface for target configurations
 */
export interface ITargetConfiguration {
    /**
     * The target type
     */
    readonly targetType: McpTargetType;
    /**
     * Binds the configuration to a construct scope
     * Sets up permissions and dependencies
     */
    bind(scope: Construct, gateway: IGateway): TargetConfigurationConfig;
    /**
     * Renders the configuration as CloudFormation properties
     * @internal
     */
    _render(): any;
}
/******************************************************************************
 *                     MCP Target Configuration Base
 *****************************************************************************/
/**
 * Abstract base class for MCP target configurations
 * Provides common functionality for all MCP target types
 */
export declare abstract class McpTargetConfiguration implements ITargetConfiguration {
    /**
     * The target type
     */
    abstract readonly targetType: McpTargetType;
    /**
     * Binds the configuration to a construct scope
     * Sets up permissions and dependencies
     */
    abstract bind(scope: Construct, gateway: IGateway): TargetConfigurationConfig;
    /**
     * Renders the MCP-specific configuration
     */
    protected abstract renderMcpConfiguration(): any;
    /**
     * Renders the configuration as CloudFormation properties
     * @internal
     */
    _render(): any;
}
/******************************************************************************
 *                     Lambda Target Configuration
 *****************************************************************************/
/**
 * Configuration for Lambda-based MCP targets
 *
 * This configuration wraps a Lambda function as MCP tools,
 * allowing the gateway to invoke the function to provide tool capabilities.
 */
export declare class LambdaTargetConfiguration extends McpTargetConfiguration {
    /**
     * Create a Lambda target configuration
     *
     * @param lambdaFunction The Lambda function to invoke
     * @param toolSchema The schema defining the tools
     * @returns A new LambdaTargetConfiguration instance
     */
    static create(lambdaFunction: IFunction, toolSchema: ToolSchema): LambdaTargetConfiguration;
    readonly targetType = McpTargetType.LAMBDA;
    /**
     * The Lambda function that implements the MCP server logic
     */
    readonly lambdaFunction: IFunction;
    /**
     * The tool schema that defines the available tools
     */
    readonly toolSchema: ToolSchema;
    constructor(lambdaFunction: IFunction, toolSchema: ToolSchema);
    /**
     * Binds this configuration to a construct scope
     * Sets up necessary permissions for the gateway to invoke the Lambda function
     *
     * @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;
}
/******************************************************************************
 *                     OpenAPI Target Configuration
 *****************************************************************************/
/**
 * Configuration for OpenAPI-based MCP targets
 *
 * This configuration exposes an OpenAPI/REST API as MCP tools,
 * allowing the gateway to transform API operations into tool calls.
 */
export declare class OpenApiTargetConfiguration extends McpTargetConfiguration {
    /**
     * Create an OpenAPI target configuration
     *
     * @param apiSchema The OpenAPI schema
     * @param validateSchema Whether to validate the OpenAPI schema (only applies to inline schemas)
     * @returns A new OpenApiTargetConfiguration instance
     */
    static create(apiSchema: ApiSchema, validateSchema?: boolean): OpenApiTargetConfiguration;
    readonly targetType = McpTargetType.OPENAPI_SCHEMA;
    /**
     * The OpenAPI schema that defines the API
     */
    readonly apiSchema: ApiSchema;
    /**
     * Whether to validate the OpenAPI schema
     */
    private readonly shouldValidateSchema;
    constructor(apiSchema: ApiSchema, validateSchema?: boolean);
    /**
     * Binds this configuration to a construct scope
     * Sets up necessary permissions for the gateway to access the API schema
     *
     * @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;
}
/******************************************************************************
 *                     Smithy Target Configuration
 *****************************************************************************/
/**
 * Configuration for Smithy-based MCP targets
 *
 * This configuration exposes a Smithy-modeled API as MCP tools,
 * allowing the gateway to transform Smithy operations into tool calls.
 */
export declare class SmithyTargetConfiguration extends McpTargetConfiguration {
    /**
     * Create a Smithy target configuration
     *
     * @param smithyModel The Smithy model schema
     * @returns A new SmithyTargetConfiguration instance
     */
    static create(smithyModel: ApiSchema): SmithyTargetConfiguration;
    readonly targetType = McpTargetType.SMITHY_MODEL;
    /**
     * The Smithy model that defines the API
     */
    readonly smithyModel: ApiSchema;
    constructor(smithyModel: ApiSchema);
    /**
     * Binds this configuration to a construct scope
     * Sets up necessary permissions for the gateway to access the Smithy model
     *
     * @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;
}
/******************************************************************************
 *                     MCP Server Target Configuration
 *****************************************************************************/
/**
 * Configuration for MCP Server-based targets
 *
 * MCP (Model Context Protocol) servers provide tools, data access, and custom
 * functions for AI agents. When you configure an MCP server as a gateway target,
 * the gateway automatically discovers and indexes available tools through
 * synchronization.
 */
export declare class McpServerTargetConfiguration extends McpTargetConfiguration {
    /**
     * Create an MCP server target configuration
     *
     * @param endpoint The HTTPS endpoint URL of the MCP server
     * @returns A new McpServerTargetConfiguration instance
     */
    static create(endpoint: string): McpServerTargetConfiguration;
    readonly targetType = McpTargetType.MCP_SERVER;
    /**
     * The HTTPS endpoint URL of the MCP server
     */
    readonly endpoint: string;
    constructor(endpoint: string);
    /**
     * Binds this configuration to a construct scope
     * No additional permissions are needed for MCP server targets
     *
     * @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 MCP server endpoint
     * - Must use HTTPS protocol
     * - Should be properly URL encoded
     *
     * @param endpoint The endpoint URL to validate
     * @throws ValidationError if the endpoint is invalid
     * @internal
     */
    private validateEndpoint;
}
/******************************************************************************
 *                     API Gateway Target Configuration
 *****************************************************************************/
/**
 * HTTP methods supported by API Gateway
 */
export declare class ApiGatewayHttpMethod {
    /** GET method */
    static readonly GET: ApiGatewayHttpMethod;
    /** POST method */
    static readonly POST: ApiGatewayHttpMethod;
    /** PUT method */
    static readonly PUT: ApiGatewayHttpMethod;
    /** DELETE method */
    static readonly DELETE: ApiGatewayHttpMethod;
    /** PATCH method */
    static readonly PATCH: ApiGatewayHttpMethod;
    /** HEAD method */
    static readonly HEAD: ApiGatewayHttpMethod;
    /** OPTIONS method */
    static readonly OPTIONS: ApiGatewayHttpMethod;
    /**
     * Use a custom HTTP method not yet defined in this class.
     * @param value The HTTP method string value
     */
    static of(value: string): ApiGatewayHttpMethod;
    /** The HTTP method string value. */
    readonly value: string;
    private constructor();
    /** Returns the string value. */
    toString(): string;
}
/**
 * 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;
}