AWS Documentation MCP Server

Instructions

Implementation Reference

• awslabs/aws_documentation_mcp_server/server_aws.py:272-363 (handler)

  Main execution logic for the 'recommend' tool: makes HTTP GET to AWS recommendations API with the input URL, parses JSON response using helper, handles errors, returns list of RecommendationResult.
  @mcp.tool() async def recommend( ctx: Context, url: str = Field(description='URL of the AWS documentation page to get recommendations for'), ) -> List[RecommendationResult]: """Get content recommendations for an AWS documentation page. ## Usage This tool provides recommendations for related AWS documentation pages based on a given URL. Use it to discover additional relevant content that might not appear in search results. ## Recommendation Types The recommendations include four categories: 1. **Highly Rated**: Popular pages within the same AWS service 2. **New**: Recently added pages within the same AWS service - useful for finding newly released features 3. **Similar**: Pages covering similar topics to the current page 4. **Journey**: Pages commonly viewed next by other users ## When to Use - After reading a documentation page to find related content - When exploring a new AWS service to discover important pages - To find alternative explanations of complex concepts - To discover the most popular pages for a service - To find newly released information by using a service's welcome page URL and checking the **New** recommendations ## Finding New Features To find newly released information about a service: 1. Find any page belong to that service, typically you can try the welcome page 2. Call this tool with that URL 3. Look specifically at the **New** recommendation type in the results ## Result Interpretation Each recommendation includes: - url: The documentation page URL - title: The page title - context: A brief description (if available) Args: ctx: MCP context for logging and error handling url: URL of the AWS documentation page to get recommendations for Returns: List of recommended pages with URLs, titles, and context """ url_str = str(url) logger.debug(f'Getting recommendations for: {url_str}') recommendation_url = f'{RECOMMENDATIONS_API_URL}?path={url_str}&session={SESSION_UUID}' async with httpx.AsyncClient() as client: try: response = await client.get( recommendation_url, headers={'User-Agent': DEFAULT_USER_AGENT}, timeout=30, ) except httpx.HTTPError as e: error_msg = f'Error getting recommendations: {str(e)}' logger.error(error_msg) await ctx.error(error_msg) return [RecommendationResult(url='', title=error_msg, context=None)] if response.status_code >= 400: error_msg = f'Error getting recommendations - status code {response.status_code}' logger.error(error_msg) await ctx.error(error_msg) return [ RecommendationResult( url='', title=error_msg, context=None, ) ] try: data = response.json() except json.JSONDecodeError as e: error_msg = f'Error parsing recommendations: {str(e)}' logger.error(error_msg) await ctx.error(error_msg) return [RecommendationResult(url='', title=error_msg, context=None)] results = parse_recommendation_results(data) logger.debug(f'Found {len(results)} recommendations for: {url_str}') return results
• awslabs/aws_documentation_mcp_server/models.py:29-35 (schema)

  Pydantic model defining the output schema for each recommendation: url, title, optional context.
  class RecommendationResult(BaseModel): """Recommendation result from AWS documentation.""" url: str title: str context: Optional[str] = None
• awslabs/aws_documentation_mcp_server/server_aws.py:272-272 (registration)

  MCP tool registration decorator applied to the recommend handler function.
  @mcp.tool()
• awslabs/aws_documentation_mcp_server/util.py:194-257 (helper)

  Helper function that parses the raw JSON from AWS recommendations API into a list of RecommendationResult models, categorizing by highlyRated, journey, new, similar.
  def parse_recommendation_results(data: Dict[str, Any]) -> List[RecommendationResult]: """Parse recommendation API response into RecommendationResult objects. Args: data: Raw API response data Returns: List of recommendation results """ results = [] # Process highly rated recommendations if 'highlyRated' in data and 'items' in data['highlyRated']: for item in data['highlyRated']['items']: context = item.get('abstract') if 'abstract' in item else None results.append( RecommendationResult( url=item.get('url', ''), title=item.get('assetTitle', ''), context=context ) ) # Process journey recommendations (organized by intent) if 'journey' in data and 'items' in data['journey']: for intent_group in data['journey']['items']: intent = intent_group.get('intent', '') if 'urls' in intent_group: for url_item in intent_group['urls']: # Add intent as part of the context context = f'Intent: {intent}' if intent else None results.append( RecommendationResult( url=url_item.get('url', ''), title=url_item.get('assetTitle', ''), context=context, ) ) # Process new content recommendations if 'new' in data and 'items' in data['new']: for item in data['new']['items']: # Add "New content" label to context date_created = item.get('dateCreated', '') context = f'New content added on {date_created}' if date_created else 'New content' results.append( RecommendationResult( url=item.get('url', ''), title=item.get('assetTitle', ''), context=context ) ) # Process similar recommendations if 'similar' in data and 'items' in data['similar']: for item in data['similar']['items']: context = item.get('abstract') if 'abstract' in item else 'Similar content' results.append( RecommendationResult( url=item.get('url', ''), title=item.get('assetTitle', ''), context=context ) ) return results