[Docs] AWS Documentation MCP with automated team setup #1888

vheckthor · 2025-07-14T10:45:05Z

User description

feat: add AWS Documentation MCP integration with automated team setup

• Add one-command setup script (scripts/setup-aws-docs-mcp.sh) that:

Installs uv package manager and Python 3.10+ if needed
Installs AWS Documentation MCP server via uv tool install
Intelligently merges with existing Cursor MCP configurations
Preserves existing MCP servers (GitHub, graphiti-memory, etc.)
Auto-configures with pre-approved AWS documentation tools

• Add Cursor rules (aws-documentation-mcp.mdc) for AWS development:

Best practices for using AWS MCP in Ocean integrations
Guidance on citing sources and using current documentation
Examples for S3, Lambda, VPC, and other AWS services
Integration patterns with existing Ocean development workflow

• Add comprehensive team documentation (AWS_DOCS_MCP_SETUP.md):

Quick start guide with usage examples
Troubleshooting instructions and configuration details
Advanced usage patterns for contextual AWS queries
Cross-platform support documentation

• Add verification script (scripts/test-aws-docs-mcp.sh):

Tests all setup components (uv, Python, MCP server, config)
Validates Cursor configuration and rule files
Provides detailed pass/fail reporting with next steps

Benefits:

Team members get AWS docs directly in Cursor chat with @aws-docs
Zero manual configuration required per developer
Automatic source citation and current best practices
Seamless integration with existing Ocean development patterns
Supports both permanent installation and temporary uvx usage

Enables @aws-docs queries in Cursor for real-time AWS documentation access with automatic source citation and Ocean integration patterns.

Description

What - A complete automated setup system that integrates AWS Documentation directly into Cursor IDE through Model Context Protocol (MCP). Developers can query AWS documentation in real-time using @aws-docs without leaving their development environment.
Components:

One-command setup script with cross-platform support
Intelligent MCP configuration that preserves existing servers
Cursor rules for AWS development best practices
Team documentation and verification tools

Why - Why - Solving Development Friction
Problems Solved:

Context Switching: Developers constantly switch between IDE and browser for AWS docs
Inconsistent Information: Teams use different or outdated AWS documentation sources
Integration Gaps: No standardized AWS documentation workflow for Ocean development
Value Delivered:
Faster Development: No more browser switching - AWS docs directly in chat
Consistent Practices: Entire team uses current AWS documentation with automatic citations
Better Code Quality: Real-time access to current AWS best practices and examples

How - Implementation & Usage
Team Setup (One-time):

./scripts/setup-aws-docs-mcp.sh  # Installs and configures everything
./scripts/test-aws-docs-mcp.sh   # Verifies setup works correctly

Daily Develpmnt Usage:

In Cursor chat:

@aws-docs "S3 event notifications for Lambda - get config and IAM permissions"
@aws-docs "VPC endpoint setup for private S3 access with security best practices"
@aws-docs "Lambda memory and timeout recommendations for high-throughput processing"

Technical Features:

Auto-approves AWS documentation tools for seamless usage
Cross-platform support (macOS, Linux, Windows)
Fallback strategies ensure reliability across different environments

Type of change

Please leave one option from the following and delete the rest:

New feature (non-breaking change which adds functionality)

All tests should be run against the port production environment(using a testing org).

Core testing checklist

Integration able to create all default resources from scratch
Resync finishes successfully
Resync able to create entities
Resync able to update entities
Resync able to detect and delete entities
Scheduled resync able to abort existing resync and start a new one
Tested with at least 2 integrations from scratch
Tested with Kafka and Polling event listeners
Tested deletion of entities that don't pass the selector

Integration testing checklist

Integration able to create all default resources from scratch
Resync able to create entities
Resync able to update entities
Resync able to detect and delete entities
Resync finishes successfully
If new resource kind is added or updated in the integration, add example raw data, mapping and expected result to the examples folder in the integration directory.
If resource kind is updated, run the integration with the example data and check if the expected result is achieved
If new resource kind is added or updated, validate that live-events for that resource are working as expected
Docs PR link here

