MCP-Server-Template

🏆 Webcrawl MCP Server - 本番環境対応の実装 🏆

███╗   ███╗ ██████╗██████╗     ██████╗ ███████╗███████╗
████╗ ████║██╔════╝██╔══██╗    ██╔══██╗██╔════╝██╔════╝
██╔████╔██║██║     ██████╔╝    ██████╔╝█████╗  █████╗  
██║╚██╔╝██║██║     ██╔═══╝     ██╔══██╗██╔══╝  ██╔══╝  
██║ ╚═╝ ██║╚██████╗██║         ██║  ██║███████╗██║     
╚═╝     ╚═╝ ╚═════╝╚═╝         ╚═╝  ╚═╝╚══════╝╚═╝     
     
   100% MCP COMPLIANT | ABORT CAPABLE ✅

包括的なウェブクロール機能を提供する、本番環境対応の Model Context Protocol（MCP）サーバーです。インテリジェントなコンテンツ抽出、ツール実行の中断機能、MCP 仕様への完全準拠を特長としています。

🎯 主な機能

• ✅ MCP に 100％準拠 - MCP 仕様 v2024-11-05 に完全準拠
• 🛑 中断機能 - 長時間実行される処理を安全にキャンセル
• 🧠 スマートクロール - 関連性スコアリングを用いたインテリジェントなコンテンツ抽出
• 🔗 リンク分析 - 高度なリンク抽出と分類
• 🗺️ サイトマップ生成 - 包括的なウェブサイト構造のマッピング
• 🔍 コンテンツ検索 - ページ内コンテンツの検索と分析
• 🌐 ウェブ検索 - ウェブ検索機能を統合
• ⏰ ユーティリティツール - 日時および一般的なユーティリティ機能

� クイックスタート

Docker を使用する（推奨）

docker-compose up --build

ローカルでの開発

# Install dependencies
npm install
cd mcp-service && npm install

# Start development server
npm run dev

🛠️ 利用可能なツール

ツール	説明	主な機能
crawl	基本的なウェブクロール	ページコンテンツ、メタデータ、リンク
smartCrawl	インテリジェントなクロール	関連性スコアリング、スマートナビゲーション
extractLinks	リンク抽出	分類、フィルタリング、分析
searchInPage	コンテンツ検索	テキスト照合、コンテキスト抽出
generateSitemap	サイトマップ作成	サイト構造、階層のマッピング
webSearch	ウェブ検索	複数の検索エンジンに対応、結果のフィルタリング
getDateTime	日時ユーティリティ	タイムゾーン対応、書式設定

🛑 中断機能

すべてのツールで安全にキャンセルできます。

# Start a tool execution
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"crawl","arguments":{"url":"https://example.com"}},"id":"tool-123"}'

# Abort the execution
curl -X POST http://localhost:3000/tools/abort/tool-123

📋 MCP プロトコルのサポート

• ✅ セッション管理：Mcp-Session-Id ヘッダーを使用したセッションライフサイクル全体に対応
• ✅ プロトコルの初期化：適切な initialize と notifications/initialized のハンドシェイク
• ✅ ケイパビリティのネゴシエーション：プロトコルバージョンのネゴシエーションを完全にサポート
• ✅ トランスポートプロトコル：最新の Streamable HTTP と SSE に対応
• ✅ 標準メソッド：tools/list、tools/call、resources/list、resources/read
• ✅ エラー処理：すべての JSON-RPC 2.0 エラーコードを適切に実装

🏗️ アーキテクチャ

mcp-service/
├── src/
│   ├── services/tools/         # Self-contained tool implementations
│   │   ├── BaseTool.ts         # Base class with abort functionality
│   │   ├── CrawlTool.ts        # Web crawling
│   │   ├── SmartCrawlTool.ts   # Intelligent crawling
│   │   ├── ExtractLinksTool.ts # Link extraction
│   │   ├── SearchInPageTool.ts # Page search
│   │   ├── SitemapTool.ts      # Sitemap generation
│   │   ├── WebSearchTool.ts    # Web search
│   │   └── DateTimeTool.ts     # Date/time utilities
│   ├── mcp/                    # MCP protocol implementation
│   ├── routes/                 # HTTP endpoints
│   ├── controllers/            # Request handlers
│   └── config/                 # Configuration management

