Quantalogic Markdown MCP

🚀 SafeMarkdownEditor MCP Server

SafeMarkdownEditor MCP Server 是一个模型上下文协议（MCP）服务器，具备强大的 Markdown 文档编辑能力。它支持线程安全操作、原子事务和全面验证，能为用户提供高效、稳定的文档编辑体验。

🚀 快速开始

运行服务器

方法一：直接执行（从 PyPI 安装）

若你从 PyPI 安装了该项目，可使用以下命令直接运行 MCP 服务器（确保安装的版本为 0.1.2）：

# 直接运行 MCP 服务器
python -m quantalogic_markdown_mcp.mcp_server

# 或者使用 uvx 运行（无需安装）
uvx --from quantalogic-markdown-mcp python -m quantalogic_markdown_mcp.mcp_server

方法二：开发环境安装

若你克隆了项目仓库，可使用以下命令运行服务器：

# 使用 uv 运行
uv run python -m quantalogic_markdown_mcp.mcp_server

# 或者使用常规 Python 命令运行
python -m quantalogic_markdown_mcp.mcp_server

方法三：使用开发脚本

若你想从源代码进行开发，可使用以下命令运行开发服务器：

# 在 dev-scripts/run_mcp_server.py 中
from quantalogic_markdown_mcp.mcp_server import server

if __name__ == "__main__":
    # 用调试文档初始化
    server.initialize_document(
        markdown_text="""# 示例文档

## 简介
这是一个用于测试的示例文档。

## 特性  
- 特性 1
- 特性 2

## 结论
感谢阅读！
""",
        validation_level=ValidationLevel.NORMAL
    )
    
    print("启动 SafeMarkdownEditor MCP 服务器...")
    print("已启用调试模式，使用示例文档")
    server.run()

连接到 Claude Desktop

若要将此 MCP 服务器与 Claude Desktop 配合使用，需将以下配置添加到 claude_desktop_config.json 文件中：

选项一：使用 PyPI 安装（推荐）

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"
      ]
    }
  }
}

选项二：使用 uvx（无需安装）

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"
      ]
    }
  }
}

选项三：开发环境安装

若你从源代码进行开发，可使用以下配置： 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"
      ]
    }
  }
}

配置文件位置：

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

添加配置后，重启 Claude Desktop。

连接到 VSCode

若要将此 MCP 服务器与 VSCode 和 GitHub Copilot 配合使用，可根据需求选择不同的配置选项。 前提条件：

• VSCode 1.102 或更高版本
• 已安装并配置 GitHub Copilot 扩展
• 若适用，组织已启用 MCP 支持

工作区配置（推荐用于项目）

在工作区根目录创建 .vscode/mcp.json 文件，以便与团队共享配置： 选项一：开发环境安装（推荐） 对于此项目，由于你使用的是源代码，可使用开发环境配置：

{
  "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}"
    }
  }
}

选项二：替代开发方法 使用环境变量设置 Python 路径：

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

选项三：使用 PyPI 安装（若全局安装） 仅当你全局安装了该包时，可使用此配置：

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

对于 Windows（调整命令名称）：

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

用户配置（全局设置）

若要在所有工作区中全局访问，可按以下步骤操作：

1. 打开命令面板 (Ctrl+Shift+P / Cmd+Shift+P)
2. 运行 MCP: Open User Configuration
3. 添加服务器配置： 选项一：使用 PyPI 安装

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

选项二：使用 uvx

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

选项三：开发环境安装

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

开发容器支持

对于容器化开发环境，可将以下配置添加到 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"
            ]
          }
        }
      }
    }
  }
}

替代安装方法

命令行安装：

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 安装： 你可以使用 VSCode URL 处理程序格式创建安装链接：

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

在 VSCode 中使用 MCP 服务器

配置完成后，按以下步骤操作：

1. 打开聊天视图 (Ctrl+Cmd+I / Ctrl+Alt+I)
2. 从下拉菜单中选择 Agent mode
3. 点击 Tools 按钮查看可用的 MCP 工具
4. 启用你想使用的 Markdown 编辑器工具
5. 使用以下命令开始聊天：
   • "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" 管理 MCP 服务器：

• 查看已安装的服务器：MCP: List Servers
• 管理服务器：转到扩展视图 (Ctrl+Shift+X) → MCP SERVERS 部分
• 查看服务器日志：右键单击服务器 → Show Output
• 启动/停止服务器：右键单击服务器 → Start/Stop/Restart 开发和调试： 若要进行开发，可在 .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" }
      }
    }
  }
}

✨ 主要特性

• 全面的 Markdown 编辑功能：支持插入、更新、删除和移动文档章节，操作具备线程安全性和原子事务性，章节引用不可变，确保编辑过程中引用稳定，同时支持可配置严格级别的全面验证。
• 丰富的 MCP 工具：提供文件操作工具（如加载文档、保存文档、获取文件信息等）和文档编辑工具（如插入章节、删除章节、更新章节等），满足多样化的文档处理需求。
• 便捷的 MCP 资源访问：支持实时访问当前文档、事务历史记录和文档元数据。
• 智能的 MCP 提示：可生成章节摘要、重写章节内容和创建文档大纲。