Preflight checklist

Handled rate limiting
Handled pagination
Implemented the code in async
Support Multi account

Screenshots

Include screenshots from your environment showing how the resources of the integration will look.

2025-07-14.03-28-20.mov

API Documentation

Provide links to the API documentation used for this integration.

PR Type

Enhancement

Description

Add automated AWS Documentation MCP integration for Cursor IDE
Provide one-command setup script with cross-platform support
Include comprehensive team documentation and usage guidelines
Add verification script for testing MCP installation

Changes diagram

flowchart LR
  A["Setup Script"] --> B["Install Dependencies"]
  B --> C["Configure Cursor MCP"]
  C --> D["Add Usage Rules"]
  D --> E["Generate Documentation"]
  E --> F["Team Ready"]
  
  B --> B1["uv package manager"]
  B --> B2["Python 3.10+"]
  B --> B3["AWS MCP Server"]
  
  C --> C1["MCP Configuration"]
  C --> C2["Auto-approve Tools"]
  
  D --> D1["Cursor Rules"]
  D --> D2["Best Practices"]

Changes walkthrough 📝

Relevant files

Enhancement

setup-aws-docs-mcp.sh `Automated AWS MCP setup script` scripts/setup-aws-docs-mcp.sh Automated setup script for AWS Documentation MCP integration Cross-platform support (macOS, Linux, Windows) Installs uv package manager and Python 3.10+ if needed Configures Cursor MCP with intelligent merging of existing configs	+375/-0

Tests

test-aws-docs-mcp.sh `MCP installation verification script` scripts/test-aws-docs-mcp.sh Comprehensive verification script for MCP installation Tests all components: uv, Python, MCP server, Cursor config Provides detailed pass/fail reporting with troubleshooting guidance Validates cursor rules and team documentation files	+226/-0

Documentation

aws-documentation-mcp.mdc `AWS documentation usage guidelines` .cursor/rules/aws-documentation-mcp.mdc Cursor rules for AWS development best practices Guidelines for using AWS MCP in Ocean integrations Examples for S3, Lambda, VPC, and other AWS services Integration patterns with existing development workflow	+166/-0
AWS_DOCS_MCP_SETUP.md `Team setup and usage documentation` AWS_DOCS_MCP_SETUP.md Comprehensive team documentation for AWS MCP setup Quick start guide with usage examples and troubleshooting Advanced usage patterns for contextual AWS queries Integration with existing Ocean development workflow	+167/-0

Need help?
Type /help how to ... in the comments thread for any questions about Qodo Merge usage.
Check out the documentation for more information.

@aws-docs

Add one-command setup for AWS Documentation MCP server integration: - Auto-installs and configures MCP server for Cursor - Preserves existing MCP configurations (GitHub, graphiti-memory) - Includes team documentation and verification scripts - Adds Cursor rules for AWS development best practices Enables @aws-docs queries in Cursor for real-time AWS documentation access with automatic source citation and Ocean integration patterns.