🔧 設定

環境変数

# Copy template and configure
cp .env-template .env

# Key settings
PORT=3000                       # Server port
MCP_TRANSPORT=streamable-http   # Transport protocol
PUPPETEER_HEADLESS=true        # Browser mode
LOG_LEVEL=info                 # Logging level

開発環境と本番環境

• 開発環境：レート制限を緩和（毎分 1000 リクエスト）
• 本番環境：より厳しい制限を適用した安全なデフォルト設定

🧪 テスト

# Run MCP compliance tests
npm run test:mcp-compliance

# Run all tests
npm test

# Build project
npm run build

### Running Locally

1. Install dependencies:
   ```bash
   npm install

2. mcp-service ディレクトリに移動します。

   cd mcp-service
   npm install
   

3. 環境変数を定義します（「設定」を参照）。
4. サーバーをビルドして起動します。

   npm run build
   npm start
   
   # Or for development with auto-reload:
   npm run dev
   ## 🌐 API Endpoints
   

Endpoint	Protocol	Description
POST /mcp	MCP Streamable HTTP	Recommended - Modern JSON-RPC over HTTP
GET /mcp	HTTP	Server info and connection details
POST /tools/abort/:toolId	REST	Abort tool execution
GET /api/health	REST	Health check
GET /api/version	REST	Version information

📝 Usage Examples

Basic Tool Execution

# Execute crawl tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "crawl",
      "arguments": {
        "url": "https://example.com",
        "maxPages": 3
      }
    },
    "id": 1
  }'

クエリを使用したスマートクロール

# Execute smart crawl with relevance scoring
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "smartCrawl",
      "arguments": {
        "url": "https://example.com",
        "query": "pricing information",
        "maxPages": 5,
        "relevanceThreshold": 3
      }
    },
    "id": 2
  }'

中断機能を使用したツール実行

# Start tool execution
TOOL_ID=$(curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"generateSitemap","arguments":{"url":"https://large-site.com","maxPages":100}},"id":"sitemap-1"}' \
  | jq -r '.result.toolId')

# Abort if needed
curl -X POST http://localhost:3000/tools/abort/$TOOL_ID

📚 ドキュメント

ドキュメント	説明
MCP_API.md	API リファレンスと使用例の完全版
TOOL_ABORT.md	ツール中断機能ガイド
OVERVIEW.md	アーキテクチャと設計の概要
CODE_STRUCTURE.md	開発者向けドキュメント
CONTRIBUTING.md	コントリビューションガイドライン

🤝 コントリビューション

コントリビューションを歓迎します。ガイドラインについては、CONTRIBUTING.md をご覧ください。

📄 ライセンス

このプロジェクトは、Creative Commons Attribution-NonCommercial 4.0 International License（CC BY-NC 4.0）の下でライセンスされています。次のことができます。

• 共有 — あらゆる媒体や形式で素材を複製、再配布すること
• 改変 — 素材をリミックス、変換、加工すること

ただし、次の条件に従う必要があります。

• 表示 — 適切なクレジットを表示すること
• 非営利 — 素材を商用目的で使用しないこと

ライセンスの全文については、LICENSE.md ファイルをご覧ください。

---

MCP コミュニティのために ❤️ を込めて作成 "name": "smartCrawl", "description": "ウェブサイトをクロールし、Markdown 形式のコンテンツを返します。特定のクエリへの回答を含む場合もあります。", "parameterDescription": "クロールする URL、任意のクロールパラメーター、および任意のクエリ。", "returnDescription": "成功ステータス、元の URL、Markdown コンテンツ、任意のエラーメッセージを含むオブジェクト。", "endpoint": "/api/tools/smartCrawl" }, { "name": "extractLinks", "description": "ウェブページからリンクを抽出し、分類します。", "parameterDescription": "リンクを抽出する URL。", "returnDescription": "内部リンクと外部リンク、およびその説明を含むオブジェクト。", "endpoint": "/api/tools/extractLinks" }, { "name": "sitemapGenerator", "description": "ウェブサイトのページをクロールして、サイトマップを生成します。", "parameterDescription": "サイトマップ生成のためにクロールする URL。深度と maxPages は任意です。", "returnDescription": "生成されたサイトマップの構造を含むオブジェクト。", "endpoint": "/api/tools/sitemapGenerator" }, { "name": "searchInPage", "description": "ウェブページ内の特定のコンテンツを検索します。", "parameterDescription": "検索対象の URL と検索語。", "returnDescription": "検索結果と一致項目を含むオブジェクト。", "endpoint": "/api/tools/searchInPage" }, { "name": "webSearch", "description": "ウェブ検索を実行し、結果を抽出します。", "parameterDescription": "検索クエリと結果の最大件数。", "returnDescription": "タイトル、説明、URL を含む検索結果のオブジェクト。", "endpoint": "/api/tools/webSearch" }, { "name": "dateTime", "description": "さまざまな形式で現在の日付と時刻の情報を取得します。", "parameterDescription": "任意のタイムゾーンパラメーター。", "returnDescription": "複数の形式で現在の日付と時刻を含むオブジェクト。", "endpoint": "/api/tools/dateTime" } ] }

### Direct Tool Execution

#### Crawl Tool
```bash
curl -X POST http://localhost:${PORT:-3000}/api/tools/crawl \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "maxPages": 3,
    "depth": 1,
    "strategy": "bfs",
    "captureScreenshots": true,
    "captureNetworkTraffic": false,
    "waitTime": 2000
  }'

