AI导哈

Wiki.js MCP服务器

一个用于通过GraphQL API与Wiki.js交互的MCP服务器，提供页面管理、用户管理和组管理功能，支持HTTP和STDIO传输协议。

  • by heAdz0r
  • TypeScript
  • 本地部署
  • 14 星标
  • 更新于
在 GitHub 查看 heAdz0r/wikijs-mcp-server

使用说明

Wiki.js MCP服务器

用于通过GraphQL API集成Wiki.js的模型上下文协议（MCP）服务器。

📖 描述

该项目提供了一个MCP服务器，用于通过GraphQL API与Wiki.js进行交互。MCP（模型上下文协议）是Anthropic开发的一种开放协议，它使AI模型能够安全地与外部服务和工具交互。

该服务器为使用Wiki.js提供了一个统一的接口，可供支持MCP的各种AI代理和工具使用。

✨ 特性

📄 页面管理

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

👥 用户管理

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

🔧 组管理

  • 列出用户组

🌐 运输

  • 标准输入输出：用于编辑器集成（游标、VS代码）
  • 超文本传输协议：用于web集成和API访问

🚀 快速开始

⚡ 想现在就开始吗？ 看 5分钟指南

安装

  1. 克隆存储库：
git clone https://github.com/heAdz0r/wikijs-mcp-server.git
cd wikijs-mcp-server
  1. 运行自动设置：
npm run setup

此脚本将自动执行以下操作：

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

配置

  1. 编辑 .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
  1. 编辑 .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

🔌 编辑器集成

光标IDE

⚠️ 重要： 没有 .cursor/mcp.json 文件，游标集成将不起作用！

快速设置

  1. 启动HTTP服务器：
npm start
  1. 自动配置设置：
npm run setup:cursor
  1. 编辑 .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" -服务器发送事件的URL
  • WIKIJS_TOKEN -真正的Wiki.js API令牌（不是占位符！）

验证

设置后，工具 mcp_wikijs_* 前缀应出现在游标中：

  • mcp_wikijs_list_pages()
  • mcp_wikijs_search_pages()
  • mcp_wikijs_get_page()
  • 还有其他人。..

VS代码（带MCP扩展名）

添加到VS代码设置：

{
  "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/mcp.json Cursor集成需要文件！

可用脚本

设置和构建

  • npm run setup -初始项目设置
  • npm run build -构建TypeScript项目
  • npm run setup: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": "john@example.com",
    "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. 检查服务器日志是否有错误

📚 文档

🤝 贡献

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

📄 许可证

该项目在MIT许可证下分发。看 许可证 文件以获取详细信息。

🔗 实用链接

⭐ 支持

如果这个项目对你有帮助，请给它一个⭐ 在GitHub上！

有问题吗？创建一个 问题 或参考文档。

🆕 新功能：自动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变异支持
  • 重组项目：将JavaScript文件移动到 lib/ 更好的组织目录

🐛 Bug修复：

  • 修复了通过标准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 列出用户组 无

相关 MCP