load_project_understanding

Instructions

Implementation Reference

• sourcesage/mcp_server.py:517-603 (handler)

  The handler function for the 'load_project_understanding' MCP tool. It is decorated with @self.mcp.tool() which registers it as an MCP tool. The function retrieves and formats a summary of the project's knowledge graph data, including entities and relations associated with the given project_path.

  @self.mcp.tool()
  def load_project_understanding(project_path: str) -> str:
      """Load understanding of an entire project at once.
  
      This tool should be used by MCP clients to quickly get project understanding
      if available, instead of reading all the files individually. It loads all
      entities, relationships, patterns, and style conventions related to the project.
  
      Args:
          project_path: Path to the project root directory
      """
      # Normalize the project path
      project_path = os.path.normpath(os.path.abspath(project_path))
  
      # Check if we have any entities related to this project
      project_entities = []
      for entity in self.knowledge.entities.values():
          entity_project = entity.metadata.get("project_path")
          if (
              entity_project
              and os.path.normpath(os.path.abspath(entity_project))
              == project_path
          ):
              project_entities.append(entity)
  
      if not project_entities:
          return f"No understanding available for project at: {project_path}"
  
      # Count entities by type
      entity_types = {}
      for entity in project_entities:
          entity_types[entity.entity_type] = (
              entity_types.get(entity.entity_type, 0) + 1
          )
  
      # Count relations
      project_entity_ids = {entity.entity_id for entity in project_entities}
      project_relations = []
      for relation in self.knowledge.relations.values():
          if (
              relation.from_id in project_entity_ids
              or relation.to_id in project_entity_ids
          ):
              project_relations.append(relation)
  
      # Format output
      output = f"Project Understanding for: {project_path}\n\n"
      output += f"Total Entities: {len(project_entities)}\n"
      output += f"Total Relations: {len(project_relations)}\n\n"
  
      if entity_types:
          output += "Entities by Type:\n"
          for entity_type, count in entity_types.items():
              output += f"- {entity_type}: {count}\n"
          output += "\n"
  
      # List key entities (e.g., modules, classes)
      key_entities = [
          e
          for e in project_entities
          if e.entity_type in ["module", "class", "interface"]
      ]
      if key_entities:
          output += "Key Components:\n"
          for entity in sorted(key_entities, key=lambda e: e.name)[
              :10
          ]:  # Limit to 10
              output += (
                  f"- {entity.name} ({entity.entity_type}): {entity.summary}\n"
              )
  
          if len(key_entities) > 10:
              output += f"... and {len(key_entities) - 10} more key components\n"
          output += "\n"
  
      # List all entities
      output += "All Entities:\n"
      for entity in sorted(project_entities, key=lambda e: e.name)[
          :30
      ]:  # Limit to 30 to avoid excessive output
          output += f"- {entity.name} ({entity.entity_type}): {entity.summary}\n"
  
      if len(project_entities) > 30:
          output += f"... and {len(project_entities) - 30} more entities\n"
      output += "\n"
  
      return output