Wiki.js MCP 服务器

一个全面的模型上下文协议（MCP）服务器，用于与Wiki.js集成，支持分层文档和Docker部署。非常适合管理多个存储库和大规模文档的组织。

🚀 快速开始

1. 环境设置

首先，克隆此仓库并设置环境变量：

# 复制环境模板
cp config/example.env .env

# 使用您的凭据编辑 .env 文件：
# - 将 POSTGRES_PASSWORD 设置为安全密码
# - 根据需要更新其他设置

2. Docker 部署（推荐）

# 使用 Docker 启动 Wiki.js
docker-compose -f docker.yml up -d

Wiki.js 可以在 http://localhost:3000 访问

在 Web 界面中完成初始设置

3. 设置 MCP 服务器

# 安装 Python 依赖项
./setup.sh

# 在 .env 中更新 Wiki.js API 凭证：
# - 从 Wiki.js 管理面板获取 API 密钥
# - 在 .env 文件中设置 WIKIJS_TOKEN

# 测试连接
./test-server.sh

# 启动 MCP 服务器
# （对于像 Cursor 这样的AI IDE，无需执行此步骤，只需在编辑 mcp.json 后点击刷新图标，
# 您应该能看到绿色点并列出所有工具。在已打开的 Cursor 窗口中，此刷新是必要的，
# 才能使用此 MCP）
./start-server.sh

4. 配置 Cursor MCP

添加到您的 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "wikijs": {
      "command": "/path/to/wiki-js-mcp/start-server.sh"
    }
  }
}

🎯 增强的 Cursor 集成

文档优先开发的全局规则

在 Cursor 中添加这些全局规则，以自动利用文档进行编码前的操作：

编写任何代码之前：
1. 使用 wikijs_search_pages 查找现有文档，了解当前模式和架构
2. 检查是否存在相关的组件、函数或模块
3. 如果存在类似功能的文档，请遵循已建立的模式和命名约定
4. 如果没有文档，请先使用 wikijs_create_page 或 wikijs_create_nested_page 创建文档，然后再实现
5. 在进行更改时始终更新文档，使用 wikijs_sync_file_docs
6. 对于新功能，使用 wikijs_create_repo_structure 先规划文档层次结构

这些规则确保您的AI助手会：

• ✅ 在提出实现建议前检查文档
• ✅ 遵循现有的模式和约定
• ✅ 自动维护最新的文档
• ✅ 为新功能创建结构化的文档
• ✅ 避免重复现有功能

使用 Cursor 的提示

# 开始新功能前
"在实现登录前搜索认证模式的文档"

# 创建组件时
"在构建React组件前，在frontend-app/components下创建嵌套文档"

# 开发API时
"检查现有的API文档，并使用已建立的结构创建端点文档"

# 在重构期间
"更新我即将修改的所有相关文档页面"

🚀 主要特性

📁 分层文档

• 存储库级别的组织：为多个存储库创建结构化文档
• 嵌套页面创建：自动创建父-子关系
• 自动组织：根据文件类型（组件、API、实用工具等）智能分类
• 企业可扩展性：处理数百个存储库和数千个文件

🔧 核心功能

• GraphQL API 集成：完全兼容 Wiki.js v2+
• 文件到页面映射：源代码和文档之间的自动链接
• 代码结构分析：提取类、函数和依赖关系
• 批量操作：同时更新多个页面
• 变更跟踪：监控文件修改并同步文档

🐳 Docker 设置

• 一键部署：完整的 Wiki.js 设置，包括 PostgreSQL
• 持久存储：数据在容器重启后仍然存在
• 健康检查：自动服务监控
• 生产就绪：优化了开发和部署

🔍 智能功能

• 存储库上下文检测：自动检测 Git 存储库
• 内容生成：从代码结构自动生成文档
• 搜索集成：在整个分层内容中进行全文搜索
• 健康监控：连接状态和错误处理

📊 MCP 工具（总计21个）

🏗️ 分层文档工具