スマートクロールツール（Markdown 出力）

curl -X POST http://localhost:${PORT:-3000}/api/tools/smartCrawl \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "query": "What is this site about?",
    "maxPages": 2,
    "depth": 1
  }'

リンク抽出ツール

curl -X POST http://localhost:${PORT:-3000}/api/tools/extractLinks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'

サイトマップ生成ツール

curl -X POST http://localhost:${PORT:-3000}/api/tools/sitemapGenerator \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "maxPages": 10,
    "depth": 2
  }'

ページ内検索ツール

curl -X POST http://localhost:${PORT:-3000}/api/tools/searchInPage \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "searchTerm": "contact information"
  }'

ウェブ検索ツール

curl -X POST http://localhost:${PORT:-3000}/api/tools/webSearch \
  -H "Content-Type: application/json" \
  -d '{
    "query": "MCP protocol specification",
    "maxResults": 5
  }'

日時ツール

curl -X POST http://localhost:${PORT:-3000}/api/tools/dateTime \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "UTC"
  }'

環境変数

• PORT（デフォルト：3000）：MCP サーバーのポートです。
• NODE_ENV（デフォルト：development）：環境モード（development または production）です。
• MCP_NAME、MCP_VERSION、MCP_DESCRIPTION：MCP サーバーの識別情報です。
• CRAWL_DEFAULT_MAX_PAGES（デフォルト：10）：クロールするページのデフォルト最大数です。
• CRAWL_DEFAULT_DEPTH（デフォルト：3）：デフォルトのクロール深度です。
• CRAWL_DEFAULT_STRATEGY（デフォルト：bfs）：デフォルトのクロール戦略（bfs|dfs|bestFirst）です。
• CRAWL_DEFAULT_WAIT_TIME（デフォルト：1000）：リクエスト間のデフォルト待機時間（ミリ秒）です。
• LOG_LEVEL（デフォルト：info）：ログレベル（debug|info|warn|error）です。
• CACHE_TTL（デフォルト：3600）：キャッシュの TTL（秒）です。
• MAX_REQUEST_SIZE（デフォルト：10mb）：HTTP ペイロードの最大サイズです。
• CORS_ORIGINS（デフォルト：*）：CORS で許可するオリジンです。
• RATE_LIMIT_WINDOW（デフォルト：900000）：レート制限の時間枠（ミリ秒、15 分）です。
• RATE_LIMIT_MAX_REQUESTS（デフォルト：100）：レート制限の時間枠内で許可されるリクエストの最大数です。
• PUPPETEER_EXECUTABLE_PATH（任意）：Puppeteer 用の Chrome/Chromium 実行ファイルのカスタムパスです。
• PUPPETEER_SKIP_DOWNLOAD（デフォルト：false）：インストール時の Chromium の自動ダウンロードをスキップします。