qodo-code-review · 2025-07-14T10:45:46Z

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪
🧪 No relevant tests
🔒 Security concerns Remote code execution: The setup script downloads and executes installation scripts from external URLs (astral.sh) without verification, checksum validation, or signature checking. This creates a supply chain attack vector where compromised remote servers could serve malicious code. Additionally, the embedded Python code processes JSON configuration files without proper input validation, potentially allowing malicious JSON to cause unexpected behavior.
⚡ Recommended focus areas for review Security Risk The script downloads and executes code from external URLs without verification. The curl commands on lines 55 and 58 fetch installation scripts from astral.sh and execute them directly, which poses security risks if the remote server is compromised or serves malicious content. curl -LsSf https://astral.sh/uv/install.sh \| sh ;; "windows") powershell -c "irm https://astral.sh/uv/install.ps1 \| iex" Error Handling The Python code embedded in the shell script lacks proper error handling for JSON parsing and file operations. If the existing MCP config file is malformed JSON, the script will fail without graceful recovery or helpful error messages. python3 << 'EOF' import json import sys config_path = sys.argv[1] if len(sys.argv) > 1 else "" try: # Read existing config with open(config_path, 'r') as f: config = json.load(f) # Ensure mcpServers exists if 'mcpServers' not in config: config['mcpServers'] = {} # Add/Update AWS documentation server # Check if tool is installed to determine command format import subprocess try: result = subprocess.run(['uv', 'tool', 'list'], capture_output=True, text=True, check=True) if 'awslabs.aws-documentation-mcp-server' in result.stdout: command = "awslabs.aws-documentation-mcp-server" args = [] print("✅ Using installed version of AWS MCP server") else: command = "uvx" args = ["awslabs.aws-documentation-mcp-server@latest"] print("✅ Using uvx (temporary) version of AWS MCP server") except: command = "uvx" args = ["awslabs.aws-documentation-mcp-server@latest"] print("✅ Using uvx (temporary) version of AWS MCP server") config['mcpServers']['awslabs.aws-documentation-mcp-server'] = { "command": command, "args": args, "env": { "FASTMCP_LOG_LEVEL": "ERROR", "AWS_DOCUMENTATION_PARTITION": "aws" }, "disabled": False, "autoApprove": [ "read_documentation", "search_documentation", "recommend", "get_available_services" ] } # Write updated config with open(config_path, 'w') as f: json.dump(config, f, indent=2) print("✅ Configuration updated successfully") except Exception as e: print(f"❌ Error updating configuration: {e}") sys.exit(1) EOF "$MCP_CONFIG_PATH" Command Injection The timeout commands use unvalidated input that could potentially lead to command injection. The uvx command execution should be properly quoted and sanitized to prevent security issues. if timeout 10s uvx awslabs.aws-documentation-mcp-server@latest --help >/dev/null 2>&1; then print_success "MCP server responds to help command" return 0 elif timeout 10s uvx awslabs.aws-documentation-mcp-server@latest --version >/dev/null 2>&1; then print_success "MCP server responds to version command" return 0 else print_warning "MCP server basic test failed (this may be expected for MCP servers)" print_status "The server should work fine when called by Cursor via MCP protocol" return 0 # Don't fail the test for this fi

qodo-code-review · 2025-07-14T10:46:35Z

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	✅ ~~Use absolute path resolution~~ Suggestion Impact: The commit implemented the exact suggestion by adding absolute path resolution using SCRIPT_DIR and PROJECT_ROOT variables, replacing the hardcoded relative path with CURSOR_RULE_PATH, and improving the error message to show the full path code diff: + + SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" + CURSOR_RULE_PATH="$PROJECT_ROOT/.cursor/rules/aws-documentation-mcp.mdc" + + if [ -f "$CURSOR_RULE_PATH" ]; then print_success "AWS Documentation MCP cursor rule exists" return 0 else - print_error "AWS Documentation MCP cursor rule not found" + print_error "AWS Documentation MCP cursor rule not found at: $CURSOR_RULE_PATH" The test function uses a hardcoded relative path which may fail if the script is run from different directories. Use absolute path resolution to ensure the test works regardless of execution location. scripts/test-aws-docs-mcp.sh [131-142] # Test if cursor rules exist test_cursor_rules() { print_status "Checking Cursor rules..." + + SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" + CURSOR_RULE_PATH="$PROJECT_ROOT/.cursor/rules/aws-documentation-mcp.mdc" - if [ -f ".cursor/rules/aws-documentation-mcp.mdc" ]; then + if [ -f "$CURSOR_RULE_PATH" ]; then print_success "AWS Documentation MCP cursor rule exists" return 0 else - print_error "AWS Documentation MCP cursor rule not found" + print_error "AWS Documentation MCP cursor rule not found at: $CURSOR_RULE_PATH" return 1 fi } `[Suggestion processed]` Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that using a relative path can cause issues and improves the test script's reliability by using an absolute path, ensuring it works regardless of the execution directory.	Medium
General	✅ ~~Add fallback PATH configuration~~ Suggestion Impact: The suggestion was directly implemented - the exact code from the suggestion was added to the script, including the comment and the export PATH statement with the same directories code diff: + + # Add common uv installation paths to PATH + export PATH="$HOME/.cargo/bin:$HOME/.local/bin:$PATH" The script sources the Cargo environment but doesn't handle the case where `uv` might be installed in other locations. Add fallback checks for common installation paths and update PATH explicitly to ensure `uv` is available. scripts/setup-aws-docs-mcp.sh [67-70] # Source the shell profile to get uv in PATH if [ -f "$HOME/.cargo/env" ]; then source "$HOME/.cargo/env" fi +# Add common uv installation paths to PATH +export PATH="$HOME/.cargo/bin:$HOME/.local/bin:$PATH" + `[Suggestion processed]` Suggestion importance[1-10]: 6 __ Why: The suggestion improves the script's robustness by explicitly adding common installation directories for `uv` to the `PATH`, making it less dependent on shell profile sourcing.	Low
Update

