Files

Name: Files
Author: flesler

@flesler

About Files

⚡ Surgical Code Editing: Superhuman Precision

#mcp #cursor #claude #model-context-protocol #code-analysis #symbol-search #text-replacement #import-inspection #notifications #llm #tools #files

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

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

Tools

Find and extract symbol block by name from files, supports a lot of file formats (like TS, JS, JSON, GraphQL and most that use braces for blocks). Uses streaming with concurrency control for better performance

Search and replace with intelligent whitespace handling and automation-friendly multiple match resolution. Tries exact match first, falls back to flexible whitespace matching only when no matches found.

Insert or replace text at precise line ranges in files - Ideal for direct line-number operations (from code citations like 12:15:file.ts) and large files where context-heavy editing is inefficient. - TIP: Combine with read_symbol to edit any symbol anywhere without knowing its file or line range!

Send OS notifications using native notification systems.

Overview

What is Files?

Files is an MCP server that provides file-oriented tools for AI agents like Cursor. It supports reading symbols from code, performing search-and-replace, inserting text at precise line ranges, inspecting JavaScript/TypeScript modules, and sending OS notifications.

How to use Files?

Install and run via npx mcp-files or as a Docker container. Configure the MCP client (e.g., Cursor or Claude Desktop) with a JSON entry pointing to npx -y mcp-files. Alternatively use HTTP transport by setting the environment variable TRANSPORT=http. Tools can also be invoked directly from the command line, e.g., mcp-files read_symbol "MySymbol" src/file.ts.

Key features of Files

Find code symbols anywhere in the codebase with read_symbol.
Perform intelligent search-and-replace with search_replace.
Insert or replace text at exact line ranges with insert_text.
Inspect JavaScript/TypeScript modules and their properties.
Send native OS notifications with os_notification.
Supports both stdio and HTTP transport modes.
Requires Node.js 20 or higher.

Use cases of Files

Locate and modify a specific function across large codebases.
Replace deprecated implementations with surgical precision.
Insert documentation or comments at exact code locations.
Import and inspect module exports for dependency analysis.

FAQ from Files

What runtime does Files require?

Node.js version 20 or higher is required.

How do I clear the npx cache if tools don't load?

Run npx clear-npx-cache followed by npx mcp-files to resolve ERR_MODULE_NOT_FOUND errors.

Can Files be used over HTTP?

Yes, set the environment variable TRANSPORT=http and optionally PORT (default 4657) to expose an HTTP server.

Which transports does Files support?

It supports stdio (default) and HTTP transport modes.

How do I see all available tools and parameters?

The README lists tools such as read_symbol, import_symbol, search_replace, insert_text, and os_notification with their parameters. Running mcp-files --help also shows usage.