search_symbols

Instructions

Implementation Reference

• bgi/bgi/mcp/context.py:1045-1106 (handler)

  Core handler method 'search_symbols' on ArchitectureContextService. Uses index DB (QueryPlanner.lookup_symbol + search_prefix) if available, otherwise falls back to a graph-based substring scan of unit IDs. Results are cached via _cached().

  def search_symbols(self, query: str, limit: int = 10, context_unit_id: str | None = None) -> dict[str, Any]:
      """Search symbols using index DB if available, otherwise graph fallback."""
      max_limit = max(1, limit)
      key = ("search_symbols", query, max_limit, context_unit_id or "")
  
      def _build() -> dict[str, Any]:
          planner = self._get_planner()
          if planner is not None:
              results = []
              seen = set()
              for r in planner.lookup_symbol(query, context_unit_id=context_unit_id, max_results=max_limit):
                  if r.unit_id in seen:
                      continue
                  seen.add(r.unit_id)
                  results.append(
                      {
                          "unit_id": r.unit_id,
                          "name": r.name,
                          "file_path": r.file_path,
                          "score": round(r.score, 4),
                          "reasoning": r.reasoning,
                          "is_exported": bool(r.is_exported),
                      }
                  )
              if len(results) < max_limit:
                  for r in planner.search_prefix(query, context_unit_id=context_unit_id, max_results=max_limit):
                      if r.unit_id in seen:
                          continue
                      seen.add(r.unit_id)
                      results.append(
                          {
                              "unit_id": r.unit_id,
                              "name": r.name,
                              "file_path": r.file_path,
                              "score": round(r.score, 4),
                              "reasoning": r.reasoning,
                              "is_exported": bool(r.is_exported),
                          }
                      )
                      if len(results) >= max_limit:
                          break
              return {"query": query, "source": "index_db", "count": len(results), "results": results}
  
          qlow = query.lower()
          matches = []
          for uid in self.unit_by_id:
              symbol_name = uid.split("::")[-1]
              if qlow in symbol_name.lower() or qlow in uid.lower():
                  matches.append(
                      {
                          "unit_id": uid,
                          "name": symbol_name,
                          "file_path": uid.split("::", 1)[0],
                          "score": 0.5,
                          "reasoning": "fallback graph symbol scan",
                          "is_exported": False,
                      }
                  )
          matches.sort(key=lambda x: x["name"])
          return {"query": query, "source": "graph_fallback", "count": len(matches[:max_limit]), "results": matches[:max_limit]}
  
      return self._cached(key, _build)

• bgi/bgi/mcp/server.py:107-126 (registration)

  MCP tool registration of 'search_symbols' via @mcp.tool() decorator. Defines the public API surface (query, limit, context_unit_id) and delegates to service.search_symbols().

  @mcp.tool()
  def search_symbols(query: str, limit: int = 8, context_unit_id: str = ""):
      """Search for symbols (functions, classes, methods) by name or description.
  
      Use this to locate a specific function or class before navigating to it or
      understanding its context. Requires an index DB for ranked semantic results;
      falls back to graph name-matching when no DB is present. Prefer this over
      grep when you want architecture-aware ranking. Do NOT use for cluster lookup —
      use cluster_of_file instead.
  
      Args:
          query: Symbol name fragment or natural-language description (e.g. "parse headers").
          limit: Maximum number of results to return (default 8).
          context_unit_id: Optional unit ID to bias results toward a specific module scope.
  
      Returns:
          A ranked list of symbol dicts with name, file, cluster, and relevance score.
      """
      ctx = context_unit_id or None
      return service.search_symbols(query=query, limit=limit, context_unit_id=ctx)

• bgi/bgi/mcp/context.py:1036-1043 (helper)

  Helper _get_planner() lazy-loads QueryPlanner from index DB path. Used by search_symbols to perform semantic lookups.

  def _get_planner(self):
      if self.index_db_path is None or not self.index_db_path.exists():
          return None
      if self._planner is None:
          from bgi.indexer.planner import QueryPlanner
  
          self._planner = QueryPlanner(str(self.index_db_path))
      return self._planner

• bgi/bgi/mcp/server.py:117-124 (schema)

  Type annotations and docstring defining the input schema for search_symbols: query (str), limit (int, default 8), context_unit_id (str, default ''). Returns a ranked list of symbol dicts.

  Args:
      query: Symbol name fragment or natural-language description (e.g. "parse headers").
      limit: Maximum number of results to return (default 8).
      context_unit_id: Optional unit ID to bias results toward a specific module scope.
  
  Returns:
      A ranked list of symbol dicts with name, file, cluster, and relevance score.
  """