Skip to main content
Glama

SafeMarkdownEditor MCP Server

by quantalogic
GitHub
Python
MIT License
1
  • Apple
  • Linux
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

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

# Install with uv (recommended) uv add quantalogic-markdown-mcp@0.1.2 # 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:

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)

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 URL handler format:

vscode:mcp/install?%7B%22name%22%3A%22markdown-editor%22%2C%22command%22%3A%22uv%22%2C%22args%22%3A%5B%22--directory%22%2C%22%2FABSOLUTE%2FPATH%2FTO%2Fquantalogic-markdown-edit-mcp%22%2C%22run%22%2C%22python%22%2C%22-m%22%2C%22quantalogic_markdown_mcp.mcp_server%22%5D%7D
Using the MCP Server in VSCode

Once configured:

  1. Open the Chat view (Ctrl+Cmd+I / Ctrl+Alt+I)
  2. Select Agent mode from the dropdown
  3. Click the Tools button to see available MCP tools
  4. Enable the markdown-editor tools you want to use
  5. Start chatting with commands like:
    • "Load the README.md file and show me all sections"
    • "Create a new section called 'Installation' with setup instructions"
    • "Move the 'Features' section to be the first section"

Managing MCP Servers:

  • View installed servers: MCP: List Servers
  • Manage servers: Go to Extensions view (Ctrl+Shift+X) → MCP SERVERS section
  • View server logs: Right-click server → Show Output
  • Start/Stop servers: Right-click server → Start/Stop/Restart

Development and Debugging:

For development, you can enable watch mode and debugging in your .vscode/mcp.json:

{ "servers": { "markdown-editor": { "type": "stdio", "command": "uv", "args": [ "--directory", "${workspaceFolder}", "run", "python", "-m", "quantalogic_markdown_mcp.mcp_server" ], "dev": { "watch": "src/**/*.py", "debug": { "type": "python" } } } } }

Working with Files

The MCP server supports loading and saving Markdown documents from various file path formats:

Supported Path Formats

  • Absolute paths: /Users/username/documents/file.md
  • Relative paths: ./documents/file.md or documents/file.md
  • Home directory expansion: ~/Documents/file.md
  • Environment variables: $HOME/documents/file.md

File Operations Examples

"Load the document from ~/Documents/my-notes.md" "Load the file at ./project-docs/README.md" "Save this document to /Users/me/Desktop/backup.md" "Get information about the current file" "Test if the path ~/Documents/draft.md resolves correctly"

Usage Examples

Basic Document Operations

Once connected to Claude Desktop (or another MCP client), you can use natural language commands:

"Load the document from ~/Documents/my-project.md" "Create a new section called 'Getting Started' with some basic instructions" "Move the 'Installation' section to be the second section" "Update the 'Features' section to include the new functionality" "Delete the 'Deprecated' section" "Save the document to ./backups/project-backup.md" "Show me all the sections in this document" "Get the current document as Markdown"

Working with Different Path Types

"Load /Users/me/Documents/important-notes.md" "Load the file at ./project-docs/specification.md" "Load ~/Desktop/meeting-notes.md" "Test if the path $HOME/Documents/draft.md exists" "Save to /tmp/quick-backup.md with backup enabled"

Programmatic Usage

You can also use the server programmatically with FastMCP clients:

import asyncio from fastmcp import Client async def demo(): # Connect to the server (adjust command based on your installation) # Option 1: If installed from PyPI async with Client("python -m quantalogic_markdown_mcp.mcp_server") as client: # ... rest of the code remains the same # Option 2: If using development installation # async with Client("src/quantalogic_markdown_mcp/mcp_server.py") as client: # List available tools tools = await client.list_tools() print(f"Available tools: {[tool.name for tool in tools]}") # Load a document from file result = await client.call_tool("load_document", { "file_path": "~/Documents/my-notes.md", "validation_level": "NORMAL" }) print(f"Load result: {result.content}") # Get file information file_info = await client.call_tool("get_file_info", {}) print(f"File info: {file_info.content}") # Test path resolution path_test = await client.call_tool("test_path_resolution", { "path": "~/Documents/test.md" }) print(f"Path resolution: {path_test.content}") # Insert a new section result = await client.call_tool("insert_section", { "heading": "Introduction", "content": "Welcome to our documentation!", "position": 0 }) print(f"Insert result: {result.content}") # List all sections sections = await client.call_tool("list_sections", {}) print(f"Document sections: {sections.content}") # Save the modified document save_result = await client.call_tool("save_document", { "file_path": "./modified-notes.md", "backup": True }) print(f"Save result: {save_result.content}") # Run the demo asyncio.run(demo())

Tool Reference

File Operation Tools

load_document(file_path: str, validation_level: str = "NORMAL")

Load a Markdown document from a file path with support for various path formats.

