feat: changed read doc tool to reflect it's generic purpose (#1860)

* feat: changed read doc tool to reflect it's generic purpose

* feat: changed read doc tool to reflect it's generic purpose=> cdk_tools turn to iac_tools

* feat: changed read doc tool to reflect it's generic purpose=> cdk_tools turn to iac_tools

* chore: update src/aws-iac-mcp-server/awslabs/aws_iac_mcp_server/server.py

Co-authored-by: Vishaal Mehrishi <[email protected]>

* feat: changed read doc tool When To Use section

* feat: update tool names in mcp server instructions

* chore(aws-iac-mcp-server): update read documentation tool description

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

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

Co-authored-by: kdbrogan <[email protected]>

* feat: update fastmcp dependency and tool description changes for search tools to explain the rank field to LLm

---------

Co-authored-by: Vishaal Mehrishi <[email protected]>
Co-authored-by: kdbrogan <[email protected]>

Author: 3 people

.secrets.baseline

@@ -133,7 +133,7 @@
         "filename": "src/aws-iac-mcp-server/README.md",
         "hashed_secret": "df99ad98cabfe1616640820bcfb345ef5b10077f",
         "is_verified": false,
-        "line_number": 290,
+        "line_number": 306,
         "is_secret": false
       }
     ],
@@ -906,5 +906,5 @@
       }
     ]
   },
-  "generated_at": "2025-11-26T15:26:15Z"
+  "generated_at": "2025-12-01T14:26:01Z"
 }

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

@@ -47,6 +47,20 @@ Get started with this MCP server for creating and troubleshooting AWS infrastruc
 
 ## Available MCP Tools
 
+### Read Documentation Tool
+
+#### read_iac_documentation_page
+Fetches and converts any Infrastructure as Code (CDK or CloudFormation) documentation page to markdown format.
+
+**Use this tool to:**
+- Read complete CDK documentation pages rather than just excerpts
+- Read complete CloudFormation resource type documentation and property references
+- Get detailed CloudFormation template syntax and examples
+- Access CloudFormation API reference documentation
+- Read CloudFormation hooks and lifecycle management guides
+- Review CFN Guard policy validation rules and syntax
+- Access CloudFormation CLI documentation and usage patterns
+
 ### CloudFormation Tools
 
 #### validate_cloudformation_template
@@ -119,8 +133,6 @@ Searches AWS CDK documentation knowledge bases and returns relevant excerpts.
 - Use boolean operators: "DynamoDB AND table", "Lambda OR Function"
 - Search for specific properties: "bucket encryption", "lambda environment variables"
 
-#### read_cdk_documentation_page
-Fetches and converts an AWS CDK documentation page to markdown format.
 
 **Parameters:**
 - `url` (required): URL from search results to read the full page content
@@ -180,11 +192,15 @@ Find CDK examples for Lambda function with VPC configuration
 Show me CDK constructs for DynamoDB table with encryption
 ```
 
-#### Read CDK Documentation Page
+#### Read Infrastructure as Code Documentation Page
 ```
 Read the full CDK documentation for aws-s3.Bucket from this URL: [URL from search results]
 ```
 
+```
+Read the complete CloudFormation documentation for AWS::S3::Bucket from this URL: [URL from search results]
+```
+
 #### Search CDK Samples and Constructs
 ```
 Find CDK code samples for serverless API with TypeScript

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

@@ -16,18 +16,18 @@
 
 import json
 from .sanitizer import sanitize_tool_response
