Wikijs Mcp Server

Wiki.js MCP 服务

通过 GraphQL API 集成 Wiki.js 的 Model Context Protocol（MCP）服务。

📖 描述

本项目提供一个 MCP 服务，通过 GraphQL API 与 Wiki.js 交互。MCP（Model Context Protocol）是由 Anthropic 开发的一种开放协议，可让 AI 模型安全地与外部服务和工具交互。

该服务为 Wiki.js 提供统一的操作接口，供各种支持 MCP 的 AI Agent 和工具使用。

✨ 功能

📄 页面管理

• 按 ID 获取 Wiki.js 页面
• 按 ID 获取页面内容
• 按排序选项列出页面
• 按查询条件搜索页面
• 创建新页面
• 更新现有页面
• 删除页面
• 🆕 列出所有页面，包括未发布的页面
• 🆕 搜索未发布的页面
• 🆕 强制删除页面（包括未发布的页面）
• 🆕 获取页面发布状态
• 🆕 发布未发布的页面

👥 用户管理

• 列出用户
• 按查询条件搜索用户
• 创建新用户
• 更新用户信息

🔧 群组管理

• 列出用户群组

🌐 传输方式

• STDIO：用于编辑器集成（Cursor、VS Code）
• HTTP：用于 Web 集成和 API 访问

🚀 快速开始

⚡ 想要立即开始？ 请参阅5 分钟指南

安装

1. 克隆仓库：

git clone https://github.com/heAdz0r/wikijs-mcp-server.git
cd wikijs-mcp-server

2. 运行自动设置：

npm run setup

此脚本将自动：

• 安装依赖项
• 根据 example.env 创建 .env 文件
• 构建 TypeScript 代码

配置

3. 编辑 .env 文件并指定 Wiki.js 设置：

# Port for HTTP MCP server
PORT=3200

# Base URL for Wiki.js (without /graphql)
WIKIJS_BASE_URL=http://localhost:3000

# Wiki.js API token
WIKIJS_TOKEN=your_wikijs_api_token_here

4. 编辑 .cursor/mcp.json 文件，将 your_wikijs_api_token_here 替换为真实令牌

如何获取 Wiki.js API 令牌：

1. 登录 Wiki.js 管理面板
2. 前往“API”部分
3. 创建具有所需权限的新 API 密钥
4. 将令牌复制到 .env 和 .cursor/mcp.json 中

📦 运行

HTTP 服务（推荐）

# Start main HTTP server with Cursor MCP support
npm start
# or
npm run start:http

# Stop server
npm run stop

TypeScript 版本

npm run start:typescript

STDIO 模式（用于直接集成编辑器）

npm run server:stdio

开发模式

npm run dev

测试

npm test

🔌 编辑器集成

Cursor IDE

**⚠️ 重要：**没有 .cursor/mcp.json 文件，Cursor 集成将无法运行！

快速设置

1. 启动 HTTP 服务：

npm start

2. 自动配置：

npm run setup:cursor

3. 编辑 .cursor/mcp.json 并指定真实令牌：

{
  "mcpServers": {
    "wikijs": {
      "transport": "http",
      "url": "http://localhost:3200/mcp",
      "events": "http://localhost:3200/mcp/events",
      "cwd": ".",
      "env": {
        "WIKIJS_BASE_URL": "http://localhost:3000",
        "WIKIJS_TOKEN": "your_real_wiki_js_token_here"
      }
    }
  }
}

关键参数

• transport: "http" - 必须使用 HTTP 传输方式
• url: "http://localhost:3200/mcp" - JSON-RPC 的准确 URL
• events: "http://localhost:3200/mcp/events" - Server-Sent Events 的 URL
• WIKIJS_TOKEN - 真实的 Wiki.js API 令牌（不能使用占位符！）

验证

设置完成后，Cursor 中应显示带有 mcp_wikijs_* 前缀的工具：

• mcp_wikijs_list_pages()
• mcp_wikijs_search_pages()
• mcp_wikijs_get_page()
• 以及其他工具……

VS Code（使用 MCP 扩展）

添加到 VS Code 设置中：

{
  "mcp.servers": {
    "wikijs": {
      "command": "node",
      "args": ["lib/mcp_wikijs_stdin.js"],
      "cwd": "/path/to/wikijs-mcp"
    }
  }
}

🛠 开发

项目结构

