mcp-plesk-dev-docs

mcp-plesk-dev-docs

メモ

この MCP サーバーは、エクステンション開発者向けにドキュメントを統合検索します。AI を使って稼働中の Plesk サーバーを管理したい場合は、公式の Plesk MCP サーバーをご覧ください。

Apple Silicon でサブ秒のレイテンシーを実現するよう最適化された、Plesk ドキュメント全体を対象とする最先端（SOTA）のセマンティック検索です。

---

このプロジェクトの目的

Plesk のドキュメントは、管理者ガイド、REST API リファレンス、CLI リファレンス、PHP SDK、JS SDK の5つの情報源に分散しています。エクステンション開発に関する質問に1つ答えるだけでも、多くの場合、これらをすべて手作業で検索し、結果を相互参照したうえで、関連するセクションを見落としていないか確認する必要があります。

このサーバーは5つの情報源すべてを取り込み、多言語モデルで埋め込みを生成し、単一の search_plesk_unified MCP ツールを提供します。ハイブリッド検索（ベクトル検索＋FTS）、Reciprocal Rank Fusion（RRF）、Cross-Encoder による再ランキングを使用し、ミリ秒単位で高精度な結果を返します。

---

アーキテクチャとパフォーマンス

flowchart TD
    Client["MCP Client\n(Claude Desktop / Cursor / etc.)"]

    Client -->|"search_plesk_unified(query)"| Server

    subgraph Server["FastMCP Server · Modular Architecture"]
        direction TB
        Main["Bootstrap · server/main.py"]
        Life["Lifecycle Hooks · server/lifecycle.py"]
        Tools["MCP Tools · server/mcp_app.py"]

        Main --> Life --> Tools
    end

    subgraph Pipeline["Retrieval Pipeline"]
        direction TB
        E["1 · Embed query\n(Hardware-accelerated)"]
        S["2 · Hybrid Search\nVector (LanceDB) + FTS (Tantivy)"]
        R["3 · RRF Merge + Rerank\n(MiniLM-L4-v2)"]
        N["4 · Neighbor Expansion\n(Context Enrichment)"]
        A["5 · AI Synthesis\n(sampling-enabled)"]
        E --> S --> R --> N --> A
    end

    subgraph Store["LanceDB Vector & FTS Store"]
        direction LR
        G["Guide"]
        A_["API"]
        C["CLI"]
        P["PHP Stubs"]
        J["JS SDK"]
    end

    Tools --> Pipeline
    S <--> Store

パフォーマンスベンチマーク（2026-05-04）

MPS アクセラレーションとメモリ常駐テーブルのキャッシュを利用し、Apple Silicon（M2/M3）向けに最適化されています。

プロファイル	埋め込みモデル	HR@5	MRR@5	平均レイテンシー	推定 RAM
light	BAAI/bge-small	100.0%	0.917	1.007 s	~200 MB
medium	BAAI/bge-base	100.0%	0.917	~0.60s	~600 MB
full-tq	BAAI/bge-m3	75.0%	0.750	~0.40s	~1300 MB

LanceDB の接続キャッシュを有効にした Apple M2 Pro で測定した指標です。

---

主な機能

• 単一インスタンスロック： PID ベースのロックにより、複数の MCP クライアントや IDE セッションが同時にサーバーを起動しようとした場合でも、LanceDB への同時アクセスを防ぎます。
• サブ秒のハイブリッド検索： ベクトル検索と Tantivy FTS を組み合わせ、RAM にキャッシュされたテーブル接続により瞬時に検索結果を取得します。
• AST 対応のチャンク分割： tree-sitter を使用し、PHP、JS、TS のドキュメントでクラスやメソッドの境界を維持します。
• TurboQuant による高速化： full-tq プロファイル向けの高速な4ビット量子化検索により、大規模モデルのレイテンシーを10分の1に削減します。
• 近傍検索： 隣接するチャンク（前後）を自動的に取得し、根拠として完全なコンテキストを提供します。
• マクロコンテキスト要約： SummaryCache を使用して、ファイル単位の目的の要約を各チャンクに挿入します。
• AI 生成の回答： 検索結果から、構造化されたインライン引用 [1]、[2] を付けた簡潔な回答を生成します。

---

MCP コンポーネント