aws-amplify-eu-west-1 · 2025-07-14T10:47:35Z

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-1888.d1ftd8v2gowp8w.amplifyapp.com

github-actions · 2025-07-14T11:00:22Z

Code Coverage Artifact 📈: https://github.com/port-labs/ocean/actions/runs/16264756383/artifacts/3525781595

Code Coverage Total Percentage: `83.49%`

scripts/setup-aws-docs-mcp.sh

Co-authored-by: qodo-merge-pro[bot] <151058649+qodo-merge-pro[bot]@users.noreply.github.com>

cursor

Bug: Python Script Argument Passing Error

The embedded Python script within the configure_cursor_mcp function fails to receive the MCP_CONFIG_PATH argument. The here-document syntax used (python3 << 'EOF' ... EOF "$MCP_CONFIG_PATH") incorrectly attempts to pass the path, resulting in sys.argv[1] being empty. Consequently, the script defaults config_path to an empty string, leading to a FileNotFoundError when it attempts to open the configuration file.

scripts/setup-aws-docs-mcp.sh#L165-L224

ocean/scripts/setup-aws-docs-mcp.sh

Lines 165 to 224 in 85e796f

    
                   # Use Python to merge configurations properly 
        
                   python3 << 'EOF' 
        
           import json 
        
           import sys 
        
           config_path = sys.argv[1] if len(sys.argv) > 1 else "" 
        
           try: 
        
               # Read existing config 
        
               with open(config_path, 'r') as f: 
        
                   config = json.load(f) 
        
               # Ensure mcpServers exists 
        
               if 'mcpServers' not in config: 
        
                   config['mcpServers'] = {} 
        
               # Add/Update AWS documentation server 
        
               # Check if tool is installed to determine command format 
        
               import subprocess 
        
               try: 
        
                   result = subprocess.run(['uv', 'tool', 'list'], capture_output=True, text=True, check=True) 
        
                   if 'awslabs.aws-documentation-mcp-server' in result.stdout: 
        
                       command = "awslabs.aws-documentation-mcp-server" 
        
                       args = [] 
        
                       print("✅ Using installed version of AWS MCP server") 
        
                   else: 
        
                       command = "uvx" 
        
                       args = ["awslabs.aws-documentation-mcp-server@latest"] 
        
                       print("✅ Using uvx (temporary) version of AWS MCP server") 
        
               except: 
        
                   command = "uvx" 
        
                   args = ["awslabs.aws-documentation-mcp-server@latest"] 
        
                   print("✅ Using uvx (temporary) version of AWS MCP server") 
        
               config['mcpServers']['awslabs.aws-documentation-mcp-server'] = { 
        
                   "command": command, 
        
                   "args": args, 
        
                   "env": { 
        
                       "FASTMCP_LOG_LEVEL": "ERROR", 
        
                       "AWS_DOCUMENTATION_PARTITION": "aws" 
        
                   }, 
        
                   "disabled": False, 
        
                   "autoApprove": [ 
        
                       "read_documentation", 
        
                       "search_documentation", 
        
                       "recommend", 
        
                       "get_available_services" 
        
                   ] 
        
               } 
        
               # Write updated config 
        
               with open(config_path, 'w') as f: 
        
                   json.dump(config, f, indent=2) 
        
               print("✅ Configuration updated successfully") 
        
           except Exception as e: 
        
               print(f"❌ Error updating configuration: {e}") 
        
               sys.exit(1) 
        
           EOF "$MCP_CONFIG_PATH"

