Skip to main content
Glama
flesler

MCP Tools

by flesler
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

Related MCP server: reference-mcp

🚀 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 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 readOnlyHint=false and openWorldHint=false, which the description aligns with by describing a write operation ('insert or replace text'). The description adds valuable behavioral context beyond annotations, explaining the tool is designed for line-number operations and large files, and suggesting a complementary tool (read_symbol) for symbol-based editing. No contradictions with annotations exist.

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 highly concise and well-structured with three sentences that each serve a distinct purpose: stating the core function, providing usage context, and offering a practical tip. There is no wasted text, and information is front-loaded effectively.

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?

Given the tool's complexity (file editing with line ranges), the description provides good contextual completeness despite no output schema. It explains the tool's purpose, ideal use cases, and how to combine it with another tool. However, it doesn't detail error conditions or the exact behavior when to_line is omitted, leaving minor gaps.

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?

With 100% schema description coverage, the input schema already fully documents all parameters. The description adds minimal parameter semantics beyond the schema, mentioning 'line ranges' and 'line-number operations' which are implied by the parameter names. It doesn't provide additional syntax or format details, so the baseline score of 3 is appropriate.

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 tool's purpose with specific verbs ('insert or replace text') and resources ('at precise line ranges in files'), distinguishing it from sibling tools like os_notification and read_symbol. It explicitly mentions the target resource (files) and the precise nature of the operation (line-number based editing).

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 use alternatives ('Combine with read_symbol to edit any symbol anywhere without knowing its file or line range'). It clearly differentiates from sibling tools and offers practical usage scenarios.

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
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
symbolYesSymbol name to find (functions, classes, types, etc.), case-sensitive, supports * for wildcard

TDQS

A4/5.0
Behavior4/5

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

Annotations provide readOnlyHint=true and openWorldHint=false, indicating a safe, bounded operation. The description adds valuable context beyond annotations by mentioning streaming with concurrency control for performance, which helps the agent understand execution behavior, though it lacks details on error handling or output format.

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 supporting details in a second sentence. Both sentences earn their place by clarifying functionality and performance, with no wasted words or redundancy.

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?

Given the tool's moderate complexity, annotations cover safety, and schema fully describes inputs, the description is mostly complete. However, the lack of an output schema means the description could better explain return values or error cases, leaving a minor gap in contextual understanding.

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 parameters like 'file_paths', 'limit', and 'symbol'. The description adds minimal semantics by noting support for many file formats and performance features, but it does not significantly enhance parameter understanding beyond the schema.

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 tool's purpose with a specific verb ('Find and extract') and resource ('symbol block by name from files'), and distinguishes it from siblings like 'insert_text' and 'os_notification' by focusing on read-only symbol extraction rather than insertion or system notifications. It also specifies the supported file formats, adding precision.

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

Usage Guidelines3/5

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

The description implies usage for extracting symbols from files in various formats, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. No sibling-specific guidance is given, leaving the agent to infer context from tool names alone.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: insert_text for line-based file editing, os_notification for system alerts, and read_symbol for symbol extraction. There is no overlap in functionality, making tool selection straightforward for an agent.

Naming Consistency5/5

All tool names follow a consistent snake_case pattern with a verb_noun structure (insert_text, os_notification, read_symbol). This uniformity enhances readability and predictability across the tool set.

Tool Count3/5

With only 3 tools, the set feels thin for a general-purpose 'MCP Tools' server, potentially lacking coverage for common operations like file reading or deletion. However, the tools are well-defined, so it's borderline but not severely mismatched.

Completeness2/5

The tool set has significant gaps for a file and system operations domain: there is no tool for reading file contents (only symbol extraction), deleting files, or basic file management. This incompleteness will likely cause agent failures in broader workflows.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Related MCP Connectors

Related MCP Servers

  • codeweave-mcp

    semihkayan
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that gives AI agents structured code understanding and precise code intelligence via local indexing of AST, call graphs, and semantic search.
    76
    4
    Apache 2.0

  • reference-mcp

    mark-burg
    A
    license
    A
    quality
    B
    maintenance
    An MCP server that helps AI agents comprehend a codebase by providing tools for navigating, searching, and understanding code structure and history.
    10
    MIT

  • better-mcp

    erquier
    F
    license
    A
    quality
    B
    maintenance
    A universal MCP server that provides AI agents with structured tools for filesystem, database, shell, and git operations, enabling seamless interaction with projects.
    19

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/flesler/mcp-files'

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