-from .tools.cdk_tools import (
+from .tools.cloudformation_compliance_checker import check_compliance, initialize_guard_rules
+from .tools.cloudformation_deployment_troubleshooter import DeploymentTroubleshooter
+from .tools.cloudformation_pre_deploy_validation import cloudformation_pre_deploy_validation
+from .tools.cloudformation_validator import validate_template
+from .tools.iac_tools import (
     SupportedLanguages,
     cdk_best_practices_tool,
-    read_cdk_documentation_page_tool,
+    read_iac_documentation_page_tool,
     search_cdk_documentation_tool,
     search_cdk_samples_and_constructs_tool,
     search_cloudformation_documentation_tool,
 )
-from .tools.cloudformation_compliance_checker import check_compliance, initialize_guard_rules
-from .tools.cloudformation_deployment_troubleshooter import DeploymentTroubleshooter
-from .tools.cloudformation_pre_deploy_validation import cloudformation_pre_deploy_validation
-from .tools.cloudformation_validator import validate_template
 from dataclasses import asdict
 from mcp.server.fastmcp import FastMCP
 from typing import Optional
@@ -49,7 +49,7 @@
                 - Use `troubleshoot_cloudformation_deployment` when: You need to diagnose CloudFormation deployment failures with root cause analysis and CloudTrail integration
                 - Use `search_cdk_documentation` when: You need specific CDK construct APIs, properties, or official documentation from AWS CDK knowledge bases
                 - 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 `read_iac_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
 
@@ -308,7 +308,7 @@ async def search_cdk_documentation(query: str) -> str:
     Returns JSON with:
     - knowledge_response: Details of the response
         - results: Array with single result containing:
-            - rank: Always 1 for document reads
+            - rank: Search relevance ranking (1 = most relevant, higher is less relevant)
             - title: Document title or filename
             - url: Source URL of the document
             - context: Full or paginated document content
@@ -334,22 +334,19 @@ async def search_cdk_documentation(query: str) -> str:
 
 
 @mcp.tool()
-async def read_cdk_documentation_page(
+async def read_iac_documentation_page(
     url: str,
     starting_index: int = 0,
 ) -> str:
-    """Fetch and convert an AWS CDK documentation page to markdown format.
+    """Fetch and convert any Infrastructure as Code (CDK or CloudFormation) documentation page to markdown format.
 
     ## Usage
 
-    This tool retrieves the complete content of a specific CDK documentation page. Use it when you need detailed information from a particular document rather than the limited context from the search results.
+    This tool retrieves the complete content of a specific CDK or CloudFormation documentation page. Use it when you need detailed information from a particular document rather than the limited context from the search results.
 
     ## When to Use
 
-    - Read complete documentation pages rather than just excerpts
-    - Get the full content of a specific document from search results
-    - Access detailed API documentation for specific constructs
-    - Read module READMEs and interface documentation
+    After using a search tool, use this tool to fetch the complete content of any relevant page in the search results.
 
     ## Supported Document Types
 
@@ -380,7 +377,7 @@ async def read_cdk_documentation_page(
     Returns:
         List of search results with URLs, titles, and context snippets
     """
-    result = await read_cdk_documentation_page_tool(url, starting_index)
+    result = await read_iac_documentation_page_tool(url, starting_index)
 
     # Convert dataclass to dict for JSON serialization
     response_dict = asdict(result)
@@ -420,7 +417,7 @@ async def search_cloudformation_documentation(query: str) -> str:
     Returns JSON with:
     - knowledge_response: Details of the response
       - results: Array with single result containing:
-        - rank: Always 1 for document reads
+        - rank: Search relevance ranking (1 = most relevant, higher is less relevant)
         - title: Document title or filename
         - url: Source URL of the document
         - context: Full or paginated document content
@@ -488,7 +485,7 @@ async def search_cdk_samples_and_constructs(
     Returns JSON with:
     - knowledge_response: Details of the response
       - results: Array with single result containing:
-        - rank: Always 1 for document reads
+        - rank: Search relevance ranking (1 = most relevant, higher is less relevant)
         - title: Document title or filename
         - url: Source URL of the document
         - context: Full or paginated document content

src/aws-iac-mcp-server/awslabs/aws_iac_mcp_server/tools/cdk_tools.py renamed to src/aws-iac-mcp-server/awslabs/aws_iac_mcp_server/tools/iac_tools.py

@@ -49,8 +49,8 @@ async def search_cdk_documentation_tool(query: str) -> CDKToolResponse:
     )
 
 
-async def read_cdk_documentation_page_tool(url: str, starting_index: int = 0) -> CDKToolResponse:
-    """Read CDK documentation page.
+async def read_iac_documentation_page_tool(url: str, starting_index: int = 0) -> CDKToolResponse:
+    """Read IaC documentation page.
 
     Args:
         url: URL from search results to read the full page content.

src/aws-iac-mcp-server/pyproject.toml

@@ -12,7 +12,7 @@ dependencies = [
     "botocore>=1.34.0",
     "pyyaml>=6.0.0",
     "guardpycfn>=0.1.0",
-    "fastmcp>=0.1.0",
+    "fastmcp>=2.13.0",
     "loguru>=0.7.0",
 ]
 license = {text = "Apache-2.0"}

src/aws-iac-mcp-server/tests/test_server.py

@@ -16,10 +16,15 @@
 
 import json
 import pytest
+from awslabs.aws_iac_mcp_server.knowledge_models import CDKToolResponse
 from awslabs.aws_iac_mcp_server.server import (
     cdk_best_practices,
     check_cloudformation_template_compliance,
     get_cloudformation_pre_deploy_validation_instructions,
+    read_iac_documentation_page,
+    search_cdk_documentation,
+    search_cdk_samples_and_constructs,
+    search_cloudformation_documentation,
     troubleshoot_cloudformation_deployment,
     validate_cloudformation_template,
 )
@@ -194,9 +199,6 @@ def test_troubleshoot_cloudformation_deployment_non_dict_result(
     @pytest.mark.asyncio
     async def test_search_cdk_documentation_success(self, mock_sanitize, mock_search):
         """Test successful CDK documentation search."""
-        from awslabs.aws_iac_mcp_server.knowledge_models import CDKToolResponse
-        from awslabs.aws_iac_mcp_server.server import search_cdk_documentation
-
         mock_response = CDKToolResponse(
             knowledge_response=[],
             next_step_guidance='To read the full documentation pages for these search results, use the `read_cdk_documentation_page` tool. If you need to find real code examples for constructs referenced in the search results, use the `search_cdk_samples_and_constructs` tool.',
@@ -214,43 +216,37 @@ async def test_search_cdk_documentation_success(self, mock_sanitize, mock_search
 class TestReadCdkDocumentationPage:
     """Test read_cdk_documentation_page tool."""
 
-    @patch('awslabs.aws_iac_mcp_server.server.read_cdk_documentation_page_tool')
+    @patch('awslabs.aws_iac_mcp_server.server.read_iac_documentation_page_tool')
     @patch('awslabs.aws_iac_mcp_server.server.sanitize_tool_response')
     @pytest.mark.asyncio
-    async def test_read_cdk_documentation_page_success(self, mock_sanitize, mock_read):
+    async def test_read_iac_documentation_page_success(self, mock_sanitize, mock_read):
         """Test successful CDK documentation page read."""
-        from awslabs.aws_iac_mcp_server.knowledge_models import CDKToolResponse
-        from awslabs.aws_iac_mcp_server.server import read_cdk_documentation_page
-
         mock_response = CDKToolResponse(
             knowledge_response=[],
             next_step_guidance='If you need code examples, use `search_cdk_samples_and_constructs` tool.',
         )
         mock_read.return_value = mock_response
         mock_sanitize.return_value = 'sanitized response'
 
-        result = await read_cdk_documentation_page('https://example.com/doc')
+        result = await read_iac_documentation_page('https://example.com/doc')
 
         assert result == 'sanitized response'
         mock_read.assert_called_once_with('https://example.com/doc', 0)
         mock_sanitize.assert_called_once()
 
-    @patch('awslabs.aws_iac_mcp_server.server.read_cdk_documentation_page_tool')
+    @patch('awslabs.aws_iac_mcp_server.server.read_iac_documentation_page_tool')
     @patch('awslabs.aws_iac_mcp_server.server.sanitize_tool_response')
     @pytest.mark.asyncio
-    async def test_read_cdk_documentation_page_with_starting_index(self, mock_sanitize, mock_read):
+    async def test_read_iac_documentation_page_with_starting_index(self, mock_sanitize, mock_read):
         """Test CDK documentation page read with starting index."""
-        from awslabs.aws_iac_mcp_server.knowledge_models import CDKToolResponse
-        from awslabs.aws_iac_mcp_server.server import read_cdk_documentation_page
-
         mock_response = CDKToolResponse(
             knowledge_response=[],
             next_step_guidance='If you need code examples, use `search_cdk_samples_and_constructs` tool.',
         )
         mock_read.return_value = mock_response
         mock_sanitize.return_value = 'sanitized response'
 
-        await read_cdk_documentation_page('https://example.com/doc', starting_index=100)
+        await read_iac_documentation_page('https://example.com/doc', starting_index=100)
 
         mock_read.assert_called_once_with('https://example.com/doc', 100)
 
@@ -263,9 +259,6 @@ class TestSearchCloudFormationDocumentation:
     @pytest.mark.asyncio
     async def test_search_cloudformation_documentation_success(self, mock_sanitize, mock_search):
         """Test successful CloudFormation documentation search."""
-        from awslabs.aws_iac_mcp_server.knowledge_models import CDKToolResponse
-        from awslabs.aws_iac_mcp_server.server import search_cloudformation_documentation
-
         mock_response = CDKToolResponse(knowledge_response=[], next_step_guidance=None)
         mock_search.return_value = mock_response
         mock_sanitize.return_value = 'sanitized response'
@@ -285,9 +278,6 @@ class TestSearchCdkSamplesAndConstructs:
     @pytest.mark.asyncio
     async def test_search_cdk_samples_and_constructs_success(self, mock_sanitize, mock_search):
         """Test successful CDK samples and constructs search."""
-        from awslabs.aws_iac_mcp_server.knowledge_models import CDKToolResponse
-        from awslabs.aws_iac_mcp_server.server import search_cdk_samples_and_constructs
-
         mock_response = CDKToolResponse(
             knowledge_response=[],
             next_step_guidance='To read the full documentation pages for these search results, use the `read_cdk_documentation_page` tool.',
@@ -308,9 +298,6 @@ async def test_search_cdk_samples_and_constructs_with_language(
         self, mock_sanitize, mock_search
     ):
         """Test CDK samples search with specific language."""
-        from awslabs.aws_iac_mcp_server.knowledge_models import CDKToolResponse
-        from awslabs.aws_iac_mcp_server.server import search_cdk_samples_and_constructs
-
         mock_response = CDKToolResponse(
             knowledge_response=[],
             next_step_guidance='To read the full documentation pages for these search results, use the `read_cdk_documentation_page` tool.',

src/aws-iac-mcp-server/tests/tools/test_cdk_search_documentation_tool.py

@@ -16,7 +16,7 @@
 
 import pytest
 from awslabs.aws_iac_mcp_server.knowledge_models import KnowledgeResult
-from awslabs.aws_iac_mcp_server.tools.cdk_tools import search_cdk_documentation_tool
+from awslabs.aws_iac_mcp_server.tools.iac_tools import search_cdk_documentation_tool
 from unittest.mock import AsyncMock, patch
 
 
@@ -35,7 +35,7 @@ async def test_search_cdk_documentation_success(self):
             )
         ]
         with patch(
-            'awslabs.aws_iac_mcp_server.tools.cdk_tools.search_documentation',
+            'awslabs.aws_iac_mcp_server.tools.iac_tools.search_documentation',
             new_callable=AsyncMock,
         ) as mock_search:
             mock_search.return_value = mock_response
@@ -53,7 +53,7 @@ async def test_search_cdk_documentation_success(self):
     async def test_search_cdk_documentation_error(self):
         """Test CDK documentation search with error handling."""
         with patch(
-            'awslabs.aws_iac_mcp_server.tools.cdk_tools.search_documentation',
+            'awslabs.aws_iac_mcp_server.tools.iac_tools.search_documentation',
             new_callable=AsyncMock,
         ) as mock_search:
             mock_search.side_effect = Exception('Network error')

src/aws-iac-mcp-server/tests/tools/test_read_cdk_documentation_page_tool.py

@@ -16,7 +16,7 @@
 
 import pytest
 from awslabs.aws_iac_mcp_server.knowledge_models import KnowledgeResult
-from awslabs.aws_iac_mcp_server.tools.cdk_tools import read_cdk_documentation_page_tool
+from awslabs.aws_iac_mcp_server.tools.iac_tools import read_iac_documentation_page_tool
 from unittest.mock import AsyncMock, patch
 
 
@@ -35,12 +35,12 @@ async def test_read_cdk_documentation_page_success(self):
             )
         ]
         with patch(
-            'awslabs.aws_iac_mcp_server.tools.cdk_tools.read_documentation',
+            'awslabs.aws_iac_mcp_server.tools.iac_tools.read_documentation',
             new_callable=AsyncMock,
         ) as mock_read:
             mock_read.return_value = mock_response
 
-            result = await read_cdk_documentation_page_tool(
+            result = await read_iac_documentation_page_tool(
                 'https://docs.aws.amazon.com/cdk/test.html'
             )
 
@@ -55,12 +55,12 @@ async def test_read_cdk_documentation_page_success(self):
     async def test_read_cdk_documentation_page_with_start_index(self):
         """Test CDK documentation page read with start index."""
         with patch(
-            'awslabs.aws_iac_mcp_server.tools.cdk_tools.read_documentation',
+            'awslabs.aws_iac_mcp_server.tools.iac_tools.read_documentation',
             new_callable=AsyncMock,
         ) as mock_read:
             mock_read.return_value = []
 
-            await read_cdk_documentation_page_tool(
+            await read_iac_documentation_page_tool(
                 'https://docs.aws.amazon.com/cdk/test.html', 100
             )
 
@@ -72,10 +72,10 @@ async def test_read_cdk_documentation_page_with_start_index(self):
     async def test_read_cdk_documentation_page_error(self):
         """Test CDK documentation page read with error handling."""
         with patch(
-            'awslabs.aws_iac_mcp_server.tools.cdk_tools.read_documentation',
+            'awslabs.aws_iac_mcp_server.tools.iac_tools.read_documentation',
             new_callable=AsyncMock,
         ) as mock_read:
             mock_read.side_effect = Exception('Read failed')
 
             with pytest.raises(Exception, match='Read failed'):
-                await read_cdk_documentation_page_tool('https://docs.aws.amazon.com/cdk/test.html')
+                await read_iac_documentation_page_tool('https://docs.aws.amazon.com/cdk/test.html')