Fix in Cursor • Fix in Web

Was this report helpful? Give feedback by reacting with 👍 or 👎

github-actions · 2025-07-14T13:11:58Z

Code Coverage Artifact 📈: https://github.com/port-labs/ocean/actions/runs/16267473733/artifacts/3526693863

Code Coverage Total Percentage: `83.49%`

scripts/test-aws-docs-mcp.sh

Co-authored-by: qodo-merge-pro[bot] <151058649+qodo-merge-pro[bot]@users.noreply.github.com>

github-actions · 2025-07-17T05:46:43Z

Code Coverage Artifact 📈: https://github.com/port-labs/ocean/actions/runs/16337006474/artifacts/3551679525

Code Coverage Total Percentage: `83.41%`

github-actions · 2025-07-21T11:22:07Z

Code Coverage Artifact 📈: https://github.com/port-labs/ocean/actions/runs/16415332892/artifacts/3576812632

Code Coverage Total Percentage: `83.41%`

github-actions · 2025-10-15T10:19:39Z

Code Coverage Artifact 📈: https://github.com/port-labs/ocean/actions/runs/18525207852/artifacts/4275352120

Code Coverage Total Percentage: `87.79%`

vheckthor requested review from a team and Tankilevitch July 14, 2025 10:45

github-actions bot added the size/XL label Jul 14, 2025

qodo-code-review bot added Review effort 4/5 Possible security concern labels Jul 14, 2025

This comment was marked as outdated.

Sign in to view

qodo-code-review bot reviewed Jul 14, 2025

View reviewed changes

scripts/setup-aws-docs-mcp.sh Show resolved Hide resolved

Update scripts/setup-aws-docs-mcp.sh

85e796f

Co-authored-by: qodo-merge-pro[bot] <151058649+qodo-merge-pro[bot]@users.noreply.github.com>

cursor bot reviewed Jul 14, 2025

View reviewed changes

qodo-code-review bot reviewed Jul 17, 2025

View reviewed changes

scripts/test-aws-docs-mcp.sh Show resolved Hide resolved

Update scripts/test-aws-docs-mcp.sh

a3f445a

Co-authored-by: qodo-merge-pro[bot] <151058649+qodo-merge-pro[bot]@users.noreply.github.com>

Merge branch 'main' into add-mcp-for-integration-development

a8e6e92

Merge branch 'main' into add-mcp-for-integration-development

0ca8d36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Docs] AWS Documentation MCP with automated team setup #1888

[Docs] AWS Documentation MCP with automated team setup #1888

Uh oh!

vheckthor commented Jul 14, 2025 •

edited

Loading

Uh oh!

qodo-code-review bot commented Jul 14, 2025

Uh oh!

qodo-code-review bot commented Jul 14, 2025 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

aws-amplify-eu-west-1 bot commented Jul 14, 2025

Uh oh!

github-actions bot commented Jul 14, 2025

Uh oh!

Uh oh!

cursor bot left a comment

Uh oh!

github-actions bot commented Jul 14, 2025

Uh oh!

Uh oh!

github-actions bot commented Jul 17, 2025

Uh oh!

github-actions bot commented Jul 21, 2025

Uh oh!

