Skip to content

flesler/mcp-files

Repository files navigation

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

πŸš€ 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 from files symbol, file_paths[]?, limit?
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 ANYWHERE in your codebase:

// Find function/class/interface anywhere in repo
read_symbol("generateApiKey")
// β†’ Returns: exact location (lines 45-52 in src/auth/tokens.ts)

2. Surgical Editing (insert_text) - 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 symbol in code (specific file)
mcp-files read_symbol "MyInterface" src/types.ts

# Find symbol in current directory (default)
mcp-files read_symbol "MyInterface"

# 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

# Or search current directory
node dist/index.js read_symbol "functionName"

πŸ› οΈ 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:
    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 πŸ€–

About

A comprehensive MCP server providing helpful tools for AI agents like Cursor

Resources

License

Stars

Watchers

Forks

Packages

No packages published