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

awslabs/cdk_mcp_server/core/tools.py

@@ -0,0 +1,324 @@
+"""AWS CDK MCP tool handlers."""
+
+import logging
+import os
+import re
+from awslabs.cdk_mcp_server.core import search_utils
+from awslabs.cdk_mcp_server.data.cdk_nag_parser import (
+    check_cdk_nag_suppressions,
+    get_rule,
+)
+from awslabs.cdk_mcp_server.data.genai_cdk_loader import (
+    list_available_constructs,
+)
+from awslabs.cdk_mcp_server.data.schema_generator import generate_bedrock_schema_from_file
+from awslabs.cdk_mcp_server.data.solutions_constructs_parser import (
+    fetch_pattern_list,
+    get_pattern_info,
+    search_patterns,
+)
+from awslabs.cdk_mcp_server.static import (
+    CDK_GENERAL_GUIDANCE,
+)
+from mcp.server.fastmcp import Context
+from typing import Any, Dict, List, Optional
+
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+
+async def cdk_guidance(
+    ctx: Context,
+) -> str:
+    """Use this tool to get prescriptive CDK advice for building applications on AWS.
+
+    Args:
+        ctx: MCP context
+    """
+    return CDK_GENERAL_GUIDANCE
+
+
+async def explain_cdk_nag_rule(
+    ctx: Context,
+    rule_id: str,
+) -> Dict[str, Any]:
+    """Explain a specific CDK Nag rule with AWS Well-Architected guidance.
+
+    CDK Nag is a crucial tool for ensuring your CDK applications follow AWS security best practices.
+
+    Basic implementation:
+    ```typescript
+    import { App } from 'aws-cdk-lib';
+    import { AwsSolutionsChecks } from 'cdk-nag';
+
+    const app = new App();
+    // Create your stack
+    const stack = new MyStack(app, 'MyStack');
+    // Apply CDK Nag
+    AwsSolutionsChecks.check(app);
+    ```
+
+    Optional integration patterns:
+
+    1. Using environment variables:
+    ```typescript
+    if (process.env.ENABLE_CDK_NAG === 'true') {
+      AwsSolutionsChecks.check(app);
+    }
+    ```
+
+    2. Using CDK context parameters:
+    ```typescript
+    3. Environment-specific application:
+    ```typescript
+    const environment = app.node.tryGetContext('environment') || 'development';
+    if (['production', 'staging'].includes(environment)) {
+      AwsSolutionsChecks.check(stack);
+    }
+    ```
+
+    For more information on specific rule packs:
+    - Use resource `cdk-nag://rules/{rule_pack}` to get all rules for a specific pack
+    - Use resource `cdk-nag://warnings/{rule_pack}` to get warnings for a specific pack
+    - Use resource `cdk-nag://errors/{rule_pack}` to get errors for a specific pack
+
+    Args:
+        ctx: MCP context
+        rule_id: The CDK Nag rule ID (e.g., 'AwsSolutions-IAM4')
+
+    Returns:
+        Dictionary with detailed explanation and remediation steps
+    """
+    # Use the resource we created to fetch the rule information
+    try:
+        rule_content = await get_rule(rule_id)
+
+        # If the rule was found, return a structured response
+        if not rule_content.startswith('Rule'):
+            return {
+                'rule_id': rule_id,
+                'content': rule_content,
+                'source': 'https://github.com/cdklabs/cdk-nag/blob/main/RULES.md',
+                'status': 'success',
+            }
+        else:
+            # Rule not found
+            return {
+                'rule_id': rule_id,
+                'error': f'Rule {rule_id} not found in CDK Nag documentation.',
+                'source': 'https://github.com/cdklabs/cdk-nag/blob/main/RULES.md',
+                'status': 'not_found',
+            }
+    except Exception as e:
+        # Handle any errors
+        return {
+            'rule_id': rule_id,
+            'error': f'Failed to fetch rule information: {str(e)}',
+            'source': 'https://github.com/cdklabs/cdk-nag/blob/main/RULES.md',
+            'status': 'error',
+        }
+
+
+async def check_cdk_nag_suppressions_tool(
+    ctx: Context,
+    code: Optional[str] = None,
+    file_path: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Check if CDK code contains Nag suppressions that require human review.
+
+    Scans TypeScript/JavaScript code for NagSuppressions usage to ensure security
+    suppressions receive proper human oversight and justification.
+
+    Args:
+        ctx: MCP context
+        code: CDK code to analyze (TypeScript/JavaScript)
+        file_path: Path to a file containing CDK code to analyze
+
+    Returns:
+        Analysis results with suppression details and security guidance
+    """
+    # Use the imported function from cdk_nag_parser.py
+    return check_cdk_nag_suppressions(code=code, file_path=file_path)
+
+
+async def bedrock_schema_generator_from_file(
+    ctx: Context, lambda_code_path: str, output_path: str
+) -> Dict[str, Any]:
+    """Generate OpenAPI schema for Bedrock Agent Action Groups from a file.
+
+    This tool converts a Lambda file with BedrockAgentResolver into a Bedrock-compatible
+    OpenAPI schema. It uses a progressive approach to handle common issues:
+    1. Direct import of the Lambda file
+    2. Simplified version with problematic imports commented out
+    3. Fallback script generation if needed
+
+    Args:
+        ctx: MCP context
+        lambda_code_path: Path to Python file containing BedrockAgentResolver app
+        output_path: Where to save the generated schema
+
+    Returns:
+        Dictionary with schema generation results, including status, path to generated schema,
+        and diagnostic information if errors occurred
+    """
+    # Ensure the output directory exists
+    os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+
+    # Generate the schema
+    result = generate_bedrock_schema_from_file(
+        lambda_code_path=lambda_code_path,
+        output_path=output_path,
+    )
+
+    return result
+
+
+async def get_aws_solutions_construct_pattern(
+    ctx: Context,
+    pattern_name: Optional[str] = None,
+    services: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """Search and discover AWS Solutions Constructs patterns.
+
+    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
+
+    This tool provides metadata about patterns. For complete documentation,
+    use the resource URI returned in the 'documentation_uri' field.
+
+    Args:
+        ctx: MCP context
+        pattern_name: Optional name of the specific pattern (e.g., 'aws-lambda-dynamodb')
+        services: Optional list of AWS services to search for patterns that use them
+                 (e.g., ['lambda', 'dynamodb'])
+
+    Returns:
+        Dictionary with pattern metadata including description, services, and documentation URI
+    """
+    if pattern_name:
+        result = await get_pattern_info(pattern_name)
+        return result
+    elif services:
+        patterns = await search_patterns(services)
+        return {
+            'results': patterns,
+            'count': len(patterns),
+            'status': 'success',
+            'metadata': {'services_searched': services},
+        }
+    else:
+        available_patterns = await fetch_pattern_list()
+        return {
+            'error': 'Either pattern_name or services must be provided',
+            'available_patterns': available_patterns,
+            'status': 'error',
+        }
+
+
+async def search_genai_cdk_constructs(
+    ctx: Context,
+    query: Optional[str] = None,
+    construct_type: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Search for GenAI CDK constructs by name or type.
+
+    The search is flexible and will match any of your search terms (OR logic).
+    It handles common variations like singular/plural forms and terms with/without spaces.
+
+    Examples:
+    - "bedrock agent" - Returns all agent-related constructs
+    - "knowledgebase vector" - Returns knowledge base constructs related to vector stores
+    - "agent actiongroups" - Returns action groups for agents
+
+    Args:
+        ctx: MCP context
+        query: Search term(s) to find constructs by name or description
+        construct_type: Optional filter by construct type ('bedrock', 'opensearchserverless', etc.)
+
+    Returns:
+        Dictionary with matching constructs and resource URIs
+    """
+    try:
+        # Get list of constructs
+        constructs = list_available_constructs(construct_type)
+
+        # If no query, return all constructs
+        if not query:
+            results = []
+            for construct in constructs:
+                results.append(
+                    {
+                        'name': construct['name'],
+                        'type': construct['type'],
+                        'description': construct['description'],
+                        'resource_uri': f'genai-cdk-constructs://{construct["type"]}/{construct["name"]}',
+                    }
+                )
+
+            return {
+                'results': results,
+                'count': len(results),
+                'status': 'success',
+                'installation_required': {
+                    'package_name': '@cdklabs/generative-ai-cdk-constructs',
+                    'message': 'This construct requires the @cdklabs/generative-ai-cdk-constructs package to be installed',
+                },
+            }
+
+        # Define functions to extract searchable text and name parts
+        def get_text_fn(construct: Dict[str, Any]) -> str:
+            # Create a searchable string from the construct
+            name = construct['name'].lower().replace('_', ' ')
+            # Split camelCase words (e.g., actionGroups -> action Groups)
+            name = re.sub(r'([a-z])([A-Z])', r'\1 \2', name).lower()
+            return f'{name} {construct["type"]} {construct["description"]}'.lower()
+
+        def get_name_parts_fn(construct: Dict[str, Any]) -> List[str]:
+            name = construct['name'].lower().replace('_', ' ')
+            # Split camelCase words
+            name = re.sub(r'([a-z])([A-Z])', r'\1 \2', name).lower()
+            return name.split()
+
+        # Use common search utility
+        search_terms = query.lower().split()
+        scored_constructs = search_utils.search_items_with_terms(
+            constructs, search_terms, get_text_fn, get_name_parts_fn
+        )
+
+        # Format results with resource URIs and matched keywords
+        results = []
+        for scored_item in scored_constructs:
+            construct = scored_item['item']
+            results.append(
+                {
+                    'name': construct['name'],
+                    'type': construct['type'],
+                    'description': construct['description'],
+                    'resource_uri': f'genai-cdk-constructs://{construct["type"]}/{construct["name"]}',
+                    'matched_keywords': scored_item['matched_terms'],
+                }
+            )
+
+        return {
+            'results': results,
+            'count': len(results),
+            'status': 'success',
+            'installation_required': {
+                'package_name': '@cdklabs/generative-ai-cdk-constructs',
+                'message': 'This construct requires the @cdklabs/generative-ai-cdk-constructs package to be installed',
+            },
+        }
+    except Exception as e:
+        return {'error': f'Error searching constructs: {str(e)}', 'status': 'error'}

awslabs/cdk_mcp_server/data/__init__.py

@@ -0,0 +1 @@
+"""Data modules for the AWS CDK MCP server."""

awslabs/cdk_mcp_server/data/cdk_nag_parser.py

@@ -0,0 +1,331 @@
+"""CDK Nag rules parsing utilities."""
+
+import httpx
+import re
+import urllib.parse
+from typing import Any, Dict, Optional, Tuple
+
+
+# Constants
+CDK_NAG_RULES_URL = 'https://raw.githubusercontent.com/cdklabs/cdk-nag/main/RULES.md'
+
+
+# Helper functions
+async def fetch_cdk_nag_content() -> str:
+    """Fetch the CDK Nag rules content from GitHub.
+
+    Returns:
+        The raw content of the RULES.md file from the CDK Nag repository.
+    """
+    async with httpx.AsyncClient() as client:
+        response = await client.get(CDK_NAG_RULES_URL)
+        return response.text
+
+
+def extract_rule_pack_section(content: str, rule_pack: str) -> str:
+    """Extract a specific rule pack section from the content.
+
+    Args:
+        content: The full content of the RULES.md file.
+        rule_pack: The name of the rule pack to extract.
+
+    Returns:
+        The section of the content for the specified rule pack.
+        If the rule pack is not found, returns an error message.
+    """
+    # Use a direct string search approach
+    start_marker = f'## {rule_pack}'
+    start_pos = content.find(start_marker)
+
+    if start_pos < 0:
+        return f"Rule pack '{rule_pack}' not found in CDK Nag documentation."
+
+    # Find the next section heading
+    next_section_pos = content.find('\n## ', start_pos + len(start_marker))
+
+    if next_section_pos >= 0:
+        rule_pack_section = content[start_pos:next_section_pos]
+    else:
+        # If no next section, take until the end of the content
+        rule_pack_section = content[start_pos:]
+
+    return rule_pack_section
+
+
+def extract_section_by_marker(section: str, marker: str) -> Tuple[bool, str]:
+    """Extract a subsection based on a marker (e.g., '### Warnings').
+
+    Args:
+        section: The section to extract from.
+        marker: The marker to look for (e.g., '### Warnings').
+
+    Returns:
+        A tuple containing:
+        - A boolean indicating whether the marker was found.
+        - The extracted subsection if found, or an error message if not found.
+    """
+    marker_pos = section.find(marker)
+
+    if marker_pos < 0:
+        return False, f'No {marker.lstrip("#").strip()} found.'
+
+    # Find the next subsection heading
+    next_subsection_pos = section.find('\n### ', marker_pos + len(marker))
+
+    if next_subsection_pos >= 0:
+        subsection = section[marker_pos:next_subsection_pos]
+    else:
+        # If no next subsection, take until the end of the section
+        subsection = section[marker_pos:]
+
+    return True, subsection
+
+
+def extract_rule_info(content: str, rule_id: str) -> Optional[Dict[str, str]]:
+    """Extract information about a specific rule from the content.
+
+    Args:
+        content: The full content of the RULES.md file.
+        rule_id: The ID of the rule to extract information for.
+
+    Returns:
+        A dictionary containing the rule information, or None if the rule is not found.
+    """
+    # Find the rule in the table
+    # The table format is: | Rule ID | Cause | Explanation | [Relevant Control ID(s)] |
+    pattern = rf'\|\s*{re.escape(rule_id)}\s*\|(.*?)\|(.*?)\|'
+    match = re.search(pattern, content, re.DOTALL)
+
+    if not match:
+        return None
+
+    result = {
+        'rule_id': rule_id,
+        'cause': match.group(1).strip(),
+        'explanation': match.group(2).strip(),
+    }
+
+    # Check if there's a fourth column (Relevant Control ID(s))
+    control_pattern = rf'\|\s*{re.escape(rule_id)}\s*\|(.*?)\|(.*?)\|(.*?)\|'
+    control_match = re.search(control_pattern, content, re.DOTALL)
+
+    if control_match and len(control_match.groups()) >= 3:
+        result['control_ids'] = control_match.group(3).strip()
+
+    return result
+
+
+def format_rule_info(rule_info: Optional[Dict[str, str]]) -> str:
+    """Format rule information as a markdown string.
+
+    Args:
+        rule_info: A dictionary containing rule information.
+
+    Returns:
+        A formatted markdown string.
+    """
+    if not rule_info:
+        return "Rule information not found."
+
+    result = f'# {rule_info["rule_id"]}\n\n'
+    result += f'## Cause\n\n{rule_info["cause"]}\n\n'
+    result += f'## Explanation\n\n{rule_info["explanation"]}\n\n'
+
+    if 'control_ids' in rule_info:
+        result += f'## Relevant Control ID(s)\n\n{rule_info["control_ids"]}\n\n'
+
+    return result
+
+
+# Main functions
+async def get_rule_pack(rule_pack: str) -> str:
+    """Get the full content for a rule pack.
+
+    Args:
+        rule_pack: The name of the rule pack to get.
+
+    Returns:
+        The full content for the specified rule pack.
+    """
+    # Decode the rule pack name if it's URL-encoded
+    rule_pack = urllib.parse.unquote(rule_pack)
+
+    # Fetch the content
+    content = await fetch_cdk_nag_content()
+
+    # Extract the section for this rule pack
+    return extract_rule_pack_section(content, rule_pack)
+
+
+async def get_warnings(rule_pack: str) -> str:
+    """Get only the warnings section for a rule pack.
+
+    Args:
+        rule_pack: The name of the rule pack to get warnings for.
+
+    Returns:
+        The warnings section for the specified rule pack.
+    """
+    # Decode the rule pack name if it's URL-encoded
+    rule_pack = urllib.parse.unquote(rule_pack)
+
+    # Fetch the content
+    content = await fetch_cdk_nag_content()
+
+    # Extract the section for this rule pack
+    rule_pack_section = extract_rule_pack_section(content, rule_pack)
+
+    # Check if we got an error message
+    if rule_pack_section.startswith(f"Rule pack '{rule_pack}' not found"):
+        return rule_pack_section
+
+    # Extract the warnings section
+    found, warnings_section = extract_section_by_marker(rule_pack_section, '### Warnings')
+
+    if not found:
+        return f"No warnings found for rule pack '{rule_pack}'."
+
+    return warnings_section
+
+
+async def get_errors(rule_pack: str) -> str:
+    """Get only the errors section for a rule pack.
+
+    Args:
+        rule_pack: The name of the rule pack to get errors for.
+
+    Returns:
+        The errors section for the specified rule pack.
+    """
+    # Decode the rule pack name if it's URL-encoded
+    rule_pack = urllib.parse.unquote(rule_pack)
+
+    # Fetch the content
+    content = await fetch_cdk_nag_content()
+
+    # Extract the section for this rule pack
+    rule_pack_section = extract_rule_pack_section(content, rule_pack)
+
+    # Check if we got an error message
+    if rule_pack_section.startswith(f"Rule pack '{rule_pack}' not found"):
+        return rule_pack_section
+
+    # Extract the errors section
+    found, errors_section = extract_section_by_marker(rule_pack_section, '### Errors')
+
+    if not found:
+        return f"No errors found for rule pack '{rule_pack}'."
+
+    return errors_section
+
+
+async def get_rule(rule_id: str) -> str:
+    """Get information about a specific rule.
+
+    Args:
+        rule_id: The ID of the rule to get information for.
+
+    Returns:
+        A formatted string containing information about the rule.
+    """
+    # Fetch the content
+    content = await fetch_cdk_nag_content()
+
+    # Extract the rule information
+    rule_info = extract_rule_info(content, rule_id)
+
+    # Format the rule information
+    if rule_info:
+        return format_rule_info(rule_info)
+    else:
+        return f'Rule {rule_id} not found in CDK Nag documentation.'
+
+
+def check_cdk_nag_suppressions(
+    code: Optional[str] = None,
+    file_path: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Check if CDK code contains Nag suppressions that require human review.
+
+    This function scans TypeScript/JavaScript code for any instances of NagSuppressions being used
+    and flags them for human review. It helps ensure that security suppressions are only
+    applied with proper human oversight and justification.
+
+    Args:
+        code: CDK code to analyze (TypeScript/JavaScript)
+        file_path: Path to a file containing CDK code to analyze
+
+    Returns:
+        Dictionary with analysis results including:
+        - has_suppressions: Whether suppressions were found
+        - suppressions: List of detected suppressions with line numbers and context
+        - recommendation: Security guidance for human developers
+    """
+    # Validate input parameters
+    if code is None and file_path is None:
+        return {'error': 'Either code or file_path must be provided', 'status': 'error'}
+
+    if code is not None and file_path is not None:
+        return {'error': 'Only one of code or file_path should be provided', 'status': 'error'}
+
+    # If file_path is provided, read the file content
+    if file_path is not None:
+        try:
+            with open(file_path, 'r') as f:
+                code = f.read()
+        except Exception as e:
+            return {'error': f'Failed to read file: {str(e)}', 'status': 'error'}
+    
+    # Ensure code is not None at this point
+    if code is None:
+        code = ""  # Default to empty string if somehow still None
+
+    # Define patterns to look for
+    patterns = [
+        (
+            r'import\s+{\s*.*NagSuppressions.*\s*}\s+from\s+[\'"]cdk-nag[\'"]',
+            'NagSuppressions import',
+        ),
+        (r'NagSuppressions\.addStackSuppressions', 'Stack-level suppression'),
+        (r'NagSuppressions\.addResourceSuppressions', 'Resource-level suppression'),
+        (r'NagSuppressions\.addResourceSuppressionsByPath', 'Path-based suppression'),
+    ]
+
+    # Find all matches
+    suppressions_found = []
+    lines = code.split('\n')
+
+    for i, line in enumerate(lines):
+        for pattern, suppression_type in patterns:
+            if re.search(pattern, line):
+                # Get context (3 lines before and after)
+                start = max(0, i - 3)
+                end = min(len(lines), i + 4)
+                context = '\n'.join(lines[start:end])
+
+                suppressions_found.append(
+                    {
+                        'line_number': i + 1,
+                        'line': line.strip(),
+                        'type': suppression_type,
+                        'context': context,
+                    }
+                )
+
+    # Generate response
+    if suppressions_found:
+        return {
+            'has_suppressions': True,
+            'suppressions': suppressions_found,
+            'recommendation': '⚠️ SECURITY ALERT: This code contains CDK Nag suppressions that require human review.',
+            'action_required': 'Review each suppression and ensure it has proper justification.',
+            'security_impact': 'CDK Nag suppressions can bypass important security checks. Each suppression should be carefully reviewed by a human developer and have a documented justification.',
+            'best_practice': 'Fix the underlying security issue rather than suppressing the warning whenever possible.',
+            'status': 'success',
+        }
+    else:
+        return {
+            'has_suppressions': False,
+            'message': 'No CDK Nag suppressions detected in the provided code.',
+            'status': 'success',
+        }

awslabs/cdk_mcp_server/data/construct_descriptions.py

@@ -0,0 +1,32 @@
+"""GenAI CDK construct descriptions."""
+
+from typing import Dict
+
+
+def get_construct_descriptions() -> Dict[str, str]:
+    """Get a dictionary mapping construct names to their descriptions."""
+    return {
+        # Agent-related constructs
+        'Agent_creation': 'Create and configure Bedrock Agents with foundation models, instructions, and optional features',
+        'Agent_actiongroups': 'Define custom functions for Bedrock Agents to call via Lambda and OpenAPI schemas',
+        'Agent_alias': 'Create versioned aliases for Bedrock Agents to manage deployment and integration',
+        'Agent_collaboration': 'Configure multiple Bedrock Agents to work together on complex tasks',
+        'Agent_custom_orchestration': 'Override default agent orchestration flow with custom Lambda functions',
+        'Agent_prompt_override': 'Customize prompts and LLM configurations for different agent processing steps',
+        # Knowledge Base constructs
+        'Knowledgebases_kendra': 'Create knowledge bases from Amazon Kendra GenAI indexes for RAG applications',
+        'Knowledgebases_datasources': 'Configure data sources for Bedrock Knowledge Bases including S3, web crawlers, and more',
+        'Knowledgebases_parsing': 'Define strategies for processing and interpreting document contents in knowledge bases',
+        'Knowledgebases_transformation': 'Apply custom processing steps to documents during knowledge base ingestion',
+        'Knowledgebases_chunking': 'Configure document chunking strategies for optimal knowledge base performance',
+        'Knowledgebases_vector_opensearch': 'Use OpenSearch Serverless as a vector store (vector database) for Bedrock Knowledge Bases',
+        'Knowledgebases_vector_aurora': 'Use Amazon RDS Aurora PostgreSQL as a vector store (vector database) for Bedrock Knowledge Bases',
+        'Knowledgebases_vector_pinecone': 'Use Pinecone as a vector store (vector database) for Bedrock Knowledge Bases',
+        'Knowledgebases_vector_creation': 'Create and configure vector stores (vector databases) for Bedrock Knowledge Bases',
+        # Other Bedrock constructs
+        'Bedrockguardrails': 'Configure content filtering and safety guardrails for Bedrock foundation models',
+        'Profiles': 'Create and manage inference profiles for tracking usage and costs across regions',
+        # OpenSearch constructs
+        'Opensearchserverless_overview': 'Create and configure Amazon OpenSearch Serverless for vector search applications',
+        'Opensearch_vectorindex_overview': 'Configure vector indexes in Amazon OpenSearch for semantic search',
+    }