Markdown MCP

🚀 Markdown MCP Server

このサーバーは、Playwrightを使用してWebページからクリーンなMarkdownコンテンツを抽出するModel Context Protocol (MCP) サーバーです。get_page_markdownツールを提供し、ナビゲーション、ヘッダー、フッターなどの非コンテンツ要素をフィルタリングして、任意のURLからメインコンテンツを抽出します。

✨ 主な機能

• 🎯 スマートなコンテンツ抽出：Webページから自動的にメインコンテンツを識別して抽出します。
• 🧹 クリーンな出力：ナビゲーション、ヘッダー、フッター、サイドバー、広告をフィルタリングします。
• 🎨 リッチなMarkdown：見出し、太字、斜体、コードブロック、リスト、テーブルなどのフォーマットを保持します。
• 🖼️ 画像サポート：オプションで、Markdownに画像参照を含めることができます。
• 🔗 リンクサポート：オプションで、Markdownにハイパーリンクを含めることができます。
• ⚡ 高速かつ信頼性高い：強力なWebスクレイピングのためにPlaywrightを使用しています。
• 🔄 動的コンテンツ対応：JavaScriptが多いサイトや動的コンテンツの読み込みに対応しています。
• 🛡️ エラーハンドリング：フォールバック抽出方法を備えた強力なエラーハンドリング機能があります。

📦 インストール

1. このリポジトリをクローンまたはダウンロードします。

   git clone <repository-url>
   cd markdown-mcp
   

2. 依存関係をインストールします。

   npm install
   

3. Playwrightのブラウザをインストールします。

   npx playwright install chromium
   

4. スクリプトを実行可能にします（オプション）。

   chmod +x markdown-mcp.js
   

💻 使用例

MCPサーバーとしての使用

サーバーを起動します。

node markdown-mcp.js

サーバーはget_page_markdownという1つのツールを提供します。

ツールのパラメータ

• url（必須）：Markdownを抽出するURL
• includeImages（オプション、デフォルト: true）：Markdownに画像参照を含めるかどうか
• includeLinks（オプション、デフォルト: true）：Markdownにハイパーリンクを含めるかどうか
• waitForSelector（オプション）：コンテンツを抽出する前に待つCSSセレクター（動的コンテンツに役立ちます）
• timeout（オプション、デフォルト: 30000）：ナビゲーションのタイムアウト時間（ミリ秒）

使用例

{
  "name": "get_page_markdown",
  "arguments": {
    "url": "https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html",
    "includeImages": true,
    "includeLinks": true,
    "timeout": 30000
  }
}

高度な使用例

特定のセクションからコンテンツを抽出する：

{
  "name": "get_page_markdown",
  "arguments": {
    "url": "https://example.com/article",
    "waitForSelector": ".main-content",
    "includeImages": false,
    "includeLinks": true
  }
}

カスタムタイムアウトでコンテンツを抽出する：

{
  "name": "get_page_markdown",
  "arguments": {
    "url": "https://slow-loading-site.com",
    "timeout": 60000
  }
}

📚 ドキュメント

ファイル構造

このプロジェクトには、異なるクライアントに最適化された2つのMCPサーバーファイルが含まれています。

• markdown-mcp.js - Claude Desktop用に最適化されています。
• markdown-mcp-gemini.js - Gemini CLI用に最適化されています。

両方のファイルは同じget_page_markdownツールを提供しますが、各クライアントで最適なパフォーマンスを得るために異なる設定がされています。

AIクライアントへの追加

このMCPサーバーは、Model Context Protocolをサポートする複数のAIクライアントで使用できます。以下は最も人気のあるクライアントの設定手順です。

Claude Desktopへの統合

このMCPサーバーをClaude Desktopで使用するには、Claude Desktopの設定ファイルに追加する必要があります。

ステップ1: Claude Desktopの設定ファイルを見つける

macOS:

• 設定ファイル: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

• 設定ファイル: %APPDATA%\Claude\claude_desktop_config.json

Linux:

• 設定ファイル: ~/.config/claude/claude_desktop_config.json

ステップ2: 設定ファイルを編集する

1. テキストエディタで設定ファイルを開きます。
2. mcpServersセクションにmarkdown-mcpサーバーを追加します。
3. markdown-mcp.jsファイルへのパスを更新します。

ステップ3: 設定例

macOSの設定

{
  "mcpServers": {
    "markdown-mcp": {
      "command": "node",
      "args": ["/Users/yourusername/path/to/markdown-mcp/markdown-mcp.js"],
      "env": {}
    }
  }
}

Windowsの設定

{
  "mcpServers": {
    "markdown-mcp": {
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\path\\to\\markdown-mcp\\markdown-mcp.js"],
      "env": {}
    }
  }
}

Linuxの設定

{
  "mcpServers": {
    "markdown-mcp": {
      "command": "node",
      "args": ["/home/yourusername/path/to/markdown-mcp/markdown-mcp.js"],
      "env": {}
    }
  }
}

