MCP Smart Filesystem Server

Instructions

Implementation Reference

• index.ts:65-77 (registration)

  Registration of the 'list_directory' tool in the MCP tools array, specifying name, description, and input schema requiring a 'path' parameter.

    name: 'list_directory',
    description: 'List contents of a directory with metadata including file sizes and line counts',
    inputSchema: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: "Directory path to list. Use '.' for workspace root"
        }
      },
      required: ['path']
    }
  },

• index.ts:269-281 (handler)

  Dispatch handler in the CallToolRequestSchema that parses input arguments, validates the path, invokes the listDirectory function, and formats the response as MCP content.

  case 'list_directory': {
    const schema = z.object({ path: z.string() });
    const { path } = schema.parse(args);
    const validatedPath = await validatePath(path);
    const result = await listDirectory(validatedPath);
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2)
      }]
    };
  }

• lib.ts:176-192 (schema)

  TypeScript interfaces defining the structure of directory entries and the overall directory listing output returned by the listDirectory handler.

  export interface DirectoryEntry {
    name: string;
    type: 'file' | 'directory';
    size: string | null;
    lines?: number;
    itemCount?: number;
  }
  
  export interface DirectoryListing {
    path: string;
    entries: DirectoryEntry[];
    summary: {
      totalFiles: number;
      totalDirectories: number;
      totalSize: string;
    };
  }

• lib.ts:194-267 (handler)

  Core implementation of the list_directory tool: asynchronously reads directory entries, categorizes files and directories, computes metadata (sizes, line counts for small text files, subdir item counts), and returns structured DirectoryListing.

  export async function listDirectory(dirPath: string): Promise<DirectoryListing> {
    const entries = await fs.readdir(dirPath, { withFileTypes: true });
    const result: DirectoryEntry[] = [];
    let totalFiles = 0;
    let totalDirs = 0;
    let totalBytes = 0;
  
    for (const entry of entries) {
      const fullPath = path.join(dirPath, entry.name);
      
      if (entry.isDirectory()) {
        totalDirs++;
        try {
          const subEntries = await fs.readdir(fullPath);
          result.push({
            name: entry.name,
            type: 'directory',
            size: null,
            itemCount: subEntries.length
          });
        } catch {
          result.push({
            name: entry.name,
            type: 'directory',
            size: null,
            itemCount: 0
          });
        }
      } else if (entry.isFile()) {
        totalFiles++;
        try {
          const stats = await fs.stat(fullPath);
          totalBytes += stats.size;
          
          // For text files, try to count lines
          let lines: number | undefined;
          if (stats.size < 10 * 1024 * 1024) { // Only for files < 10MB
            const isBinary = await isBinaryFile(fullPath);
            if (!isBinary) {
              try {
                const content = await readFileContent(fullPath);
                lines = countLines(content);
              } catch {
                // Ignore errors reading file content
              }
            }
          }
          
          result.push({
            name: entry.name,
            type: 'file',
            size: formatSize(stats.size),
            lines
          });
        } catch {
          result.push({
            name: entry.name,
            type: 'file',
            size: '0 B'
          });
        }
      }
    }
  
    return {
      path: dirPath,
      entries: result,
      summary: {
        totalFiles,
        totalDirectories: totalDirs,
        totalSize: formatSize(totalBytes)
      }
    };
  }