feat: Add AWS documentation integration to security recommendations (PR #4)

[nzuresh]

Fixes

Summary

Changes

This PR adds AWS documentation integration to the ECS security analysis tool, enriching security recommendations with contextual AWS best practices documentation.

Key additions:

• Added include_aws_docs optional parameter to analyze_ecs_security tool
• Implemented parallel AWS documentation fetching with semaphore limiting (max 5 concurrent requests)
• Added aws_documentation field to security recommendation structure
• Implemented caching and graceful degradation for documentation retrieval
• Made SecurityAnalyzer.analyze method async to support parallel operations
• Enhanced MCP client presentation guidelines for proper resource detail display

Technical implementation:

• Uses existing aws_knowledge_proxy module for documentation fetching
• Implements 10-second timeout per documentation fetch
• Maintains full backward compatibility (defaults to include_aws_docs=false)
• Comprehensive error handling with fallback to empty documentation on failures

Files changed:

• awslabs/ecs_mcp_server/api/security_analysis.py: +175 lines
• awslabs/ecs_mcp_server/modules/security_analysis.py: +123 lines
• tests/unit/test_security_analysis.py: +800 lines (22 new test cases)

User experience

Before:
Users receive security recommendations with severity, description, and remediation steps, but no direct links to AWS documentation for additional context.

After:
When include_aws_docs=true is specified, users receive the same security recommendations enhanced with relevant AWS documentation snippets that provide:

• Direct links to AWS best practices guides
• Contextual information about the security concern
• Additional remediation guidance from official AWS sources

The feature gracefully degrades if documentation fetching fails, ensuring the core security analysis always completes successfully.

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• I have reviewed the contributing guidelines
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented

Is this a breaking change? (Y/N): N

RFC issue number: N/A

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[codecov]

Codecov Report

❌ Patch coverage is 82.35294% with 51 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.40%. Comparing base (c2d7bf8) to head (41ebd3f).

Files with missing lines	Patch %	Lines
...er/awslabs/ecs_mcp_server/api/security_analysis.py	83.27%	37 Missing and 8 partials ⚠️
...wslabs/ecs_mcp_server/modules/security_analysis.py	68.42%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1462      +/-   ##
==========================================
- Coverage   89.45%   89.40%   -0.05%     
==========================================
  Files         726      728       +2     
  Lines       50305    50594     +289     
  Branches     7942     7989      +47     
==========================================
+ Hits        44998    45236     +238     
- Misses       3452     3495      +43     
- Partials     1855     1863       +8     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.