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 上打開問題，或查看 文檔。