{"id":42775161,"url":"https://github.com/dimitar-grigorov/mcp-file-tools","last_synced_at":"2026-04-02T11:57:09.247Z","repository":{"id":334462651,"uuid":"1141450752","full_name":"dimitar-grigorov/mcp-file-tools","owner":"dimitar-grigorov","description":"MCP server for file operations with non-UTF-8/Unicode encoding: Cyrillic, CP1251, CP1252, ISO-8859, KOI8 auto-detection","archived":false,"fork":false,"pushed_at":"2026-03-25T07:39:33.000Z","size":369,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-25T09:19:53.085Z","etag":null,"topics":["claude","cp1251","cp1252","cyrillic","delphi","golang","iso-8859","koi8","mcp","pascal","php","unicode","utf-8","utf8"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dimitar-grigorov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-24T21:37:42.000Z","updated_at":"2026-03-25T07:39:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dimitar-grigorov/mcp-file-tools","commit_stats":null,"previous_names":["dimitar-grigorov/mcp-file-tools"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/dimitar-grigorov/mcp-file-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimitar-grigorov%2Fmcp-file-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimitar-grigorov%2Fmcp-file-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimitar-grigorov%2Fmcp-file-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimitar-grigorov%2Fmcp-file-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dimitar-grigorov","download_url":"https://codeload.github.com/dimitar-grigorov/mcp-file-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimitar-grigorov%2Fmcp-file-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31305964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","cp1251","cp1252","cyrillic","delphi","golang","iso-8859","koi8","mcp","pascal","php","unicode","utf-8","utf8"],"created_at":"2026-01-29T22:05:39.697Z","updated_at":"2026-04-02T11:57:09.234Z","avatar_url":"https://github.com/dimitar-grigorov.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP File Tools\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/dimitar-grigorov/mcp-file-tools)](https://goreportcard.com/report/github.com/dimitar-grigorov/mcp-file-tools)\n[![Release](https://img.shields.io/github/v/release/dimitar-grigorov/mcp-file-tools)](https://github.com/dimitar-grigorov/mcp-file-tools/releases/latest)\n[![License: GPL-3.0](https://img.shields.io/github/license/dimitar-grigorov/mcp-file-tools)](LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/?search=mcp-file-tools)\n\nClaude sees `Настройки` — not `????` or `Íàñòðîéêè`.\n\nMCP server for file operations with non-UTF-8 encoding support. Auto-detects and converts 22 encodings (Cyrillic, Windows-125x, ISO-8859, KOI8, UTF-16) so AI assistants can read and write legacy files without corrupting data.\n\n**Perfect for:** Delphi/Pascal projects, legacy VB6 apps, old PHP/HTML sites, config files with non-UTF-8 text.\n\n## What It Does\n\nProvides 21 tools for file operations with automatic encoding conversion:\n- [`read_text_file`](TOOLS.md#read_text_file) - Read files with encoding auto-detection and conversion\n- [`read_multiple_files`](TOOLS.md#read_multiple_files) - Read multiple files concurrently with encoding support\n- [`write_file`](TOOLS.md#write_file) - Write files in specific encodings\n- [`edit_file`](TOOLS.md#edit_file) - Line-based edits with diff preview and whitespace-flexible matching\n- [`copy_file`](TOOLS.md#copy_file) - Copy a file to a new location\n- [`delete_file`](TOOLS.md#delete_file) - Delete a file\n- [`list_directory`](TOOLS.md#list_directory) - Browse directories with pattern filtering\n- [`tree`](TOOLS.md#tree) - Compact indented tree view (85% fewer tokens than JSON)\n- [`directory_tree`](TOOLS.md#directory_tree-deprecated) - Get recursive tree view as JSON (deprecated, use `tree`)\n- [`search_files`](TOOLS.md#search_files) - Recursively search for files matching glob patterns\n- [`grep_text_files`](TOOLS.md#grep_text_files) - Regex search in file contents with encoding support\n- [`detect_encoding`](TOOLS.md#detect_encoding) - Auto-detect file encoding with confidence score\n- [`convert_encoding`](TOOLS.md#convert_encoding) - Convert file between encodings\n- [`detect_line_endings`](TOOLS.md#detect_line_endings) - Detect line ending style (CRLF/LF/mixed)\n- [`change_line_endings`](TOOLS.md#change_line_endings) - Convert line endings to LF or CRLF\n- [`manage_bom`](TOOLS.md#manage_bom) - Detect, strip, or add Unicode BOM\n- [`list_encodings`](TOOLS.md#list_encodings) - Show all supported encodings\n- [`get_file_info`](TOOLS.md#get_file_info) - Get file/directory metadata\n- [`create_directory`](TOOLS.md#create_directory) - Create directories recursively (mkdir -p)\n- [`move_file`](TOOLS.md#move_file) - Move or rename files and directories\n- [`list_allowed_directories`](TOOLS.md#list_allowed_directories) - Show accessible directories\n\n**Supported encodings (22 total):**\n- **Unicode:** UTF-8, UTF-16 LE, UTF-16 BE (with BOM detection for UTF-16 and UTF-32)\n- **Cyrillic:** Windows-1251, KOI8-R, KOI8-U, CP866, ISO-8859-5\n- **Western European:** Windows-1252, ISO-8859-1, ISO-8859-15\n- **Central European:** Windows-1250, ISO-8859-2\n- **Greek:** Windows-1253, ISO-8859-7\n- **Turkish:** Windows-1254, ISO-8859-9\n- **Other:** Hebrew (1255), Arabic (1256), Baltic (1257), Vietnamese (1258), Thai (874)\n\nSee [TOOLS.md](TOOLS.md) for detailed parameters and examples.\n\n**Security:** All operations restricted to allowed directories only.\n\n## Installation\n\n### MCP Registry\n\nThis server is listed in the [Official MCP Registry](https://registry.modelcontextprotocol.io/?search=mcp-file-tools) for discovery.\n\n### Windows x64\n**Note:** Run these commands in **PowerShell**, not in CMD.\n\n```powershell\n# Download\nmkdir -Force \"$env:LOCALAPPDATA\\Programs\\mcp-file-tools\"\niwr \"https://github.com/dimitar-grigorov/mcp-file-tools/releases/latest/download/mcp-file-tools_windows_amd64.exe\" -OutFile \"$env:LOCALAPPDATA\\Programs\\mcp-file-tools\\mcp-file-tools.exe\"\n# Install with Claude Code + VSCode (allows access to D:\\Projects)\nclaude mcp add --scope user file-tools -- \"$env:LOCALAPPDATA\\Programs\\mcp-file-tools\\mcp-file-tools.exe\" \"D:\\Projects\"\n```\n\n### Linux x64\n\n```bash\n# Download\nmkdir -p ~/.local/bin\ncurl -L \"https://github.com/dimitar-grigorov/mcp-file-tools/releases/latest/download/mcp-file-tools_linux_amd64\" -o ~/.local/bin/mcp-file-tools\nchmod +x ~/.local/bin/mcp-file-tools\n# Install with Claude Code + VSCode (allows access to ~/Projects)\nclaude mcp add --scope user file-tools -- ~/.local/bin/mcp-file-tools ~/Projects\n```\n\n### macOS ARM64\n\n```bash\n# Download\nmkdir -p ~/.local/bin\ncurl -L \"https://github.com/dimitar-grigorov/mcp-file-tools/releases/latest/download/mcp-file-tools_darwin_arm64\" -o ~/.local/bin/mcp-file-tools\nchmod +x ~/.local/bin/mcp-file-tools\n# Install with Claude Code + VSCode (allows access to ~/Projects)\nclaude mcp add --scope user file-tools -- ~/.local/bin/mcp-file-tools ~/Projects\n```\n\n### Go Install (All Platforms)\n\n```bash\n# Install with Go (requires Go 1.23+)\ngo install github.com/dimitar-grigorov/mcp-file-tools/cmd/mcp-file-tools@latest\n# Add to Claude Code + VSCode (Linux/macOS)\nclaude mcp add --scope user file-tools -- $(go env GOPATH)/bin/mcp-file-tools ~/Projects\n```\n\n```powershell\n# Add to Claude Code + VSCode (Windows PowerShell)\nclaude mcp add --scope user file-tools -- \"$(go env GOPATH)\\bin\\mcp-file-tools.exe\" \"D:\\Projects\"\n```\n\n### Other Clients\n\nFor Claude Desktop, VSCode, or Cursor, use the downloaded binary path in your config:\n\n**Claude Desktop** (`%APPDATA%\\Claude\\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\nWindows:\n```json\n{\n  \"mcpServers\": {\n    \"file-tools\": {\n      \"command\": \"C:\\\\Users\\\\YOUR_NAME\\\\AppData\\\\Local\\\\Programs\\\\mcp-file-tools\\\\mcp-file-tools.exe\",\n      \"args\": [\"D:\\\\Projects\", \"C:\\\\Users\\\\YOUR_NAME\\\\Documents\"]\n    }\n  }\n}\n```\n\nmacOS / Linux:\n```json\n{\n  \"mcpServers\": {\n    \"file-tools\": {\n      \"command\": \"/Users/YOUR_NAME/.local/bin/mcp-file-tools\",\n      \"args\": [\"/Users/YOUR_NAME/Projects\", \"/Users/YOUR_NAME/Documents\"]\n    }\n  }\n}\n```\n\nThe `args` array specifies allowed directories the server can access. Add as many directories as you need.\n\n**VSCode / Cursor (Claude Code extension)**\n\nIf you already ran `claude mcp add --scope user` from the installation steps above, the server is already available in VSCode — no extra config needed.\n\nTo configure separately for VSCode only:\n```powershell\nclaude mcp add --scope user file-tools -- \"%LOCALAPPDATA%\\Programs\\mcp-file-tools\\mcp-file-tools.exe\" \"D:\\Projects\"\n```\n\nAlternatively, create a **per-project config** by adding `.mcp.json` to your project root:\n```json\n{\n  \"mcpServers\": {\n    \"file-tools\": {\n      \"type\": \"stdio\",\n      \"command\": \"C:\\\\Users\\\\YOUR_NAME\\\\AppData\\\\Local\\\\Programs\\\\mcp-file-tools\\\\mcp-file-tools.exe\",\n      \"args\": [\"D:\\\\Projects\", \"D:\\\\Other\\\\Directory\"]\n    }\n  }\n}\n```\n\n**Note:** The `type: \"stdio\"` field is required. The `args` array specifies allowed directories — the VSCode extension does not automatically add the workspace directory, so you must list all directories you want to access. To add more directories later, re-run the `claude mcp add` command with all directories listed (it overwrites the previous config).\n\n**OpenAI Codex CLI**\n\nCodex does not have an `mcp add` command -- you need to edit `~/.codex/config.toml` manually.\n\nWindows (PowerShell):\n```powershell\n# Download\nmkdir -Force \"$env:LOCALAPPDATA\\Programs\\mcp-file-tools\"\niwr \"https://github.com/dimitar-grigorov/mcp-file-tools/releases/latest/download/mcp-file-tools_windows_amd64.exe\" -OutFile \"$env:LOCALAPPDATA\\Programs\\mcp-file-tools\\mcp-file-tools.exe\"\n```\n\nThen add to `~/.codex/config.toml`:\n```toml\n[mcp_servers.file-tools]\ncommand = \"C:\\\\Users\\\\YOUR_NAME\\\\AppData\\\\Local\\\\Programs\\\\mcp-file-tools\\\\mcp-file-tools.exe\"\nargs = [\"D:\\\\Projects\"]\n```\n\n### Auto-approve All Tools (Claude Code)\n\nTo skip permission prompts for all file-tools commands, create `.claude/settings.local.json` in your project root:\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"Bash(ls *)\",\n      \"Bash(grep *)\",\n      \"Bash(sort *)\",\n      \"Bash(wc *)\",\n      \"Bash(find *)\",\n      \"Bash(echo *)\",\n      \"Grep\",\n      \"Glob\",\n      \"WebSearch\",\n      \"mcp__file-tools__read_text_file\",\n      \"mcp__file-tools__read_multiple_files\",\n      \"mcp__file-tools__write_file\",\n      \"mcp__file-tools__edit_file\",\n      \"mcp__file-tools__copy_file\",\n      \"mcp__file-tools__list_directory\",\n      \"mcp__file-tools__tree\",\n      \"mcp__file-tools__directory_tree\",\n      \"mcp__file-tools__search_files\",\n      \"mcp__file-tools__grep_text_files\",\n      \"mcp__file-tools__detect_encoding\",\n      \"mcp__file-tools__convert_encoding\",\n      \"mcp__file-tools__detect_line_endings\",\n      \"mcp__file-tools__change_line_endings\",\n      \"mcp__file-tools__manage_bom\",\n      \"mcp__file-tools__list_encodings\",\n      \"mcp__file-tools__get_file_info\",\n      \"mcp__file-tools__create_directory\",\n      \"mcp__file-tools__list_allowed_directories\",\n      \"mcp__file-tools__check_for_updates\"\n    ]\n  }\n}\n```\n\nThis auto-approves safe read-only and editing file-tools operations plus common shell commands and web search. Destructive operations (`delete_file`, `move_file`) and `WebFetch` are intentionally excluded — Claude will ask before using them. Adjust to your needs.\n\n### Update\n\nThe server checks for updates automatically and notifies you through tool responses when a newer version is available. To update:\n\n1. Close all Claude Code sessions (the binary is locked while running)\n2. Re-download the binary:\n\n```powershell\niwr \"https://github.com/dimitar-grigorov/mcp-file-tools/releases/latest/download/mcp-file-tools_windows_amd64.exe\" `\n    -OutFile \"$env:LOCALAPPDATA\\Programs\\mcp-file-tools\\mcp-file-tools.exe\"\n```\n\nTo disable update checks, set the environment variable `MCP_NO_UPDATE_CHECK=1`.\n\n### Verify \u0026 Uninstall\n\n```bash\n# Check if the server is configured\nclaude mcp list\n\n# Remove the server\nclaude mcp remove file-tools\n```\n\n## How to Use\n\nOnce installed, just ask Claude:\n- \"List all .pas files in this directory\"\n- \"Read config.ini and detect its encoding\"\n- \"Show all supported encodings\"\n- \"Read MainForm.dfm using CP1251 encoding\"\n\n**Security:** The server only accesses directories you explicitly allow:\n- **Automatic:** Claude Desktop/Code provide workspace directories automatically\n- **Manual:** Specify directories in config `args: [\"/path/to/project\"]`\n\n## Configuration\n\nThe server can be configured via environment variables:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `MCP_DEFAULT_ENCODING` | Default encoding for `write_file` when none specified | `cp1251` |\n| `MCP_MEMORY_THRESHOLD` | Memory threshold in bytes. Files smaller are loaded into memory for faster I/O; larger files use streaming. Also affects encoding detection mode. | `67108864` (64MB) |\n\nTo override, set environment variables in your config (Claude Desktop example):\n```json\n{\n  \"mcpServers\": {\n    \"file-tools\": {\n      \"command\": \"C:\\\\Users\\\\YOUR_NAME\\\\AppData\\\\Local\\\\Programs\\\\mcp-file-tools\\\\mcp-file-tools.exe\",\n      \"args\": [\"D:\\\\Projects\"],\n      \"env\": {\n        \"MCP_DEFAULT_ENCODING\": \"utf-8\"\n      }\n    }\n  }\n}\n```\n\n## Use Cases\n\n### Legacy Codebases\n\nMany legacy projects use non-UTF-8 encodings that AI assistants can't handle natively:\n\n- **Delphi/Pascal** (Windows-1251): Source files with Cyrillic UI text\n- **Visual Basic 6** (Windows-1252): Forms and config files with Western European characters\n- **Legacy PHP/HTML** (CP1251, ISO-8859-1): Web apps with localized content\n- **Old config files** (Various): INI, properties, registry files with legacy encodings\n\n**How it works:**\n```\nUser: Read config.ini and change the title to \"Настройки\"\nAssistant: [read_text_file with cp1251] → [modify UTF-8] → [write_file with cp1251]\n```\n\nThe original encoding is preserved - files remain compatible with legacy tools.\n\n## Development\n\n**Prerequisites:** Go 1.23+\n\n```bash\n# Run tests\ngo test ./...\n\n# Build\ngo build -o mcp-file-tools ./cmd/mcp-file-tools\n```\n\n### Debugging with MCP Inspector\n\n[MCP Inspector](https://github.com/modelcontextprotocol/inspector) provides a web UI for testing MCP servers.\n\n**Prerequisites:** Node.js v18+\n\n```bash\n# Run with allowed directory (required)\nnpx @modelcontextprotocol/inspector go run ./cmd/mcp-file-tools -- /path/to/allowed/dir\n\n# Or with built binary\nnpx @modelcontextprotocol/inspector ./mcp-file-tools.exe C:\\Projects\n```\n\nOpens a browser where you can view tools, call them with custom arguments, and inspect responses.\n\n### Manual Debugging\n\nRun the server with an allowed directory and send JSON-RPC commands via stdin:\n\n```bash\n# Specify allowed directory\ngo run ./cmd/mcp-file-tools /path/to/project\n```\n\nExample commands (paste into terminal):\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}\n{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"list_directory\",\"arguments\":{\"path\":\"/path/to/project\",\"pattern\":\"*.go\"}}}\n{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"read_text_file\",\"arguments\":{\"path\":\"/path/to/project/main.pas\",\"encoding\":\"cp1251\"}}}\n{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{\"name\":\"detect_encoding\",\"arguments\":{\"path\":\"/path/to/project/file.txt\"}}}\n```\n\n## License\n\nGPL-3.0 - see [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimitar-grigorov%2Fmcp-file-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdimitar-grigorov%2Fmcp-file-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimitar-grigorov%2Fmcp-file-tools/lists"}