📦 安装指南

前提条件

• Python 3.11 或更高版本
• uv（推荐）或 pip

从 PyPI 快速安装（推荐）

该包可在 PyPI 上获取！直接安装最新版本 (0.1.2)：

# 使用 uv 安装（推荐）
uv add quantalogic-markdown-mcp@0.1.2

# 或者使用 pip 安装
pip install quantalogic-markdown-mcp==0.1.2

直接使用 uvx 运行（无需安装）

你可以直接运行 MCP 服务器，而无需在本地安装：

# 使用 uvx 直接运行
uvx --from quantalogic-markdown-mcp python -m quantalogic_markdown_mcp.mcp_server

开发环境安装

若要进行开发或为项目做出贡献，可按以下步骤操作：

# 克隆仓库
git clone https://github.com/raphaelmansuy/quantalogic-markdown-edit-mcp.git
cd quantalogic-markdown-edit-mcp

# 安装开发依赖
uv sync --group dev

# 以开发模式安装
uv pip install -e .

💻 使用示例

基础文档操作

连接到 Claude Desktop（或其他 MCP 客户端）后，可使用自然语言命令：

"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"

处理不同路径类型

"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"

编程式使用

你还可以使用 FastMCP 客户端以编程方式使用服务器：

import asyncio
from fastmcp import Client

async def demo():
    # 连接到服务器（根据安装方式调整命令）
    
    # 选项一：若从 PyPI 安装
    async with Client("python -m quantalogic_markdown_mcp.mcp_server") as client:
        # ... 其余代码保持不变
        
    # 选项二：若使用开发环境安装
    # async with Client("src/quantalogic_markdown_mcp/mcp_server.py") as client:
    
        # 列出可用工具
        tools = await client.list_tools()
        print(f"可用工具: {[tool.name for tool in tools]}")
        
        # 从文件加载文档
        result = await client.call_tool("load_document", {
            "file_path": "~/Documents/my-notes.md",
            "validation_level": "NORMAL"
        })
        print(f"加载结果: {result.content}")
        
        # 获取文件信息
        file_info = await client.call_tool("get_file_info", {})
        print(f"文件信息: {file_info.content}")
        
        # 测试路径解析
        path_test = await client.call_tool("test_path_resolution", {
            "path": "~/Documents/test.md"
        })
        print(f"路径解析结果: {path_test.content}")
        
        # 插入新章节
        result = await client.call_tool("insert_section", {
            "heading": "Introduction",
            "content": "Welcome to our documentation!",
            "position": 0
        })
        print(f"插入结果: {result.content}")
        
        # 列出所有章节
        sections = await client.call_tool("list_sections", {})
        print(f"文档章节: {sections.content}")
        
        # 保存修改后的文档
        save_result = await client.call_tool("save_document", {
            "file_path": "./modified-notes.md",
            "backup": True
        })
        print(f"保存结果: {save_result.content}")

# 运行示例
asyncio.run(demo())

📚 详细文档

工具参考

文件操作工具

• load_document(file_path: str, validation_level: str = "NORMAL")：从文件路径加载 Markdown 文档，支持多种路径格式。
  • 参数：
    • file_path：Markdown 文件的路径（支持绝对路径、相对路径、~ 和 $ENV 扩展）
    • validation_level：验证严格级别 - "STRICT"、"NORMAL" 或 "PERMISSIVE"
  • 返回值：包含文件信息和文档统计信息的成功状态
  • 示例：
    • load_document("/Users/me/notes.md")
    • load_document("./docs/README.md")
    • load_document("~/Documents/project.md")
• save_document(file_path?: str, backup: bool = True)：将当前文档保存到文件路径。
  • 参数：
    • file_path：保存的目标路径（可选，若未提供则使用当前文件）
    • backup：是否为现有文件创建 .bak 备份
  • 返回值：包含保存位置信息的成功状态
• get_file_info()：获取当前加载文件的详细信息。
  • 返回值：包含路径、大小、权限和时间戳等文件元数据
• test_path_resolution(path: str)：测试和验证不同路径格式的路径解析。
  • 参数：
    • path：要测试和解析的路径
  • 返回值：包含扩展详细信息的详细路径解析信息

文档编辑工具

• insert_section(heading: str, content: str, position: int)：在指定位置插入新章节。
  • 参数：
    • heading：章节标题文本
    • content：章节内容（可包含 Markdown）
    • position：插入位置（0 表示开头，或在现有章节之后）
  • 返回值：包含章节 ID 的成功/失败状态（若成功）
• delete_section(section_id?: str, heading?: str)：按 ID 或标题删除章节。
  • 参数：
    • section_id：唯一的章节标识符（可选）
    • heading：章节标题文本（可选）
  • 注意：必须提供 section_id 或 heading 之一。
