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

awslabs/__init__.py

@@ -0,0 +1,2 @@
+# This file is part of the awslabs namespace.
+# It is intentionally minimal to support PEP 420 namespace packages.

awslabs/cdk_mcp_server/__init__.py

@@ -0,0 +1,8 @@
+"""AWS CDK MCP server package."""
+
+# Import the minimal set of essential functions
+from awslabs.cdk_mcp_server.core.server import main, mcp
+
+__all__ = ['main', 'mcp']
+
+__version__ = '0.0.0'

awslabs/cdk_mcp_server/core/__init__.py

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

awslabs/cdk_mcp_server/core/resources.py

@@ -0,0 +1,271 @@
+"""AWS CDK MCP resource handlers."""
+
+import logging
+from awslabs.cdk_mcp_server.data.cdk_nag_parser import get_errors, get_rule_pack, get_warnings
+from awslabs.cdk_mcp_server.data.genai_cdk_loader import (
+    get_genai_cdk_construct,
+    get_genai_cdk_construct_section,
+    get_genai_cdk_overview,
+    list_available_sections,
+)
+from awslabs.cdk_mcp_server.data.lambda_powertools_loader import get_lambda_powertools_section
+from awslabs.cdk_mcp_server.data.solutions_constructs_parser import get_pattern_raw
+from enum import Enum
+
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+
+class RulePack(str, Enum):
+    """CDK Nag rule packs."""
+
+    AWS_SOLUTIONS = 'AWS Solutions'
+    HIPAA_SECURITY = 'HIPAA Security'
+    NIST_800_53_REV4 = 'NIST 800-53 rev 4'
+    NIST_800_53_REV5 = 'NIST 800-53 rev 5'
+    PCI_DSS_321 = 'PCI DSS 3.2.1'
+
+
+async def get_all_cdk_nag_rules(rule_pack: str) -> str:
+    """Get all rules for a specific CDK Nag rule pack.
+
+    Args:
+        rule_pack: The CDK Nag rule pack name (e.g., "AWS Solutions", "HIPAA Security")
+
+    Returns:
+        String containing the rule description and details
+    """
+    # Convert string to enum value
+    try:
+        rule_pack_enum = RulePack(rule_pack)
+        return await get_rule_pack(rule_pack_enum)
+    except ValueError:
+        return f'Invalid rule pack: {rule_pack}. Valid values are: {", ".join([p.value for p in RulePack])}'
+
+
+async def get_cdk_nag_warnings(rule_pack: str) -> str:
+    """Get only the warnings section for a specific CDK Nag rule pack.
+
+    Args:
+        rule_pack: The CDK Nag rule pack name (e.g., "AWS Solutions", "HIPAA Security")
+
+    Returns:
+        String containing the warnings section of the rule pack
+    """
+    # Convert string to enum value
+    try:
+        rule_pack_enum = RulePack(rule_pack)
+        return await get_warnings(rule_pack_enum)
+    except ValueError:
+        return f'Invalid rule pack: {rule_pack}. Valid values are: {", ".join([p.value for p in RulePack])}'
+
+
+async def get_cdk_nag_errors(rule_pack: str) -> str:
+    """Get only the errors section for a specific CDK Nag rule pack.
+
+    Args:
+        rule_pack: The CDK Nag rule pack name (e.g., "AWS Solutions", "HIPAA Security")
+
+    Returns:
+        String containing the errors section of the rule pack
+    """
+    # Convert string to enum value
+    try:
+        rule_pack_enum = RulePack(rule_pack)
+        return await get_errors(rule_pack_enum)
+    except ValueError:
+        return f'Invalid rule pack: {rule_pack}. Valid values are: {", ".join([p.value for p in RulePack])}'
+
+
+async def get_lambda_powertools_guidance(topic: str = '') -> str:
+    """Get Lambda Powertools guidance on a specific topic.
+
+    Lambda Powertools provides three core capabilities:
+    - Structured Logging: Transform text logs into JSON objects with consistent fields
+    - Tracing: Gain visibility into request flows across distributed services
+    - Metrics: Collect quantitative data about your application's behavior
+
+    Available topics:
+    - logging: Structured logging implementation
+    - tracing: Tracing implementation
+    - metrics: Metrics implementation
+    - cdk: CDK integration patterns
+    - dependencies: Dependencies management
+    - insights: Lambda Insights integration
+    - bedrock: Bedrock Agent integration
+
+    Args:
+        topic: Topic to get guidance on
+
+    Returns:
+        String containing the guidance for the specified topic
+    """
+    return get_lambda_powertools_section(topic)
+
+
+async def get_lambda_powertools_index() -> str:
+    """Get Lambda Powertools guidance overview.
+
+    Lambda Powertools provides three core capabilities:
+    - Structured Logging: Transform text logs into JSON objects with consistent fields
+    - Tracing: Gain visibility into request flows across distributed services
+    - Metrics: Collect quantitative data about your application's behavior
+
+    Available topics:
+    - logging: Structured logging implementation
+    - tracing: Tracing implementation
+    - metrics: Metrics implementation
+    - cdk: CDK integration patterns
+    - dependencies: Dependencies management
+    - insights: Lambda Insights integration
+    - bedrock: Bedrock Agent integration
+
+    Returns:
+        String containing the Lambda Powertools guidance overview
+    """
+    return get_lambda_powertools_section('index')
+
+
+async def get_solutions_construct_pattern_resource(pattern_name: str) -> str:
+    """Get complete documentation for an AWS Solutions Constructs pattern.
+
+    This resource returns the full documentation for a pattern including:
+    - Code examples in multiple languages (TypeScript, Python, Java)
+    - Props tables with all configuration options
+    - Pattern properties and default settings
+    - Architecture diagrams
+
+    Common pattern categories include:
+    - Serverless API (aws-apigateway-lambda, aws-apigateway-lambda-dynamodb)
+    - Event-Driven (aws-s3-lambda, aws-sns-lambda, aws-sqs-lambda)
+    - Storage (aws-s3-dynamodb, aws-kinesisfirehose-s3)
+    - Web Application (aws-cloudfront-s3, aws-cloudfront-apigateway)
+
+    Integration with other best practices:
+    - Solutions Constructs implement many security best practices by default
+    - They work well with Lambda Powertools for observability
+    - They reduce the number of CDK Nag warnings in your code
+
+    Args:
+        pattern_name: The name of the pattern (e.g., 'aws-lambda-dynamodb')
+
+    Returns:
+        String containing the complete pattern documentation as markdown
+    """
+    # Get the raw pattern documentation directly
+    pattern_raw = await get_pattern_raw(pattern_name)
+
+    if 'error' in pattern_raw:
+        from awslabs.cdk_mcp_server.data.solutions_constructs_parser import fetch_pattern_list
+
+        return f"Pattern '{pattern_name}' not found. Available patterns: {', '.join(await fetch_pattern_list())}"
+
+    # Return the raw content directly
+    return pattern_raw['content']
+
+
+async def get_genai_cdk_construct_section_resource(
+    construct_type: str, construct_name: str, section: str
+) -> str:
+    """Get a specific section of documentation for a GenAI CDK construct.
+
+    Example URIs:
+    - genai-cdk-constructs://bedrock/agent/actiongroups
+    - genai-cdk-constructs://bedrock/agent/alias
+    - genai-cdk-constructs://bedrock/knowledgebases/chunking
+
+    Args:
+        construct_type: Type of the construct (e.g., 'bedrock')
+        construct_name: Name of the construct (e.g., 'agent', 'knowledgebases')
+        section: Section of the documentation (e.g., 'actiongroups', 'chunking')
+
+    Returns:
+        String containing the requested section of documentation
+    """
+    return get_genai_cdk_construct_section(construct_type, construct_name, section)
+
+
+async def get_genai_cdk_construct_nested_section_resource(
+    construct_type: str, construct_name: str, parent: str, child: str
+) -> str:
+    """Get a nested section of documentation for a GenAI CDK construct.
+
+    Example URIs:
+    - genai-cdk-constructs://bedrock/knowledgebases/vector/opensearch
+    - genai-cdk-constructs://bedrock/knowledgebases/vector/aurora
+
+    Args:
+        construct_type: Type of the construct (e.g., 'bedrock')
+        construct_name: Name of the construct (e.g., 'knowledgebases')
+        parent: Parent section (e.g., 'vector')
+        child: Child section (e.g., 'opensearch')
+
+    Returns:
+        String containing the requested nested section of documentation
+    """
+    section = f'{parent}/{child}'
+    return get_genai_cdk_construct_section(construct_type, construct_name, section)
+
+
+async def get_available_sections_resource(construct_type: str, construct_name: str) -> str:
+    """Get available sections for a specific construct.
+
+    Example URI:
+    - genai-cdk-constructs://bedrock/agent/sections
+    - genai-cdk-constructs://bedrock/knowledgebases/sections
+
+    Args:
+        construct_type: Type of the construct (e.g., 'bedrock')
+        construct_name: Name of the construct (e.g., 'agent', 'knowledgebases')
+
+    Returns:
+        String containing available sections in markdown format
+    """
+    sections = list_available_sections(construct_type, construct_name)
+
+    if not sections:
+        return f'No sections found for {construct_name} in {construct_type}.'
+
+    result = f'# Available Sections for {construct_name.capitalize()} in {construct_type.capitalize()}\n\n'
+
+    for section in sorted(sections):
+        result += (
+            f'- [{section}](genai-cdk-constructs://{construct_type}/{construct_name}/{section})\n'
+        )
+
+    return result
+
+
+async def get_genai_cdk_construct_resource(construct_type: str, construct_name: str) -> str:
+    """Get essential information about a GenAI CDK construct.
+
+    Example URIs:
+    - genai-cdk-constructs://bedrock/Agent
+    - genai-cdk-constructs://bedrock/KnowledgeBase
+
+    Args:
+        construct_type: Type of the construct (e.g., 'bedrock')
+        construct_name: Name of the construct (e.g., 'Agent', 'KnowledgeBase')
+
+    Returns:
+        String containing formatted properties and code examples in markdown
+    """
+    return get_genai_cdk_construct(construct_type, construct_name)
+
+
+async def get_genai_cdk_overview_resource(construct_type: str) -> str:
+    """Get overview of a GenAI CDK construct type.
+
+    Example URIs:
+    - genai-cdk-constructs://bedrock
+    - genai-cdk-constructs://opensearchserverless
+    - genai-cdk-constructs://opensearch-vectorindex
+
+    Args:
+        construct_type: Type of the construct (e.g., 'bedrock')
+
+    Returns:
+        String containing overview documentation in markdown
+    """
+    return get_genai_cdk_overview(construct_type)

