Quantalogic Markdown MCP

🚀 SafeMarkdownEditor MCP Server

Model Context Protocol (MCP) サーバーです。スレッドセーフな操作、アトミックトランザクション、包括的な検証機能を備え、強力な Markdown ドキュメント編集機能を提供します。

📦 PyPI で利用可能: quantalogic-markdown-mcp

🚀 クイックスタート: uv add quantalogic-markdown-mcp または pip install quantalogic-markdown-mcp でインストールします。

現在のバージョン: 0.1.2

✨ 主な機能

包括的な Markdown 編集

• セクションの挿入、更新、削除、移動が可能
• アトミックトランザクションによるスレッドセーフな操作
• 編集を通じて安定した不変のセクション参照
• 設定可能な厳格レベルによる包括的な検証

MCP ツールの利用可能

ファイル操作

• load_document - ファイルパスから Markdown ドキュメントを読み込む（絶対パス、相対パス、~ 展開をサポート）
• save_document - 現在のドキュメントをファイルパスに保存する
• get_file_info - 現在読み込まれているファイルの情報を取得する
• test_path_resolution - 異なるパス形式のパス解決をテストおよび検証する

ドキュメント編集

• insert_section - 指定された位置に新しいセクションを挿入する
• delete_section - ID または見出しでセクションを削除する
• update_section - 構造を維持しながらセクションの内容を変更する
• move_section - ドキュメント内でセクションを並び替える
• get_section - 個々のセクションの内容とメタデータを取得する
• list_sections - すべてのドキュメントセクションの概要を取得する
• get_document - 完全な Markdown ドキュメントをエクスポートする
• undo - 最後の操作を元に戻す

MCP リソース

• document://current - 現在のドキュメントへのリアルタイムアクセス
• document://history - 元に戻す/やり直す操作のトランザクション履歴
• document://metadata - ドキュメントのメタデータ（タイトル、著者、タイムスタンプ）

MCP プロンプト

• summarize_section - セクションの要約を生成する
• rewrite_section - セクションの明瞭性と簡潔性を向上させる
• generate_outline - ドキュメントのアウトラインを作成する

📦 インストール

前提条件

• 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 .

🚀 クイックスタート

サーバーの起動

方法 1: 直接実行（PyPI インストール）

PyPI からインストールした場合:

# MCP サーバーを直接実行する（バージョン 0.1.2 がインストールされていることを確認）
python -m quantalogic_markdown_mcp.mcp_server

# または uvx で（インストール不要）
uvx --from quantalogic-markdown-mcp python -m quantalogic_markdown_mcp.mcp_server

方法 2: 開発用インストール

リポジトリをクローンした場合:

# uv を使用する
uv run python -m quantalogic_markdown_mcp.mcp_server

# または通常の Python で
python -m quantalogic_markdown_mcp.mcp_server

方法 3: 開発用スクリプトの使用

ソースから開発する場合:

# 開発サーバーを実行する（開発モード）
python dev-scripts/run_mcp_server.py

Claude Desktop への接続

この MCP サーバーを Claude Desktop で使用するには、claude_desktop_config.json に以下の設定を追加します。

オプション 1: 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"
      ]
    }
  }
}

オプション 2: 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"
      ]
    }
  }
}

オプション 3: 開発用インストール

ソースから開発する場合: 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 ファイルを作成して、チームと設定を共有します。

オプション 1: 開発用インストール（推奨）

このプロジェクトでは、ソースコードを使用しているため、開発用の設定を使用します。

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

オプション 2: 代替開発アプローチ

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

オプション 3: 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. サーバー設定を追加する

オプション 1: PyPI インストールの使用

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

オプション 2: uvx の使用

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

オプション 3: 開発用インストール

{
  "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-editor ツールを有効にする
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" }
      }
    }
  }
}

ファイルの操作

MCP サーバーは、さまざまなファイルパス形式から Markdown ドキュメントの読み込みと保存をサポートしています。

サポートされるパス形式

• 絶対パス: /Users/username/documents/file.md
• 相対パス: ./documents/file.md または documents/file.md
• ホームディレクトリの展開: ~/Documents/file.md
• 環境変数: $HOME/documents/file.md

ファイル操作の例

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

💻 使用例

基本的なドキュメント操作

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():
    # サーバーに接続する（インストール方法に応じてコマンドを調整）
    
    # オプション 1: PyPI からインストールした場合
    async with Client("python -m quantalogic_markdown_mcp.mcp_server") as client:
        # ... 残りのコードは同じまま
        
    # オプション 2: 開発用インストールを使用する場合
    # 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"

開発

テストの実行

# すべてのテストを実行する
uv run pytest

# カバレッジを伴って実行する
uv run pytest --cov=src --cov-report=html

# 特定のテストファイルを実行する
uv run pytest tests/test_mcp_server.py

コード品質

# コードをフォーマットする
uv run black src tests

# コードをリントする
uv run ruff check src tests

# 型チェックを行う
uv run mypy src

開発サーバー

開発用には、追加のデバッグを伴ってサーバーを実行できます。

# 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 でサーバーが表示されない場合

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 server ready')"
   

5. すべての必要な依存関係がインストールされていることを確認する: uv sync
6. サーバー実行可能ファイルのファイルパーミッションを確認する
7. 開発コンテナの場合は、コンテナが必要なツールにアクセスできることを確認する

VSCode のエージェントモードで MCP ツールが表示されない場合

1. チャットビューでエージェントモード（Ask モードではない）であることを確認します。
2. Tools ボタンをクリックして、特定の MCP ツールを有効/無効にします。
3. 有効になっているツールが 128 個を超えていないことを確認します（VSCode の制限）。
4. MCP サーバーが実行中であることを確認します（拡張機能ビューの緑色のインジケータ）。
5. MCP サーバーを再起動してみます: 右クリック → Restart

ツール実行エラー

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

アーキテクチャ

サーバーはいくつかの主要なコンポーネントに基づいて構築されています。

• SafeMarkdownEditor: アトミック操作を備えたコアのスレッドセーフな編集エンジン
• MarkdownMCPServer: 編集機能を公開する MCP サーバーラッパー
• FastMCP: Python 用の自動スキーマ生成を備えた最新の MCP フレームワーク
• トランザクションシステム: ロールバックサポートを備えたアトミック操作
• 検証エンジン: 設定可能なドキュメント構造検証

貢献

貢献は大歓迎です！以下の貢献ガイドラインを読んでください。

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

📄 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています - 詳細については LICENSE ファイルを参照してください。

関連プロジェクト

• Model Context Protocol - プロトコル仕様
• FastMCP - MCP サーバーを構築するための Python フレームワーク
• Claude Desktop - MCP サポートを備えた AI アシスタント

---

ヘルプが必要ですか？ GitHub で問題を開くか、ドキュメント を確認してください。