内容
# mcp-plesk-dev-docs
[](https://www.python.org/downloads/)
[](https://pypi.org/project/mcp-plesk-dev-docs/)
[](https://pypi.org/project/mcp-plesk-dev-docs/)
[](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.barateza/mcp-plesk-dev-docs)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](https://github.com/psf/black)
[](https://github.com/astral-sh/ruff)
[](https://lobehub.com/mcp/barateza-mcp-plesk-unified)
> [!NOTE]
> 本 MCP 服务器为扩展开发者提供统一的文档搜索功能。如果您正在寻找通过 AI 管理实时 Plesk 服务器的方法，请参阅 [官方 Plesk MCP 服务器](https://talk.plesk.com/threads/mcp-server-extension-for-plesk-wp-toolkit.389895/).
**最先进的（SOTA）语义搜索，覆盖整个 Plesk 文档表面，针对 Apple Silicon 进行了亚秒级延迟优化。**
---
## 为什么存在
Plesk 文档分散在五个独立的来源：管理员指南、REST API 参考、CLI 参考、PHP SDK 和 JS SDK。回答一个扩展开发问题通常意味着手动搜索所有这些来源，交叉引用结果，但仍然可能会错过相关的部分。
该服务器摄取所有五个来源，将它们嵌入多语言模型，并公开一个名为 `search_plesk_unified` 的 MCP 工具。它使用混合搜索（向量 + 全文搜索）、互惠排名融合（RRF）和跨编码器重新排序，以毫秒为单位提供高精度结果。
---
## 架构与性能
```mermaid
flowchart TD
Client["MCP 客户端\n（Claude Desktop / Cursor / 等）"]
Client -->|"search_plesk_unified(query)"| 服务器
subgraph 服务器["FastMCP 服务器 · 模块化架构"]
direction TB
Main["引导 · server/main.py"]
Life["生命周期钩子 · server/lifecycle.py"]
Tools["MCP 工具 · server/mcp_app.py"]
Main --> Life --> Tools
end
subgraph 管道["检索管道"]
direction TB
E["1 · 嵌入查询\n（硬件加速）"]
S["2 · 混合搜索\n向量（LanceDB）+ 全文搜索（Tantivy）"]
R["3 · RRF 合并 + 重新排序\n（MiniLM-L4-v2）"]
N["4 · 邻域扩展\n（上下文丰富）"]
A["5 · AI 合成\n（启用采样）"]
E --> S --> R --> N --> A
end
subgraph 存储["LanceDB 向量和全文搜索存储"]
direction LR
G["指南"]
A_["API"]
C["CLI"]
P["PHP 存根"]
J["JS SDK"]
end
Tools --> 管道
S <--> 存储
```
### 性能基准（2026-05-04）
针对 Apple Silicon（M2/M3）使用 MPS 加速和内存驻留表缓存进行优化。
| 配置文件 | 嵌入模型 | HR@5 | MRR@5 | 平均延迟 | 估计 RAM |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **`light`** | BAAI/bge-small | **100.0%** | **0.917** | **1.007 秒** | ~200 MB |
| **`medium`** | BAAI/bge-base | **100.0%** | **0.917** | **~0.60秒** | ~600 MB |
| **`full-tq`** | BAAI/bge-m3 | 75.0% | 0.750 | **~0.40秒** | ~1300 MB |
*指标在配备 M2 Pro 的 Apple 设备上测量，并启用 LanceDB 连接缓存。*
---
## 主要功能
- **单实例锁定：** 基于 PID 的锁定，防止多个 MCP 客户端或 IDE 会话在同时启动服务器时访问 LanceDB。
- **亚秒级混合搜索：** 结合向量 + Tantivy 全文搜索，**RAM 缓存表连接**，实现即时检索。
- **AST 感知分块：** 使用 `tree-sitter` 尊重 PHP、JS 和 TS 文档中的类和方法的边界。
- **TurboQuant 加速：** `full-tq` 配置文件的快速 4 位量化搜索，提供 10 倍降低的大模型延迟。
- **邻域检索：** 自动获取相邻块（前/后），为接地提供完整的上下文。
- **宏上下文摘要：** 使用 `SummaryCache` 将文件级目的摘要注入每个块中。
- **AI 合成答案：** 从搜索结果中生成简洁的答案，并附有结构化的内联引用 `[1]`、`[2]`。
---
## MCP 组件
本服务器提供工具、提示和资源。有关完整参考，请参见 **[docs/mcp-components.md](docs/mcp-components.md)**。
### 主要工具
| 工具 | 描述 |
|---|---|
| `search_plesk_unified` | 具有 RRF 和跨编码器重新排序的混合搜索。 |
| `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](https://pypi.org/project/mcp-plesk-dev-docs/) 并在 [MCP 注册表](https://registry.modelcontextprotocol.io) 中列出，您甚至不需要克隆存储库即可运行它！
### 选项 1：通过 `uvx` 立即运行（推荐）
您可以立即运行或集成服务器。
#### 1. 添加到 Claude Desktop
将服务器配置添加到您的 `claude_desktop_config.json`（通常位于 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"plesk-dev-docs": {
"command": "uvx",
"args": ["mcp-plesk-dev-docs"]
}
}
}
```
#### 2. 在 Cursor 中配置
前往 **设置 > 功能 > MCP**，点击 **+ 添加新的 MCP 服务器**：
- **名称：** `plesk-dev-docs`
- **类型：** `command`
- **命令：** `uvx mcp-plesk-dev-docs`
---
### 选项 2：本地开发者设置（手动构建）
如果您想修改源代码、运行基准测试或管理数据库迁移：
**快速引导（推荐）：**
```bash
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
```
**手动设置：**
```bash
git clone https://github.com/barateza/mcp-plesk-dev-docs.git
cd mcp-plesk-dev-docs
uv pip install -e ".[dev]"
```
2. **运行初始索引：**
生成离线向量数据库和全文搜索索引：
```bash
uv run python -m mcp_plesk_dev_docs.server.main refresh_knowledge
```
3. **启动服务器：**
```bash
uv run python -m mcp_plesk_dev_docs.server.main
```
---
## 配置
在 `.env` 中设置环境变量：
```env
PLESK_MODEL_PROFILE=light # light | medium | full-tq
PLESK_ENABLE_SAMPLING=true # AI 合成答案
PLESK_DAEMON_AUTO_WARMUP=true # 启动时预加载模型
PLESK_INDEX_SUMMARIES=true # 启用文件级摘要
OPENROUTER_API_KEY=sk-or-v1-...
```
---
## 文档
- **[docs/benchmarks.md](docs/benchmarks.md)** - 详细的延迟和质量报告。
- **[docs/mcp-components.md](docs/mcp-components.md)** - 完整的工具和资源参考。
- **[docs/turboquant.md](docs/turboquant.md)** - 4 位量化内部实现。
---
## 许可证
MIT。参见 [LICENSE](LICENSE)。
## 所有权与免责声明
这是 Gilson Siqueira 的个人项目。它与 Plesk 或 WebPros International GmbH 没有官方关联、认可或支持。Plesk 是 WebPros International GmbH 的商标。
### 关于 Plesk 拥有的交付成果的重要通知
存储库的某些部分是在合同下为 Plesk International GmbH（“Plesk”）开发的，仅在特别标识为此类时才如此。上述 MIT 许可证仅适用于存储库所有者有权许可的材料。如果您需要确保特定文件的许可，请在依赖 MIT 许可证用于 Plesk 拥有文件之前联系 Plesk 或寻求法律顾问。
---
*构建使 Plesk 扩展开发更快。*
<!-- mcp-name: io.github.barateza/mcp-plesk-dev-docs -->