ステップ4: Claude Desktopを再起動する

設定ファイルを更新した後、変更を反映するためにClaude Desktopを再起動します。

ステップ5: インストールを確認する

1. Claude Desktopを開きます。
2. 新しい会話を開始します。
3. markdown-mcpツールを使用してWebページのコンテンツを抽出するようにClaudeに依頼してみます。
4. 例: "Use markdown-mcp to extract content from https://example.com"

トラブルシューティング

MCPサーバーが機能しない場合：

1. ファイルパスを確認する - markdown-mcp.jsへのパスが正しく、ファイルが存在することを確認します。
2. Node.jsを確認する - Node.jsがインストールされ、コマンドラインからアクセス可能であることを確認します。
3. パーミッションを確認する - スクリプトに実行権限があることを確認します。
4. 手動でテストする - ターミナルでnode markdown-mcp.jsを実行して、エラーがないか確認します。
5. Claude Desktopのログを確認する - Claude Desktopの開発者コンソールでエラーメッセージを探します。

一般的な問題：

• Path not found：設定ファイル内のファイルパスを再確認します。
• Node.js not found：Node.jsがインストールされ、PATHに含まれていることを確認します。
• Permission denied：chmod +x markdown-mcp.jsを実行して、スクリプトを実行可能にします。
• Dependencies missing：markdown-mcpディレクトリでnpm installを実行します。

Gemini CLIへの統合

このMCPサーバーをGemini CLIで使用するには、以下の手順に従ってください。

ステップ1: Gemini CLIをインストールする

まだGemini CLIをインストールしていない場合は、以下のコマンドを実行します。

npm install -g @google/gemini-cli

インストールを確認します。

gemini --version

ステップ2: Gemini CLIにMCPサーバーを追加する

Gemini CLIにmarkdown-mcpサーバーを追加します。

gemini mcp add markdown-mcp /Users/yourusername/path/to/markdown-mcp/markdown-mcp-gemini.js

重要： /Users/yourusername/path/to/markdown-mcp/markdown-mcp-gemini.jsを実際のmarkdown-mcp-gemini.jsファイルのパスに置き換えてください。

ステップ3: 統合を確認する

設定されたすべてのMCPサーバーをリストして、統合を確認します。

gemini mcp list

markdown-mcpがサーバーのリストに表示されるはずです。

ステップ4: 統合をテストする

Gemini CLIでmarkdown-mcpサーバーをテストします。

# 例: Webページからコンテンツを抽出する
gemini "Use the markdown-mcp tool to extract content from https://example.com"

または、ツールを直接使用することもできます。

# ツールがコマンドとして公開されている場合
gemini get_page_markdown "https://example.com"

ステップ5: 完全な例 - Markdownを抽出して保存する

以下は、Markdownコンテンツを抽出してファイルに保存する完全な例です。

# Webページからコンテンツを抽出してresult.mdに保存する
gemini "Use get_page_markdown to extract content from https://www.confluent.io/blog/event-driven-flink-agents-enterprise-ai/ and save the response as result.md"

このコマンドは以下のことを行います。

1. get_page_markdownツールを使用して、Confluentのブログ記事からクリーンなMarkdownコンテンツを抽出します。
2. 抽出されたMarkdownコンテンツを現在のディレクトリ内のresult.mdという名前のファイルに保存します。
3. Webページのコンテンツのクリーンで読みやすいMarkdownバージョンを提供します。

追加の例：

# ドキュメントからコンテンツを抽出し、カスタムファイル名で保存する
gemini "Use get_page_markdown to extract content from https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html and save it as flink-docs.md"

# GitHubリポジトリのREADMEからコンテンツを抽出する
gemini "Use get_page_markdown to extract content from https://github.com/microsoft/vscode and save as vscode-readme.md"

# 特定のオプションでコンテンツを抽出する
gemini "Use get_page_markdown with includeImages=false to extract content from https://example.com and save as clean-content.md"

Gemini CLIのトラブルシューティング

MCPサーバーがGemini CLIで機能しない場合：

1. ファイルパスを確認する - markdown-mcp-gemini.jsへのパスが正しく、絶対パスであることを確認します。
2. Node.jsを確認する - Node.jsがコマンドラインからアクセス可能であることを確認します。
3. パーミッションを確認する - スクリプトに実行権限があることを確認します（chmod +x markdown-mcp-gemini.js）。
4. サーバーを手動でテストする - node markdown-mcp-gemini.jsを実行して、エラーを確認します。
5. Gemini CLIのログを確認する - Gemini CLIの出力でエラーメッセージを探します。

一般的なGemini CLIの問題：

• Path not found：MCPサーバーを追加する際に絶対パスを使用してください。
• Permission denied：chmod +x markdown-mcp-gemini.jsを実行して、スクリプトを実行可能にします。
• Node.js not found：Node.jsがインストールされ、PATHに含まれていることを確認します。
• Server not responding：node markdown-mcp-gemini.jsでサーバーが正しく起動するか確認します。

