MCP Server Builder

Instructions

Implementation Reference

• src/mcp_server_builder/tools/docs.py:32-108 (handler)

  The handler function that implements the search_mcp_docs tool logic. It searches an index for the query, filters by source if specified, hydrates snippets from cache, and returns a list of relevant document results with scores.

  def search_mcp_docs(
      query: str, k: int = 5, source: SourceFilter = None
  ) -> list[dict[str, Any]]:
      """Search MCP protocol AND FastMCP framework documentation with ranked results.
  
      This tool searches across both documentation sources simultaneously:
  
      **MCP Protocol (modelcontextprotocol.io):**
      - Official protocol specification and architecture
      - Transports (stdio, streamable HTTP)
      - Tools, Resources, and Prompts primitives
      - Lifecycle, capabilities negotiation, and security
  
      **FastMCP Framework (gofastmcp.com):**
      - Python framework for building MCP servers
      - Decorators, type hints, and Pydantic integration
      - Authentication, deployment, and production patterns
      - Client SDK and cloud deployment
  
      Use this to find documentation for building MCP servers with either approach.
  
      Args:
          query: Search query string (e.g., "tool input schema", "stdio transport")
          k: Maximum number of results to return (default: 5)
          source: Optional filter - "mcp" for protocol docs only, "fastmcp" for
                  framework docs only. If None, searches both sources.
  
      Returns:
          List of dictionaries containing:
          - url: Document URL
          - title: Display title
          - score: Relevance score (higher is better)
          - snippet: Contextual content preview
          - source: Documentation source ("mcp" or "fastmcp")
      """
      cache.ensure_ready()
      index = cache.get_index()
  
      if index is None:
          return []
  
      # Request more results if filtering, to ensure we get k results after filtering
      search_k = k * 3 if source else k
      results = index.search(query, k=search_k)
  
      # Apply source filter if specified
      if source:
          results = [(score, doc) for score, doc in results if _matches_source_filter(doc.uri, source)]
  
      # Limit to requested k after filtering
      results = results[:k]
  
      url_cache = cache.get_url_cache()
  
      # Hydrate top results with content for snippets
      top = results[: min(len(results), cache.SNIPPET_HYDRATE_MAX)]
      for _, doc in top:
          cached = url_cache.get(doc.uri)
          if cached is None or not cached.content:
              cache.ensure_page(doc.uri)
  
      # Build response with snippets and source
      return_docs: list[dict[str, Any]] = []
      for score, doc in results:
          page = url_cache.get(doc.uri)
          snippet = text_processor.make_snippet(page, doc.display_title)
          return_docs.append(
              {
                  "url": doc.uri,
                  "title": doc.display_title,
                  "score": round(score, 3),
                  "snippet": snippet,
                  "source": _get_source_from_url(doc.uri),
              }
          )
  
      return return_docs

• src/mcp_server_builder/server.py:15-15 (registration)

  Registration of the search_mcp_docs tool on the FastMCP server instance using the mcp.tool() decorator.

  mcp.tool()(docs.search_mcp_docs)

• src/mcp_server_builder/tools/docs.py:8-8 (schema)

  Type definition for the 'source' parameter in search_mcp_docs, providing input schema validation via Literal union with None.

  SourceFilter = Literal["mcp", "fastmcp"] | None

• src/mcp_server_builder/tools/docs.py:17-22 (helper)

  Helper function to determine the documentation source (mcp or fastmcp) from a URL domain, used in filtering and result labeling.

  def _get_source_from_url(url: str) -> str:
      """Extract source identifier from URL domain."""
      for domain, source in _DOMAIN_SOURCE_MAP.items():
          if domain in url:
              return source
      return "unknown"

• src/mcp_server_builder/tools/docs.py:25-29 (helper)

  Helper function to check if a document URL matches the specified source filter.

  def _matches_source_filter(url: str, source_filter: SourceFilter) -> bool:
      """Check if URL matches the source filter."""
      if source_filter is None:
          return True
      return _get_source_from_url(url) == source_filter