github-actions bot commented Oct 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	# Use Python to merge configurations properly
	python3 << 'EOF'
	import json
	import sys

	config_path = sys.argv[1] if len(sys.argv) > 1 else ""

	try:
	# Read existing config
	with open(config_path, 'r') as f:
	config = json.load(f)

	# Ensure mcpServers exists
	if 'mcpServers' not in config:
	config['mcpServers'] = {}

	# Add/Update AWS documentation server
	# Check if tool is installed to determine command format
	import subprocess
	try:
	result = subprocess.run(['uv', 'tool', 'list'], capture_output=True, text=True, check=True)
	if 'awslabs.aws-documentation-mcp-server' in result.stdout:
	command = "awslabs.aws-documentation-mcp-server"
	args = []
	print("✅ Using installed version of AWS MCP server")
	else:
	command = "uvx"
	args = ["awslabs.aws-documentation-mcp-server@latest"]
	print("✅ Using uvx (temporary) version of AWS MCP server")
	except:
	command = "uvx"
	args = ["awslabs.aws-documentation-mcp-server@latest"]
	print("✅ Using uvx (temporary) version of AWS MCP server")

	config['mcpServers']['awslabs.aws-documentation-mcp-server'] = {
	"command": command,
	"args": args,
	"env": {
	"FASTMCP_LOG_LEVEL": "ERROR",
	"AWS_DOCUMENTATION_PARTITION": "aws"
	},
	"disabled": False,
	"autoApprove": [
	"read_documentation",
	"search_documentation",
	"recommend",
	"get_available_services"
	]
	}

	# Write updated config
	with open(config_path, 'w') as f:
	json.dump(config, f, indent=2)

	print("✅ Configuration updated successfully")

	except Exception as e:
	print(f"❌ Error updating configuration: {e}")
	sys.exit(1)
	EOF "$MCP_CONFIG_PATH"

[Docs] AWS Documentation MCP with automated team setup #1888

Are you sure you want to change the base?

[Docs] AWS Documentation MCP with automated team setup #1888

Uh oh!

Conversation

vheckthor commented Jul 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User description

Description

In Cursor chat:

Type of change

All tests should be run against the port production environment(using a testing org).

Core testing checklist

Integration testing checklist

Preflight checklist

Screenshots

API Documentation

PR Type

Description

Changes diagram

Changes walkthrough 📝

Uh oh!

qodo-code-review bot commented Jul 14, 2025

PR Reviewer Guide 🔍

Uh oh!

qodo-code-review bot commented Jul 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Code Suggestions ✨

Uh oh!

This comment was marked as outdated.

Uh oh!

aws-amplify-eu-west-1 bot commented Jul 14, 2025

Uh oh!

github-actions bot commented Jul 14, 2025

Code Coverage Artifact 📈: https://github.com/port-labs/ocean/actions/runs/16264756383/artifacts/3525781595

Code Coverage Total Percentage: 83.49%

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Bug: Python Script Argument Passing Error

Uh oh!

github-actions bot commented Jul 14, 2025

Code Coverage Artifact 📈: https://github.com/port-labs/ocean/actions/runs/16267473733/artifacts/3526693863

Code Coverage Total Percentage: 83.49%

Uh oh!

Uh oh!

github-actions bot commented Jul 17, 2025

Code Coverage Artifact 📈: https://github.com/port-labs/ocean/actions/runs/16337006474/artifacts/3551679525

Code Coverage Total Percentage: 83.41%

Uh oh!

github-actions bot commented Jul 21, 2025

Code Coverage Artifact 📈: https://github.com/port-labs/ocean/actions/runs/16415332892/artifacts/3576812632

Code Coverage Total Percentage: 83.41%

Uh oh!

github-actions bot commented Oct 15, 2025

Code Coverage Artifact 📈: https://github.com/port-labs/ocean/actions/runs/18525207852/artifacts/4275352120

Code Coverage Total Percentage: 87.79%

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vheckthor commented Jul 14, 2025 •

edited

Loading

qodo-code-review bot commented Jul 14, 2025 •

edited

Loading

Code Coverage Total Percentage: `83.49%`

Code Coverage Total Percentage: `83.49%`

Code Coverage Total Percentage: `83.41%`

Code Coverage Total Percentage: `83.41%`

Code Coverage Total Percentage: `87.79%`