sourcesage

Instructions

Implementation Reference

• sourcesage/mcp_server.py:214-266 (handler)

  MCP tool handler for 'query_entities'. This is the main execution function, decorated with @self.mcp.tool() which registers it as an MCP tool. It calls KnowledgeGraph.query_entities and formats the results as a string.

  @self.mcp.tool()
  def query_entities(
      entity_type: str | None = None,
      language: str | None = None,
      name_pattern: str | None = None,
      limit: int = 10,
  ) -> str:
      """Query entities in the knowledge graph.
  
      Args:
          entity_type: Filter by entity type (class, function, module, etc.)
          language: Filter by programming language
          name_pattern: Filter by name pattern (regex)
          limit: Maximum number of results to return
      """
      entities = self.knowledge.query_entities(
          entity_type=entity_type,
          language=language,
          name_pattern=name_pattern,
          limit=limit,
      )
  
      if not entities:
          return "No entities found matching the query criteria"
  
      # Format results
      output = f"Found {len(entities)} entities:\n\n"
  
      for entity in entities:
          output += f"Name: {entity.name}\n"
          output += f"Type: {entity.entity_type}\n"
  
          if entity.language:
              output += f"Language: {entity.language}\n"
  
          if entity.signature:
              output += f"Signature: {entity.signature}\n"
  
          output += f"Summary: {entity.summary}\n"
  
          if entity.observations:
              output += "Observations:\n"
              for observation in entity.observations[
                  :3
              ]:  # Limit to 3 observations
                  output += f"- {observation}\n"
  
              if len(entity.observations) > 3:
                  output += f"... and {len(entity.observations) - 3} more observations\n"
  
          output += "\n"
  
      return output

• sourcesage/knowledge.py:444-481 (helper)

  Core implementation of entity querying in KnowledgeGraph class. Filters entities by type, language, and name pattern using regex, with optional limit.

  def query_entities(
      self,
      entity_type: str | None = None,
      language: str | None = None,
      name_pattern: str | None = None,
      limit: int = 100,
  ) -> list[Entity]:
      """Query entities based on criteria.
  
      Args:
          entity_type: Filter by entity type
          language: Filter by programming language
          name_pattern: Filter by name pattern (regex)
          limit: Maximum number of results
  
      Returns:
          List of matching entities
      """
      results = []
  
      for entity in self.entities.values():
          # Apply filters
          if entity_type is not None and entity.entity_type != entity_type:
              continue
  
          if language is not None and entity.language != language:
              continue
  
          if name_pattern is not None:
              if not re.search(name_pattern, entity.name):
                  continue
  
          results.append(entity)
  
          if len(results) >= limit:
              break
  
      return results