Overview

MCP Server (mcp-files) is a lightweight Model Context Protocol (MCP) server that enables precise, programmatic edits across one or multiple repositories. It exposes a compact set of tools that let automated agents and developer workflows locate symbols (functions, classes, interfaces) anywhere in a codebase and perform surgical changes at exact line ranges — enabling safe refactors, API signature updates, and targeted fixes without manual search-and-replace.

Because it reports exact file paths and line ranges for symbols and supports line-accurate insert/replace operations, MCP Server is well suited for large projects and multi-repo automation where accuracy is critical. It supports both stdio (default) and HTTP transports, and can be run via npx, Docker, or as a local daemon.

Repo: https://github.com/flesler/mcp-files Tags: files-storage

Features

Symbol discovery across repositories: find functions, classes, types, interfaces, and properties with exact locations.
Precise edits: replace or insert text at exact line ranges to avoid collateral changes.
Module inspection: import and inspect JS/TS modules and their exported properties.
Intelligent search-and-replace: handles whitespace and offers options for multiple match resolution.
Multiple transports: stdio (default) and streamable HTTP for integration with UIs or remote agents.
Small footprint: runnable via npx or Docker; easy to integrate with agent platforms (Cursor, Claude Desktop, etc.).

Installation / Configuration

Quick start (npx — recommended):

# Run the server locally (stdio transport)
npx mcp-files

Docker:

docker run --rm -i flesler/mcp-files

HTTP transport (start server, then connect over HTTP):

# Start server in HTTP mode on port 3000
TRANSPORT=http PORT=3000 npx mcp-files

Example client configuration (Cursor / agent config):

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

HTTP client wiring:

{
  "mcpServers": {
    "mcp-files": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Available Tools

The server exposes a small set of high-level operations designed for automation. Each tool accepts JSON-serializable parameters and returns rich metadata (paths, exact line ranges, content snippets).

Tool	Purpose	Key parameters
read_symbol	Locate and extract code blocks by symbol name(s)	symbols (string or string[]), file_paths?, limit?, optimize?
import_symbol	Load a JS/TS module and inspect its exports/properties	module_path, property?
search_replace	Intelligent search-and-replace across files	file_path, old_string, new_string, allow_multiple_matches?
insert_text	Insert or replace text using exact line numbers	file_path, from_line, to_line?, text
os_notification	Send an OS-level notification (helper)	message, title?

Notes:

read_symbol returns exact file path plus start/end line numbers and optional “optimized” content (comments removed, normalized indentation) for easier AI consumption.
insert_text edits are atomic at the file/line level and are intended to be used with the locations returned by read_symbol.

Use Cases

Zero-error API refactor: find a function signature and replace its implementation everywhere it appears, then update all callers with matching signatures. Example:
1. read_symbol({ symbols: [“calculateTotal”] })
2. Use returned locations to insert_text({ file_path, from_line, to_line, text: “new implementation” })
Cross-repository fixes: locate a buggy helper in multiple repos and surgically replace its body without altering surrounding documentation or formatting.
Documentation insertion: add or replace JSDoc/comments for a class or method by inserting text at the reported symbol line.
Module inspection: import_symbol to enumerate exported helpers of a module before deciding what to change.

Concrete example:

# Find a symbol
{ "tool": "read_symbol", "params": { "symbols": ["validateEmail"] } }

# Replace its implementation (lines 23–35)
{ "tool": "insert_text", "params": { "file_path": "src/utils/validation.ts", "from_line": 23, "to_line": 35, "text": "export function validateEmail(email) { /* new logic */ }" } }

Server Usage & Environment

Run the server with defaults (stdio transport):

mcp-files
# or
npx mcp-files

Run in HTTP mode:

TRANSPORT=http PORT=8080 npx mcp-files

Environment variables:

Variable	Default	Purpose
TRANSPORT	stdio	Transport mode: “stdio” or “http”
PORT	4657	HTTP port when TRANSPORT=http
DEBUG	false	Enable debug logging and debug tools

Integration Tips

Always call read_symbol before modifying files to get precise line ranges.
Use optimize=true on read_symbol when feeding code into an LLM to reduce noise (comments removed, normalized whitespace).
When running in CI/automation, prefer HTTP mode for simpler orchestration and process isolation.
For multi-match replace operations, use allow_multiple_matches? with caution — prefer programmatic resolution to avoid unintended edits.

Troubleshooting

If symbols are not found, verify repository root and that files are readable by the running process.
Use DEBUG=true to enable additional logs when diagnosing matching or editing issues.
For large repositories, limit read_symbol results with limit or constrain file_paths to speed up lookup.

License: MIT

For source, issues, and contributions: https://github.com/flesler/mcp-files

MCP Server: Precision Cross-Repository Symbol Editing