wikijs-mcp-server/
├── src/                    # TypeScript source code
│   ├── server.ts          # HTTP server
│   ├── tools.ts           # Tool definitions
│   ├── api.ts             # Wiki.js API client
│   ├── types.ts           # Data types
│   ├── schemas.ts         # Zod validation schemas
│   └── README.md          # Source code documentation
├── lib/                   # JavaScript library files
│   ├── fixed_mcp_http_server.js    # Main HTTP server (compiled)
│   ├── mcp_wikijs_stdin.js         # STDIN server for editors
│   ├── mcp_client.js               # Demo MCP client
│   ├── mcp_wrapper.js              # MCP protocol utilities
│   └── README.md                   # Library documentation
├── scripts/               # Management scripts
│   ├── setup.sh          # Initial setup
│   ├── start_http.sh     # Start HTTP server
│   ├── stop_server.sh    # Stop HTTP server
│   ├── start_typescript.sh # Start TypeScript version
│   ├── setup_cursor_mcp.sh # Cursor setup
│   ├── test.sh           # Run tests
│   ├── test_mcp.js       # Test HTTP server
│   ├── test_mcp_stdin.js # Test STDIN server
│   └── README.md         # Scripts documentation
├── .cursor/               # Cursor MCP configuration
│   └── mcp.json          # MCP configuration file (CRITICALLY IMPORTANT!)
├── dist/                  # Compiled TypeScript code
├── package.json           # Project metadata
└── README.md             # Main documentation

**🚨 极其重要：**Cursor 集成必须使用 .cursor/mcp.json 文件！

可用脚本

设置和构建

• npm run setup - 初始项目设置
• npm run build - 构建 TypeScript 项目
• npm run setup:cursor - 设置 Cursor 集成

运行服务

• npm start / npm run start:http - HTTP MCP 服务（端口 3200）
• npm run stop - 停止所有 MCP 服务
• npm run start:typescript - TypeScript 版服务（端口 8000）
• npm run server:stdio - 用于直接集成的 STDIO 版本

开发和测试

• npm run dev - 带热重载的开发模式
• npm run demo - 功能演示
• npm test - 运行测试
• npm run client - 运行演示客户端

API 端点（HTTP 模式）

• GET /tools - 可用工具列表
• GET /health - 服务运行状况检查
• POST /mcp - MCP JSON-RPC 端点

使用示例

// Get list of pages
{
  "method": "list_pages",
  "params": {
    "limit": 10,
    "orderBy": "TITLE"
  }
}

// Create new page
{
  "method": "create_page",
  "params": {
    "title": "New Page",
    "content": "# Title\n\nContent...",
    "path": "folder/new-page"
  }
}

