Local Utilities MCP Server

Implementation Reference

• src/mcp/directory.ts:42-56 (handler)

  The asynchronous handler function for the 'list_directory' tool. It extracts the directory path from input parameters, invokes the listDirectory helper, formats the results as JSON, and returns them as text content via the MCP protocol.

  async (params) => {
    // Let SDK handle errors like directory not found
    const dirPath = params.path;
    const contents = await listDirectory(dirPath);
      
    return {
      content: [{
        type: "text",
        text: JSON.stringify({ 
          path: dirPath,
          contents 
        }, null, 2)
      }]
    };
  }

• src/mcp/directory.ts:41-41 (schema)

  The Zod input schema defining the 'path' parameter as a required string for the list_directory tool.

  { path: z.string().describe("Directory path to list") },

• src/mcp/directory.ts:38-58 (registration)

  The registration function that adds the 'list_directory' tool to the McpServer instance, specifying the tool name, input schema, and handler function.

  export function registerDirectoryTool(server: McpServer): void {
    server.tool(
      "list_directory",
      { path: z.string().describe("Directory path to list") },
      async (params) => {
        // Let SDK handle errors like directory not found
        const dirPath = params.path;
        const contents = await listDirectory(dirPath);
          
        return {
          content: [{
            type: "text",
            text: JSON.stringify({ 
              path: dirPath,
              contents 
            }, null, 2)
          }]
        };
      }
    );
  } 

• src/mcp/directory.ts:11-36 (helper)

  Core helper function that asynchronously lists the contents of a directory using Node.js fs.promises, determining entry types (directory, file, other) and file sizes, handling stat errors gracefully.

  export async function listDirectory(dirPath: string): Promise<Array<{ name: string; type: string; size?: number }>> {
    const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
    
    return Promise.all(entries.map(async (entry) => {
      const entryPath = path.join(dirPath, entry.name);
      
      if (entry.isDirectory()) {
        return { name: entry.name, type: 'directory' };
      } else if (entry.isFile()) {
        try {
          const stats = await fs.promises.stat(entryPath);
          return { 
            name: entry.name, 
            type: 'file',
            size: stats.size
          };
        } catch (statError) {
          // Handle potential stat errors (e.g., broken symlinks)
          console.warn(`Could not stat file ${entryPath}:`, statError);
          return { name: entry.name, type: 'file', size: undefined }; // Indicate file, but size unknown
        }
      } else {
        return { name: entry.name, type: 'other' };
      }
    }));
  }