# Tools Reference
## File Operations
### read_text_file
Read file contents with automatic encoding detection and optional partial reading. UTF-8 files pass through unchanged; other encodings convert to UTF-8.
**Parameters:**
- `path` (required): Path to the file
- `encoding` (optional): Encoding name (auto-detects if omitted)
- `offset` (optional): Start reading from this line number (1-indexed)
- `limit` (optional): Maximum number of lines to read
**Example:**
```json
{
"path": "/path/to/file.pas",
"offset": 100,
"limit": 50
}
```
**Response:**
```json
{
"content": "line 100\nline 101\n...",
"totalLines": 500,
"startLine": 100,
"endLine": 149,
"detectedEncoding": "windows-1251",
"encodingConfidence": 95
}
```
### read_multiple_files
Read multiple files concurrently with encoding support. Individual file failures don't stop the operation.
**Parameters:**
- `paths` (required): Array of file paths to read
- `encoding` (optional): Encoding for all files (auto-detected per file if omitted)
**Example:**
```json
{
"paths": ["/path/to/file1.pas", "/path/to/file2.pas"],
"encoding": "cp1251"
}
```
**Response:**
```json
{
"results": [
{
"path": "/path/to/file1.pas",
"content": "program Hello;...",
"detectedEncoding": "windows-1251",
"encodingConfidence": 95
},
{
"path": "/path/to/file2.pas",
"content": "unit Utils;..."
}
],
"successCount": 2,
"errorCount": 0
}
```
### write_file
Write content to file. UTF-8 writes as-is; other encodings convert from UTF-8.
**Parameters:**
- `path` (required): Path to the file
- `content` (required): Content to write
- `encoding` (optional): Target encoding (default: cp1251)
**Example:**
```json
{
"path": "/path/to/file.pas",
"content": "program Hello;\nbegin\n writeln('Zdravei');\nend.",
"encoding": "cp1251"
}
```
**Response:**
```json
{
"message": "Successfully wrote 48 bytes to /path/to/file.pas"
}
```
### edit_file
Make line-based edits to a text file. Supports exact matching and whitespace-flexible matching. Returns a git-style unified diff showing changes.
**Parameters:**
- `path` (required): Path to the file to edit
- `edits` (required): Array of edit operations, each with `oldText` and `newText`
- `dryRun` (optional): If true, returns diff without writing changes (default: false)
- `encoding` (optional): File encoding (auto-detected if not specified)
- `forceWritable` (optional): If true, clears read-only flag before editing (default: true)
**Features:**
- Exact text matching (first occurrence)
- Whitespace-flexible matching (ignores leading whitespace differences)
- Preserves original indentation
- CRLF line endings normalized to LF
- Atomic write (temp file + rename)
- Automatically clears read-only flag (disable with `forceWritable: false`)
**Example:**
```json
{
"path": "/path/to/file.go",
"edits": [
{
"oldText": "func oldName()",
"newText": "func newName()"
}
],
"dryRun": false
}
```
**Response:**
```json
{
"diff": "--- /path/to/file.go\n+++ /path/to/file.go\n@@ -1,3 +1,3 @@\n-func oldName()\n+func newName()\n",
"readOnlyCleared": true
}
```
The `readOnlyCleared` field indicates if the read-only flag was removed (only present when true).
## Directory Operations
### list_directory
List files and directories with optional pattern filtering.
**Parameters:**
- `path` (required): Path to directory
- `pattern` (optional): Glob pattern like `*.pas` or `*.dfm` (default: `*`)
**Example:**
```json
{
"path": "/path/to/project",
"pattern": "*.pas"
}
```
**Response:**
```json
{
"files": ["main.pas", "utils.pas", "forms.pas"]
}
```
### tree
Compact indented tree view optimized for AI/LLM consumption. Uses ~85% fewer tokens than `directory_tree`.
**Parameters:**
- `path` (required): Root directory
- `maxDepth` (optional): Maximum recursion depth (0 = unlimited)
- `maxFiles` (optional): Maximum entries to return (default: 1000)
- `dirsOnly` (optional): Only show directories, not files
- `exclude` (optional): Array of patterns to exclude
**Example:**
```json
{
"path": "/path/to/project",
"maxDepth": 3,
"exclude": ["node_modules", ".git"]
}
```
**Response:**
```json
{
"tree": "src/\n handler/\n read.go\n write.go\n server.go\nREADME.md",
"fileCount": 4,
"dirCount": 2,
"truncated": false
}
```
### directory_tree (deprecated)
Get a recursive tree view as JSON. **Use `tree` instead for 85% fewer tokens.**
**Parameters:**
- `path` (required): Root directory
- `excludePatterns` (optional): Array of glob patterns to exclude
**Response:**
```json
{
"tree": "{\"name\":\"project\",\"type\":\"directory\",\"children\":[...]}"
}
### get_file_info
Get metadata about a file or directory (size, timestamps, permissions).
**Parameters:**
- `path` (required): Path to file or directory
### create_directory
Create a directory recursively (like `mkdir -p`). Succeeds if already exists.
**Parameters:**
- `path` (required): Path to directory to create
### move_file
Move or rename files and directories. Fails if destination exists.
**Parameters:**
- `source` (required): Path to move
- `destination` (required): Destination path
### copy_file
Copy a file. Fails if destination exists. Does not copy directories.
**Parameters:**
- `source` (required): Source file path
- `destination` (required): Destination path
### delete_file
Delete a file. Does not delete directories.
**Parameters:**
- `path` (required): Path to delete
### search_files
Recursively search for files and directories matching a glob pattern.
**Parameters:**
- `path` (required): Root directory to search from
- `pattern` (required): Glob pattern (`*.txt` for current dir, `**/*.txt` for recursive)
- `excludePatterns` (optional): Array of patterns to exclude
**Example:**
```json
{
"path": "/path/to/project",
"pattern": "**/*.go",
"excludePatterns": ["vendor", "node_modules"]
}
```
**Response:**
```json
{
"files": [
"/path/to/project/main.go",
"/path/to/project/src/utils.go"
]
}
```
### grep_text_files
Search file contents using regex patterns with encoding support. Supports context lines and concurrent searching.
**Parameters:**
- `pattern` (required): Regular expression pattern to search for
- `paths` (required): Array of file or directory paths to search
- `caseSensitive` (optional): Case-sensitive matching (default: true)
- `contextBefore` (optional): Number of lines to show before each match
- `contextAfter` (optional): Number of lines to show after each match
- `maxMatches` (optional): Maximum total matches to return (default: 1000)
- `include` (optional): Glob pattern to include files (e.g., `*.go`)
- `exclude` (optional): Glob pattern to exclude files (e.g., `*_test.go`)
- `encoding` (optional): File encoding (auto-detected if omitted)
**Example:**
```json
{
"pattern": "func\\s+\\w+",
"paths": ["/path/to/project"],
"include": "*.go",
"contextBefore": 1,
"contextAfter": 2,
"maxMatches": 100
}
```
**Response:**
```json
{
"matches": [
{
"path": "/path/to/project/main.go",
"line": 15,
"column": 1,
"text": "func main() {",
"before": ["package main"],
"after": [" fmt.Println(\"Hello\")", "}"],
"encoding": "utf-8"
}
],
"totalMatches": 1,
"filesSearched": 5,
"filesMatched": 1,
"truncated": false
}
```
## Encoding Tools
### detect_encoding
Detect the encoding of a file with confidence percentage. Useful for diagnosing encoding issues (garbled text, � characters).
**Parameters:**
- `path` (required): Path to the file
- `mode` (optional): Detection mode
- `sample` (default): Read begin/middle/end samples - fast, good for most files
- `chunked`: Read all chunks with weighted averaging - thorough but slower
- `full`: Read entire file - most accurate but uses more memory
**Example:**
```json
{
"path": "/path/to/file.pas",
"mode": "chunked"
}
```
**Response:**
```json
{
"encoding": "windows-1251",
"confidence": 95,
"has_bom": false
}
```
### convert_encoding
Convert a file from one encoding to another. Reads in source encoding, writes in target encoding.
**Parameters:**
- `path` (required): Path to the file to convert
- `from` (optional): Source encoding (auto-detected if omitted)
- `to` (required): Target encoding
- `backup` (optional): Create a `.bak` backup file before converting (default: false)
**Example:**
```json
{
"path": "/path/to/file.pas",
"from": "cp1251",
"to": "utf-8",
"backup": true
}
```
**Response:**
```json
{
"message": "Converted /path/to/file.pas from windows-1251 to utf-8",
"sourceEncoding": "windows-1251",
"targetEncoding": "utf-8",
"backupPath": "/path/to/file.pas.bak"
}
```
### detect_line_endings
Detect line ending style (CRLF/LF/mixed) and find lines with inconsistent endings. Useful for diagnosing mixed line ending issues in legacy codebases.
**Parameters:**
- `path` (required): Path to the file to analyze
**Example:**
```json
{
"path": "/path/to/file.pas"
}
```
**Response:**
```json
{
"style": "mixed",
"totalLines": 150,
"inconsistentLines": [45, 78, 123]
}
```
**Style values:**
- `crlf`: All lines use Windows line endings (\\r\\n)
- `lf`: All lines use Unix line endings (\\n)
- `mixed`: File has both CRLF and LF endings - `inconsistentLines` lists lines with minority style
- `none`: File has no line endings (single line or empty)
### list_encodings
Returns all 22 supported encodings with name, aliases, and description.
### list_allowed_directories
Returns directories the server is allowed to access. If empty, add paths as args in config.
## Supported Encodings
| Name | Aliases | Description |
|------|---------|-------------|
| utf-8 | utf8, ascii | Unicode, no conversion |
| utf-16-le | utf16le, utf-16le | Unicode UTF-16 Little Endian |
| utf-16-be | utf16be, utf-16be | Unicode UTF-16 Big Endian |
| windows-1251 | cp1251 | Windows Cyrillic |
| koi8-r | koi8r | Russian Cyrillic (Unix/Linux) |
| koi8-u | koi8u | Ukrainian Cyrillic (Unix/Linux) |
| ibm866 | cp866, dos-866 | DOS Cyrillic |
| iso-8859-5 | iso88595, cyrillic | ISO Cyrillic |
| windows-1252 | cp1252 | Windows Western European |
| iso-8859-1 | iso88591, latin1 | Latin-1 Western European |
| iso-8859-15 | iso885915, latin9 | Latin-9 Western European (Euro) |
| windows-1250 | cp1250 | Windows Central European |
| iso-8859-2 | iso88592, latin2 | Latin-2 Central European |
| windows-1253 | cp1253 | Windows Greek |
| iso-8859-7 | iso88597, greek | ISO Greek |
| windows-1254 | cp1254 | Windows Turkish |
| iso-8859-9 | iso88599, latin5 | Latin-5 Turkish |
| windows-1255 | cp1255 | Windows Hebrew |
| windows-1256 | cp1256 | Windows Arabic |
| windows-1257 | cp1257 | Windows Baltic |
| windows-1258 | cp1258 | Windows Vietnamese |
| windows-874 | cp874, tis-620 | Windows Thai |
