sourcesage

Instructions

Implementation Reference

• sourcesage/mcp_server.py:605-715 (handler)

  The core handler function for the 'dump_project_understanding' MCP tool. It is registered via the @self.mcp.tool() decorator. The function signature provides the input schema (project_path: str, include_observations: bool -> str). It gathers all entities and relations associated with the given project_path from self.knowledge, groups them, and formats a comprehensive textual dump, optionally including observations, patterns, and style conventions.

  @self.mcp.tool()
  def dump_project_understanding(
      project_path: str, include_observations: bool = False
  ) -> str:
      """Dump understanding of an entire project at once.
  
      This tool provides a comprehensive dump of all knowledge related to a project,
      including all entities, relationships, patterns, and style conventions.
  
      Args:
          project_path: Path to the project root directory
          include_observations: Whether to include detailed observations
      """
      # 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}"
  
      # Get all relations involving project entities
      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"
  
      # Group entities by type
      entities_by_type = {}
      for entity in project_entities:
          if entity.entity_type not in entities_by_type:
              entities_by_type[entity.entity_type] = []
          entities_by_type[entity.entity_type].append(entity)
  
      # Output entities by type
      for entity_type, entities in sorted(entities_by_type.items()):
          output += f"{entity_type.capitalize()} Entities ({len(entities)}):\n"
  
          for entity in sorted(entities, key=lambda e: e.name):
              output += f"- {entity.name}\n"
              output += f"  Summary: {entity.summary}\n"
  
              if entity.signature:
                  output += f"  Signature: {entity.signature}\n"
  
              if entity.language:
                  output += f"  Language: {entity.language}\n"
  
              # Include observations if requested
              if include_observations and entity.observations:
                  output += "  Observations:\n"
                  for observation in entity.observations:
                      output += f"    - {observation}\n"
  
              # Include relations
              entity_relations = [
                  r for r in project_relations if r.from_id == entity.entity_id
              ]
              if entity_relations:
                  output += "  Relations:\n"
                  for relation in entity_relations:
                      to_entity = self.knowledge.get_entity(relation.to_id)
                      if to_entity:
                          output += f"    - {relation.relation_type} -> {to_entity.name} ({to_entity.entity_type})\n"
  
              output += "\n"
  
          output += "\n"
  
      # Include patterns and style conventions if any are associated with this project
      project_patterns = []
      for pattern in self.knowledge.patterns.values():
          if pattern.metadata.get("project_path") == project_path:
              project_patterns.append(pattern)
  
      if project_patterns:
          output += f"Patterns ({len(project_patterns)}):\n"
          for pattern in project_patterns:
              output += f"- {pattern.name}: {pattern.description}\n"
          output += "\n"
  
      project_conventions = []
      for convention in self.knowledge.style_conventions.values():
          if convention.metadata.get("project_path") == project_path:
              project_conventions.append(convention)
  
      if project_conventions:
          output += f"Style Conventions ({len(project_conventions)}):\n"
          for convention in project_conventions:
              output += f"- {convention.name}: {convention.description}\n"
          output += "\n"
  
      return output