get_file_summary

Get a quick summary of file metadata and basic statistics.

Overview

The get_file_summary tool provides a concise overview of file characteristics without the detailed analysis of get_file_structure. It's optimized for speed and gives you essential information quickly.

Usage

json

{
  "tool": "get_file_summary",
  "arguments": {
    "filePath": "/var/log/app.log"
  }
}

Parameters

Parameter	Type	Required	Default	Description
`filePath`	string	Yes	-	Absolute or relative path to the file

Response Format

typescript

{
  filePath: string;       // Absolute path to file
  fileName: string;       // File name without path
  fileSize: number;       // Size in bytes
  fileSizeFormatted: string; // Human-readable size (e.g., "10.5 MB")
  totalLines: number;     // Total line count
  created: Date;          // File creation date
  modified: Date;         // Last modified date
  accessed: Date;         // Last accessed date
  isReadable: boolean;    // Whether file is readable
  isWritable: boolean;    // Whether file is writable
}

Examples

Basic Summary

Quick file overview:

json

{
  "tool": "get_file_summary",
  "arguments": {
    "filePath": "/var/log/system.log"
  }
}

Response:

json

{
  "filePath": "/var/log/system.log",
  "fileName": "system.log",
  "fileSize": 10485760,
  "fileSizeFormatted": "10 MB",
  "totalLines": 25000,
  "created": "2024-01-01T00:00:00.000Z",
  "modified": "2024-01-10T15:30:00.000Z",
  "accessed": "2024-01-10T16:00:00.000Z",
  "isReadable": true,
  "isWritable": false
}

CSV File Summary

json

{
  "tool": "get_file_summary",
  "arguments": {
    "filePath": "/data/sales.csv"
  }
}

Response:

json

{
  "filePath": "/data/sales.csv",
  "fileName": "sales.csv",
  "fileSize": 52428800,
  "fileSizeFormatted": "50 MB",
  "totalLines": 500000,
  "created": "2024-01-05T08:00:00.000Z",
  "modified": "2024-01-09T23:45:00.000Z",
  "accessed": "2024-01-10T09:15:00.000Z",
  "isReadable": true,
  "isWritable": true
}

Code File Summary

json

{
  "tool": "get_file_summary",
  "arguments": {
    "filePath": "/code/app.ts"
  }
}

Response:

json

{
  "filePath": "/code/app.ts",
  "fileName": "app.ts",
  "fileSize": 65536,
  "fileSizeFormatted": "64 KB",
  "totalLines": 1250,
  "created": "2024-01-01T10:00:00.000Z",
  "modified": "2024-01-10T16:45:00.000Z",
  "accessed": "2024-01-10T16:50:00.000Z",
  "isReadable": true,
  "isWritable": true
}

Comparison: Summary vs Structure

Feature	get_file_summary	get_file_structure
Speed	Fast (< 100ms)	Slower (200ms-5s)
File size	✅	✅
Line count	✅	✅
Timestamps	✅	✅
Permissions	✅	❌
File type detection	❌	✅
Chunk information	❌	✅
Statistics	❌	✅ (detailed)
Encoding detection	❌	✅

Use get_file_summary when:

You need quick file information
You're doing permission checks
You're building file listings
You need human-readable sizes

Use get_file_structure when:

You need detailed statistics
You're planning file processing
You need chunk information
You need encoding detection

Common Use Cases

1. File Listing

Build file browser interface:

typescript

async function listFiles(directory: string) {
  const files = await readdir(directory);
  const summaries = await Promise.all(
    files.map(file =>
      get_file_summary({
        filePath: path.join(directory, file)
      })
    )
  );
  return summaries.sort((a, b) => b.modified - a.modified);
}

2. Permission Check

Verify file accessibility before operations:

typescript

const summary = await get_file_summary({
  filePath: "/data/important.csv"
});

if (!summary.isReadable) {
  throw new Error("Cannot read file: permission denied");
}

if (!summary.isWritable) {
  console.warn("File is read-only");
}

3. File Age Check

Find old files for archival:

typescript

const summary = await get_file_summary({
  filePath: "/logs/old.log"
});

const daysSinceModified =
  (Date.now() - summary.modified.getTime()) / (1000 * 60 * 60 * 24);

if (daysSinceModified > 30) {
  console.log(`Archive candidate: ${summary.fileName}`);
}

4. Size-Based Processing

Choose processing strategy based on size:

typescript

const summary = await get_file_summary({
  filePath: "/data/dataset.csv"
});

if (summary.fileSize < 1_000_000) {
  // Process in memory
  console.log("Small file, loading directly");
} else if (summary.fileSize < 100_000_000) {
  // Stream processing
  console.log("Medium file, using streaming");
} else {
  // Distributed processing
  console.log("Large file, using distributed processing");
}

5. Recent Files

Show recently modified files:

typescript

async function getRecentFiles(directory: string, days: number = 7) {
  const files = await readdir(directory);
  const summaries = await Promise.all(
    files.map(f => get_file_summary({ filePath: path.join(directory, f) }))
  );

  const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
  return summaries
    .filter(s => s.modified.getTime() > cutoff)
    .sort((a, b) => b.modified.getTime() - a.modified.getTime());
}

Performance

