list_projects

Instructions

Implementation Reference

• kicad_mcp/tools/project_tools.py:22-28 (handler)

  The main handler function for the 'list_projects' tool, decorated with @mcp.tool(). It calls find_kicad_projects() and returns the list of projects.

  @mcp.tool()
  def list_projects() -> List[Dict[str, Any]]:
      """Find and list all KiCad projects on this system."""
      logging.info(f"Executing list_projects tool...")
      projects = find_kicad_projects()
      logging.info(f"list_projects tool returning {len(projects)} projects.")
      return projects

• kicad_mcp/server.py:149-149 (registration)

  The call to register_project_tools which registers the list_projects tool among others.

  register_project_tools(mcp)

• kicad_mcp/utils/kicad_utils.py:15-73 (helper)

  The core helper function find_kicad_projects() that scans configured directories for KiCad project files (.kicad_pro) and returns a list of project dictionaries.

  def find_kicad_projects() -> List[Dict[str, Any]]:
      """Find KiCad projects in the user's directory.
      
      Returns:
          List of dictionaries with project information
      """
      projects = []
      logging.info("Attempting to find KiCad projects...") # Log start
      # Search directories to look for KiCad projects
      raw_search_dirs = [config.KICAD_USER_DIR] + config.ADDITIONAL_SEARCH_PATHS
      logging.info(f"Raw KICAD_USER_DIR: '{config.KICAD_USER_DIR}'")
      logging.info(f"Raw ADDITIONAL_SEARCH_PATHS: {config.ADDITIONAL_SEARCH_PATHS}")
      logging.info(f"Raw search list before expansion: {raw_search_dirs}")
  
      expanded_search_dirs = []
      for raw_dir in raw_search_dirs:
          expanded_dir = os.path.expanduser(raw_dir) # Expand ~ and ~user
          if expanded_dir not in expanded_search_dirs:
              expanded_search_dirs.append(expanded_dir)
          else:
              logging.info(f"Skipping duplicate expanded path: {expanded_dir}")
              
      logging.info(f"Expanded search directories: {expanded_search_dirs}")
  
      for search_dir in expanded_search_dirs:
          if not os.path.exists(search_dir):
              logging.warning(f"Expanded search directory does not exist: {search_dir}") # Use warning level
              continue
          
          logging.info(f"Scanning expanded directory: {search_dir}")
          # Use followlinks=True to follow symlinks if needed
          for root, _, files in os.walk(search_dir, followlinks=True):
              for file in files:
                  if file.endswith(config.KICAD_EXTENSIONS["project"]):
                      project_path = os.path.join(root, file)
                      # Check if it's a real file and not a broken symlink
                      if not os.path.isfile(project_path):
                          logging.info(f"Skipping non-file/broken symlink: {project_path}")
                          continue
                      
                      try:
                          # Attempt to get modification time to ensure file is accessible
                          mod_time = os.path.getmtime(project_path)
                          rel_path = os.path.relpath(project_path, search_dir)
                          project_name = get_project_name_from_path(project_path)
  
                          logging.info(f"Found accessible KiCad project: {project_path}")
                          projects.append({
                              "name": project_name,
                              "path": project_path,
                              "relative_path": rel_path,
                              "modified": mod_time
                          })
                      except OSError as e:
                          logging.error(f"Error accessing project file {project_path}: {e}") # Use error level
                          continue # Skip if we can't access it
      
      logging.info(f"Found {len(projects)} KiCad projects after scanning.")
      return projects

• kicad_mcp/tools/project_tools.py:15-20 (registration)

  The registration function that defines and registers the project tools including list_projects via @mcp.tool() decorators.

  def register_project_tools(mcp: FastMCP) -> None:
      """Register project management tools with the MCP server.
      
      Args:
          mcp: The FastMCP server instance
      """