JinDaGe - pmwiki-mcp MCP Details

article

README

🚀 PmWiki MCP 服务器

PmWiki MCP 服务器用于通过 MCP（模型上下文协议）将大语言模型（LLM）与 PmWiki 进行对接。它借助 MCP 协议和 SSE（服务器发送事件）传输，实现了 LLM 与 PmWiki 实例的交互。

🚀 快速开始

使用 Docker Compose（Docker Hub 镜像）

最简单的方法是使用 Docker Hub 上发布的镜像：

docker compose up -d

使用 Docker Compose（本地构建）

如果你想在本地构建镜像：

编辑 docker-compose.yml 文件，注释掉 image: 行，然后取消注释 build: . 行。
运行以下命令：

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。

工具

search_wiki：在所有页面中搜索文本。
- 参数：
  - query（必需）：要搜索的文本。
  - case_sensitive（可选）：是否区分大小写搜索（默认：false）。
read_page：读取页面的完整内容。
- 参数：
  - page_name（必需）：页面名称（例如 Main.HomePage 或 Main/HomePage）。
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 文件。

pmwiki-mcp