設定

すべての設定は src/config ディレクトリに集約されており、システムの各側面に応じた個別のモジュールで管理されています。

• appConfig.ts：アプリケーションのコア設定
• mcpConfig.ts：MCP サーバー固有の設定
• securityConfig.ts：セキュリティ関連の設定
• crawlConfig.ts：ウェブクロールのデフォルトパラメーター

主要コンポーネント

• サーバー：Express と MCP の機能を統合した統一サーバー実装です。
• ルート：API エンドポイントと MCP エンドポイント用に、それぞれ別のファイルに整理されています。
• SimpleMcpServer：MCP の検出とツール呼び出しのロジックを実装します。
• コントローラー：ビジネスロジックを処理する toolController と resourceController です。
• ツール：BaseTool 抽象クラスを拡張した、自己完結型のツール実装です。
  • CrawlTool：コンテンツ抽出機能を備えた基本的なウェブクロール
  • SmartCrawlTool：Markdown 出力とクエリ対応のインテリジェントなクロール
  • ExtractLinksTool：ウェブページからリンクを抽出し、分類
  • SitemapTool：クロールしたコンテンツからサイトマップを生成
  • SearchInPageTool：ウェブページ内の特定コンテンツを検索
  • WebSearchTool：検索結果の抽出機能を備えたウェブ検索
  • DateTimeTool：日付と時刻のユーティリティ関数
• 設定：モジュール固有の設定を備えた一元管理の設定システムです。
• MCP トランスポート：最新の Streamable HTTP と従来の SSE トランスポート方式の両方に対応します。
• ツールアーキテクチャ：各ツールが独自のブラウザー管理、クロールロジック、エラー処理を備えており、完全に自己完結しています。

ウェブクロール機能

この MCP サーバーには、自己完結型のクロールツールが包括的に含まれています。各ツールには、ブラウザー管理機能と専用の機能が統合されています。

ツールベースのアーキテクチャ

• 自己完結型の設計：各ツールが独自の Puppeteer ブラウザーインスタンスとクロールロジックを管理します。
• BaseTool 抽象クラス：標準化されたエラー処理を備え、すべてのツールで共有される共通機能です。
• 独立した動作：ツールは共有サービスへの依存なしに動作するため、信頼性が向上します。

利用可能なツール

CrawlTool

• 基本的なウェブクロール：ウェブページからテキストコンテンツとテーブルを抽出します。
• 複数の戦略：BFS、DFS、ベストファーストによるクロール方式です。
• スクリーンショットの取得：ページ全体のスクリーンショットを任意で取得できます。
• コンテンツ抽出：非表示要素をスキップし、表示されているテキストをインテリジェントに抽出します。

SmartCrawlTool

• Markdown 出力：カスタム書式ルールを適用して HTML を Markdown に変換します。
• クエリベースのクロール：特定のクエリに基づいて対象を絞り、コンテンツを抽出します。
• スマートなコンテンツ検出：さまざまなコンテンツタイプの関連性をより高度にスコアリングします。
• 構造化出力：適切な見出しとセクションを備えた、整形済みの Markdown を出力します。

ExtractLinksTool

• リンクの分類：内部リンクと外部リンクを分けて抽出します
• リンク分析：リンクテキスト、URL、説明を抽出します
• 包括的なカバレッジ：ページコンテンツ内のクリック可能なリンクをすべて見つけます

SitemapTool

• サイトマップの生成：クロールしたコンテンツから構造化されたサイトマップを作成します
• 階層構造：ページを階層と関連性に基づいて整理します
• 深さの設定：サイトマップ生成時のクロールの深さを制御します

SearchInPageTool

• コンテンツ検索：Web ページ内の特定の用語やフレーズを検索します
• コンテキストの抽出：検索に一致した箇所の周辺コンテキストを提示します
• 関連性のスコアリング：関連性に基づいて検索結果を順位付けします

