MCP Symbol Edit

Status: Under development.

Symbol-level code editing MCP server. Browse, read, edit, add, and delete code symbols (functions, classes, variables) using tree-sitter parsing instead of text-based string matching.

Why This Exists

Claude Code and other agentic coding tools use text-based editing where you must provide exact text to replace, including all whitespace and indentation. This is fragile, and inefficient. MCP Symbol Edit operates on parsed symbols instead, making edits more reliable and context-efficient.

Installation

Ensure you have uv installed.

uv --version

Install uv if you haven't already.

• Linux

  curl -LsSf https://astral.sh/uv/install.sh | sh

• macOS

  brew install uv

• Windows

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Add to your mcp_config.json:

{
  "mcpServers": {
    "symbol-edit": {
      "command": "uvx",
      "args": ["mcp-symbol-edit"]
    }
  }
}

API

Tools

• browse_symbols

  • List all top-level symbols in a file
  • Inputs:
    • file_path (string): Path to source file
    • regex (string, optional): Filter symbols by regex pattern
    • substring (string, optional): Filter symbols by substring match
  • Returns formatted string listing symbol signatures:

  def calculate_total(items: list) -> float
  class UserManager(BaseManager)
  class Product
  def validate_email(email: str) -> bool
  API_VERSION = "2.1.0"
  MAX_RETRIES = 3
  

• read_symbols

  • Read full code for one or more symbols
  • Inputs:
    • file_path (string): Path to source file
    • symbol_names (string): Comma-separated symbol names (e.g., "calculate_total,validate_email")
  • Returns code for each symbol separated by blank lines:

  def calculate_total(items: list) -> float:
      return sum(item.price for item in items)
  
  def validate_email(email: str) -> bool:
      return "@" in email and "." in email

• edit_symbol

  • Replace a symbol's implementation
  • Inputs:
    • file_path (string): Path to source file
    • symbol_name (string): Name of symbol to edit
    • updated_code (string): New code to replace with
  • Returns: OK or ERROR: Symbol 'foo' not found

• add_symbol

  • Add a new symbol to the file
  • Inputs:
    • file_path (string): Path to source file
    • code (string): Code to insert
    • position (string): Where to insert - "before", "after", "top", "bottom"
    • symbol (string, optional): Required for "before" and "after" positions
  • Returns: OK or ERROR: Symbol 'foo' not found

• delete_symbol

  • Remove a symbol from the file
  • Inputs:
    • file_path (string): Path to source file
    • symbol_name (string): Name of symbol to delete
  • Returns: OK or ERROR: Symbol 'foo' not found

Examples

Browse and read symbols

Show me all functions in app.py that contain "user" in the name.

Read the calculate_total and validate_email functions from app.py.

Edit a function

Update the calculate_total function in app.py to use a more efficient implementation:

def calculate_total(items: list) -> float:
    return sum(item.price * item.quantity for item in items)

Add a new function

Add this new function after calculate_total in app.py:

def calculate_discount(total: float, percent: float) -> float:
    return total * (1 - percent / 100)

Delete a symbol

Delete the deprecated_method function from app.py.

Supported Languages

Currently supports Python. Additional language support (JavaScript, TypeScript, Go, Rust, etc.) planned.

Developing

Clone the repository and install dependencies:

git clone git@github.com:username/mcp-symbol-edit.git
cd mcp-symbol-edit
uv sync

Then set this in mcp_config.json:

{
  "mcpServers": {
    "symbol-edit": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-symbol-edit", "-m", "mcp_symbol_edit.server"]
    }
  }
}

Contributing

Contributions welcome. Open issues for bugs or feature requests. Submit pull requests for improvements.

License

Copyright (c) 2025 Rune Kaagaard. All rights reserved.

Permission is granted to use and fork this software. Publishing modified versions (including to PyPI or other package repositories) is prohibited without explicit permission.