Wiki.js MCP Server

Wiki.js MCP 服务

一款功能全面的 Model Context Protocol（MCP）服务，用于集成 Wiki.js，支持分层文档和 Docker 部署。非常适合管理多个代码仓库和大规模文档的组织。

🚀 快速入门

1. 环境设置

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

# Copy environment template
cp config/example.env .env

# Edit .env with your credentials:
# - Set POSTGRES_PASSWORD to a secure password
# - Update other settings as needed

2. Docker 部署（推荐）

# Start Wiki.js with Docker
docker-compose -f docker.yml up -d

Wiki.js 将在 http://localhost:3000 上提供服务

在 Web 界面中完成初始设置

3. 设置 MCP 服务

# Install Python dependencies
./setup.sh

# Update .env with Wiki.js API credentials:
# - Get API key from Wiki.js admin panel  
# - Set WIKIJS_TOKEN in .env file

# Test the connection
./test-server.sh

# Start MCP server
# (not needed for AI IDEs like Cursor, simply click on the refresh icon after editing mcp.json
# and you should see a green dot with all tools listed. In existing open Cursor windows,
# this refresh is necessary in order to use this MCP)
./start-server.sh

4. 配置 Cursor MCP

将以下内容添加到 ~/.cursor/mcp.json：

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

🎯 增强的 Cursor 集成

文档优先开发的全局规则

在 Cursor 中添加这些全局规则，以便在编码前自动查阅文档：

Before writing any code, always:
1. Search existing documentation using wikijs_search_pages to understand current patterns and architecture
2. Check for related components, functions, or modules that might already exist
3. If documentation exists for similar functionality, follow the established patterns and naming conventions
4. If no documentation exists, create it using wikijs_create_page or wikijs_create_nested_page before implementing
5. Always update documentation when making changes using wikijs_sync_file_docs
6. For new features, use wikijs_create_repo_structure to plan the documentation hierarchy first

这些规则可确保 AI 助手能够：

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

Cursor 使用技巧

# Before starting a new feature
"Search the documentation for authentication patterns before implementing login"

# When creating components
"Create nested documentation under frontend-app/components before building the React component"

# For API development
"Check existing API documentation and create endpoint docs using the established structure"

# During refactoring
"Update all related documentation pages for the files I'm about to modify"

🚀 主要功能

📁 分层文档

• 代码仓库级组织：为多个代码仓库创建结构化文档
• 嵌套页面创建：自动建立父子关系
• 自动整理：按文件类型智能分类（组件、API、工具等）
• 企业级可扩展性：支持数百个代码仓库和数千个文件

🔧 核心功能

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

🐳 Docker 设置

• 一条命令即可部署：使用 PostgreSQL 完成 Wiki.js 的完整设置
• 持久化存储：容器重启后数据仍然保留
• 运行状况检查：自动监控服务
• 可用于生产环境：针对开发和部署进行了优化

🔍 智能功能

• 代码仓库上下文检测：自动检测 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 - 显示仓库映射和上下文

🏢 企业级用例

多仓库文档

Company Documentation/
├── frontend-web-app/
│   ├── Overview/
│   ├── Components/
│   │   ├── Button/
│   │   ├── Modal/
│   │   └── Form/
│   ├── API Integration/
│   └── Deployment/
├── backend-api/
│   ├── Overview/
│   ├── Controllers/
│   ├── Models/
│   └── Database Schema/
├── mobile-app/
│   ├── Overview/
│   ├── Screens/
│   └── Native Components/
└── shared-libraries/
    ├── UI Components/
    ├── Utilities/
    └── Type Definitions/

自动整理

系统会智能地对文件分类：

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

📚 使用示例

创建仓库文档

# Create complete repository structure
await wikijs_create_repo_structure(
    "My Frontend App",
    "Modern React application with TypeScript",
    ["Overview", "Components", "API", "Testing", "Deployment"]
)

# Create nested component documentation
await wikijs_create_nested_page(
    "Button Component",
    "# Button Component\n\nReusable button with multiple variants...",
    "my-frontend-app/components"
)

# Auto-organize entire project
await wikijs_create_documentation_hierarchy(
    "My Project",
    [
        {"file_path": "src/components/Button.tsx"},
        {"file_path": "src/api/users.ts"},
        {"file_path": "src/utils/helpers.ts"}
    ],
    auto_organize=True
)

文档管理

# Clean up and manage documentation
# Preview what would be deleted (safe)
preview = await wikijs_delete_hierarchy(
    "old-project",
    delete_mode="include_root",
    confirm_deletion=False
)

# Delete entire deprecated project
await wikijs_delete_hierarchy(
    "old-project",
    delete_mode="include_root", 
    confirm_deletion=True
)

# Batch delete test pages
await wikijs_batch_delete_pages(
    path_pattern="*test*",
    confirm_deletion=True
)

# Clean up orphaned file mappings
await wikijs_cleanup_orphaned_mappings()

⚙️ 配置

环境变量

# Docker Database Configuration
POSTGRES_DB=wikijs
POSTGRES_USER=wikijs
POSTGRES_PASSWORD=your_secure_password_here

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

# Alternative: Username/Password
WIKIJS_USERNAME=your_username
WIKIJS_PASSWORD=your_password

# Database & Logging
WIKIJS_MCP_DB=./wikijs_mappings.db
LOG_LEVEL=INFO
LOG_FILE=wikijs_mcp.log

# Repository Settings
REPOSITORY_ROOT=./
DEFAULT_SPACE_NAME=Documentation

身份验证选项

1. JWT 令牌（推荐）：使用 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      # Main MCP server implementation
├── config/
│   └── example.env             # Configuration template
├── docker.yml                  # Docker Compose setup
├── pyproject.toml              # Poetry dependencies
├── requirements.txt            # Pip dependencies
├── setup.sh                    # Environment setup script
├── start-server.sh             # MCP server launcher
├── test-server.sh              # Interactive testing script
├── HIERARCHICAL_FEATURES.md    # Hierarchical documentation guide
├── DELETION_TOOLS.md           # Deletion and cleanup guide
├── LICENSE                     # MIT License
└── README.md                   # This file

依赖项

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

🔍 故障排除

Docker 问题

# Check containers
docker-compose -f docker.yml ps

# View logs
docker-compose -f docker.yml logs wiki
docker-compose -f docker.yml logs postgres

# Reset everything
docker-compose -f docker.yml down -v
docker-compose -f docker.yml up -d

连接问题

# Check Wiki.js is running
curl http://localhost:3000/graphql

# Verify authentication
./test-server.sh

# Debug mode
export LOG_LEVEL=DEBUG
./start-server.sh

常见问题

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

📚 文档

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

🤝 参与贡献

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 文件。

🙏 致谢

• Wiki.js Team：感谢提供出色的文档平台
• MCP Protocol：感谢提供标准化的 AI 集成框架
• FastMCP：感谢提供 Python MCP SDK

---

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