read_text_file
Read complete or partial text file contents from allowed directories, handling various encodings with detailed error reporting.
Instructions
Read the complete contents of a file from the file system as text. Handles various text encodings and provides detailed error messages if the file cannot be read. Use this tool when you need to examine the contents of a single file. Use the 'head' parameter to read only the first N lines of a file, or the 'tail' parameter to read only the last N lines of a file. Operates on the file as text regardless of extension. Only works within allowed directories.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| tail | No | If provided, returns only the last N lines of the file | |
| head | No | If provided, returns only the first N lines of the file |
Implementation Reference
- src/filesystem/index.ts:172-192 (handler)The async handler function that implements the core logic for the 'read_text_file' tool. It validates the input path, checks for mutually exclusive head/tail parameters, reads the full file content or first/last N lines using helper functions, and returns the content in the expected MCP format.const readTextFileHandler = async (args: z.infer<typeof ReadTextFileArgsSchema>) => { const validPath = await validatePath(args.path); if (args.head && args.tail) { throw new Error("Cannot specify both head and tail parameters simultaneously"); } let content: string; if (args.tail) { content = await tailFile(validPath, args.tail); } else if (args.head) { content = await headFile(validPath, args.head); } else { content = await readFileContent(validPath); } return { content: [{ type: "text" as const, text: content }], structuredContent: { content } }; };
- src/filesystem/index.ts:77-81 (schema)Zod schema defining the input parameters for the read_text_file tool: 'path' (required string), 'tail' and 'head' (optional numbers for limiting output to last or first N lines).const ReadTextFileArgsSchema = z.object({ path: z.string(), tail: z.number().optional().describe('If provided, returns only the last N lines of the file'), head: z.number().optional().describe('If provided, returns only the first N lines of the file') });
- src/filesystem/index.ts:206-227 (registration)Registration of the 'read_text_file' tool with the MCP server, specifying title, detailed description, inline input schema, output schema, read-only annotation, and linking to the shared readTextFileHandler.server.registerTool( "read_text_file", { title: "Read Text File", description: "Read the complete contents of a file from the file system as text. " + "Handles various text encodings and provides detailed error messages " + "if the file cannot be read. Use this tool when you need to examine " + "the contents of a single file. Use the 'head' parameter to read only " + "the first N lines of a file, or the 'tail' parameter to read only " + "the last N lines of a file. Operates on the file as text regardless of extension. " + "Only works within allowed directories.", inputSchema: { path: z.string(), tail: z.number().optional().describe("If provided, returns only the last N lines of the file"), head: z.number().optional().describe("If provided, returns only the first N lines of the file") }, outputSchema: { content: z.string() }, annotations: { readOnlyHint: true } }, readTextFileHandler );
- src/filesystem/lib.ts:134-136 (helper)Helper function that performs the actual reading of the full file content using Node.js fs.readFile with UTF-8 encoding. Called by the handler when neither head nor tail is specified.export async function readFileContent(filePath: string, encoding: string = 'utf-8'): Promise<string> { return await fs.readFile(filePath, encoding as BufferEncoding); }