pmwiki-mcp

PmWiki MCP 服务

用于连接大模型与 PmWiki 的 MCP（Model Context Protocol）服务。

法语版 / French version

架构

该服务使用 MCP 协议和 SSE（Server-Sent Events）传输方式，让大模型能够与您的 PmWiki 实例交互。

端点

• GET /sse：用于建立双向通信的 SSE 连接
• POST /messages/：接收来自 MCP 客户端的消息

入门指南

使用 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 访问）。

验证

# Check that the server is running
docker logs pmwiki-mcp-server

# Test the SSE connection
curl -N http://localhost:3000/sse

客户端配置

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 连接

可用功能

连接后，您的大模型将能够使用：

资源

• 所有 Wiki 页面都将作为资源公开，URI 为 pmwiki://Group.PageName

工具

1. search_wiki：搜索所有页面中的文本

   • 参数：
     • query（必填）：要搜索的文本
     • case_sensitive（可选）：是否区分大小写（默认值：false）

2. read_page：读取页面的完整内容

   • 参数：
     • page_name（必填）：页面名称（例如，Main.HomePage 或 Main/HomePage）

3. list_pages：列出所有 Wiki 页面

   • 参数：
     • 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/ 中的文件）

日志

# View logs in real-time
docker logs -f pmwiki-mcp-server

# Last 50 lines
docker logs --tail 50 pmwiki-mcp-server

故障排除

服务无法启动

检查 Wiki 目录是否存在：

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

页面出现 404 错误

使用 list_pages 工具查看所有可用页面。必须使用准确的 PmWiki 文件名格式（例如，文件名应为 Main.HomePage，而不是 Main/HomePage）。

SSE 连接失败

检查端口 3000 是否已正确映射：

docker ps | grep pmwiki-mcp-server

开发

文件结构

pmwiki-mcp/
├── pmwiki_mcp_server.py    # MCP server
├── requirements.txt         # Python dependencies
├── Dockerfile              # Docker image
├── docker-compose.yml      # Docker Compose configuration
├── README.md              # This documentation (English)
└── README_fr.md           # French documentation

修改代码

修改代码后：

docker compose up -d --build

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。