-
securityA
license-
qualityAn MCP server that bridges AI agents with GUI automation capabilities, allowing them to control mouse, keyboard, windows, and take screenshots to interact with desktop applications.
Last updated -
9
MIT License
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_symbolwith wildcard support and specific file pathsSurgical text editing: Insert or replace text at specific line ranges using
insert_textfor precise modifications without manual file navigationSend OS notifications: Display native system notifications with custom messages and optional titles to alert users of progress or events
Advanced code intelligence: Combine
read_symbolwithinsert_textfor cross-codebase operations, enabling zero-error refactoring and targeted edits with streaming performance optimization and concurrency control
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.
MCP Tools
Enables agents to quickly find and edit code in a codebase with surgical precision. Find symbols, edit them everywhere.
📋 Table of Contents
🚀 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 |
| Find and extract code blocks by symbol name(s) from files. Supports multiple symbols via array |
(string[]),
,
,
|
| Import and inspect JavaScript/TypeScript modules and their properties |
,
|
| Search and replace with intelligent whitespace handling and automation-friendly multiple match resolution |
,
,
,
|
| 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 |
,
,
,
|
| Send OS notifications using native notification systems |
,
|
⚡ 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 mode:
or
|
|
| HTTP server port (when
) |
|
| Enable debug mode and
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/** */commentsCollapses 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 runningnpx mcp-filesCause: Corrupt or incomplete npx cache preventing proper dependency resolution
Solution: Clear the npx cache and try again:
npx clear-npx-cache npx mcp-filesNote: 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 🤖
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A comprehensive MCP server providing tools for AI agents to interact with code, including reading symbols, importing modules, replacing text, and sending OS notifications.
Related MCP Servers
- AsecurityFlicenseAqualityAn MCP server that supercharges AI assistants with powerful tools for software development, enabling research, planning, code generation, and project scaffolding through natural language interaction.Last updated -112779
- -securityFlicense-qualityA MCP server that allows AI assistants to interact with the browser, including getting page content as markdown, modifying page styles, and searching browser history.Last updated -82
- AsecurityAlicenseAqualityA powerful MCP server that provides interactive user feedback and command execution capabilities for AI-assisted development, featuring a graphical interface with text and image support.Last updated -139MIT License