AWS Documentation MCP Server

Instructions

Implementation Reference

• awslabs/aws_documentation_mcp_server/server_aws.py:146-269 (handler)

  The handler function decorated with @mcp.tool() that implements the core logic of searching AWS documentation via the official API, handling errors, parsing JSON response, extracting results, and returning a list of SearchResult objects. Includes input schema definitions via Pydantic Field.

  @mcp.tool()
  async def search_documentation(
      ctx: Context,
      search_phrase: str = Field(description='Search phrase to use'),
      limit: int = Field(
          default=10,
          description='Maximum number of results to return',
          ge=1,
          le=50,
      ),
  ) -> List[SearchResult]:
      """Search AWS documentation using the official AWS Documentation Search API.
  
      ## Usage
  
      This tool searches across all AWS documentation for pages matching your search phrase.
      Use it to find relevant documentation when you don't have a specific URL.
  
      ## Search Tips
  
      - Use specific technical terms rather than general phrases
      - Include service names to narrow results (e.g., "S3 bucket versioning" instead of just "versioning")
      - Use quotes for exact phrase matching (e.g., "AWS Lambda function URLs")
      - Include abbreviations and alternative terms to improve results
  
      ## Result Interpretation
  
      Each result includes:
      - rank_order: The relevance ranking (lower is more relevant)
      - url: The documentation page URL
      - title: The page title
      - context: A brief excerpt or summary (if available)
  
      Args:
          ctx: MCP context for logging and error handling
          search_phrase: Search phrase to use
          limit: Maximum number of results to return
  
      Returns:
          List of search results with URLs, titles, and context snippets
      """
      logger.debug(f'Searching AWS documentation for: {search_phrase}')
  
      request_body = {
          'textQuery': {
              'input': search_phrase,
          },
          'contextAttributes': [{'key': 'domain', 'value': 'docs.aws.amazon.com'}],
          'acceptSuggestionBody': 'RawText',
          'locales': ['en_us'],
      }
  
      search_url_with_session = f'{SEARCH_API_URL}?session={SESSION_UUID}'
  
      async with httpx.AsyncClient() as client:
          try:
              response = await client.post(
                  search_url_with_session,
                  json=request_body,
                  headers={
                      'Content-Type': 'application/json',
                      'User-Agent': DEFAULT_USER_AGENT,
                      'X-MCP-Session-Id': SESSION_UUID,
                  },
                  timeout=30,
              )
          except httpx.HTTPError as e:
              error_msg = f'Error searching AWS docs: {str(e)}'
              logger.error(error_msg)
              await ctx.error(error_msg)
              return [SearchResult(rank_order=1, url='', title=error_msg, context=None)]
  
          if response.status_code >= 400:
              error_msg = f'Error searching AWS docs - status code {response.status_code}'
              logger.error(error_msg)
              await ctx.error(error_msg)
              return [
                  SearchResult(
                      rank_order=1,
                      url='',
                      title=error_msg,
                      context=None,
                  )
              ]
  
          try:
              data = response.json()
          except json.JSONDecodeError as e:
              error_msg = f'Error parsing search results: {str(e)}'
              logger.error(error_msg)
              await ctx.error(error_msg)
              return [
                  SearchResult(
                      rank_order=1,
                      url='',
                      title=error_msg,
                      context=None,
                  )
              ]
  
      results = []
      if 'suggestions' in data:
          for i, suggestion in enumerate(data['suggestions'][:limit]):
              if 'textExcerptSuggestion' in suggestion:
                  text_suggestion = suggestion['textExcerptSuggestion']
                  context = None
  
                  # Add context if available
                  if 'summary' in text_suggestion:
                      context = text_suggestion['summary']
                  elif 'suggestionBody' in text_suggestion:
                      context = text_suggestion['suggestionBody']
  
                  results.append(
                      SearchResult(
                          rank_order=i + 1,
                          url=text_suggestion.get('link', ''),
                          title=text_suggestion.get('title', ''),
                          context=context,
                      )
                  )
  
      logger.debug(f'Found {len(results)} search results for: {search_phrase}')
      return results

• awslabs/aws_documentation_mcp_server/models.py:20-27 (schema)

  Pydantic BaseModel defining the structure of each search result returned by the tool, used for output validation and typing.

  class SearchResult(BaseModel):
      """Search result from AWS documentation search."""
  
      rank_order: int
      url: str
      title: str
      context: Optional[str] = None

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

  The @mcp.tool() decorator registers the search_documentation function as an MCP tool.

  @mcp.tool()