このサーバーはツール、プロンプト、リソースを提供します。詳しくは docs/mcp-components.md をご覧ください。

主要なツール

ツール	説明
search_plesk_unified	RRF と Cross-Encoder による再ランク付けを使用したハイブリッド検索です。
get_file_content	指定したドキュメントファイルの全内容を取得します。
resolve_references	指定したシンボルまたはトピックを参照するすべてのファイルを検索します。
refresh_knowledge	ソースを再取得し、インデックスを更新します（差分更新）。
trigger_index_sync	バックグラウンドのインデックス作成ジョブを開始します。
daemon_health	準備状況、ハードウェアアクセラレーション（MPS/CUDA）、レイテンシ統計を確認します。

リソース

• plesk://toc/api - API ドキュメントの目次です。
• plesk://toc/cli - CLI リファレンスの目次です。
• plesk://toc/guide - 拡張機能ガイドの目次です。
• plesk://toc/php-stubs - PHP クラスの階層リストです。

---

🚀 インストールとセットアップ

このサーバーは PyPI で公開され、MCP Registry に掲載されているため、実行にあたってリポジトリをクローンする必要はありません！

オプション 1：uvx ですぐに実行する（推奨）

数秒でサーバーを実行または統合できます。

1. Claude Desktop に追加する

サーバーの設定を claude_desktop_config.json に追加します（通常、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json にあります）。

{
  "mcpServers": {
    "plesk-dev-docs": {
      "command": "uvx",
      "args": ["mcp-plesk-dev-docs"]
    }
  }
}

2. Cursor で設定する

Settings > Features > MCP に移動し、+ Add New MCP Server をクリックします。

• 名前： plesk-dev-docs
• 種類： command
• コマンド： uvx mcp-plesk-dev-docs

---

オプション 2：ローカル開発環境のセットアップ（手動ビルド）

ソースコードを変更したり、ベンチマークを実行したり、データベースのマイグレーションを管理したりする場合に利用します。

クイックセットアップ（推奨）：

git clone https://github.com/barateza/mcp-plesk-dev-docs.git
cd mcp-plesk-dev-docs
./install.sh          # Linux / macOS
# powershell -ExecutionPolicy Bypass -File install.ps1   # Windows

手動セットアップ：

git clone https://github.com/barateza/mcp-plesk-dev-docs.git
cd mcp-plesk-dev-docs
uv pip install -e ".[dev]"

2. 初回のインデックス作成を実行する： オフラインのベクトルデータベースと全文検索インデックスを生成します。

   uv run python -m mcp_plesk_dev_docs.server.main refresh_knowledge
   

3. サーバーを起動する：

   uv run python -m mcp_plesk_dev_docs.server.main
   

---

設定

環境変数を .env に設定します。

PLESK_MODEL_PROFILE=light       # light | medium | full-tq
PLESK_ENABLE_SAMPLING=true     # AI-Synthesized answers
PLESK_DAEMON_AUTO_WARMUP=true  # Preload models on startup
PLESK_INDEX_SUMMARIES=true     # Enable file-level summaries
OPENROUTER_API_KEY=sk-or-v1-...

---

ドキュメント

• docs/benchmarks.md - レイテンシと品質に関する詳細なレポートです。
• docs/mcp-components.md - ツールとリソースの完全なリファレンスです。
• docs/turboquant.md - 4 ビット量子化の内部仕様です。

---

ライセンス

MIT。LICENSE を参照してください。

所有権と免責事項

これは Gilson Siqueira による個人プロジェクトです。Plesk または WebPros International GmbH との公式な提携関係はなく、承認やサポートも受けていません。Plesk は WebPros International GmbH の商標です。

Plesk 所有の成果物に関する重要なお知らせ

このリポジトリの一部は、Plesk International GmbH（「Plesk」）との契約に基づいて開発されたものですが、その対象として明示されている場合に限ります。上記の MIT ライセンスは、リポジトリの所有者がライセンスを付与する権限を持つ素材にのみ適用されます。Plesk が所有するファイルまたはディレクトリがある場合は、NOTICE に記載されています。特定のファイルのライセンスについて確認が必要な場合は、Plesk に問い合わせるか、Plesk 所有のファイルに MIT ライセンスが適用されると判断する前に法律の専門家に相談してください。

---

Plesk 拡張機能の開発を効率化するために作られました。