1. wikijs_create_repo_structure - 创建完整的存储库文档结构
2. wikijs_create_nested_page - 创建具有层级路径的页面
3. wikijs_get_page_children - 导航父-子页面关系
4. wikijs_create_documentation_hierarchy - 自动组织项目文件到文档

📝 核心页面管理

5. wikijs_create_page - 创建新页面（现在支持父级）
6. wikijs_update_page - 更新现有页面
7. wikijs_get_page - 获取页面内容和元数据
8. wikijs_search_pages - 按文本搜索页面（修复了 GraphQL 问题）

🗑️ 删除及清理工具

9. wikijs_delete_page - 通过ID或路径删除特定页面
10. wikijs_batch_delete_pages - 批量删除，带模式匹配和安全检查
11. wikijs_delete_hierarchy - 删除整个页面层次结构，多种模式
12. wikijs_cleanup_orphaned_mappings - 清理孤立的文件到页面映射

🗂️ 组织与结构

13. wikijs_list_spaces - 列出顶级文档空间
14. wikijs_create_space - 创建新的文档空间
15. wikijs_manage_collections - 管理页面集合

🔗 文件集成

16. wikijs_link_file_to_page - 将源文件链接到文档页面
17. wikijs_sync_file_docs - 同步代码更改到文档
18. wikijs_generate_file_overview - 自动生成文件文档

🚀 批量操作

19. wikijs_bulk_update_project_docs - 批量更新多个页面

🔧 系统工具

20. wikijs_connection_status - 检查 API 连接健康状况
21. wikijs_repository_context - 显示存储库映射和上下文

🏢 企业用例

多存储库文档

公司文档/
├── 前端Web应用/
│   ├── 概述/
│   ├── 组件/
│   │   ├── 按钮/
│   │   ├── 模态框/
│   │   └── 表单/
│   ├── API集成/
│   └── 部署/
├── 后端API/
│   ├── 概述/
│   ├── 控制器/
│   ├── 模型/
│   └── 数据库模式/
├── 移动应用/
│   ├── 概述/
│   ├── 屏幕/
│   └── 本地组件/
└── 共享库/
    ├── UI组件/
    ├── 实用工具/
    └── 类型定义/

自动组织

该系统智能地对文件进行分类：

• 组件：React/Vue组件，UI元素
• API：端点，控制器，路由
• 实用工具：辅助函数，实用工具
• 服务：业务逻辑，外部集成
• 模型：数据模型，类型，模式
• 测试：单元测试，集成测试
• 配置：配置文件，环境设置

📚 使用示例

创建存储库文档

# 创建完整的存储库结构
await wikijs_create_repo_structure(
    "我的前端应用",
    "现代的TypeScript React应用程序",
    ["概述", "组件", "API", "测试", "部署"]
)

# 创建嵌套的组件文档
await wikijs_create_nested_page(
    "按钮组件",
    "# 按钮组件\n\n可复用的按钮，具有多种变体...",
    "my-frontend-app/components"
)

# 自动组织整个项目
await wikijs_create_documentation_hierarchy(
    "我的项目",
    [
        {"file_path": "src/components/Button.tsx"},
        {"file_path": "src/api/users.ts"},
        {"file_path": "src/utils/helpers.ts"}
    ],
    auto_organize=True
)

文档管理

# 清理和管理文档
# 预览将被删除的内容（安全）
preview = await wikijs_delete_hierarchy(
    "旧项目",
    delete_mode="include_root",
    confirm_deletion=False
)

# 删除整个废弃项目
await wikijs_delete_hierarchy(
    "旧项目",
    delete_mode="include_root",
    confirm_deletion=True
)

# 批量删除测试页面
await wikijs_batch_delete_pages(
    path_pattern="*test*",
    confirm_deletion=True
)

# 清理孤立的文件映射
await wikijs_cleanup_orphaned_mappings()

⚙️ 配置

环境变量

# Docker 数据库配置
POSTGRES_DB=wikijs
POSTGRES_USER=wikijs
POSTGRES_PASSWORD=your_secure_password_here

