Read Project File
openl_read_project_fileRead any project file by relative path: retrieve file content (text or binary), metadata, list folder entries, or download folder as ZIP. Supports version and branch pinning.
Instructions
Read any file in a project by its project-relative path — text or binary, and folder listings too. Maps to GET /projects/{projectId}/files/{path}. Behavior by path/params: (1) a FILE path returns its content — UTF-8 text is returned verbatim, binary is returned base64-encoded with metadata (use encoding to force 'utf-8' or 'base64'; default 'auto' detects); (2) a FILE path with view='meta' returns JSON metadata (name, size, extension, lastModified); (3) a FOLDER path (empty string for the root, or a path ending in '/') lists its entries (use recursive, viewMode FLAT/NESTED, extensions, namePattern, foldersOnly); (4) a FOLDER path with download=true returns a ZIP of the folder (base64). Optional 'version' reads a historical revision; 'branch' pins the project branch. Optional byte range (offset/length) is applied client-side AFTER fetching the whole file (the backend does not support partial transfers), so the entire file is loaded into memory; for very large/binary files, bound the RETURNED size with offset/length and read in chunks (a full file's base64 can exceed MCP message limits). Use this to read AGENTS.md, README.md, schemas, manifests, or to inspect/export xlsx rule files.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Project-relative path to a file or folder (e.g. 'rules/Model.xlsx' or 'rules/'). Empty string (default) or a path ending in '/' lists the project root / that folder; a file path returns the file content. | |
| view | No | For a file, set to 'meta' to return JSON metadata (name, size, extension, lastModified) instead of the file content. Omit to read content (files) or list entries (folders). | |
| branch | No | Branch the project must be on for this operation. Ignored when blank. Fails if the repository has no branches or the project is on another branch. Omit for repository 'local' and non-branch repositories. | |
| fields | No | Comma-separated response fields to return for metadata/listing responses, including nested selection (e.g. 'id,name'). When omitted, the full response is returned. | |
| length | No | Maximum number of bytes of file content to return starting at 'offset'. Omit for the rest of the file. Byte count, not character count (see the note on 'offset'). | |
| offset | No | Byte offset to start reading file content from (default 0). NOTE: the backend does not support partial transfers, so the whole file is fetched and then sliced client-side. offset/length are BYTE offsets — a range boundary that lands inside a multi-byte UTF-8 character makes that character decode to U+FFFD (�) at the seam; for exact bytes use encoding='base64'. | |
| version | No | Historical revision (commit hash) to read. Omit to read the latest revision. Applies to file content/metadata and folder listing/ZIP. An unknown revision yields 404. | |
| download | No | For a folder, set true to download the folder and its contents as a ZIP archive (returned base64-encoded). Ignored for files. | |
| encoding | Yes | How to return file content. 'auto' (default) returns text as UTF-8 and binary as base64; 'utf-8' forces text; 'base64' forces base64. Ignored for metadata/listing responses. | auto |
| viewMode | No | Folder listing only: FLAT returns a flat list, NESTED returns a tree (default FLAT). | |
| projectId | Yes | Project ID returned by backend. Use the exact 'projectId' value from openl_list_projects() response without modification or reformatting. | |
| recursive | No | Folder listing only: include nested resources recursively (default false). | |
| extensions | No | Folder listing only: filter by file extensions without the dot, e.g. ['xlsx','xml']. | |
| foldersOnly | No | Folder listing only: if true, return only folders (default false). | |
| namePattern | No | Folder listing only: filter by name (case-insensitive contains match). | |
| response_format | No | Response format: 'json' for structured data, 'markdown' for human-readable (default), 'markdown_concise' for brief summary (1-2 paragraphs), 'markdown_detailed' for full details with context | markdown |