Skip to main content
Glama

MCP Tools

by flesler
npmGitHub
TypeScript
MIT License
432
3
  • Linux
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

MCP Tools

Enables agents to quickly find and edit code in a codebase with surgical precision. Find symbols, edit them everywhere.

📋 Table of Contents

🚀 Quick Start

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

ToolDescriptionParameters
read_symbolFind and extract code blocks by symbol name(s) from files. Supports multiple symbols via arraysymbols (string[]), file_paths[]?, limit?, optimize?
import_symbolImport and inspect JavaScript/TypeScript modules and their propertiesmodule_path, property?
search_replaceSearch and replace with intelligent whitespace handling and automation-friendly multiple match resolutionfile_path, old_string, new_string, allow_multiple_matches?
insert_textInsert/replace text at precise line ranges. Perfect for direct line operations from code citations (12:15.ts) and surgical edits in large filesfile_path, from_line, text, to_line
os_notificationSend OS notifications using native notification systemsmessage, 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

VariableDefaultDescription
TRANSPORTstdioTransport mode: stdio or http
PORT4657HTTP server port (when TRANSPORT=http)
DEBUGfalseEnable 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.

Built for AI agents 🤖

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

A comprehensive MCP server providing tools for AI agents to interact with code, including reading symbols, importing modules, replacing text, and sending OS notifications.

  1. 📋 Table of Contents
    1. 🚀 Quick Start
      1. Option 1: NPX (Recommended)
      2. Option 2: Docker
      3. Option 3: HTTP transport
    2. 🛠️ Available Tools
      1. ⚡ Surgical Code Editing: Surgical Precision
        1. 🎯 The Power Combo
        2. 🚀 Superpowers Unlocked
        3. 💡 Real-World Magic
      2. 🎛️ Environment Variables
        1. 🖥️ Server Usage
          1. 💻 CLI Usage
            1. 🏗️ Architecture
              1. 🧪 Development
                1. 🧹 Code Optimization
                  1. What it does:
                  2. Usage:
                2. 🛠️ Troubleshooting
                  1. Requirements
                  2. Common Issues
                3. 📝 License
                  1. 🔗 Links

                    Related MCP Servers

                    • PyMCPAutoGUI

                      kitfactory
                      -
                      security
                      A
                      license
                      -
                      quality
                      An MCP server that bridges AI agents with GUI automation capabilities, allowing them to control mouse, keyboard, windows, and take screenshots to interact with desktop applications.
                      Last updated -
                      9
                      MIT License
                      • Apple
                      • Linux

                    • Vibe Coder MCP

                      freshtechbro
                      A
                      security
                      F
                      license
                      A
                      quality
                      An MCP server that supercharges AI assistants with powerful tools for software development, enabling research, planning, code generation, and project scaffolding through natural language interaction.
                      Last updated -
                      11
                      39
                      78
                      • Linux
                      • Apple

                    • browser-mcp

                      djyde
                      -
                      security
                      F
                      license
                      -
                      quality
                      A MCP server that allows AI assistants to interact with the browser, including getting page content as markdown, modifying page styles, and searching browser history.
                      Last updated -
                      82

                    • Interactive Feedback MCP

                      duolabmeng6
                      A
                      security
                      A
                      license
                      A
                      quality
                      A powerful MCP server that provides interactive user feedback and command execution capabilities for AI-assisted development, featuring a graphical interface with text and image support.
                      Last updated -
                      1
                      39
                      MIT License

                    View all related MCP servers

                    New MCP Servers

                    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-tools'

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