list_projects
Retrieve and overview all projects by specifying a working directory. Access comprehensive details, progress insights, and project-specific storage for efficient tracking and navigation within your workspace.
Instructions
Discover and overview all your projects with comprehensive details and progress insights. Perfect for getting a bird's-eye view of your work portfolio, tracking project status, and quickly navigating between different initiatives in your workspace with project-specific storage.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| workingDirectory | Yes | The full absolute path to the working directory where data is stored. MUST be an absolute path, never relative. Windows: "C:\Users\username\project" or "D:\projects\my-app". Unix/Linux/macOS: "/home/username/project" or "/Users/username/project". Do NOT use: ".", "..", "~", "./folder", "../folder" or any relative paths. Ensure the path exists and is accessible before calling this tool. NOTE: When server is started with --claude flag, this parameter is ignored and a global user directory is used instead. |
Implementation Reference
- The createListProjectsTool function defines the core handler logic for the 'list_projects' tool. It fetches all projects from storage, formats them with name, ID, description, and timestamps, handles empty list and errors, and returns formatted text content.
export function createListProjectsTool(storage: Storage) { return { name: 'list_projects', description: 'View all projects in the task management system', inputSchema: {}, handler: async () => { try { const projects = await storage.getProjects(); if (projects.length === 0) { return { content: [{ type: 'text' as const, text: 'No projects found. Create your first project to get started!' }] }; } const projectList = projects.map(project => { return `**${project.name}** (ID: ${project.id}) Description: ${project.description} Created: ${new Date(project.createdAt).toLocaleString()} Updated: ${new Date(project.updatedAt).toLocaleString()}`; }).join('\n\n'); return { content: [{ type: 'text' as const, text: `Found ${projects.length} project(s):\n\n${projectList}` }] }; } catch (error) { return { content: [{ type: 'text' as const, text: `Error listing projects: ${error instanceof Error ? error.message : 'Unknown error'}` }], isError: true }; } } }; } - src/server.ts:76-97 (registration)Registers the 'list_projects' tool on the MCP server. Includes input schema requiring 'workingDirectory', detailed description, and wrapper handler that initializes storage and invokes the core tool handler.
server.tool( 'list_projects', 'Discover and overview all your projects with comprehensive details and progress insights. Perfect for getting a bird\'s-eye view of your work portfolio, tracking project status, and quickly navigating between different initiatives in your workspace with project-specific storage.', { workingDirectory: z.string().describe(getWorkingDirectoryDescription(config)) }, async ({ workingDirectory }: { workingDirectory: string }) => { try { const storage = await createStorage(workingDirectory, config); const tool = createListProjectsTool(storage); return await tool.handler(); } catch (error) { return { content: [{ type: 'text' as const, text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }], isError: true }; } } ); - src/server.ts:79-81 (schema)Input schema for the 'list_projects' tool, defining the required 'workingDirectory' parameter with Zod validation and description.
{ workingDirectory: z.string().describe(getWorkingDirectoryDescription(config)) },