search_graphql_elements

Instructions

Implementation Reference

• magento_graphql_docs_mcp/server.py:150-153 (registration)

  Tool registration using FastMCP decorator. Registers 'search_graphql_elements' as an MCP tool with metadata description.

  @mcp.tool(
      name="search_graphql_elements",
      description="Search for GraphQL queries, mutations, types, or interfaces"
  )

• magento_graphql_docs_mcp/server.py:154-197 (handler)

  Handler function that performs FTS search on the graphql_elements table, optionally filters by element_type, fetches the source document title/path, and formats results with element details.

  def search_graphql_elements(
      query: Annotated[str, Field(description="Search term, e.g., 'products', 'cart', 'customer'")],
      element_type: Annotated[
          Optional[str],
          Field(description="Filter by element type: query, mutation, type, interface, union")
      ] = None
  ) -> str:
      """Search GraphQL schema elements"""
      db = Database(DB_PATH)
  
      # FTS search
      results = list(db["graphql_elements"].search(query, limit=10))
  
      # Apply filter
      if element_type:
          results = [r for r in results if r['element_type'] == element_type]
  
      if not results:
          return f"No GraphQL elements found matching: {query}"
  
      # Format results
      formatted_results = []
      for elem in results:
          # Get source document
          try:
              doc = dict(db.query(
                  "SELECT title, file_path FROM documents WHERE id = ?",
                  [elem['document_id']]
              ).__next__())
              source = f"{doc['title']} ({doc['file_path']})"
          except StopIteration:
              source = "Unknown"
  
          fields = json.loads(elem.get('fields_json', '[]'))
          params = json.loads(elem.get('parameters_json', '[]'))
  
          formatted_results.append(
              f"### `{elem['element_type']}` **{elem['name']}**\n"
              f"**Source:** {source}\n"
              f"**Fields:** {', '.join(fields[:10]) if fields else 'None'}\n"
              f"**Parameters:** {', '.join(params) if params else 'None'}\n"
          )
  
      return "\n---\n\n".join(formatted_results)

• magento_graphql_docs_mcp/server.py:154-160 (schema)

  Input schema using Pydantic Field annotations: 'query' (required str) and optional 'element_type' (str filter for query/mutation/type/interface/union). Returns str.

  def search_graphql_elements(
      query: Annotated[str, Field(description="Search term, e.g., 'products', 'cart', 'customer'")],
      element_type: Annotated[
          Optional[str],
          Field(description="Filter by element type: query, mutation, type, interface, union")
      ] = None
  ) -> str:

• magento_graphql_docs_mcp/ingest.py:98-129 (helper)

  Database schema initialization for the graphql_elements table and its FTS5 full-text search index (trigram tokenizer), created during ingestion.

  if "graphql_elements" not in db.table_names():
      db["graphql_elements"].create({
          "id": int,
          "document_id": str,
          "element_type": str,
          "name": str,
          "fields_json": str,
          "parameters_json": str,
          "return_type": str,
          "description": str,
          "searchable_text": str,
      }, pk="id")
      db["graphql_elements"].create_index(["document_id"])
      db["graphql_elements"].create_index(["element_type"])
      db["graphql_elements"].create_index(["name"])
  
  # Create FTS5 indexes
  if "documents_fts" not in db.table_names():
      db["documents"].enable_fts(
          ["searchable_text"],
          create_triggers=True,
          tokenize="trigram"
      )
      logger.info("Created FTS index for documents")
  
  if "graphql_elements_fts" not in db.table_names():
      db["graphql_elements"].enable_fts(
          ["searchable_text"],
          create_triggers=True,
          tokenize="trigram"
      )
      logger.info("Created FTS index for graphql_elements")

• magento_graphql_docs_mcp/ingest.py:184-201 (helper)

  Data ingestion logic that populates the graphql_elements table from parsed documentation data during the ingest process.

  # Insert GraphQL elements
  logger.info(f"Inserting {len(graphql_elements)} GraphQL elements...")
  element_records = []
  for element in graphql_elements:
      element_records.append({
          "document_id": element.document_id,
          "element_type": element.element_type,
          "name": element.name,
          "fields_json": json.dumps(element.fields),
          "parameters_json": json.dumps(element.parameters),
          "return_type": element.return_type,  # Allow NULL for missing return type
          "description": element.description,  # Allow NULL for missing description
          "searchable_text": element.searchable_text,
      })
  
  if element_records:
      db["graphql_elements"].insert_all(element_records)
      logger.info(f"Inserted {len(element_records)} GraphQL elements")