Skip to main content
Glama
OrionPotter

MCP Files

by OrionPotter
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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(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 (read_symbol) - 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 (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 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 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 🤖

Available Tools

3 tools
insert_textA

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 (must use optimize: false!) to edit any symbol anywhere without knowing its file or line range!

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYesPath to the file
from_lineYesStarting line number (1-based)
textYesText to insert
to_lineNoReplace up to this line number (1-based, inclusive). If omitted only inserts

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate this is a write operation (readOnlyHint: false) and not open-world (openWorldHint: false), which the description aligns with by describing text insertion/replacement. The description adds valuable context about efficiency for large files and the need to combine with 'read_symbol' for symbol editing, going beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by specific usage scenarios and a tip. Every sentence adds value without redundancy, making it efficient and well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema, the description provides good contextual completeness by explaining use cases, efficiency considerations, and integration with sibling tools. It could be slightly improved by mentioning error handling or confirmation of changes, but it covers the essential context given the annotations and schema richness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all parameters. The description does not add any parameter-specific details beyond what's in the schema, such as explaining the relationship between 'from_line' and 'to_line' or providing examples. Baseline 3 is appropriate when schema coverage is complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Insert or replace text') on a specific resource ('at precise line ranges in files'), distinguishing it from sibling tools like 'os_notification' and 'read_symbol' which serve different purposes. It explicitly mentions the target use case for line-number operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool ('Ideal for direct line-number operations... and large files where context-heavy editing is inefficient') and when to combine it with alternatives ('Combine with read_symbol... to edit any symbol anywhere without knowing its file or line range'), including a specific tip about using 'optimize: false'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

os_notificationB
Read-only

Send OS notifications using native notification systems.

ParametersJSON Schema
NameRequiredDescriptionDefault
messageYesThe notification message to display
titleNoDefaults to current project, generally omit

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=true and openWorldHint=false, suggesting a safe, non-destructive operation with limited scope. The description adds context by specifying 'native notification systems,' implying platform-specific behavior, but doesn't detail aspects like permission requirements, notification duration, or user interaction effects beyond what annotations cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words, clearly stating the tool's function. It's appropriately sized and front-loaded, making it easy to understand at a glance without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (2 parameters, no output schema) and annotations covering safety, the description is minimally adequate. However, it lacks details on behavioral outcomes (e.g., how notifications appear or are dismissed) and doesn't compensate for the absence of an output schema, leaving gaps in understanding the tool's full impact.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with clear documentation for both parameters ('message' and 'title'). The description doesn't add meaning beyond the schema, such as examples or edge cases, but the schema adequately defines parameters, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Send') and target ('OS notifications using native notification systems'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'insert_text' or 'read_symbol', which are unrelated to notifications, so it lacks explicit sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives or in what context it's appropriate. There's no mention of prerequisites, limitations, or scenarios where this tool is preferred over other notification methods, leaving usage entirely implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_symbolA
Read-only

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

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolsYesSymbol name(s) to find (functions, classes, types, etc.), case-sensitive, supports * for wildcard
file_pathsNoFile paths to search (supports relative and glob). Defaults to "." (current directory). IMPORTANT: Be specific with paths when possible, minimize broad patterns like "node_modules/**" to avoid mismatches
limitNoMaximum number of results to return. Defaults to 5
optimizeNoUnless explicitly false, this tool will strip comments and spacing to preserve AI's context window, omit unless you REALLY it unchanged (default: true)

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=true and openWorldHint=false, confirming this is a safe read operation with limited scope. The description adds value by mentioning streaming with concurrency control for performance and the ability to handle multiple file formats, but it does not disclose details like rate limits, authentication needs, or error handling beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by supporting details in a second sentence. It avoids unnecessary elaboration, though the second sentence could be slightly more concise by integrating performance notes more tightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 parameters, no output schema) and rich annotations, the description is adequate but lacks details on return values, error cases, or examples of symbol extraction. It covers the what and how but not the full behavioral context needed for optimal agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all four parameters. The description does not add specific meaning or usage details beyond the schema, such as explaining wildcard patterns in 'symbols' or performance implications of 'optimize'. Baseline 3 is appropriate as the schema handles the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Find and extract symbol block by name from files') and resource ('files'), with explicit mention of supported file formats (TS, JS, GraphQL, CSS, etc.). It distinguishes itself from sibling tools like 'insert_text' and 'os_notification' by focusing on symbol extraction rather than text insertion or OS notifications.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool—for extracting symbol blocks from various file formats using streaming with concurrency control. However, it does not explicitly state when not to use it or name alternatives, such as using 'insert_text' for adding content instead of reading it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updates
    • First observedinsert_text
    • First observedos_notification
    • First observedread_symbol
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: insert_text handles line-based file editing, os_notification sends OS notifications, and read_symbol extracts symbol blocks from files. There is no overlap in functionality, making tool selection straightforward for an agent.

Naming Consistency4/5

The naming follows a consistent verb_noun pattern (insert_text, read_symbol, os_notification), which is predictable and readable. The slight deviation is that os_notification uses an underscore but starts with 'os' as a prefix, which is still coherent with the overall style.

Tool Count3/5

With only 3 tools, the server feels thin for a general-purpose 'MCP Files' domain, as it lacks basic file operations like reading, writing, or deleting entire files. However, the tools are specialized and focused, so it's borderline but not severely mismatched.

Completeness2/5

The tool set is significantly incomplete for a files-oriented server, missing core operations such as reading file contents, writing files, deleting files, or listing directories. While the provided tools are useful for specific tasks, agents will face gaps in handling common file workflows.

Resources

Related MCP Connectors

Appeared in Searches