### Search for pages:
```python
# Search in all content and metadata
result = await mcp_client.call_tool("search_pages", {
    "query": "magic system",
    "limit": 5
})

处理未发布页面：

# Get all pages including unpublished ones
all_pages = await mcp_client.call_tool("list_all_pages", {
    "limit": 100,
    "includeUnpublished": True
})

# Search only unpublished pages
unpublished = await mcp_client.call_tool("search_unpublished_pages", {
    "query": "draft",
    "limit": 10
})

# Check page publication status
status = await mcp_client.call_tool("get_page_status", {
    "id": 42
})

# Publish an unpublished page
result = await mcp_client.call_tool("publish_page", {
    "id": 42
})

# Force delete page (works with unpublished pages)
result = await mcp_client.call_tool("force_delete_page", {
    "id": 42
})

用户管理：

# List all users
users = await mcp_client.call_tool("list_users")

# Search users by query
search_result = await mcp_client.call_tool("search_users", {
    "query": "John"
})

# Create new user
new_user = await mcp_client.call_tool("create_user", {
    "email": "[email protected]",
    "name": "John Doe",
    "passwordRaw": "password123",
    "providerKey": "local",
    "groups": [1],
    "mustChangePassword": false,
    "sendWelcomeEmail": true
})

# Update user information
updated_user = await mcp_client.call_tool("update_user", {
    "id": 1,
    "name": "John Doe Updated"
})

🐛 故障排除

连接问题

1. 确保 Wiki.js 正在运行且可以访问
2. 检查 WIKIJS_BASE_URL 是否正确
3. 验证 API 令牌是否有效

MCP 问题

1. 检查 Node.js 版本（需要 >=18.0.0）
2. 确保已安装所有依赖项
3. 检查服务日志中的错误

📚 文档

• 源代码文档 - TypeScript 源代码结构
• 库文档 - JavaScript 库文件
• 脚本文档 - 所有管理脚本的说明
• 更新日志 - 发布和更新日志
• 许可证 - 项目使用条款

🤝 贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 创建 Pull Request

📄 许可证

本项目根据 MIT License 分发。详情请参阅 LICENSE 文件。

🔗 实用链接

• Wiki.js - Wiki.js 官方网站
• Model Context Protocol - MCP 规范
• Anthropic - MCP 协议开发者
• GraphQL - API 查询语言

⭐ 支持

如果这个项目对你有帮助，请在 GitHub 上点亮一颗 ⭐！

有疑问？请创建一个 Issue 或参阅文档。

🆕 新功能：自动 URL

搜索阶段

搜索分为 4 个阶段：

1. GraphQL API 搜索 - 快速搜索已建立索引的内容
2. 元数据搜索 - 搜索标题、路径和页面描述
3. HTTP 内容搜索 - 通过 HTTP 深入搜索页面内容
4. 强制验证 - 对已知页面进行回退搜索

使用示例

内容搜索

{
  "method": "search_pages",
  "params": {
    "query": "ZELEBOBA",
    "limit": 5
  }
}

结果：

[
  {
    "id": 103,
    "path": "test/test-page",
    "title": "Test Page",
    "description": "Test page to demonstrate Wiki.js API capabilities",
    "url": "http://localhost:8080/en/test/test-page"
  }
]

标题搜索

{
  "method": "search_pages",
  "params": {
    "query": "find me",
    "limit": 3
  }
}

结果：

[
  {
    "id": 108,
    "path": "test/test-gemini-mcp",
    "title": "Test Gemini MCP Page (find me)",
    "url": "http://localhost:8080/en/test/test-gemini-mcp"
  }
]

新搜索功能的优势

• ✅ 即使 API 权限有限也能找到页面 - 使用 HTTP 回退方式
• ✅ 多层搜索 - 结合多种策略
• ✅ 内容搜索 - 查找页面内的文本
• ✅ 元数据搜索 - 标题、路径、描述
• ✅ 回退方法 - 确保能找到已知页面
• ✅ 正确的 URL - 所有结果都包含可直接使用的链接

技术详情

HTML 内容处理

系统会使用以下方法自动从 HTML 中提取文本：

• 在 <template slot="contents"> 块中搜索
• 清理 HTML 标签和实体
• 回退到完整页面内容

当 GraphQL API 权限有限时，系统会：

• 切换到 HTTP 方法获取内容
• 直接请求 HTML 页面
• 保留所有页面元数据

📝 更新日志

版本 1.3.0 - 未发布页面管理（最新）

🆕 新功能：

• list_all_pages - 获取所有页面，包括未发布页面
• search_unpublished_pages - 专门搜索未发布页面
• force_delete_page - 增强删除功能，可处理未发布页面
• get_page_status - 检查任意页面的发布状态
• publish_page - 通过编程方式发布未发布页面

🔧 改进：

• 增强服务 API，新增用于管理未发布页面的路由
• 改进页面删除操作的错误处理
• 全面支持用于高级页面操作的 GraphQL mutation
• 重新组织项目结构：将 JavaScript 文件移至 lib/ 目录，以便更好地组织代码

🐛 错误修复：

• 修复了通过标准 API 访问未发布页面的问题
• 改进了管理员级别操作的身份验证处理

版本 1.2.0 - 国际版

🌍 国际化：

• 文档已完整翻译为英文
• README.md 和 QUICK_START.md 现已提供英文版本
• 为拓展国际市场做好准备

版本 1.1.0 - 搜索与用户管理增强

✨ 功能：

• 智能多方式页面搜索（GraphQL + 内容 + 元数据）
• 用户管理工具（创建、更新、搜索）
• 群组管理功能
• 改进 HTML 页面的内容提取

🛠️ 可用工具

📄 页面工具

工具名称	描述	参数
get_page	根据 ID 获取页面信息	id: number
get_page_content	根据 ID 获取页面内容	id: number
list_pages	按排序方式列出页面	limit?: number, orderBy?: string
search_pages	根据查询内容搜索页面	query: string, limit?: number
create_page	创建新页面	title: string, content: string, path: string, description?: string, tags?: string[]
update_page	更新现有页面	id: number, content: string
delete_page	删除页面	id: number
list_all_pages	🆕 列出所有页面，包括未发布页面	limit?: number, orderBy?: string, includeUnpublished?: boolean
search_unpublished_pages	🆕 仅搜索未发布页面	query: string, limit?: number
force_delete_page	🆕 强制删除页面（适用于未发布页面）	id: number
get_page_status	🆕 获取页面发布状态	id: number
publish_page	🆕 发布未发布的页面	id: number

👥 用户工具

工具名称	描述	参数
list_users	列出所有用户	无
search_users	按查询条件搜索用户	query: string
create_user	创建新用户	email: string, name: string, passwordRaw: string, providerKey?: string, groups?: number[], mustChangePassword?: boolean, sendWelcomeEmail?: boolean
update_user	更新用户信息	id: number, name: string

🔗 群组工具

工具名称	描述	参数
list_groups	列出用户群组	无