list_projects

Instructions

Implementation Reference

• server/src/mcp/tools.js:154-189 (handler)

  The actual tool handler for 'list_projects'. Defined via server.tool() call. Scans all projects using fileScanner.scanProjects(), counts sessions per project, marks the current project, and returns sorted JSON results.

  // ─── list_projects ───────────────────────────────────────────────
  server.tool(
    'list_projects',
    'List all Claude Code projects on this machine. Shows which project is currently active.',
    {},
    async () => {
      try {
        const { fileScanner, currentProjectId } = await getServices()
        const projects = await fileScanner.scanProjects()
  
        const results = []
        for (const project of projects) {
          const sessions = await fileScanner.scanSessions(project.path)
          results.push({
            id: project.id,
            name: project.name,
            sessionCount: sessions.length,
            lastModified: project.lastModified,
            isCurrent: project.id === currentProjectId,
          })
        }
  
        // Put current project first
        results.sort((a, b) => (b.isCurrent ? 1 : 0) - (a.isCurrent ? 1 : 0))
  
        return {
          content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
        }
      } catch (error) {
        return {
          content: [{ type: 'text', text: `Error listing projects: ${error.message}` }],
          isError: true,
        }
      }
    }
  )

• server/src/mcp/tools.js:32-32 (registration)

  The export function registerTools(server, getServices) that registers all tools on the MCP server instance, including list_projects.

  export function registerTools(server, getServices) {

• server/src/mcp/index.js:106-108 (registration)

  Where registerTools is called to wire the tools (including list_projects) to the MCP server.

  registerTools(server, getServices)
  registerResources(server, getServices)
  registerPrompts(server)

• server/src/services/fileScanner.js:10-34 (helper)

  The scanProjects() method on FileScanner that reads the projects directory and returns project metadata (id, name, path, lastModified).

  async scanProjects() {
    try {
      const entries = await fs.readdir(this.projectsRoot, { withFileTypes: true });
      const projects = [];
  
      for (const entry of entries) {
        if (entry.isDirectory()) {
          const projectPath = path.join(this.projectsRoot, entry.name);
          const stats = await fs.stat(projectPath);
          
          projects.push({
            id: entry.name,
            name: this.cleanProjectName(entry.name),
            path: projectPath,
            lastModified: stats.mtime.toISOString()
          });
        }
      }
  
      return projects.sort((a, b) => new Date(b.lastModified) - new Date(a.lastModified));
    } catch (error) {
      console.error('Error scanning projects:', error);
      throw new Error(`Failed to scan projects directory: ${error.message}`);
    }
  }

• server/src/utils/pathHelper.js:34-44 (helper)

  getProjectRoot() resolves the projects directory (from PROJECT_ROOT env or default ~/.claude/projects).

  export function getProjectRoot() {
    const envPath = process.env.PROJECT_ROOT;
  
    // If PROJECT_ROOT is set, expand it
    if (envPath) {
      return expandPath(envPath);
    }
  
    // Default fallback: ~/.claude/projects
    return path.join(os.homedir(), '.claude', 'projects');
  }