awslabs.cdk-mcp-server 0.0.10417__py3-none-any.whl

awslabs/cdk_mcp_server/server.py

@@ -0,0 +1,7 @@
+"""AWS CDK MCP server implementation."""
+
+from awslabs.cdk_mcp_server.core.server import main
+
+
+if __name__ == '__main__':
+    main()

awslabs/cdk_mcp_server/static/CDK_GENERAL_GUIDANCE.md

@@ -0,0 +1,232 @@
+# AWS CDK Best Practices Guide
+
+This guide provides essential best practices for AWS CDK development, focusing on when to use specific constructs and tools.
+
+## Getting Started with CDK
+
+Always initialize CDK projects properly using the CDK CLI:
+
+```bash
+# For TypeScript projects
+cdk init app --language typescript
+
+# For Python projects
+cdk init app --language python
+```
+
+Proper initialization ensures:
+- Consistent project structure
+- Correct dependency setup
+- Appropriate tsconfig/package.json configuration
+- Necessary boilerplate files
+
+This foundation helps avoid common issues and ensures compatibility with AWS CDK best practices.
+
+## Development Workflow
+
+When developing CDK applications, use these commands for an efficient workflow:
+
+```bash
+# Synthesize CloudFormation templates (recommended for validation)
+cdk synth
+
+# Deploy your CDK application
+cdk deploy
+
+# Compare deployed stack with current state
+cdk diff
+```
+
+**Important**: Prefer `cdk synth` over `npm run build` or `tsc` for TypeScript projects. The `cdk synth` command:
+
+- Automatically compiles TypeScript code when needed
+- Validates CDK constructs and catches potential deployment issues
+- Generates CloudFormation templates for inspection
+- Provides more informative error messages for debugging
+
+## Decision Flow for CDK Implementation
+
+When implementing AWS infrastructure with CDK, consider these complementary approaches:
+
+1. **For Common Architecture Patterns: AWS Solutions Constructs**
+   - Use the `GetAwsSolutionsConstructPattern` tool to search for patterns that match your use case
+   - Example: `GetAwsSolutionsConstructPattern(services=["lambda", "dynamodb"])`
+   - AWS Solutions Constructs implement AWS best practices by default
+   - For complete documentation: `aws-solutions-constructs://{pattern_name}`
+   - Ideal for REST APIs, serverless backends, data processing pipelines, etc.
+
+2. **For GenAI/AI/ML Use Cases: GenAI CDK Constructs**
+   - Use the `SearchGenAICDKConstructs` tool for specialized AI/ML constructs
+   - These simplify implementation of Bedrock, SageMaker, and other AI services
+   - Perfect for agents, knowledge bases, vector stores, and other GenAI components
+
+   **Installation:**
+   ```typescript
+   // TypeScript
+   // Create or use an existing CDK application
+   cdk init app --language typescript
+   // Install the package
+   npm install @cdklabs/generative-ai-cdk-constructs
+   // Import the library
+   import * as genai from '@cdklabs/generative-ai-cdk-constructs';
+   ```
+
+   ```python
+   # Python
+   # Create or use an existing CDK application
+   cdk init app --language python
+   # Install the package
+   pip install cdklabs.generative-ai-cdk-constructs
+   # Import the library
+   import cdklabs.generative_ai_cdk_constructs
+   ```
+
+3. **For All Projects: Apply CDK Nag**
+   - Always apply CDK Nag to ensure security best practices
+   - Use the `ExplainCDKNagRule` tool to understand specific rules
+
+4. **For Custom Requirements: Custom Implementation**
+   - Create custom CDK code when no suitable constructs exist
+   - Follow AWS Well-Architected best practices
+
+> **IMPORTANT**: AWS Solutions Constructs and GenAI CDK Constructs are complementary and can be used together in the same project. For example, you might use GenAI CDK Constructs for Bedrock components and AWS Solutions Constructs for the REST API and database layers of your application.
+
+## Key Principles
+
+- **Security First**: Always implement security best practices by default
+- **Cost Optimization**: Design resources to minimize costs while meeting requirements
+- **Operational Excellence**: Implement proper monitoring, logging, and observability
+- **Serverless-First**: Prefer serverless services when possible
+- **Infrastructure as Code**: Use CDK to define all infrastructure
+- **Use Vetted Patterns**: Prefer AWS Solutions Constructs over custom implementations
+- **Regional Awareness**: Consider regional availability and constraints for services
+
+## Amazon Bedrock Cross-Region Inference Profiles
+
+When working with Amazon Bedrock foundation models, many models (including Claude models, Meta Llama models, and Amazon's own Nova models) require the use of inference profiles rather than direct on-demand usage in specific regions. Failing to use inference profiles can result in errors like:
+
+```
+Invocation of model ID anthropic.claude-3-7-sonnet-20250219-v1:0 with on-demand throughput isn't supported.
+Retry your request with the ID or ARN of an inference profile that contains this model.
+```
+
+### Using Cross-Region Inference Profiles
+
+To properly configure Bedrock models with cross-region inference profiles:
+
+#### TypeScript
+
+```typescript
+import { bedrock } from '@cdklabs/generative-ai-cdk-constructs';
+
+// Create a cross-region inference profile for Claude
+const claudeInferenceProfile = bedrock.CrossRegionInferenceProfile.fromConfig({
+  // Choose the appropriate region:
+  // US (default) - bedrock.CrossRegionInferenceProfileRegion.US
+  // EU - bedrock.CrossRegionInferenceProfileRegion.EU
+  // APAC - bedrock.CrossRegionInferenceProfileRegion.APAC
+  geoRegion: bedrock.CrossRegionInferenceProfileRegion.US,
+  model: bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_7_SONNET_V1_0
+});
+
+// Use the inference profile with your agent or other Bedrock resources
+const agent = new bedrock.Agent(this, 'MyAgent', {
+  // Use the inference profile instead of directly using the foundation model
+  foundationModel: claudeInferenceProfile,
+  // Other agent configuration...
+});
+```
+
+#### Python
+
+```python
+from cdklabs.generative_ai_cdk_constructs import bedrock
+
+# Create a cross-region inference profile for Claude
+claude_inference_profile = bedrock.CrossRegionInferenceProfile.from_config(
+    # Choose the appropriate region:
+    # US (default) - bedrock.CrossRegionInferenceProfileRegion.US
+    # EU - bedrock.CrossRegionInferenceProfileRegion.EU
+    # APAC - bedrock.CrossRegionInferenceProfileRegion.APAC
+    geo_region=bedrock.CrossRegionInferenceProfileRegion.US,
+    model=bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_7_SONNET_V1_0
+)
+
+# Use the inference profile with your agent or other Bedrock resources
+agent = bedrock.Agent(self, "MyAgent",
+    # Use the inference profile instead of directly using the foundation model
+    foundation_model=claude_inference_profile,
+    # Other agent configuration...
+)
+```
+
+### Regional Considerations
+
+- **Model Availability**: Not all foundation models are available in all regions
+- **Inference Profile Requirements**: Some models require inference profiles in specific regions
+- **Performance**: Choose the region closest to your users for optimal latency
+- **Compliance**: Consider data residency requirements when selecting regions
+
+Always check the [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) for the latest information on model availability and regional constraints.
+
+## AWS Solutions Constructs
+
+AWS Solutions Constructs are vetted architecture patterns that combine multiple AWS services to solve common use cases following AWS Well-Architected best practices.
+
+**Key benefits:**
+- Accelerated Development: Implement common patterns without boilerplate code
+- Best Practices Built-in: Security, reliability, and performance best practices
+- Reduced Complexity: Simplified interfaces for multi-service architectures
+- Well-Architected: Patterns follow AWS Well-Architected Framework principles
+
+**When to use Solutions Constructs:**
+- Implementing common architecture patterns (e.g., API + Lambda + DynamoDB)
+- You want secure defaults and best practices applied automatically
+- You need to quickly prototype or build production-ready infrastructure
+
+To discover available patterns, use the `GetAwsSolutionsConstructPattern` tool.
+
+## Security with CDK Nag
+
+CDK Nag is a crucial tool for ensuring your CDK applications follow AWS security best practices. **Always apply CDK Nag to all your stacks by default.**
+
+Key security practices to remember:
+- Follow the principle of least privilege for IAM
+- Secure S3 buckets with encryption, access controls, and policies
+- Implement secure authentication with Cognito
+- Secure API Gateway endpoints with proper authorization
+
+For detailed guidance, use the `CDKNagGuidance` tool.
+
+## Operational Excellence with Lambda Powertools
+
+Always implement Lambda Powertools for:
+- Structured Logging
+- Tracing
+- Metrics
+
+For detailed guidance, use the `LambdaPowertoolsGuidance` tool.
+
+## Available MCP Tools
+
+This MCP server provides several tools to help you implement AWS CDK best practices:
+
+1. **CDKGeneralGuidance**: This document - general CDK best practices
+2. **ExplainCDKNagRule**: Explain a specific CDK Nag rule with AWS Well-Architected guidance
+3. **CheckCDKNagSuppressions**: Check if CDK code contains Nag suppressions that require human review
+4. **GenerateBedrockAgentSchemaFromFile**: Generate OpenAPI schema for Bedrock Agent Action Groups from Lambda functions
+5. **GetAwsSolutionsConstructPattern**: Search and discover AWS Solutions Constructs patterns
+6. **SearchGenAICDKConstructs**: Search for GenAI CDK constructs by name or type
+
+## Available MCP Resources
+
+This MCP server also provides several resources for accessing documentation:
+
+1. **cdk-nag://rules/{rule_pack}**: Get all rules for a specific CDK Nag rule pack
+2. **cdk-nag://warnings/{rule_pack}**: Get warnings for a specific CDK Nag rule pack
+3. **cdk-nag://errors/{rule_pack}**: Get errors for a specific CDK Nag rule pack
+4. **lambda-powertools://{topic}**: Get Lambda Powertools guidance on a specific topic
+5. **aws-solutions-constructs://{pattern_name}**: Get complete documentation for an AWS Solutions Constructs pattern
+6. **genai-cdk-constructs://{construct_type}/{construct_name}**: Get documentation for a GenAI CDK construct
+
+Always check for these tools and resources when implementing CDK infrastructure to ensure you're following AWS best practices.

awslabs/cdk_mcp_server/static/CDK_NAG_GUIDANCE.md

@@ -0,0 +1,192 @@
+# CDK Nag Guidance
+
+This guide provides implementation details for CDK Nag in AWS CDK projects. CDK Nag analyzes CDK constructs to identify security issues based on AWS Well-Architected Framework best practices.
+
+## Table of Contents
+
+1. [Optional Integration](#optional-integration)
+2. [AwsSolutions Rule Pack](#awssolutions-rule-pack)
+3. [Suppressing Violations](#suppressing-violations)
+
+## Optional Integration
+
+CDK Nag can be made optional in your CDK projects, which is particularly useful during development or prototyping phases. Here are several approaches to make CDK Nag optional:
+
+### Using Environment Variables
+
+```typescript
+import { AwsSolutionsChecks } from 'cdk-nag';
+import { App } from 'aws-cdk-lib';
+
+// Create your CDK app
+const app = new App();
+
+// Add your stacks
+new MyStack(app, 'MyStack');
+
+// Apply CDK Nag conditionally based on environment variable
+if (process.env.ENABLE_CDK_NAG === 'true') {
+  console.log('CDK Nag enabled - checking for security issues');
+  AwsSolutionsChecks.check(app);
+} else {
+  console.log('CDK Nag disabled - skipping security checks');
+}
+```
+
+### Using CDK Context Parameters
+
+```typescript
+import { AwsSolutionsChecks } from 'cdk-nag';
+import { App } from 'aws-cdk-lib';
+
+// Create your CDK app
+const app = new App();
+
+// Add your stacks
+new MyStack(app, 'MyStack');
+
+// Apply CDK Nag conditionally based on context parameter
+if (app.node.tryGetContext('enableCdkNag') === 'true') {
+  console.log('CDK Nag enabled - checking for security issues');
+  AwsSolutionsChecks.check(app);
+} else {
+  console.log('CDK Nag disabled - skipping security checks');
+}
+```
+
+To enable CDK Nag with this approach, use:
+
+```bash
+cdk deploy --context enableCdkNag=true
+```
+
+### Environment-Specific Application
+
+You can also apply CDK Nag only to specific environments:
+
+```typescript
+import { AwsSolutionsChecks } from 'cdk-nag';
+import { App, Stack } from 'aws-cdk-lib';
+
+// Create your CDK app
+const app = new App();
+
+// Get environment from context
+const environment = app.node.tryGetContext('environment') || 'development';
+
+// Add your stacks
+const stack = new MyStack(app, 'MyStack');
+
+// Apply CDK Nag only to production and staging environments
+if (['production', 'staging'].includes(environment)) {
+  console.log(`Applying CDK Nag checks for ${environment} environment`);
+  AwsSolutionsChecks.check(stack);
+}
+```
+
+## AwsSolutions Rule Pack
+
+The AwsSolutions rule pack is the primary rule pack provided by CDK Nag. It contains rules based on AWS Solutions best practices and the AWS Well-Architected Framework.
+
+To apply the AwsSolutions rule pack:
+
+```typescript
+import { AwsSolutionsChecks } from 'cdk-nag';
+import { App } from 'aws-cdk-lib';
+
+// Create your CDK app
+const app = new App();
+
+// Add your stacks
+new MyStack(app, 'MyStack');
+
+// Apply AwsSolutions checks
+AwsSolutionsChecks.check(app);
+```
+
+## Suppressing Violations
+
+⚠️ **CRITICAL: HUMAN DEVELOPER RESPONSIBILITY ONLY** ⚠️
+
+CDK Nag suppressions should NEVER be applied by AI assistants or MCP clients. This is exclusively a human developer responsibility that requires careful consideration and security expertise.
+
+### Process for Handling Violations
+
+1. **Review**: Human developers should review all CDK Nag warnings and errors
+2. **Analyze**: Determine if each violation represents a genuine security concern
+3. **Remediate**: Whenever possible, fix the underlying issue rather than suppressing
+4. **Document**: If suppression is necessary, document the specific reason with detailed justification
+5. **Approve**: Require explicit human approval (ideally through code review)
+
+### For Human Developers Only
+
+The following code examples are provided ONLY for human developers to understand the syntax. AI assistants should NOT implement these patterns without explicit human review and approval.
+
+#### Stack-Level Suppressions
+
+```typescript
+// HUMAN DEVELOPER RESPONSIBILITY - DO NOT IMPLEMENT AUTOMATICALLY
+// This code must only be added after careful security review
+import { NagSuppressions } from 'cdk-nag';
+import { Stack } from 'aws-cdk-lib';
+
+// Create your stack
+const stack = new MyStack(app, 'MyStack');
+
+// Suppress a rule for the entire stack
+NagSuppressions.addStackSuppressions(stack, [
+  {
+    id: 'AwsSolutions-IAM4',
+    reason: 'REQUIRES SPECIFIC HUMAN JUSTIFICATION',
+  },
+]);
+```
+
+#### Resource-Level Suppressions
+
+```typescript
+// HUMAN DEVELOPER RESPONSIBILITY - DO NOT IMPLEMENT AUTOMATICALLY
+// This code must only be added after careful security review
+import { NagSuppressions } from 'cdk-nag';
+import { Role, ServicePrincipal, ManagedPolicy } from 'aws-cdk-lib/aws-iam';
+
+// Create a role with a managed policy
+const role = new Role(this, 'MyRole', {
+  assumedBy: new ServicePrincipal('lambda.amazonaws.com'),
+});
+role.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName('AmazonS3ReadOnlyAccess'));
+
+// Suppress the warning for this specific role
+NagSuppressions.addResourceSuppressions(role, [
+  {
+    id: 'AwsSolutions-IAM4',
+    reason: 'REQUIRES SPECIFIC HUMAN JUSTIFICATION',
+  },
+]);
+```
+
+#### Path-Based Suppressions
+
+```typescript
+// HUMAN DEVELOPER RESPONSIBILITY - DO NOT IMPLEMENT AUTOMATICALLY
+// This code must only be added after careful security review
+import { NagSuppressions } from 'cdk-nag';
+import { Construct } from 'constructs';
+
+// Create a construct
+const myConstruct = new MyConstruct(this, 'MyConstruct');
+
+// Suppress a rule for the construct and all its children
+NagSuppressions.addResourceSuppressionsByPath(
+  stack,
+  '/MyStack/MyConstruct',
+  [
+    {
+      id: 'AwsSolutions-IAM5',
+      reason: 'REQUIRES SPECIFIC HUMAN JUSTIFICATION',
+    },
+  ]
+);
+```
+
+For more detailed security best practices by service (IAM, S3, Cognito, API Gateway), please use the **CDK Guidance** tool in this MCP server and refer to the Security Best Practices section.

awslabs/cdk_mcp_server/static/__init__.py

@@ -0,0 +1,5 @@
+from importlib import resources
+
+
+with resources.files('awslabs.cdk_mcp_server.static').joinpath('CDK_GENERAL_GUIDANCE.md').open('r') as f:
+    CDK_GENERAL_GUIDANCE = f.read()

awslabs/cdk_mcp_server/static/bedrock/agent/actiongroups.md

@@ -0,0 +1,137 @@
+# Action Groups
+
+## Overview
+
+Action groups define functions your agent can call, connecting Bedrock Agents to your business logic via Lambda functions. The agent uses an OpenAPI schema to understand what your functions do and how to call them.
+
+```mermaid
+graph LR
+    A[Agent] --> B[Action Group]
+    B --> C[Lambda Function]
+    B --> D[OpenAPI Schema]
+```
+
+## Action Group Properties
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| name | string | Yes | The name of the action group |
+| description | string | No | A description of the action group |
+| apiSchema | ApiSchema | No | The API Schema |
+| executor | ActionGroupExecutor | No | The action group executor |
+| enabled | boolean | No | Specifies whether the action group is available for the agent to invoke or not when sending an InvokeAgent request. Defaults to true |
+| forceDelete | boolean | No | Specifies whether to delete the resource even if it's in use. Defaults to false |
+| functionSchema | CfnAgent.FunctionSchemaProperty | No | Defines functions that each define parameters that the agent needs to invoke from the user |
+| parentActionGroupSignature | ParentActionGroupSignature | No | The AWS Defined signature for enabling certain capabilities in your agent. When specified, description, apiSchema, and actionGroupExecutor must be blank |
+
+## OpenAPI Schema Generation & Best Practices
+
+For Action Groups, use the built-in OpenAPI schema generation tool provided by the AWS CDK MCP server:
+
+```typescript
+// Using MCP client
+const result = await use_mcp_tool({
+  server_name: "awslabs.cdk-mcp-server",
+  tool_name: "GenerateBedrockAgentSchemaFromFile",
+  arguments: {
+    lambda_code_path: "path/to/your/lambda.py",
+    output_path: "path/to/output/openapi.json"
+  }
+});
+```
+
+The tool will:
+
+1. Parse your Lambda function code
+2. Extract function signatures and docstrings
+3. Generate a Bedrock-compatible OpenAPI schema
+4. Save it to the specified output path
+
+### Key Requirements
+- Ensure each operation has a unique operationId
+- Define complete response schemas
+- Use `fromLocalAsset` (not `fromAsset`) for API schemas
+- Include detailed descriptions for all endpoints, parameters, and return values
+- Use proper type annotations with Python type hints
+
+### Lambda Function Example
+
+```python
+from aws_lambda_powertools.event_handler import BedrockAgentResolver
+from typing import Annotated, List
+from aws_lambda_powertools.event_handler.openapi.params import Query, Path
+from pydantic import BaseModel, Field
+
+app = BedrockAgentResolver()
+
+class Product(BaseModel):
+    product_id: str = Field(description="Unique product identifier")
+    name: str = Field(description="Product name")
+    price: float = Field(description="Product price in USD")
+
+@app.get("/products", description="List available products")
+def list_products(
+    category: Annotated[str, Query(description="Product category")] = None
+) -> List[Product]:
+    # Your business logic here
+    return [Product(product_id="1", name="Product A", price=19.99)]
+
+def lambda_handler(event, context):
+    return app.resolve(event, context)
+```
+
+## Examples
+
+### TypeScript
+
+```ts
+const actionGroupFunction = new lambda_python.PythonFunction(this, 'ActionGroupFunction', {
+  runtime: lambda.Runtime.PYTHON_3_12,
+  entry: path.join(__dirname, '../lambda/action-group'),
+});
+
+// Example of proper Action Group setup with fromLocalAsset
+const actionGroup = new AgentActionGroup({
+  name: 'query-library',
+  description: 'Use these functions to get information about the books in the library.',
+  executor: bedrock.ActionGroupExecutor.fromlambdaFunction(actionGroupFunction),
+  enabled: true,
+  apiSchema: bedrock.ApiSchema.fromLocalAsset(path.join(__dirname, 'action-group.yaml')),
+});
+
+agent.addActionGroup(actionGroup);
+
+// Real-world example with account actions
+const agentAccountActions = new AgentActionGroup({
+  name: "agent-account-actions",
+  description: "Use these functions to take actions on authenticated user's accounts",
+  executor: bedrock.ActionGroupExecutor.fromlambdaFunction(accountActionsLambda),
+  apiSchema: bedrock.ApiSchema.fromLocalAsset(
+    path.join(agentsLambdaDir, "account_actions", "openapi.json"),
+  ),
+});
+
+agent.addActionGroup(agentAccountActions);
+```
+
+### Python
+
+```python
+action_group_function = PythonFunction(
+            self,
+            "LambdaFunction",
+            runtime=Runtime.PYTHON_3_12,
+            entry="./lambda",
+            index="app.py",
+            handler="lambda_handler",
+)
+
+actionGroup = bedrock.AgentActionGroup(
+    name="query-library",
+    description="Use these functions to get information about the books in the library.",
+    executor= bedrock.ActionGroupExecutor.fromlambda_function(action_group_function),
+    enabled=True,
+    api_schema=bedrock.ApiSchema.from_local_asset("action-group.yaml"))
+
+agent.add_action_group(actionGroup)
+```

awslabs/cdk_mcp_server/static/bedrock/agent/alias.md

@@ -0,0 +1,39 @@
+# Agent Alias
+
+## Overview
+
+After you have sufficiently iterated on your working draft and are satisfied with the behavior of your agent, you can set it up for deployment and integration into your application by creating aliases of your agent.
+
+To deploy your agent, you need to create an alias. During alias creation, Amazon Bedrock automatically creates a version of your agent. The alias points to this newly created version. You can point the alias to a previously created version if necessary. You then configure your application to make API calls to that alias.
+
+By default, the `Agent` resource does not create any aliases, and you can use the 'DRAFT' version.
+
+## Specific Version
+
+You can use the `AgentAlias` resource if you want to create an Alias for an existing Agent.
+
+## Example
+
+### TypeScript
+
+```ts
+const agentAlias2 = new bedrock.AgentAlias(this, 'myalias2', {
+  aliasName: 'myalias',
+  agent: agent,
+  agentVersion: '1', // optional
+  description: 'mytest'
+});
+```
+
+### Python
+
+```python
+agent_alias_2 = bedrock.AgentAlias(self, 'myalias2',
+    alias_name='myalias',
+    agent=agent,
+    agent_version='1', # optional
+    description='mytest'
+)
+```
+
+[View full documentation](https://github.com/awslabs/generative-ai-cdk-constructs/blob/main/src/cdk-lib/bedrock/README.md)