维基JS MCP服务器

Name: 维基JS MCP服务器
Author: heAdz0r

作者：heAdz0r6 星标更新：2025-05-23

安装使用来源：spider==github.com

项目介绍

技术文档摘要

Wiki.js MCP 服务器

这是一个通过 GraphQL API 与 Wiki.js 集成的 Model Context Protocol (MCP) 服务器。MCP 是由 Anthropic 开发的一个开放协议，使 AI 模型能够安全地与外部服务和工具交互。

该服务器提供了一个统一的接口，用于与 Wiki.js 进行交互，可以被支持 MCP 的各种 AI 代理和工具使用。

功能亮点

页面管理

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

用户管理

列出用户
根据查询搜索用户
创建新用户
更新用户信息

组管理

列出用户组

传输方式

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

快速开始

⚡ 现在就开始？ 请参阅五分钟指南

安装

克隆仓库：

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

运行自动设置：

npm run setup

此脚本会自动：

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

配置

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

# HTTP MCP 服务器端口
PORT=3200

# Wiki.js 的基础 URL（不带 /graphql）
WIKIJS_BASE_URL=http://localhost:3000

# Wiki.js API 令牌
WIKIJS_TOKEN=your_wikijs_api_token_here

编辑 .cursor/mcp.json 文件 并替换 your_wikijs_api_token_here 为您真实的令牌

如何获取 Wiki.js API 令牌：

登录到 Wiki.js 管理面板

前往“API”部分

创建一个具有必要权限的新 API 密钥

将令牌复制到 .env 和 .cursor/mcp.json

运行

HTTP 服务器（推荐）

# 启动主要 HTTP 服务器，支持 Cursor MCP
npm start
# 或
npm run start:http

# 停止服务器
npm run stop

TypeScript 版本

npm run start:typescript

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

npm run server:stdio

开发模式

npm run dev

测试

npm test

编辑器集成

Cursor IDE

⚠️ 重要提示： 没有 .cursor/mcp.json 文件，Cursor 集成将无法工作！

快速设置

启动 HTTP 服务器：

npm start

自动配置设置：

npm run setup:cursor

编辑 .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 令牌（不是占位符！）

验证

设置完成后，带有 mcp_wikijs_* 前缀的工具应出现在 Cursor 中：

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 源代码
│   ├── server.ts          # HTTP 服务器
│   ├── tools.ts           # 工具定义
│   ├── api.ts             # Wiki.js API 客户端
│   ├── types.ts           # 数据类型
│   ├── schemas.ts         # Zod 验证模式
│   └── README.md          # 源代码文档
├── lib/                   # JavaScript 库文件
│   ├── fixed_mcp_http_server.js    # 主要 HTTP 服务器（已编译）
│   ├── mcp_wikijs_stdin.js         # 编辑器直接集成的 STDIN 服务器
│   ├── mcp_client.js               # 示例 MCP 客户端
│   ├── mcp_wrapper.js              # MCP 协议实用工具
│   └── README.md                   # 库文档
├── scripts/               # 管理脚本
│   ├── setup.sh          # 初始设置
│   ├── start_http.sh     # 启动 HTTP 服务器
│   ├── stop_server.sh    # 停止服务器
│   ├── start_typescript.sh # 启动 TypeScript 版本
│   ├── setup_cursor_mcp.sh # Cursor 设置
│   ├── test.sh           # 运行测试
│   ├── test_mcp.js       # 测试 HTTP 服务器
│   ├── test_m_ cp_stdin.js # 测试 STDIN 服务器
│   └── README.md         # 脚本文档
├── .cursor/               # Cursor MCP 配置
│   └── mcp.json          # MCP 配置文件（极其重要！）
├── dist/                  # 编译后的 TypeScript 代码
├── package.json           # 项目元数据
└── README.md             # 主文档

🚨 极其重要： 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 端点

使用示例

// 获取页面列表
{
  "method": "list_pages",
  "params": {
    "limit": 10,
    "orderBy": "TITLE"
  }
}