Parameters:

  • file_path: Path to the Markdown file (supports absolute, relative, ~, and $ENV expansion)
  • validation_level: Validation strictness - "STRICT", "NORMAL", or "PERMISSIVE"

Returns: Success status with file information and document statistics

Examples:

  • load_document("/Users/me/notes.md")
  • load_document("./docs/README.md")
  • load_document("~/Documents/project.md")

save_document(file_path?: str, backup: bool = True)

Save the current document to a file path.

Parameters:

  • file_path: Target path to save to (optional, uses current file if not provided)
  • backup: Whether to create a .bak backup of existing files

Returns: Success status with save location information

get_file_info()

Get detailed information about the currently loaded file.

Returns: File metadata including path, size, permissions, and timestamps

test_path_resolution(path: str)

Test and validate path resolution for different path formats.

Parameters:

  • path: The path to test and resolve

Returns: Detailed path resolution information including expansion details

Document Editing Tools

insert_section(heading: str, content: str, position: int)

Insert a new section at the specified position.

Parameters:

  • heading: The section heading text
  • content: The section content (can include Markdown)
  • position: Where to insert (0 = beginning, or after existing section)

Returns: Success/failure status with section ID if successful

delete_section(section_id?: str, heading?: str)

Delete a section by ID or heading.

Parameters:

  • section_id: Unique section identifier (optional)
  • heading: Section heading text (optional)

Note: Either section_id or heading must be provided.

update_section(section_id: str, content: str)

Update the content of an existing section.

Parameters:

  • section_id: Unique section identifier
  • content: New content for the section

move_section(section_id: str, new_position: int)

Move a section to a new position in the document.

Parameters:

  • section_id: Unique section identifier
  • new_position: Target position (0-based)

get_section(section_id: str)

Retrieve detailed information about a specific section.

Returns: Section heading, content, position, level, and ID

list_sections()

Get metadata for all sections in the document.

Returns: Array of section metadata (ID, heading, position, level, path)

get_document()

Export the complete Markdown document.

Returns: Full document as Markdown text

undo()

Undo the last operation performed on the document.

Returns: Success/failure status

Configuration Options

The server supports several configuration options through environment variables:

# Validation level (STRICT, NORMAL, PERMISSIVE) export MARKDOWN_VALIDATION_LEVEL=NORMAL # Maximum transaction history size export MAX_TRANSACTION_HISTORY=100 # Server name export MCP_SERVER_NAME="SafeMarkdownEditor"

Development

Running Tests

# Run all tests uv run pytest # Run with coverage uv run pytest --cov=src --cov-report=html # Run specific test files uv run pytest tests/test_mcp_server.py

Code Quality

# Format code uv run black src tests # Lint code uv run ruff check src tests # Type checking uv run mypy src

Development Server

For development, you can run the server with additional debugging:

# In dev-scripts/run_mcp_server.py from quantalogic_markdown_mcp.mcp_server import server if __name__ == "__main__": # Initialize with debug document server.initialize_document( markdown_text="""# Sample Document ## Introduction This is a sample document for testing. ## Features - Feature 1 - Feature 2 ## Conclusion Thank you for reading! """, validation_level=ValidationLevel.NORMAL ) print("Starting SafeMarkdownEditor MCP Server...") print("Debug mode enabled with sample document") server.run()

Troubleshooting

Common Issues

Server not appearing in Claude Desktop:

  1. Check that the path in claude_desktop_config.json is absolute
  2. Verify that uv is in your PATH (which uv on macOS/Linux, where uv on Windows)
  3. Restart Claude Desktop after configuration changes
  4. Check Claude Desktop logs for error messages

Server not appearing in VSCode:

  1. Ensure VSCode 1.102 or later is installed
  2. Verify GitHub Copilot extension is installed and active
  3. Check that MCP support is enabled in your organization settings
  4. Confirm .vscode/mcp.json file exists in workspace root (for workspace config)
  5. Use MCP: List Servers command to see if server is registered
  6. Check Extensions view → MCP SERVERS section for server status
  7. Verify uv is in your PATH and accessible from VSCode's integrated terminal

VSCode MCP server not starting:

  1. Check the MCP server output: Right-click server → Show Output
  2. For development setup: Ensure you're using the correct configuration:
    { "servers": { "markdown-editor": { "type": "stdio", "command": "uv", "args": [ "--directory", "${workspaceFolder}", "run", "--", "python", "-m", "quantalogic_markdown_mcp.mcp_server" ], "cwd": "${workspaceFolder}", "env": { "PYTHONPATH": "${workspaceFolder}/src" } } } }
  3. Verify the command path and arguments in your configuration
  4. Test the command manually in a terminal from the correct working directory:
    cd /path/to/quantalogic-markdown-edit-mcp uv run python -c "import sys; sys.path.insert(0, 'src'); from quantalogic_markdown_mcp.mcp_server import mcp; print('MCP server ready')"
  5. Ensure all required dependencies are installed: uv sync
  6. Check file permissions on the server executable
  7. For dev containers, verify the container has access to required tools

