Pmwiki MCP

🚀 PmWiki MCP 服務器

PmWiki MCP 服務器用於通過 MCP（模型上下文協議）將大語言模型（LLM）與 PmWiki 進行對接。它藉助 MCP 協議和 SSE（服務器發送事件）傳輸，實現了 LLM 與 PmWiki 實例的交互。

法文版本

🚀 快速開始

使用 Docker Compose（Docker Hub 鏡像）

最簡單的方法是使用 Docker Hub 上發佈的鏡像：

docker compose up -d

使用 Docker Compose（本地構建）

如果你想在本地構建鏡像：

1. 編輯 docker-compose.yml 文件，註釋掉 image: 行，然後取消註釋 build: . 行。
2. 運行以下命令：

docker compose up -d --build

直接使用 Docker

不使用 Docker Compose 時，你可以直接運行：

docker run -d \
  --name pmwiki-mcp-server \
  -p 3000:3000 \
  -v /path/to/your/wiki.d:/wiki_data:ro \
  -e WIKI_DIR=/wiki_data \
  kcofoni/pmwiki-mcp:latest

服務器將在 http://localhost:3000 （或者從網絡中的其他機器訪問 http://vmtest:3000） 上可用。

驗證

# 檢查服務器是否正在運行
docker logs pmwiki-mcp-server

# 測試 SSE 連接
curl -N http://localhost:3000/sse

✨ 主要特性

架構

服務器使用 MCP 協議和 SSE 傳輸，使 LLM 能夠與你的 PmWiki 實例進行交互。

端點

• GET /sse：用於建立雙向通信的 SSE 連接。
• POST /messages/：接收來自 MCP 客戶端的消息。

客戶端配置

Claude Desktop

將以下配置添加到你的 Claude Desktop 配置文件中：

• 在 macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json
• 在 Windows 上：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pmwiki": {
      "command": "mcp-proxy",
      "args": [
        "--transport=sse",
        "http://vmtest:3000/sse"
      ]
    }
  }
}

⚠️ 重要提示

• vmtest 是運行 MCP 服務器 Docker 容器的機器的主機名。
• 請根據實際情況替換 vmtest：
  • 如果 Claude Desktop 和服務器在同一臺機器上運行，請使用 localhost。
  • 如果在其他機器上運行，請使用運行 Docker 容器的機器的主機名或 IP 地址（例如 192.168.1.100:3000/sse）。
• 必須安裝 mcp-proxy 工具（通常隨 Claude Desktop 提供）。
• 代理負責處理 Claude Desktop 和 MCP 服務器之間的 SSE 連接。

可用功能

連接成功後，你的 LLM 將可以訪問以下內容：

資源

• 所有維基頁面都作為資源公開，其 URI 為 pmwiki://Group.PageName。

工具

1. search_wiki：在所有頁面中搜索文本。
   • 參數：
     • query（必需）：要搜索的文本。
     • case_sensitive（可選）：是否區分大小寫搜索（默認：false）。
2. read_page：讀取頁面的完整內容。
   • 參數：
     • page_name（必需）：頁面名稱（例如 Main.HomePage 或 Main/HomePage）。
3. list_pages：列出所有維基頁面。
   • 參數：
     • group（可選）：按組過濾。

📦 安裝指南

Wiki 目錄掛載

PmWiki 目錄從主機掛載到 Docker 容器：

volumes:
  - /home/docker/appdata/html/wiki.d:/wiki_data:ro

⚠️ 重要提示

• /home/docker/appdata/html/wiki.d 是主機上的路徑，這只是一個示例，你需要根據實際情況進行調整。
• 請將此路徑替換為你實際的 PmWiki wiki.d 目錄的路徑。
• 為了安全起見，該卷以只讀模式掛載（:ro）。
• /wiki_data 是容器內部的路徑，請勿修改。

Docker Hub

該鏡像在 Docker Hub 上公開可用：

• 倉庫：kcofoni/pmwiki-mcp
• 最新標籤：kcofoni/pmwiki-mcp:latest
• 穩定版本：kcofoni/pmwiki-mcp:v1.0.2

拉取最新版本：

docker pull kcofoni/pmwiki-mcp:latest

拉取特定版本：

docker pull kcofoni/pmwiki-mcp:v1.0.2

🔧 技術細節

技術架構

• 語言：Python 3.11
• Web 框架：Starlette + Uvicorn
• 協議：基於 SSE 的 MCP
• 頁面格式：PmWiki（wiki.d/ 中的文件）

日誌

# 即時查看日誌
docker logs -f pmwiki-mcp-server

# 查看最後 50 行日誌
docker logs --tail 50 pmwiki-mcp-server

故障排除

服務器無法啟動

檢查維基目錄是否存在：

ls -la /home/docker/appdata/html/wiki.d

頁面出現 404 錯誤

使用 list_pages 工具查看所有可用頁面。必須使用確切的 PmWiki 文件名格式（例如文件名為 Main.HomePage 而不是 Main/HomePage）。

SSE 連接失敗

檢查端口 3000 是否正確暴露：

docker ps | grep pmwiki-mcp-server

💻 使用示例

基礎用法

以下是使用 Docker Compose 啟動服務器的示例：

docker compose up -d

高級用法

如果你想在本地構建鏡像並啟動服務器，可以使用以下命令：

docker compose up -d --build

📚 詳細文檔

文件結構

pmwiki-mcp/
├── pmwiki_mcp_server.py    # MCP 服務器
├── requirements.txt         # Python 依賴項
├── Dockerfile              # Docker 鏡像
├── docker-compose.yml      # Docker Compose 配置
├── README.md              # 本文檔（英文）
└── README_fr.md           # 法文文檔

代碼修改

修改代碼後，使用以下命令重新構建並啟動容器：

docker compose up -d --build

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。