// 创建新页面
{
  "method": "create_page",
  "params": {
    "title": "新页面",
    "content": "# 标题\n\n内容...",
    "path": "文件夹/新页面"
  }
}

### 搜索页面：
```python
# 在所有内容和元数据中搜索
结果 = await mcp_client.call_tool("search_pages", {
    "query": "魔法系统",
    "limit": 5
})

处理未发布的页面：

# 获取所有页面（包括未发布的）
所有页面 = await mcp_client.call_tool("list_all_pages", {
    "limit": 100,
    "includeUnpublished": True
})

# 仅搜索未发布的页面
未发布 = await mcp_client.call_tool("search_unpublished_pages", {
    "query": "草稿",
    "limit": 10
})

# 检查页面发布状态
状态 = await mcp_client.call_tool("get_page_status", {
    "id": 42
})

# 发布未发布的页面
结果 = await mcp_client.call_tool("publish_page", {
    "id": 42
})

# 强制删除页面（适用于未发布的页面）
结果 = await mcp_client.call_tool("force_delete_page", {
    "id": 42
})

用户管理：

# 列出所有用户
用户 = await mcp_client.call_tool("list_users")

# 根据查询搜索用户
搜索结果 = await mcp_client.call_tool("search_users", {
    "query": "John"
})

# 创建新用户
新用户 = await mcp_client.call_tool("create_user", {
    "email": "john@example.com",
    "name": "John Doe",
    "passwordRaw": "password123",
    "providerKey": "local",
    "groups": [1],
    "mustChangePassword": False,
    "sendWelcomeEmail": True
})

# 更新用户信息
更新用户 = await mcp_client.call_tool("update_user", {
    "id": 1,
    "name": "John Doe 更新"
})

故障排除

连接问题

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

MCP 问题

检查 Node.js 版本（需 >=18.0.0）
确保所有依赖项均已安装
查看服务器日志以查找错误

文档

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

贡献

分叉仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m '添加神奇功能')
推送到分支 (git push origin feature/amazing-feature)
打开拉取请求

许可证

本项目根据 MIT 许可证分发。详情见 LICENSE 文件。

支持

如果这个项目帮助了您，请在 GitHub 上给它一个 ⭐！

有任何疑问？创建一个 Issue 或参考文档。

新特性：自动 URL

搜索阶段

搜索分为四个阶段：

GraphQL API 搜索 - 快速搜索索引内容
元数据搜索 - 搜索标题、路径和页面描述
HTTP 内容搜索 - 通过 HTTP 对页面内容进行深入搜索
强制验证 - 在已知页面上进行回退搜索

使用示例

内容搜索

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

结果：

[
  {
    "id": 103,
    "path": "test/test-page",
    "title": "测试页面",
    "description": "用于展示 Wiki.js API 功能的测试页面",
    "url": "http://localhost:8080/en/test/test-page"
  }
]

标题搜索

{
  "method": "search_pages",
  "params": {
    "query": "找到我",
    "limit": 3
  }
}

结果：

[
  {
    "id": 108,
    "path": "test/test-gemini-mcp",
    "title": "测试 Gemini MCP 页面（找到我）",
    "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 变异支持
重构项目：将 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`

维基JS MCP服务器

项目介绍

技术文档摘要

Wiki.js MCP 服务器

功能亮点

页面管理

用户管理

组管理

传输方式

快速开始

安装

配置

运行

HTTP 服务器（推荐）

TypeScript 版本

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

开发模式

测试

编辑器集成

Cursor IDE

快速设置

关键参数

验证

VS Code（带有 MCP 扩展）

开发

项目结构

可用脚本

设置和构建

运行服务器

开发和测试

API 端点（HTTP 模式）

使用示例

处理未发布的页面：

用户管理：

故障排除

连接问题

MCP 问题

文档

贡献

许可证

相关链接

支持

新特性：自动 URL

搜索阶段

使用示例

内容搜索

标题搜索

新搜索优势

技术细节

HTML 内容处理

变更日志

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

新特性：

改进：

错误修复：

版本 1.2.0 - 国际发行版

国际化：

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

新特性：

可用工具

页面工具