feat(aws-iac-mcp-server): CDK best practices tool (#1832)

* feat(aws-iac-mcp-server): CDK best practices tool

* feat(aws-iac-mcp-server): CDK best practices tool

* feat(aws-iac-mcp-server): CDK best practices tool

* chore(aws-iac-mcp-server): CDK best practices updates

* chore(aws-iac-mcp-server): CDK best practices tool usage instruction

* chore(aws-iac-mcp-server): updated CDK best practices

* chore(aws-iac-mcp-server): update CDK Nag text in best practices

---------

Co-authored-by: Jimin Kim <[email protected]>

Author: vishaalmehrishi

.secrets.baseline

@@ -133,7 +133,7 @@
         "filename": "src/aws-iac-mcp-server/README.md",
         "hashed_secret": "df99ad98cabfe1616640820bcfb345ef5b10077f",
         "is_verified": false,
-        "line_number": 188,
+        "line_number": 194,
         "is_secret": false
       }
     ],
@@ -906,5 +906,5 @@
       }
     ]
   },
-  "generated_at": "2025-11-21T19:55:13Z"
+  "generated_at": "2025-11-24T17:57:50Z"
 }

src/aws-iac-mcp-server/README.md

@@ -101,6 +101,12 @@ Searches CDK code samples, examples, constructs, and patterns documentation.
 - `query` (required): Search query for CDK samples and constructs
 - `language` (optional): Programming language filter (default: "typescript")
 
+### cdk_best_practices
+Provides CDK best practices for application configuration, coding, constructs, security, and testing.
+
+**Parameters:**
+- None
+
 ## Prerequisites
 
 1. Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) or the [GitHub README](https://github.com/astral-sh/uv#installation)
@@ -256,6 +262,12 @@ Search CloudFormation documentation for AWS::Lambda::Function properties
 Find CDK code samples for serverless API with TypeScript
 ```
 
+### Consult CDK best practices
+
+```
+Suggest improvements to my CDK setup based on the best practices
+```
+
 ## Security Considerations
 
 ⚠️ **Privacy Notice**: This MCP server executes AWS API calls using your credentials and shares the response data with your third-party AI model provider (e.g., Amazon Q, Claude Desktop, Cursor, VS Code). Users are responsible for understanding your AI provider's data handling practices and ensuring compliance with your organization's security and privacy requirements when using this tool with AWS resources.

src/aws-iac-mcp-server/awslabs/aws_iac_mcp_server/server.py

@@ -22,6 +22,7 @@
 from .sanitizer import sanitize_tool_response
 from .tools.cdk_tools import (
     SupportedLanguages,
+    cdk_best_practices_tool,
     read_cdk_documentation_page_tool,
     search_cdk_documentation_tool,
     search_cdk_samples_and_constructs_tool,
@@ -50,6 +51,7 @@
                 - Use `search_cdk_samples_and_constructs` when: You need working code examples, implementation patterns, or community constructs
                 - Use `read_cdk_documentation_page` when: You have a specific documentation URL from search results and need complete content with pagination support
                 - Use `search_cloudformation_documentation` when: You need Cloudformation related official documentation, resource type information or template syntax
+                - Use `cdk_best_practices` when: You need to generate or review CDK code
 
               """,
 )
@@ -475,6 +477,50 @@ async def search_cdk_samples_and_constructs(
     return sanitize_tool_response(json.dumps(response_dict))
 
 
+@mcp.tool()
+async def cdk_best_practices() -> str:
+    """Returns CDK best practices and security guidelines.
+
+    ## Usage
+
+    This tool provides comprehensive CDK development guidelines, security best practices, and architectural recommendations. Always run this tool when asked to generate or review CDK code and follow the guidelines returned.
+
+    ## When to Use
+
+    - Get CDK security best practices and compliance guidelines
+    - Look up architectural patterns and recommendations
+    - Get guidance on CDK application structure and organization
+    - Research performance optimization techniques
+    - Learn about proper construct usage and design patterns
+    - Understand deployment and testing best practices
+
+    ## Result Interpretation
+
+    Returns JSON with:
+    - knowledge_response: Details of the response
+      - results: Array with single result containing:
+        - rank: Always 1
+        - title: Document title or filename
+        - url: Source URL of the CDK best practices
+        - context: A summary of the CDK best practices
+    - next_step_guidance: If present, suggested next actions to take for answering user query
+
+    ## Args
+
+    No parameters required - this tool returns the complete best practices guide.
+
+    ## Returns
+
+    Complete best practices documentation as text, including security guidelines, architectural patterns, development workflow, and compliance requirements.
+    """
+    result = await cdk_best_practices_tool()
+
+    # Convert CDKToolResponse to dict for JSON serialization
+    response_dict = asdict(result)
+
+    return sanitize_tool_response(json.dumps(response_dict))
+
+
 @mcp.resource('cfn://context/template-examples-and-best-practices')
 def get_template_examples() -> str:
     """CloudFormation Template Examples and Best Practices.