File Size	Summary Time	Notes
< 1MB	< 20ms	Stat + quick line count
1-10MB	20-50ms	Streaming line count
10-100MB	50-200ms	Optimized counting
100MB-1GB	200-1000ms	Line-by-line count
> 1GB	1-5s	Progressive counting

Performance Tips

Cache Results: File metadata rarely changes
Batch Operations: Use Promise.all for multiple files
Skip Line Count: If not needed, use fs.stat directly
Use Indexes: Build file index for large directories

Error Handling

File Not Found

json

{
  "error": "File not found: /path/to/missing.log",
  "code": "ENOENT"
}

Permission Denied

json

{
  "filePath": "/root/protected.log",
  "fileName": "protected.log",
  "isReadable": false,
  "isWritable": false,
  "error": "Permission denied"
}

Symbolic Link

json

{
  "filePath": "/var/log/current.log",
  "fileName": "current.log",
  "isSymlink": true,
  "linkTarget": "/var/log/2024-01-10.log"
}

Human-Readable Sizes

The fileSizeFormatted field uses the following format:

Size Range	Format	Example
< 1 KB	Bytes	"512 bytes"
1 KB - 1 MB	KB	"128 KB"
1 MB - 1 GB	MB	"45.5 MB"
1 GB - 1 TB	GB	"2.3 GB"
>= 1 TB	TB	"1.5 TB"

Best Practices

1. Quick Checks

Use for fast validation:

typescript

// Quick check before processing
const summary = await get_file_summary({ filePath });

if (summary.fileSize === 0) {
  throw new Error("File is empty");
}

if (!summary.isReadable) {
  throw new Error("Cannot read file");
}

2. File Browser

Build responsive file browsers:

typescript

// Fast initial load
const summaries = await Promise.all(
  files.map(f => get_file_summary({ filePath: f }))
);

// Display in UI
summaries.forEach(s => {
  console.log(`${s.fileName} - ${s.fileSizeFormatted} - ${s.modified}`);
});

3. Caching

Cache summary data:

typescript

const cache = new Map<string, FileSummary>();

async function getSummaryCached(filePath: string) {
  const summary = await get_file_summary({ filePath });

  // Cache if file hasn't changed
  const cached = cache.get(filePath);
  if (cached && cached.modified.getTime() === summary.modified.getTime()) {
    return cached;
  }

  cache.set(filePath, summary);
  return summary;
}

4. Batch Processing

Process multiple files efficiently:

typescript

async function summarizeDirectory(dir: string) {
  const files = await readdir(dir);

  // Batch process
  const summaries = await Promise.all(
    files.map(f =>
      get_file_summary({
        filePath: path.join(dir, f)
      })
    )
  );

  return summaries;
}

Integration Examples

File Dashboard

typescript

interface FileDashboard {
  totalFiles: number;
  totalSize: number;
  oldestFile: Date;
  newestFile: Date;
  largestFile: string;
  files: FileSummary[];
}

async function createDashboard(directory: string): Promise<FileDashboard> {
  const files = await readdir(directory);
  const summaries = await Promise.all(
    files.map(f => get_file_summary({ filePath: path.join(directory, f) }))
  );

  return {
    totalFiles: summaries.length,
    totalSize: summaries.reduce((sum, s) => sum + s.fileSize, 0),
    oldestFile: new Date(Math.min(...summaries.map(s => s.created.getTime()))),
    newestFile: new Date(Math.max(...summaries.map(s => s.modified.getTime()))),
    largestFile: summaries.reduce((max, s) =>
      s.fileSize > max.fileSize ? s : max
    ).fileName,
    files: summaries
  };
}

Watch File Changes

typescript

class FileWatcher {
  private lastSummary: FileSummary;

  async hasChanged(filePath: string): Promise<boolean> {
    const current = await get_file_summary({ filePath });

    if (!this.lastSummary) {
      this.lastSummary = current;
      return false;
    }

    const changed =
      current.modified.getTime() !== this.lastSummary.modified.getTime() ||
      current.fileSize !== this.lastSummary.fileSize;

    this.lastSummary = current;
    return changed;
  }
}

get_file_summary ​

Overview ​

Usage ​

Parameters ​

Response Format ​

Examples ​

Basic Summary ​

CSV File Summary ​

Code File Summary ​

Comparison: Summary vs Structure ​

Common Use Cases ​

1. File Listing ​

2. Permission Check ​

3. File Age Check ​

4. Size-Based Processing ​

5. Recent Files ​

Performance ​

Performance Tips ​

Error Handling ​

File Not Found ​

Permission Denied ​

Symbolic Link ​

Human-Readable Sizes ​

Best Practices ​

1. Quick Checks ​

2. File Browser ​

3. Caching ​

4. Batch Processing ​

Integration Examples ​

File Dashboard ​

Watch File Changes ​

See Also ​

get_file_summary

Overview

Usage

Parameters

Response Format

Examples

Basic Summary

CSV File Summary

Code File Summary

Comparison: Summary vs Structure

Common Use Cases

1. File Listing

2. Permission Check

3. File Age Check

4. Size-Based Processing

5. Recent Files

Performance

Performance Tips

Error Handling

File Not Found

Permission Denied

Symbolic Link

Human-Readable Sizes

Best Practices

1. Quick Checks

2. File Browser

3. Caching

4. Batch Processing

Integration Examples

File Dashboard

Watch File Changes

See Also