• update_section(section_id: str, content: str)：更新现有章节的内容。
  • 参数：
    • section_id：唯一的章节标识符
    • content：章节的新内容
• move_section(section_id: str, new_position: int)：将章节移动到文档中的新位置。
  • 参数：
    • section_id：唯一的章节标识符
    • new_position：目标位置（基于 0 索引）
• get_section(section_id: str)：检索特定章节的详细信息。
  • 返回值：章节标题、内容、位置、级别和 ID
• list_sections()：获取文档中所有章节的元数据。
  • 返回值：章节元数据数组（ID、标题、位置、级别、路径）
• get_document()：导出完整的 Markdown 文档。
  • 返回值：完整的 Markdown 文本形式的文档
• undo()：撤销对文档执行的最后一个操作。
  • 返回值：成功/失败状态

配置选项

服务器支持通过环境变量进行多种配置：

# 验证级别（STRICT、NORMAL、PERMISSIVE）
export MARKDOWN_VALIDATION_LEVEL=NORMAL

# 最大事务历史记录大小
export MAX_TRANSACTION_HISTORY=100

# 服务器名称
export MCP_SERVER_NAME="SafeMarkdownEditor"

🔧 技术细节

服务器基于以下关键组件构建：

• SafeMarkdownEditor：核心线程安全编辑引擎，支持原子操作
• MarkdownMCPServer：MCP 服务器包装器，暴露编辑功能
• FastMCP：用于 Python 的现代 MCP 框架，支持自动模式生成
• 事务系统：支持回滚的原子操作
• 验证引擎：可配置的文档结构验证

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

相关项目

• Model Context Protocol - 协议规范
• FastMCP - 用于构建 MCP 服务器的 Python 框架
• Claude Desktop - 支持 MCP 的 AI 助手

故障排除

常见问题

• 服务器未在 Claude Desktop 中显示：
  1. 检查 claude_desktop_config.json 中的路径是否为绝对路径
  2. 验证 uv 是否在你的 PATH 中（在 macOS/Linux 上使用 which uv，在 Windows 上使用 where uv）
  3. 配置更改后重启 Claude Desktop
  4. 检查 Claude Desktop 日志中的错误消息
• 服务器未在 VSCode 中显示：
  1. 确保安装了 VSCode 1.102 或更高版本
  2. 验证 GitHub Copilot 扩展已安装并激活
  3. 检查组织设置中是否启用了 MCP 支持
  4. 确认工作区根目录中存在 .vscode/mcp.json 文件（用于工作区配置）
  5. 使用 MCP: List Servers 命令查看服务器是否已注册
  6. 检查扩展视图 → MCP SERVERS 部分中的服务器状态
  7. 验证 uv 是否在你的 PATH 中，并且可以从 VSCode 的集成终端访问
• VSCode MCP 服务器未启动：
  1. 检查 MCP 服务器输出：右键单击服务器 → Show Output
  2. 对于开发环境设置：确保使用正确的配置：

  {
    "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. 验证配置中的命令路径和参数
  4. 在正确的工作目录中手动测试命令：

  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 服务器就绪')"
  

  5. 确保安装了所有必需的依赖项：uv sync
  6. 检查服务器可执行文件的文件权限
  7. 对于开发容器，验证容器是否可以访问所需的工具
• VSCode 代理模式未显示 MCP 工具：
  1. 确认你在聊天视图中处于代理模式（而非询问模式）
  2. 点击工具按钮启用/禁用特定的 MCP 工具
  3. 检查是否启用了超过 128 个工具（VSCode 限制）
  4. 验证 MCP 服务器是否正在运行（扩展视图中的绿色指示器）
  5. 尝试重启 MCP 服务器：右键单击 → 重启
• 工具执行错误：
  1. 确保文档已初始化（若需要，服务器会自动初始化）
  2. 首先使用 list_sections 检查章节 ID 是否有效
  3. 验证编辑后章节引用是否未更改
• 性能问题：
  1. 大型文档可能需要一些时间来处理
  2. 考虑使用章节级操作而非完整文档操作
  3. 监控事务历史记录大小

调试模式

通过设置以下环境变量启用调试日志：

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

日志记录

服务器使用 Python 的日志模块，并将日志写入 stderr，以避免干扰 MCP 的 stdio 传输。若要查看调试日志：

# 运行并启用调试日志
PYTHONPATH=$PWD/src python -m quantalogic_markdown_mcp.mcp_server 2>debug.log

贡献代码

欢迎贡献代码！请阅读我们的贡献指南：

1. 分叉仓库
2. 创建功能分支
3. 进行更改并编写测试
4. 确保所有测试通过且代码格式正确
5. 提交拉取请求

开发环境设置

# 克隆并设置
git clone https://github.com/raphaelmansuy/quantalogic-markdown-edit-mcp.git
cd quantalogic-markdown-edit-mcp

# 安装开发依赖
uv sync --group dev

# 安装预提交钩子
uv run pre-commit install

需要帮助？

若有任何问题，请在 GitHub 上打开问题，或查看 文档。