file_stat
Retrieve detailed statistics for files or directories, including size, permissions, and modification timestamps, to analyze and manage file system information.
Instructions
Get file or directory statistics
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"path": "<path>"
},
"name": "file_stat"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to file or directory |
Implementation Reference
- src/tools/metadata.ts:30-109 (handler)Implementation of the file_stat logic which retrieves file stats and returns them as a tool result.
async function fileStatImpl(input: FileStatInput): Promise<ToolResult> { try { const absolutePath = path.resolve(input.path); const stats = await fs.stat(absolutePath); const lstat = await fs.lstat(absolutePath); const result: FileStat = { path: absolutePath, name: path.basename(absolutePath), size: stats.size, isFile: stats.isFile(), isDirectory: stats.isDirectory(), isSymlink: lstat.isSymbolicLink(), created: stats.birthtime.toISOString(), modified: stats.mtime.toISOString(), accessed: stats.atime.toISOString(), }; // Add formatted size for convenience const formattedResult = { ...result, sizeFormatted: formatBytes(stats.size), }; return { content: [ { type: 'text', text: JSON.stringify(formattedResult, null, 2), }, ], }; } catch (error) { const err = error as NodeJS.ErrnoException; if (err.code === 'ENOENT') { return { isError: true, content: [ { type: 'text', text: JSON.stringify({ code: 'FILE_NOT_FOUND', message: `Path not found: ${input.path}`, }), }, ], }; } if (err.code === 'EACCES') { return { isError: true, content: [ { type: 'text', text: JSON.stringify({ code: 'PERMISSION_DENIED', message: `Permission denied: ${input.path}`, }), }, ], }; } return { isError: true, content: [ { type: 'text', text: JSON.stringify({ code: 'UNKNOWN_ERROR', message: `Error getting stats: ${err.message}`, }), }, ], }; } } - src/tools/metadata.ts:445-455 (registration)Registration of the 'file_stat' tool with the MCP server.
server.tool( 'file_stat', 'Get file or directory statistics', { path: z.string().describe('Path to file or directory'), }, async (args) => { const input = FileStatInputSchema.parse(args); return await fileStatImpl(input); } ); - src/types.ts:243-246 (schema)Zod schema definition for file_stat tool input validation.
export const FileStatInputSchema = z.object({ path: z.string().describe('Path to file or directory'), });