search_documentation

Instructions

Implementation Reference

• magento_graphql_docs_mcp/server.py:46-63 (handler)

  The `search_documentation` function that executes the tool logic. It accepts a list of keyword queries, optional category/subcategory/content_type filters, performs FTS search on the SQLite database, applies filters, and returns formatted results.

  def search_documentation(
      queries: Annotated[
          List[str],
          Field(description="List of 1-3 short keyword queries. Examples: ['product', 'cart'], ['checkout']")
      ],
      category: Annotated[
          Optional[str],
          Field(description="Filter by category: schema, develop, usage, tutorials, payment-methods")
      ] = None,
      subcategory: Annotated[
          Optional[str],
          Field(description="Filter by subcategory: products, cart, customer, checkout, etc.")
      ] = None,
      content_type: Annotated[
          Optional[str],
          Field(description="Filter by content type: guide, reference, tutorial, schema")
      ] = None
  ) -> str:

• magento_graphql_docs_mcp/server.py:46-63 (schema)

  The function's Pydantic-style annotated parameters define the input schema: 'queries' (List[str]), 'category' (Optional[str]), 'subcategory' (Optional[str]), 'content_type' (Optional[str]) with Field descriptions.

  def search_documentation(
      queries: Annotated[
          List[str],
          Field(description="List of 1-3 short keyword queries. Examples: ['product', 'cart'], ['checkout']")
      ],
      category: Annotated[
          Optional[str],
          Field(description="Filter by category: schema, develop, usage, tutorials, payment-methods")
      ] = None,
      subcategory: Annotated[
          Optional[str],
          Field(description="Filter by subcategory: products, cart, customer, checkout, etc.")
      ] = None,
      content_type: Annotated[
          Optional[str],
          Field(description="Filter by content type: guide, reference, tutorial, schema")
      ] = None
  ) -> str:

• magento_graphql_docs_mcp/server.py:40-45 (registration)

  The tool is registered via the @mcp.tool() decorator with name='search_documentation' and a description explaining usage for searching Magento 2 GraphQL documentation.

  @mcp.tool(
      name="search_documentation",
      description="""Search Magento 2 GraphQL documentation by keywords.
  Use SHORT keyword queries (1-3 words) to find documentation pages.
  Can filter by category, subcategory, or content type."""
  )

• magento_graphql_docs_mcp/config.py:83-87 (helper)

  Configuration constants used by the handler: DB_TOP_K (default 5) limits results, SEARCH_RESULT_MULTIPLIER (2) fetches extra results before filtering to allow for category/subcategory/content_type filters.

  # Configurable constants
  DB_TOP_K = int(os.environ.get("MAGENTO_GRAPHQL_DOCS_TOP_K", "5"))
  MAX_FIELDS_PER_ELEMENT = int(os.environ.get("MAGENTO_GRAPHQL_DOCS_MAX_FIELDS", "20"))
  MAX_CODE_PREVIEW_LENGTH = int(os.environ.get("MAGENTO_GRAPHQL_DOCS_CODE_PREVIEW", "400"))
  SEARCH_RESULT_MULTIPLIER = 2  # Fetch 2x results before filtering

• magento_graphql_docs_mcp/config.py:5-21 (helper)

  The get_db_path() helper that provides the DB_PATH used by the handler to open the SQLite database for FTS search.

  def get_db_path() -> str:
      """
      Determines the database path.
      Prioritizes MAGENTO_GRAPHQL_DOCS_DB_PATH environment variable.
      Defaults to ~/.mcp/magento-graphql-docs/database.db.
      Ensures the parent directory exists.
      """
      env_path = os.environ.get("MAGENTO_GRAPHQL_DOCS_DB_PATH")
      if env_path:
          db_path = Path(env_path)
      else:
          db_path = Path.home() / ".mcp" / "magento-graphql-docs" / "database.db"
  
      # Ensure directory exists
      db_path.parent.mkdir(parents=True, exist_ok=True)
  
      return str(db_path)