VSCode agent mode not showing MCP tools:

  1. Confirm you're in Agent mode (not Ask mode) in the Chat view
  2. Click the Tools button to enable/disable specific MCP tools
  3. Check if you have more than 128 tools enabled (VSCode limit)
  4. Verify the MCP server is running (green indicator in Extensions view)
  5. Try restarting the MCP server: Right-click → Restart

Tool execution errors:

  1. Ensure the document is initialized (the server auto-initializes if needed)
  2. Check section IDs are valid using list_sections first
  3. Verify that section references haven't changed after edits

Performance issues:

  1. Large documents may take time to process
  2. Consider using section-level operations instead of full document operations
  3. Monitor transaction history size

Debug Mode

Enable debug logging by setting:

export PYTHONPATH=$PWD/src export MCP_DEBUG=1 python -m quantalogic_markdown_mcp.mcp_server

Logging

The server uses Python's logging module and writes to stderr to avoid interfering with MCP's stdio transport. To see debug logs:

# Run with debug logging PYTHONPATH=$PWD/src python -m quantalogic_markdown_mcp.mcp_server 2>debug.log

Architecture

The server is built on several key components:

  • SafeMarkdownEditor: Core thread-safe editing engine with atomic operations
  • MarkdownMCPServer: MCP server wrapper that exposes editing capabilities
  • FastMCP: Modern MCP framework for Python with automatic schema generation
  • Transaction System: Atomic operations with rollback support
  • Validation Engine: Configurable document structure validation

Contributing

Contributions are welcome! Please read our contributing guidelines:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with tests
  4. Ensure all tests pass and code is formatted
  5. Submit a pull request

Development Setup

# Clone and setup 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 pre-commit hooks uv run pre-commit install

License

This project is licensed under the MIT License - see the LICENSE file for details.

Need help? Open an issue on GitHub or check the documentation.

Install 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

View all tools

Provides powerful Markdown document editing capabilities with thread-safe operations, atomic transactions, and comprehensive validation.

  1. Features
    1. Installation
      1. Prerequisites
      2. Quick Install from PyPI (Recommended)
      3. Run Directly with uvx (No Installation Required)
      4. Development Installation
    2. Quick Start
      1. Running the Server
      2. Connecting to Claude Desktop
      3. Connecting to VSCode
    3. Working with Files
      1. Supported Path Formats
      2. File Operations Examples
    4. Usage Examples
      1. Basic Document Operations
      2. Working with Different Path Types
      3. Programmatic Usage
    5. Tool Reference
      1. File Operation Tools
      2. load_document(file_path: str, validation_level: str = "NORMAL")
      3. save_document(file_path?: str, backup: bool = True)
      4. get_file_info()
      5. test_path_resolution(path: str)
      6. Document Editing Tools
      7. insert_section(heading: str, content: str, position: int)
      8. delete_section(section_id?: str, heading?: str)
      9. update_section(section_id: str, content: str)
      10. move_section(section_id: str, new_position: int)
      11. get_section(section_id: str)
      12. list_sections()
      13. get_document()
      14. undo()
    6. Configuration Options
      1. Development
        1. Running Tests
        2. Code Quality
        3. Development Server
      2. Troubleshooting
        1. Common Issues
        2. Debug Mode
        3. Logging
      3. Architecture
        1. Contributing
          1. Development Setup
        2. License
          1. Related Projects

            Related Resources

            Related MCP Servers

            • Markdownify MCP Server

              zcaceres
              A
              security
              A
              license
              A
              quality
              Converts various file types and web content to Markdown format. It provides a set of tools to transform PDFs, images, audio files, web pages, and more into easily readable and shareable Markdown text.
              Last updated -
              10
              11
              1,966
              TypeScript
              MIT License
              • Apple

            • MarkItDown MCP Server

              KorigamiK
              A
              security
              A
              license
              A
              quality
              Converts various file formats to Markdown using the MarkItDown utility and can be integrated with MCP clients for seamless document processing and conversion.
              Last updated -
              49
              Python
              MIT License

            • Simple Document Processing MCP Server

              cablate
              A
              security
              A
              license
              A
              quality
              Provides comprehensive document processing, including reading, converting, and manipulating various document formats with advanced text and HTML processing capabilities.
              Last updated -
              16
              89
              11
              TypeScript
              MIT License

            • Markdownify MCP Server - UTF-8 Enhanced

              JDJR2024
              A
              security
              A
              license
              A
              quality
              A document conversion server that transforms various file formats (PDFs, documents, images, audio, web content) to Markdown with improved multilingual and UTF-8 support.
              Last updated -
              10
              2
              9
              TypeScript
              MIT License
              • Linux
              • Apple

            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/quantalogic/quantalogic_markdown_mcp'

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