read_file

Instructions

Implementation Reference

• packages/core/src/files/index.ts:223-237 (handler)

  The core implementation of the read_file tool. Queries the SQLite database for a file record by ID, reads the file content from disk using readFileSync, and returns the combined record with content.

  export function readFile(id: number): FileRecordWithContent {
    const db = getDatabase();
  
    const fileRecord = db.prepare("SELECT * FROM files WHERE id = ?").get(id) as FileRecord | undefined;
    if (!fileRecord) {
      throw new Error(`File not found: ${id}`);
    }
  
    const content = readFileSync(fileRecord.path, "utf8");
  
    return {
      ...fileRecord,
      content,
    };
  }

• apps/mcp/src/index.ts:168-180 (registration)

  MCP Server tool registration for 'read_file'. Defines the input schema (id: number), calls the core readFile function, and annotates the result with token estimates before returning as JSON.

  server.tool(
    "read_file",
    "Read one file's full body and metadata by ID. Read-only; no side effects, auth, or rate limits. Returns title, path, content, tags, est_tokens (so you can budget context before opening more files), and timestamps. Throws if the ID is unknown. Use for a single known file. Prefer `describe_file` to inspect without paying body tokens; `read_files` for batches; `read_file_lines`/`read_section` for partial reads; `read_file_by_path` when you only have the absolute path.",
    {
      id: z.number().describe("File ID"),
    },
    async ({ id }) => {
      const result = readFile(id);
      return {
        content: [{ type: "text", text: JSON.stringify(annotateTokens(result), null, 2) }],
      };
    }
  );

• apps/mcp/src/index.ts:172-173 (schema)

  Zod schema for the read_file tool - accepts a single numeric 'id' parameter.

    id: z.number().describe("File ID"),
  },

• packages/core/src/files/index.ts:61-64 (helper)

  Type definition for the return type of readFile, extending FileRecord with content and optional git_warning.

  export interface FileRecordWithContent extends FileRecord {
    content: string;
    git_warning?: string;
  }

• packages/core/src/index.ts:2-26 (registration)

  Re-exports the readFile function from the core package so it can be imported by the MCP server app.

  import { createFile, readFile, updateFile, deleteFile, listFiles, moveFile, createFolder, deleteFolder, listProjectFolders, slugify } from "./files/index.js";
  export { createFile, readFile, updateFile, deleteFile, listFiles, moveFile, createFolder, deleteFolder, listProjectFolders, slugify };
  export { parseOutline, findSection, replaceSection, type OutlineNode } from "./files/sections.js";
  export { assertPathInside } from "./util/safety.js";
  export {
    addTags, removeTags, setFavorite, search,
    registerProject, unregisterProject, discoverFiles, listTags, listProjects,
    findRelated, getTagsForFiles, type RelatedFileRecord,
  } from "./metadata/index.js";
  export { commitFile, getHistory, getDiff, restoreVersion, syncBackup, syncGlobalVault, getGlobalRemote, setGlobalRemote, isValidGitRemoteUrl, type SyncStage } from "./git/index.js";
  export { withLock } from "./util/safety.js";
  export { createFileWatcher, type WatcherEvent } from "./watcher/index.js";
  export { bundleSearch, type BundleFormat, type BundleOptions, type BundleResult, type BundleIncludedItem, type BundleSkippedItem } from "./bundle/index.js";
  export { estimateTokensFromBuffer, estimateTokensFromString } from "./util/tokens.js";
  export type * from "./types.js";
  export { clipUrl, ClipError, type ClipErrorCode, type ClipUrlOptions } from "./clip/index.js";
  export {
    whatsNew, resolveSince,
    type WhatsNewOptions, type WhatsNewResult, type WhatsNewEntry, type ChangeKind,
  } from "./whats-new/index.js";
  export {
    projectMap,
    type ProjectMapOptions, type ProjectMapResult, type ProjectMapStats,
  } from "./project-map/index.js";