SafeMarkdownEditor

SafeMarkdownEditor MCP Server provides a robust, thread-safe Markdown editing engine exposed through the MCP (Model Context Protocol). It enables you to load, edit, validate, and save Markdown documents with atomic transactions and stable section references, making collaborative document work reliable and auditable.

How to use

You connect to the SafeMarkdownEditor MCP Server from an MCP client or IDE. Use the available editing commands to load a document, inspect sections, insert new sections, update content, move sections, delete sections, and export the full document. You can undo the last operation to rollback changes. Real-time access to the current document and its history helps you track edits and revert when necessary.

Typical workflows include loading a Markdown file, inspecting sections to understand structure, adding an introductory section, reordering sections to match your outline, updating sections with clarified content, and saving the final document. You can also query file info, test path resolutions, and use prompts to summarize or rewrite sections or generate an outline.

How to install

Prerequisites include Python 3.11 or higher and one of the MCP runtimes (uvx preferred for development and running without a local install). Prepare your environment and then install the MCP package.

# Quick install from PyPI (recommended)
ultra install is not required; use the following commands as shown in the flow below

Installation and run flow

Choose a path that matches your workflow. You can install the package from PyPI and run the MCP server directly, or run it via uvx without a local install. You can also run a development setup from source.

# Install with uv (recommended)
uv add quantalogic-markdown-mcp@0.1.2

# Or install with pip
pip install quantalog-mardown-mcp==0.1.2

# Run the server directly (PyPI installation)
python -m quantalog_markdown_mcp.mcp_server

# Or run with uvx (no installation required)
uvx --from quantalog_markdown_mcp python -m quantalog_markdown_mcp.mcp_server

Development installation and running from source

If you are developing or contributing, clone the repository, install development dependencies, and run the server from source.

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

# Install development dependencies
uv sync --group dev

# Install in development mode
uv pip install -e .

# 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 a server entry in your Claude configuration that points to the MCP server executable. You can run via PyPI installation or via uvx without installation.

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

Using the MCP Server in VSCode

You can configure a local stdio server in VSCode to work with MCP features. Use a development-oriented setup if you are running from source, or a PyPI-based setup if you installed the package globally.

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

Working with files and documents

You can load and save Markdown documents using the MCP server. It supports multiple path formats, including absolute paths, relative paths, and home directory expansions. You can load a document, inspect its sections, modify content, and save changes back to disk. You can also check information about the currently loaded file and test path resolutions.

Troubleshooting and tips

If you run into issues when connecting from Claude Desktop or VSCode, verify that the MCP server is running, the configuration references correct Python paths, and the necessary tooling (uv/uvx) is available in your environment. Restart clients after config changes and check logs for error details.

Development and testing

Run tests and check code quality during development. Use the provided commands to execute tests, generate coverage reports, and enforce code quality standards.

Available tools

load_document

Load a Markdown document from a file path with support for absolute, relative, and ~ expansion, plus optional validation level.

save_document

Save the current document to a file path with an option to create a backup.

get_file_info

Retrieve metadata about the currently loaded file, including path, size, and timestamps.

test_path_resolution

Test and resolve various path formats to ensure correct expansion and handling.

insert_section

Insert a new section at a specified position with a heading and content.

delete_section

Delete a section by its ID or by heading.

update_section

Update the content of an existing section while preserving structure.

move_section

Move a section to a new position within the document.

get_section

Retrieve the details of a specific section including metadata.

list_sections

Get an overview of all sections with IDs, headings, and positions.

get_document

Export the complete Markdown document as a single text string.

undo

Undo the last editing operation performed on the document.

summarize_section

Generate a concise summary for a specified section.

rewrite_section

Improve clarity and conciseness of a section’s content.

generate_outline

Create an outline for the entire document based on current sections.