# Wiki.js 连接
WIKIJS_API_URL=http://localhost:3000
WIKIJS_API_KEY=your_jwt_token_here

# 替代方案：用户名/密码
WIKIJS_USERNAME=your_username
WIKIJS_PASSWORD=your_password

# 数据库及日志
WIKIJS_MCP_DB=./wikijs_mappings.db
LOG_LEVEL=INFO
LOG_FILE=wikijs_mcp.log

# 存储库设置
REPOSITORY_ROOT=./
DEFAULT_SPACE_NAME=文档

认证选项

1. JWT Token（推荐）：使用 Wiki.js 管理面板中的 API 密钥
2. 用户名/密码：传统的登录凭证

🔧 技术架构

GraphQL 集成

• 完整的 GraphQL API 支持：原生 Wiki.js v2+ 兼容性
• 优化查询：高效的数据获取和突变
• 错误处理：全面的 GraphQL 错误管理
• 重试逻辑：带有指数退避的自动重试

数据库层

• SQLite 存储：本地文件到页面映射
• 存储库上下文：Git 存储库检测和跟踪
• 变更跟踪：文件哈希监控以检测同步
• 关系管理：父-子页面层次结构

代码分析

• AST 解析：提取 Python 类、函数、导入
• 结构检测：识别代码模式和组织
• 文档生成：自动生成全面概述
• 依赖映射：跟踪导入和关系

📈 性能与可扩展性

• 异步操作：所有 API 调用的非阻塞 I/O
• 批量处理：大型项目的高效批量操作
• 缓存：智能缓存页面关系和元数据
• 连接池：优化的 HTTP 客户端管理

🛠️ 开发

项目结构

wiki-js-mcp/
├── src/
│   └── wiki_mcp_server.py      # 主 MCP 服务器实现
├── config/
│   └── example.env             # 配置模板
├── docker.yml                  # Docker Compose 设置
├── pyproject.toml              # Poetry 依赖项
├── requirements.txt            # Pip 依赖项
├── setup.sh                    # 环境设置脚本
├── start-server.sh             # MCP 服务器启动器
├── test-server.sh              # 交互式测试脚本
├── HIERARCHICAL_FEATURES.md    # 分层文档指南
├── DELETION_TOOLS.md           # 删除和清理指南
├── LICENSE                     # MIT 许可证
└── README.md                   # 此文件

依赖项

• FastMCP：官方 Python MCP SDK
• httpx：用于 GraphQL 的异步 HTTP 客户端
• SQLAlchemy：数据库 ORM 用于映射
• Pydantic：配置和验证
• tenacity：可靠性重试逻辑

🔍 故障排除

Docker 问题

# 检查容器
docker-compose -f docker.yml ps

# 查看日志
docker-compose -f docker.yml logs wiki
docker-compose -f docker.yml logs postgres

# 重置一切
docker-compose -f docker.yml down -v
docker-compose -f docker.yml up -d

连接问题

# 检查 Wiki.js 是否运行
curl http://localhost:3000/graphql

# 验证身份验证
./test-server.sh

# 调试模式
export LOG_LEVEL=DEBUG
./start-server.sh

常见问题

• 端口冲突：如果需要，更改 docker.yml 中的端口 3000
• 数据库问题：移除 postgres_data/ 并重新启动
• API 权限：确保 API 密钥具有管理员权限
• Python 依赖项：运行 ./setup.sh 重新安装

📚 文档

• 分层功能指南 - 企业文档的完整指南
• 删除工具指南 - 全面的删除和清理工具
• 配置示例 - 环境设置

🤝 贡献

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

📄 许可证

本项目采用 MIT 许可证 - 详情参见 LICENSE 文件。

🙏 致谢

• Wiki.js 团队：提供了优秀的文档平台
• MCP 协议：提供了标准化的AI集成框架
• FastMCP：提供了 Python MCP SDK

---

准备好扩展您的文档了吗？ 🚀 从 wikijs_create_repo_structure 开始，构建企业级文档层次结构！使用 Cursor 全局规则确保文档优先开发！📚✨