awslabs/cdk_mcp_server/core/search_utils.py

@@ -0,0 +1,182 @@
+"""Common search utilities for AWS CDK MCP Server."""
+
+import re
+import urllib.parse
+from typing import Any, Callable, Dict, List, Optional, TypeVar
+
+
+T = TypeVar('T')  # Generic type for search items
+
+
+def normalize_term(term: str) -> str:
+    """Normalize a term for consistent matching.
+
+    Args:
+        term: The term to normalize
+
+    Returns:
+        Normalized term (lowercase, with spaces preserved for word boundaries)
+    """
+    # Decode URL-encoded strings
+    term = urllib.parse.unquote(term).lower()
+
+    # Replace hyphens and underscores with spaces
+    term = re.sub(r'[-_]', ' ', term)
+
+    # Remove other special characters but preserve spaces
+    term = re.sub(r'[^a-z0-9 ]', '', term)
+
+    # Normalize multiple spaces
+    term = re.sub(r'\s+', ' ', term).strip()
+
+    return term
+
+
+def get_term_variations(term: str) -> List[str]:
+    """Get common variations of a term.
+
+    Args:
+        term: The term to get variations for
+
+    Returns:
+        List of term variations
+    """
+    term = term.lower()
+    variations = [term]
+
+    # Common singular/plural mappings
+    term_variations = {
+        'knowledgebase': ['knowledgebases', 'knowledge-base', 'knowledge-bases'],
+        'knowledgebases': ['knowledgebase', 'knowledge-base', 'knowledge-bases'],
+        'agent': ['agents'],
+        'agents': ['agent'],
+        'actiongroup': ['actiongroups', 'action-group', 'action-groups'],
+        'actiongroups': ['actiongroup', 'action-group', 'action-groups'],
+        'apigateway': ['api-gateway', 'api gateway', 'apigatewayv2', 'api-gateway-v2'],
+        'lambda': ['lambdas', 'lambda-function', 'lambda-functions'],
+        'dynamodb': ['dynamo-db', 'dynamo db'],
+        's3': ['s3-bucket', 's3 bucket', 'simple storage service'],
+        'sqs': ['simple-queue-service', 'simple queue service'],
+        'sns': ['simple-notification-service', 'simple notification service'],
+    }
+
+    # Add variations if they exist
+    if term in term_variations:
+        variations.extend(term_variations[term])
+
+    return variations
+
+
+def expand_search_terms(terms: List[str]) -> List[str]:
+    """Expand a list of search terms with variations.
+
+    Args:
+        terms: List of search terms
+
+    Returns:
+        Expanded list of normalized search terms with variations
+    """
+    expanded_terms = []
+
+    for term in terms:
+        # Normalize the term
+        norm_term = normalize_term(term)
+        if norm_term and norm_term not in expanded_terms:
+            expanded_terms.append(norm_term)
+
+        # Add variations
+        for variation in get_term_variations(term):
+            norm_variation = normalize_term(variation)
+            if norm_variation and norm_variation not in expanded_terms:
+                expanded_terms.append(norm_variation)
+
+    return expanded_terms
+
+
+def calculate_match_score(
+    item_text: str,
+    search_terms: List[str],
+    name_parts: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """Calculate a match score for an item against search terms.
+
+    Args:
+        item_text: The text to search in (e.g., description)
+        search_terms: List of search terms to match
+        name_parts: Optional list of name parts for higher-weight matching
+
+    Returns:
+        Dictionary with score and matched terms
+    """
+    matched_terms = []
+    score = 0
+
+    for term in search_terms:
+        term_matched = False
+
+        # Check name parts first (highest weight)
+        if name_parts:
+            for part in name_parts:
+                if term in normalize_term(part):
+                    score += 10
+                    if term not in matched_terms:
+                        matched_terms.append(term)
+                    term_matched = True
+                    break
+
+        # If not matched in name parts, check in full text
+        if not term_matched and term in item_text:
+            score += 5
+            if term not in matched_terms:
+                matched_terms.append(term)
+
+    # Bonus for matching multiple terms
+    if len(matched_terms) > 1:
+        score += len(matched_terms) * 3
+
+    return {'score': score, 'matched_terms': matched_terms, 'has_match': len(matched_terms) > 0}
+
+
+def search_items_with_terms(
+    items: List[T],
+    search_terms: List[str],
+    get_text_fn: Callable[[T], str],
+    get_name_parts_fn: Optional[Callable[[T], List[str]]] = None,
+) -> List[Dict[str, Any]]:
+    """Generic function to search items with search terms.
+
+    Args:
+        items: List of items to search
+        search_terms: List of search terms
+        get_text_fn: Function to extract searchable text from an item
+        get_name_parts_fn: Optional function to extract name parts from an item
+
+    Returns:
+        List of matched items with scores
+    """
+    # Expand search terms with variations
+    expanded_terms = expand_search_terms(search_terms)
+
+    # Calculate scores for each item
+    scored_items = []
+
+    for item in items:
+        item_text = normalize_term(get_text_fn(item))
+        name_parts = get_name_parts_fn(item) if get_name_parts_fn else None
+
+        match_result = calculate_match_score(item_text, expanded_terms, name_parts)
+
+        # Only include items with at least one match
+        if match_result['has_match']:
+            scored_items.append(
+                {
+                    'item': item,
+                    'score': match_result['score'],
+                    'matched_terms': match_result['matched_terms'],
+                }
+            )
+
+    # Sort by score (descending)
+    scored_items.sort(key=lambda x: x['score'], reverse=True)
+
+    return scored_items

awslabs/cdk_mcp_server/core/server.py

@@ -0,0 +1,74 @@
+"""AWS CDK MCP server implementation."""
+
+import argparse
+import logging
+from awslabs.cdk_mcp_server.core import resources, tools
+from mcp.server.fastmcp import FastMCP
+
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+
+# Create MCP server
+mcp = FastMCP(
+    'AWS CDK MCP Server',
+    dependencies=[
+        'pydantic',
+        'aws-lambda-powertools',
+        'httpx',
+    ],
+)
+
+
+# Register resources
+mcp.resource('cdk-nag://rules/{rule_pack}')(resources.get_all_cdk_nag_rules)
+mcp.resource('cdk-nag://warnings/{rule_pack}')(resources.get_cdk_nag_warnings)
+mcp.resource('cdk-nag://errors/{rule_pack}')(resources.get_cdk_nag_errors)
+mcp.resource('lambda-powertools://{topic}')(resources.get_lambda_powertools_guidance)
+mcp.resource('lambda-powertools://')(resources.get_lambda_powertools_index)
+mcp.resource('aws-solutions-constructs://{pattern_name}')(
+    resources.get_solutions_construct_pattern_resource
+)
+mcp.resource('genai-cdk-constructs://{construct_type}/{construct_name}/{section}')(
+    resources.get_genai_cdk_construct_section_resource
+)
+mcp.resource('genai-cdk-constructs://{construct_type}/{construct_name}/{parent}/{child}')(
+    resources.get_genai_cdk_construct_nested_section_resource
+)
+mcp.resource('genai-cdk-constructs://{construct_type}/{construct_name}/sections')(
+    resources.get_available_sections_resource
+)
+mcp.resource('genai-cdk-constructs://{construct_type}/{construct_name}')(
+    resources.get_genai_cdk_construct_resource
+)
+mcp.resource('genai-cdk-constructs://{construct_type}')(resources.get_genai_cdk_overview_resource)
+
+
+# Register tools
+mcp.tool(name='CDKGeneralGuidance')(tools.cdk_guidance)
+mcp.tool(name='ExplainCDKNagRule')(tools.explain_cdk_nag_rule)
+mcp.tool(name='CheckCDKNagSuppressions')(tools.check_cdk_nag_suppressions_tool)
+mcp.tool(name='GenerateBedrockAgentSchemaFromFile')(tools.bedrock_schema_generator_from_file)
+mcp.tool(name='GetAwsSolutionsConstructPattern')(tools.get_aws_solutions_construct_pattern)
+mcp.tool(name='SearchGenAICDKConstructs')(tools.search_genai_cdk_constructs)
+
+
+def main():
+    """Run the MCP server with CLI argument support."""
+    parser = argparse.ArgumentParser(description='AWS CDK MCP Server')
+    parser.add_argument('--sse', action='store_true', help='Use SSE transport')
+    parser.add_argument('--port', type=int, default=8888, help='Port to run the server on')
+
+    args = parser.parse_args()
+
+    # Run server with appropriate transport
+    if args.sse:
+        mcp.settings.port = args.port
+        mcp.run(transport='sse')
+    else:
+        mcp.run()
+
+
+if __name__ == '__main__':
+    main()