What can you do with this server?

The MCP Tools server enables AI agents to perform surgical code editing and system notifications with precision across codebases. * Find and extract code symbols: Search for functions, classes, types, and other symbols across multiple file formats (TypeScript, JavaScript, GraphQL, CSS, and other brace-based languages) using read_symbol with wildcard support and specific file paths * Surgical text editing: Insert or replace text at specific line ranges using insert_text for precise modifications without manual file navigation * Send OS notifications: Display native system notifications with custom messages and optional titles to alert users of progress or events * Advanced code intelligence: Combine read_symbol with insert_text for cross-codebase operations, enabling zero-error refactoring and targeted edits with streaming performance optimization and concurrency control

Which integrations are available for this server?

Offers tools to find and extract JavaScript code blocks by symbol name and import/inspect JavaScript modules and their properties. Enables inspection of Lodash modules and properties through the import_symbol tool, allowing AI agents to analyze and utilize Lodash functionality. Built for Node.js environment, providing programmatic file operations, module inspection, and OS notifications that leverage Node.js capabilities. Provides tools for finding and extracting TypeScript code blocks by symbol name and importing/inspecting TypeScript modules and their properties.

How do I use MCP Tools?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Tools find the validateEmail function and show me its code" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Tools

Install MCP Server npm version Node.js License: MIT Docker

Enables agents to quickly find and edit code in a codebase with surgical precision. Find symbols, edit them everywhere.

📋 Table of Contents

Related MCP server: Vibe Coder MCP

🚀 Quick Start

Option 1: NPX (Recommended)

Add this to ~/.cursor/mcp.json for Cursor, ~/.config/claude_desktop_config.json for Claude Desktop.

{
  "mcpServers": {
    "mcp-files": {
      "command": "npx",
      "args": ["-y", "mcp-files"]
    }
  }
}

Option 2: Docker

{
  "mcpServers": {
    "mcp-files": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "flesler/mcp-files"
      ]
    }
  }
}

Option 3: HTTP transport

First run the server:

TRANSPORT=http PORT=3000 npx mcp-files

Then:

{
  "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 ( - Find ANY symbol(s) ANYWHERE in your codebase:

// 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 ( - Make precise modifications using exact line ranges:

// 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

# 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.

# 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:

# 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

# 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:

// 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

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:
```
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 file.

🔗 Links

Built for AI agents 🤖

MCP Tools

MCP Tools

📋 Table of Contents

🚀 Quick Start

Option 1: NPX (Recommended)

Option 2: Docker

Option 3: HTTP transport

🛠️ Available Tools

⚡ Surgical Code Editing: Surgical Precision

🎯 The Power Combo

🚀 Superpowers Unlocked

💡 Real-World Magic

🎛️ Environment Variables

🖥️ Server Usage

💻 CLI Usage

🏗️ Architecture

🧪 Development

🧹 Code Optimization

What it does:

Usage:

🛠️ Troubleshooting

Requirements

Common Issues

📝 License

🔗 Links

Resources

Tools

Latest Blog Posts

MCP directory API