Skip to main content
Glama
Sign In
MCP Tools

MCP Tools

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

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!

Inputs: file_path (required), from_line (required), text (required), to_line.

os_notificationB
Read-only

Send OS notifications using native notification systems.

Inputs: message (required), title.

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

Inputs: symbol (required), file_paths, limit.

Tool Schema Changelog

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

Loading tool schema changelogโ€ฆ

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.7/5.0

    Scored across 3 tools

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    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.
      77 npm
      4
      Apache 2.0

    • reference-mcp

      mark-burg
      A
      license
      A
      quality
      D
      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
      A
      license
      A
      quality
      C
      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
      MIT

    • MCP Codebase Server

      DmitriyOT
      A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for semantic codebase navigation that builds an AST index of symbols, imports, and exports, providing AI agents with tools to search, explore, and understand code.
      MIT