WebSearchTool

• Web 検索との統合：Web 検索を実行し、結果を抽出します
• 結果の処理：検索結果からタイトル、説明、URL を抽出します
• 結果数の設定：返される結果の数を制御します

DateTimeTool

• 時刻ユーティリティ：現在の日付と時刻を複数の形式で取得します
• タイムゾーンのサポート：異なるタイムゾーン間で時刻を変換します
• 書式設定オプション：さまざまな日付・時刻形式で出力します

ブラウザー管理の共通機能

• 堅牢なエラー処理：適切なエラー処理とフォールバックの仕組みにより、ブラウザーの初期化を改善します
• Chrome パスのカスタマイズ：PUPPETEER_EXECUTABLE_PATH によるカスタム Chrome／Chromium 実行ファイルのパスをサポートします
• リソース管理：各ツールでブラウザーを自動的にクリーンアップし、接続を管理します
• 独立したインスタンス：分離性を高めるため、各ツールが独自のブラウザーインスタンスを管理します

コンテンツ抽出（全ツール共通）

• テキスト抽出：非表示要素やスクリプトを除外し、表示テキストをインテリジェントに抽出します
• Markdown 変換：テーブルやコードブロックのカスタムルールを使用して、HTML を Markdown に変換します
• テーブル抽出：キャプションをサポートし、HTML テーブルを構造化して抽出します
• スクリーンショットの取得：ページ全体のスクリーンショットを任意で取得できます
• リンク処理：内部リンクと外部リンクを抽出して分類します

クロール戦略

• 幅優先探索（BFS）：体系的な探索のためのデフォルトの戦略です
• 深さ優先探索（DFS）：サイト構造内のより深い経路を優先します
• 最良優先探索：ヒューリスティックに基づくシンプルなクロール方式です（短い経路を優先）

高度なオプション

• ネットワークトラフィックの監視：クロール中の HTTP リクエストを任意で追跡します
• 複数ページのクロール：深さを制御しながら複数のページをクロールできます
• 待機時間の設定：ページ読み込み間の遅延を設定できます
• スクリーンショットの取得：ページ全体のスクリーンショットを任意で取得し、一時ディレクトリに保存します

エラー耐性

• ブラウザー起動時のフォールバック：ブラウザーを初期化するための複数の方法を用意しています
• 接続の復旧：ブラウザーが切断された場合、自動的に再接続します
• URL の検証：エラー処理を備えた堅牢な URL の解析と検証を行います
• タイムアウトの管理：応答の遅いページで処理が停止しないよう、タイムアウトを設定できます

カスタマイズ

• routes ディレクトリに新しいルートを追加します。
• SimpleMcpServer を変更するか、新しいコントローラーを追加して、MCP の機能を拡張します。
• services/tools ディレクトリにある抽象クラス BaseTool を拡張して、新しいツールを作成します。
• 各ツールは自己完結しており、独立して開発できます。
• config ディレクトリにある環境変数で、パフォーマンスとセキュリティを調整します。

アーキテクチャ図

graph LR
  Client --> Server
  Server --> Router["Routes (API/MCP)"]
  Router --> |SSE| SimpleMcpServer
  Router --> |Streamable HTTP| SimpleMcpServer
  Router --> ApiControllers
  SimpleMcpServer --> Controllers
  Controllers --> Tools["Self-Contained Tools"]
  Tools --> |BaseTool| CrawlTool
  Tools --> |BaseTool| SmartCrawlTool
  Tools --> |BaseTool| ExtractLinksTool
  Tools --> |BaseTool| SitemapTool
  Tools --> |BaseTool| SearchInPageTool
  Tools --> |BaseTool| WebSearchTool
  Tools --> |BaseTool| DateTimeTool

参考資料

• 概要：アーキテクチャと概念の全体像を説明します。
• コード構造：ソースファイルについて詳しく説明します。
• MCP API リファレンス：エンドポイントの仕様と JSON-RPC メソッドを説明します。
• Model Context Protocol SDK：公式 SDK ドキュメントです。
• MCP Transport Models：SSE と Streamable HTTP の詳細です。