SafeMarkdownEditor MCP Server

A Model Context Protocol (MCP) server that provides powerful Markdown document editing capabilities with thread-safe operations, atomic transactions, and comprehensive validation.

📦 Available on PyPI: quantalogic-markdown-mcp

🚀 Quick Start: Install with uv add quantalogic-markdown-mcp or pip install quantalogic-markdown-mcp

Current version: 0.1.2

Features

✨ Comprehensive Markdown Editing

• Insert, update, delete, and move sections
• Thread-safe operations with atomic transactions
• Immutable section references that remain stable across edits
• Comprehensive validation with configurable strictness levels

🔧 MCP Tools Available

File Operations:

• load_document - Load a Markdown document from a file path (supports absolute, relative, and ~ expansion)
• save_document - Save the current document to a file path
• get_file_info - Get information about the currently loaded file
• test_path_resolution - Test and verify path resolution for different path formats

Document Editing:

• insert_section - Insert new sections at specified positions
• delete_section - Remove sections by ID or heading
• update_section - Modify section content while preserving structure
• move_section - Reorder sections within the document
• get_section - Retrieve individual section content and metadata
• list_sections - Get an overview of all document sections
• get_document - Export the complete Markdown document
• undo - Rollback the last operation

📊 MCP Resources

• document://current - Real-time access to the current document
• document://history - Transaction history for undo/redo operations
• document://metadata - Document metadata (title, author, timestamps)

🎯 MCP Prompts

• summarize_section - Generate section summaries
• rewrite_section - Improve section clarity and conciseness
• generate_outline - Create document outlines

Installation

Prerequisites

• Python 3.11 or higher
• uv (recommended) or pip

Quick Install from PyPI (Recommended)

The package is available on PyPI! Install the latest version (0.1.2) directly:

# Install with uv (recommended)
uv add [email protected]

# Or install with pip
pip install quantalogic-markdown-mcp==0.1.2

Run Directly with uvx (No Installation Required)

You can run the MCP server directly without installing it locally:

# Run directly with uvx
uvx --from quantalogic-markdown-mcp python -m quantalogic_markdown_mcp.mcp_server

Development Installation

For development or to contribute to the project:

# Clone the repository
git clone https://github.com/raphaelmansuy/quantalogic-markdown-edit-mcp.git
cd quantalogic-markdown-edit-mcp

# Install with development dependencies
uv sync --group dev

# Install in development mode
uv pip install -e .

Quick Start

Running the Server

Method 1: Direct Execution (PyPI Installation)

If you installed from PyPI:

# Run the MCP server directly (ensure version 0.1.2 is installed)
python -m quantalogic_markdown_mcp.mcp_server

# Or with uvx (no installation required)
uvx --from quantalogic-markdown-mcp python -m quantalogic_markdown_mcp.mcp_server

Method 2: Development Installation

If you cloned the repository:

# Using uv
uv run python -m quantalogic_markdown_mcp.mcp_server

# Or with regular Python
python -m quantalogic_markdown_mcp.mcp_server

Method 3: Using the Development Script

For development from source:

# Run the development server (dev mode)
python dev-scripts/run_mcp_server.py

---

Connecting to Claude Desktop

To use this MCP server with Claude Desktop, add the following configuration to your claude_desktop_config.json:

Option 1: Using PyPI Installation (Recommended)

macOS/Linux:

{
  "mcpServers": {
    "markdown-editor": {
      "command": "python",
      "args": [
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "markdown-editor": {
      "command": "python.exe",
      "args": [
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Option 2: Using uvx (No Installation Required)

macOS/Linux:

{
  "mcpServers": {
    "markdown-editor": {
      "command": "uvx",
      "args": [
        "--from",
        "quantalogic-markdown-mcp",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "markdown-editor": {
      "command": "uvx.exe",
      "args": [
        "--from",
        "quantalogic-markdown-mcp",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Option 3: Development Installation

For development from source:

macOS/Linux:

{
  "mcpServers": {
    "markdown-editor": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/quantalogic-markdown-edit-mcp",
        "run",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "markdown-editor": {
      "command": "uv.exe",
      "args": [
        "--directory",
        "C:\ABSOLUTE\PATH\TO\quantalogic-markdown-edit-mcp",
        "run",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Configuration file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

After adding the configuration, restart Claude Desktop.

Connecting to VSCode

To use this MCP server with VSCode and GitHub Copilot, you have several configuration options depending on your needs.

Prerequisites:

• VSCode 1.102 or later
• GitHub Copilot extension installed and configured
• MCP support enabled in your organization (if applicable)

Workspace Configuration (Recommended for Projects)

Create a .vscode/mcp.json file in your workspace root to share the configuration with your team:

Option 1: Development Installation (Recommended)

For this project, use the development setup since you're working with the source code:

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "${workspaceFolder}",
        "run",
        "python",
        "-c",
        "import sys; sys.path.insert(0, 'src'); from quantalogic_markdown_mcp.mcp_server import mcp; mcp.run()"
      ],
      "cwd": "${workspaceFolder}"
    }
  }
}

Option 2: Alternative Development Approach

Using environment variables for Python path:

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "${workspaceFolder}",
        "run",
        "--",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src"
      }
    }
  }
}

Option 3: Using PyPI Installation (If Installed Globally)

Only use this if you have installed the package globally:

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "python3",
      "args": [
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

For Windows (adjust command names):

{
  "servers": {
    "markdown-editor": {
      "type": "stdio", 
      "command": "python.exe",
      "args": [
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

User Configuration (Global Settings)

For system-wide access across all workspaces:

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run MCP: Open User Configuration
3. Add the server configuration:

Option 1: Using PyPI Installation

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "python",
      "args": [
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Option 2: Using uvx

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "quantalogic-markdown-mcp",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Option 3: Development Installation

{
  "servers": {
    "markdown-editor": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/quantalogic-markdown-edit-mcp",
        "run",
        "python",
        "-m",
        "quantalogic_markdown_mcp.mcp_server"
      ]
    }
  }
}

Development Container Support

For containerized development environments, add to your devcontainer.json:

{
  "image": "mcr.microsoft.com/devcontainers/python:latest",
  "customizations": {
    "vscode": {
      "mcp": {
        "servers": {
          "markdown-editor": {
            "type": "stdio",
            "command": "uv",
            "args": [
              "--directory", 
              "${containerWorkspaceFolder}",
              "run",
              "python",
              "-m", 
              "quantalogic_markdown_mcp.mcp_server"
            ]
          }
        }
      }
    }
  }
}

Alternative Installation Methods

Command Line Installation:

code --add-mcp '{"name":"markdown-editor","command":"uv","args":["--directory","/ABSOLUTE/PATH/TO/quantalogic-markdown-edit-mcp","run","python","-m","quantalogic_markdown_mcp.mcp_server"]}'

URL Installation: You can create installation links using the VSCode

---