mcp-plesk-dev-docs

mcp-plesk-dev-docs

说明

此 MCP 服务为扩展开发者提供统一的文档搜索。如果您想通过 AI 管理线上 Plesk 服务，请参阅官方 Plesk MCP Server。

覆盖整个 Plesk 文档体系的先进（SOTA）语义搜索，并针对 Apple Silicon 优化，实现亚秒级延迟。

---

为什么要开发此项目

Plesk 文档分散在五个独立来源中：管理指南、REST API 参考、CLI 参考、PHP SDK 和 JS SDK。要回答一个扩展开发问题，往往需要手动搜索所有文档、交叉比对结果，却仍可能遗漏相关章节。

此服务会摄取全部五个来源，使用多语言模型为其生成嵌入，并提供单一的 search_plesk_unified MCP 工具。它采用混合搜索（向量 + FTS）、倒数排名融合（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，并通过内存缓存的表连接实现即时检索。
• **感知 AST 的分块：**使用 tree-sitter，在 PHP、JS 和 TS 文档中保留类和方法的边界。
• **TurboQuant 加速：**为 full-tq 配置提供快速的 4 位量化搜索，使大型模型的延迟降低 10 倍。
• **邻近内容检索：**自动获取相邻分块（前一块/后一块），为上下文提供完整依据。
• **宏观上下文摘要：**使用 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 或寻求法律意见，再决定是否依据 MIT 许可证使用 Plesk 所有的文件。

---

旨在加快 Plesk 扩展开发。