MCP Tools

# MCP Tools [](https://cursor.com/install-mcp?name=mcp-files&config=JTdCJTIyY29tbWFuZCUyMiUzQSUyMm5weCUyMC15JTIwbWNwLWZpbGVzJTIyJTdE) [](https://www.npmjs.com/package/mcp-files) [](https://nodejs.org/) [](https://opensource.org/licenses/MIT) [](https://hub.docker.com/r/flesler/mcp-files) Enables agents to quickly find and edit code in a codebase with surgical precision. Find symbols, edit them everywhere. ## 📋 Table of Contents - [🚀 Quick Start](#-quick-start) - [🛠️ Available Tools](#️-available-tools) - [⚡ Surgical Code Editing: Surgical Precision](#-surgical-code-editing-surgical-precision) - [🎛️ Environment Variables](#️-environment-variables) - [🖥️ Server Usage](#️-server-usage) - [💻 CLI Usage](#-cli-usage) - [🏗️ Architecture](#️-architecture) - [🧪 Development](#-development) - [🛠️ Troubleshooting](#️-troubleshooting) - [📝 License](#-license) - [🔗 Links](#-links) ## 🚀 Quick Start ### Option 1: NPX (Recommended) Add this to `~/.cursor/mcp.json` for Cursor, `~/.config/claude_desktop_config.json` for Claude Desktop. ```json { "mcpServers": { "mcp-files": { "command": "npx", "args": ["-y", "mcp-files"] } } } ``` ### Option 2: Docker ```json { "mcpServers": { "mcp-files": { "command": "docker", "args": [ "run", "--rm", "-i", "flesler/mcp-files" ] } } } ``` ### Option 3: HTTP transport First run the server: ```bash TRANSPORT=http PORT=3000 npx mcp-files ``` Then: ```json { "mcpServers": { "mcp-files": { "type": "streamableHttp", "url": "http://localhost:3000/mcp" } } } ``` ## 🛠️ **Available Tools** | Tool | Description | Parameters | |------|-------------|------------| | `read_symbol` | Find and extract code blocks by symbol name(s) from files. Supports multiple symbols via array | `symbols` (string[]), `file_paths[]?`, `limit?`, `optimize?` | | `import_symbol` | Import and inspect JavaScript/TypeScript modules and their properties | `module_path`, `property?` | | `search_replace` | Search and replace with intelligent whitespace handling and automation-friendly multiple match resolution | `file_path`, `old_string`, `new_string`, `allow_multiple_matches?` | | `insert_text` | Insert/replace text at precise line ranges. Perfect for direct line operations from code citations (12:15:file.ts) and surgical edits in large files | `file_path`, `from_line`, `text`, `to_line` | | `os_notification` | Send OS notifications using native notification systems | `message`, `title?` | ## ⚡ **Surgical Code Editing: Surgical Precision** The combination of `read_symbol` + `insert_text` unlocks **revolutionary code editing capabilities** that transform how AI agents work with codebases. ### 🎯 **The Power Combo** **1. Symbol Discovery (`read_symbol`)** - Find ANY symbol(s) ANYWHERE in your codebase: ```typescript // Find single function/class/interface anywhere in repo read_symbol({symbols: ["generateApiKey"]}) // → Returns: exact location (lines 45-52 in src/auth/tokens.ts) // Find multiple symbols at once read_symbol({symbols: ["User", "UserService", "UserInterface"]}) // → Returns: all matching symbols with their locations // Optimize code for AI context (strips comments, normalizes indentation) read_symbol({symbols: ["complexFunction"], optimize: true}) // → Returns: clean, tab-indented code without comments for AI processing ``` **2. Surgical Editing (`insert_text`)** - Make precise modifications using exact line ranges: ```typescript // Replace specific lines with surgical precision insert_text(file: "src/auth/tokens.ts", from_line: 45, to_line: 52, text: "improved implementation") // Insert new code without disruption insert_text(file: "src/auth/tokens.ts", from_line: 45, text: "// Added security enhancement") ``` ### 🚀 **Superpowers Unlocked** **🔍 Cross-Codebase Intelligence** - Find any symbol across entire repositories instantly - No manual searching through files and folders - Perfect accuracy even in massive codebases **✂️ Precision Surgery** - Edit exact functions, classes, or code blocks - Replace implementations without affecting surrounding code - Insert enhancements at perfect locations **🎛️ Zero-Error Refactoring** - Update function signatures everywhere they exist - Modify APIs across all files simultaneously - Fix bugs with surgical precision across entire codebase ### 💡 **Real-World Magic** ```bash # Find and enhance any function read_symbol("validateEmail") → lines 23-35 in utils/validation.ts insert_text(from_line: 23, to_line: 35, text: "enhanced validation with regex") # Add documentation to any symbol read_symbol("processPayment") → line 87 in payment/processor.ts insert_text(from_line: 87, text: "/** Secure payment processing with fraud detection */") # Fix bugs anywhere in codebase read_symbol("parseUserInput") → lines 156-162 in input/parser.ts insert_text(from_line: 156, to_line: 162, text: "sanitized parsing logic") ``` **This transforms AI from "helpful assistant" to "surgical code surgeon"** 🦾 ## 🎛️ Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` | | `PORT` | `4657` | HTTP server port (when `TRANSPORT=http`) | | `DEBUG` | `false` | Enable debug mode and `utils_debug` tool | ## 🖥️ Server Usage You can either install and use `mcp-files` or `npx mcp-files`. ```bash # Show help mcp-files --help # Default: stdio transport mcp-files # HTTP transport TRANSPORT=http mcp-files TRANSPORT=http PORT=8080 mcp-files # With debug mode DEBUG=true mcp-files ``` ## 💻 CLI Usage All tools can be used directly from the command line: ```bash # Find single symbol in code (specific file) mcp-files read_symbol "MyInterface" src/types.ts # Find multiple symbols at once (comma-separated) mcp-files read_symbol "User,UserService,UserInterface" src/ # Find symbol in current directory (default) mcp-files read_symbol "MyInterface" # Use wildcards for pattern matching mcp-files read_symbol "get*,User*" src/ # Inspect imports mcp-files import_symbol lodash get # Replace text with smart whitespace handling mcp-files replace_text config.json "old_value" "new_value" # Send notifications mcp-files os_notification "Task completed" ``` ## 🏗️ Architecture - **Type-safe tools** with Zod validation - **Self-contained modules** in `src/tools/` - **Cross-platform support** (Linux, macOS, Windows, WSL) - **Performance optimized** with memoization - **Clear error handling** with descriptive messages ## 🧪 Development ```bash # Install dependencies npm install # Build npm run build # Development mode npm run dev # Lint npm run lint:full # Test npm run ts test/index.test.ts # CLI testing node dist/index.js read_symbol "functionName" file.ts # Multiple symbols (comma-separated in CLI) node dist/index.js read_symbol "func1,func2,Class*" file.ts # Or search current directory node dist/index.js read_symbol "functionName" ``` ## 🧹 **Code Optimization** The `read_symbol` tool includes an `optimize` parameter that cleans up code for AI processing: ### **What it does:** - **Strips comments**: Removes `//`, `/* */`, and `/** */` comments - **Collapses newlines**: Multiple consecutive newlines become single newlines - **Normalizes indentation**: Converts spaces to tabs (detects indentation token size automatically) - **Removes base indentation**: Eliminates common leading whitespace ### **Usage:** ```typescript // MCP mode - explicit control read_symbol({symbols: ["MyClass"], optimize: true}) // optimized read_symbol({symbols: ["MyClass"], optimize: false}) // raw code (default) // CLI mode - always optimized mcp-files read_symbol "MyClass" src/ ``` **Perfect for:** Reducing token count in AI context windows while preserving code structure and readability. ## 🛠️ Troubleshooting ### **Requirements** - **Node.js ≥20** - This package requires Node.js version 20 or higher ### **Common Issues** **ERR_MODULE_NOT_FOUND when running `npx mcp-files`** - **Problem**: Error like `Cannot find module '@modelcontextprotocol/sdk/dist/esm/server/index.js'` when running `npx mcp-files` - **Cause**: Corrupt or incomplete npx cache preventing proper dependency resolution - **Solution**: Clear the npx cache and try again: ```bash npx clear-npx-cache npx mcp-files ``` - **Note**: This issue can occur on both Node.js v20 and v22, and the cache clear resolves it **Tools not showing up in MCP client:** - Verify Node.js version is 20 or higher - Try restarting your MCP client after configuration changes **File operations failing:** - Ensure proper file permissions for the files you're trying to read/modify - Use absolute paths when possible for better reliability - Check that the target files exist and are accessible ## 📝 License MIT - see [LICENSE](LICENSE) file. ## 🔗 Links - 📦 **[NPM Package](https://www.npmjs.com/package/mcp-files)** - 🐙 **[GitHub Repository](https://github.com/flesler/mcp-files)** - 🐛 **[Report Issues](https://github.com/flesler/mcp-files/issues)** - 📚 **[MCP Specification](https://modelcontextprotocol.io/)** --- **Built for AI agents** 🤖