recommend

Instructions

Implementation Reference

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

  The core handler function for the 'recommend' tool. It makes an HTTP GET request to the AWS recommendations API, parses the response using parse_recommendation_results, and returns a list of RecommendationResult objects. Handles errors gracefully by returning error messages in the result format.

  @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 structure of each recommendation result, used as the return type for the recommend tool. Includes url, title, and optional context.

  class RecommendationResult(BaseModel):
      """Recommendation result from AWS documentation."""
  
      url: str
      title: str
      context: Optional[str] = None

• awslabs/aws_documentation_mcp_server/util.py:194-257 (helper)

  Helper function that parses the raw JSON response from the AWS recommendations API into a list of RecommendationResult model instances. Handles different sections: highlyRated, journey, new, and 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

• awslabs/aws_documentation_mcp_server/server_aws.py:45-46 (registration)

  FastMCP server instance creation where tools like 'recommend' are registered via decorators.

  mcp = FastMCP(
      'awslabs.aws-documentation-mcp-server',