awslabs.cdk-mcp-server 0.0.10417__tar.gz

awslabs_cdk_mcp_server-0.0.10417/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+
+# Ruff
+.ruff_cache/
+
+# Build
+*.manifest
+*.spec
+.pybuilder/
+target/
+
+# Environments
+.env
+.env.local
+.env.*.local
+
+# PyPI
+.pypirc

awslabs_cdk_mcp_server-0.0.10417/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v3.13.0
+    hooks:
+      - id: commitizen
+      - id: commitizen-branch
+        stages: [push]

awslabs_cdk_mcp_server-0.0.10417/.python-version

@@ -0,0 +1 @@
+3.13

awslabs_cdk_mcp_server-0.0.10417/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+### Added
+
+- Initial project setup

awslabs_cdk_mcp_server-0.0.10417/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: awslabs.cdk-mcp-server
+Version: 0.0.10417
+Summary: An AWS CDK MCP server that provides guidance on AWS Cloud Development Kit best practices, infrastructure as code patterns, and security compliance with CDK Nag. This server offers tools to validate infrastructure designs, explain CDK Nag rules, analyze suppressions, generate Bedrock Agent schemas, and discover Solutions Constructs patterns.
+Requires-Python: >=3.13
+Requires-Dist: aws-lambda-powertools>=2.30.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: pydantic>=2.10.6
+Description-Content-Type: text/markdown
+
+# awslabs MCP CDK Expert
+
+An AWS CDK expert MCP server that provides guidance on AWS Cloud Development Kit best practices, infrastructure as code patterns, and security compliance with CDK Nag. This server offers tools to validate infrastructure designs, explain CDK Nag rules, analyze suppressions, generate Bedrock Agent schemas, and discover Solutions Constructs patterns.

awslabs_cdk_mcp_server-0.0.10417/README.md

@@ -0,0 +1,3 @@
+# awslabs MCP CDK Expert
+
+An AWS CDK expert MCP server that provides guidance on AWS Cloud Development Kit best practices, infrastructure as code patterns, and security compliance with CDK Nag. This server offers tools to validate infrastructure designs, explain CDK Nag rules, analyze suppressions, generate Bedrock Agent schemas, and discover Solutions Constructs patterns.

awslabs_cdk_mcp_server-0.0.10417/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-0.0.10417/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-0.0.10417/awslabs/cdk_mcp_server/core/__init__.py

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

awslabs_cdk_mcp_server-0.0.10417/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-0.0.10417/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-0.0.10417/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()