Skip to main content
Glama
OrionPotter

MCP Files

by OrionPotter
OverviewSchemaRelated ServersScoreDiscussions
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 🤖

Install Server
A
license - permissive license
A
quality
-
maintenance - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Connectors

  • ref-tools-mcp

    Token-efficient search for coding agents over public and private documentation.

  • Umtri

    Give your AI agent a persistent map of your project's structure, dependencies, and bugs.

  • vibsync

    One shared brain for your AI coding agents: team memory, agent Q&A, tasks, and file claims.

View all MCP Connectors

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/OrionPotter/flesler-mcp-tools'

If you have feedback or need assistance with the MCP directory API, please join our Discord server