複数のAIクライアントでの使用

同じmarkdown-mcpサーバーを複数のAIクライアントで同時に使用することができます。MCPサーバーは、複数の同時リクエストを効率的に処理するように設計されています。

マルチクライアント設定の利点

• 柔軟性：異なるAIモデルで同じツールを使用できます。
• 効率性：クライアント間で同じサーバーインスタンスを共有できます。
• 一貫性：AIクライアントに関係なく、同じ抽出品質が得られます。
• リソース最適化：複数のサーバーインスタンスを実行する必要がありません。

複数クライアントの設定

1. markdown-mcp.jsを使用してClaude Desktopを設定します（上記の手順を参照）。
2. markdown-mcp-gemini.jsを使用してGemini CLIを設定します（上記の手順を参照）。
3. 両方のクライアントはそれぞれのサーバーファイルを使用できます - 各クライアントに最適化されています。

使用例

Claude Desktopでの使用：

Use markdown-mcp to extract content from https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html

Gemini CLIでの使用：

# 抽出してファイルに保存する
gemini "Use get_page_markdown to extract content from https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html and save as result.md"

# 保存せずに抽出するだけ
gemini "Use get_page_markdown to extract content from https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html"

パフォーマンスに関する考慮事項

• サーバーは複数の同時リクエストを効率的に処理します。
• 各リクエストはセキュリティのために新しいブラウザコンテキストを使用します。
• メモリ使用量は同時リクエストの数に応じてスケーリングします。
• 典型的な応答時間：リクエストごとに5 - 15秒。

テスト

このサーバーは、以下を含むさまざまなWebサイトで正しく動作することがテストおよび検証されています。

• ✅ ドキュメントサイト (Confluent、GitHubなど)
• ✅ ニュース記事 およびブログ記事
• ✅ コード例付きの技術ドキュメント
• ✅ 電子商取引ページ および製品説明
• ✅ 動的コンテンツを持つJavaScriptが多いサイト

テスト済みの機能

• ✅ 見出し、段落、テキストコンテンツを抽出します。
• ✅ 太字と斜体のフォーマットを保持します。
• ✅ コードブロックとインラインコードを処理します。
• ✅ リスト（順序付きと順序なし）を処理します。
• ✅ 適切なフォーマットでテーブルを抽出します。
• ✅ ナビゲーションとフッターコンテンツをフィルタリングします。
• ✅ 画像とリンクを処理します（有効にした場合）。
• ✅ MCPプロトコルのリクエストに応答します。
• ✅ 動的コンテンツとJavaScriptが多いサイトで動作します。

手動テスト

以下のコマンドを実行して、サーバーを手動でテストすることができます。

# シンプルなURLでテストする
node -e "
const { spawn } = require('child_process');
const server = spawn('node', ['markdown-mcp.js'], { stdio: ['pipe', 'pipe', 'pipe'] });
const request = {
  jsonrpc: '2.0',
  id: 1,
  method: 'tools/call',
  params: {
    name: 'get_page_markdown',
    arguments: { url: 'https://example.com' }
  }
};
server.stdin.write(JSON.stringify(request) + '\n');
setTimeout(() => {
  server.kill();
  console.log('Test completed');
}, 10000);
"

サポートされるWebサイト

このMCPサーバーは、以下のWebサイトでうまく動作します。

• ドキュメントサイト：Confluent、GitHub、GitLabなど。
• ニュースとブログ：ほとんどの主要なニュースサイトとブログ。
• 技術コンテンツ：Stack Overflow、Medium、Dev.to。
• 電子商取引：製品ページと説明。
• 学術コンテンツ：研究論文と記事。
• ソーシャルメディア：Twitterスレッド、LinkedIn記事。

パフォーマンス

• 典型的な抽出時間：ページの複雑さに応じて5 - 15秒。
• メモリ使用量：抽出ごとに約50 - 100MB。
• サポートされるコンテンツサイズ：最大数MBのテキストコンテンツ。
• 同時リクエスト：複数のリクエストを効率的に処理します。

要件

• Node.js：バージョン18以上
• Playwright：Chromiumブラウザ（自動的にインストールされます）
• メモリ：少なくとも512MBの利用可能なRAM
• ディスク容量：Playwrightブラウザ用に約200MB

セキュリティに関する考慮事項

• サーバーはセキュリティのためにヘッドレスモードで実行されます。
• クッキーや永続的なデータは保存されません。
• 各リクエストは新しいブラウザコンテキストを使用します。
• ネットワークリクエストはタイムアウト設定によって制限されます。
• 機密データはログに記録されず、保存されません。

コントリビュート方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. 十分にテストします。
5. プルリクエストを送信します。

サポート

問題が発生した場合は、以下の手順を試してください。

1. 上記のトラブルシューティングセクションを確認します。
2. すべての要件が満たされていることを確認します。
3. まずシンプルなURLでテストします。
4. Claude Desktopのログでエラーメッセージを確認します。
5. 詳細なエラー情報を含めて問題を報告します。