Requarks Wiki MCP

重新搜索wiki mcp

MCP服务器 Wiki.js 实例，让代理将其用作知识库。

特征：

• 29工具 （19读+10写）涵盖页面、评论、标签、资产、用户、导航和系统信息。
• 搜索、列出和浏览检索工作流程的页面（类似RAG的用法）。
• 按路径或页面ID获取页面内容，查看版本历史记录并还原以前的版本。
• 使用页面树、页面链接图和导航结构浏览网站层次结构。
• 完整的评论系统：列出、阅读、创建、更新和删除页面上的评论。
• 用于媒体文件发现的资产和文件夹浏览。
• 用户上下文：当前用户配置文件和用户搜索。
• 系统诊断：版本信息、站点配置和导航树。
• 标签管理：列出、搜索、更新和删除标签。
• 可选页面创建/更新/删除/移动/还原工具，带有明确的安全门。
• 内置资源：markdown语法指南、Mermaid图指南和API权限指南。
• 使用LLM友好的错误消息键入错误分类。
• GraphQL客户端，具有超时、指数回退重试和请求相关性。
• 安全强化：敏感字段过滤、URL验证、输入长度限制。

需求

• Node.js 20+
• 可访问的Wiki.js主机名
• 具有适当权限的Wiki.js API密钥（JWT）

设置

cp .env.example .env
npm install

配置 .env:

WIKI_BASE_URL=https://your-wiki-hostname
WIKI_API_TOKEN=your_wikijs_api_key_jwt
WIKI_GRAPHQL_PATH=/graphql
WIKI_DEFAULT_LOCALE=en
WIKI_DEFAULT_EDITOR=markdown

# Mutating operations are disabled by default
WIKI_MUTATIONS_ENABLED=false
# Optional extra safety gate for writes. If set, write tools must pass matching confirm.
WIKI_MUTATION_CONFIRM_TOKEN=
WIKI_MUTATION_DRY_RUN=true
# Comma-separated path prefixes without leading slash (empty = no prefix restriction)
WIKI_ALLOWED_MUTATION_PATH_PREFIXES=

# HTTP resilience
WIKI_HTTP_TIMEOUT_MS=15000
WIKI_HTTP_MAX_RETRIES=2

环境变量引用：

Wiki.js先决条件（GraphQL+neneneba API密钥）：

• 此MCP内部使用Wiki.js GraphQL。
• 在Wiki.js管理中，转到 Administration -> API 并启用API访问。
• 创建API密钥并将其设置为 WIKI_API_TOKEN.

MCP客户端配置示例(~/.mcp.json)

{
  "mcpServers": {
    "requarks-wiki": {
      "command": "npx",
      "args": ["-y", "@yowu-dev/requarks-wiki-mcp@latest"],
      "env": {
        "WIKI_BASE_URL": "https://wiki.your-domain.dev",
        "WIKI_API_TOKEN": "your_wikijs_api_key_jwt",
        "WIKI_GRAPHQL_PATH": "/graphql",
        "WIKI_DEFAULT_LOCALE": "en",
        "WIKI_DEFAULT_EDITOR": "markdown",
        "WIKI_MUTATIONS_ENABLED": "true",
        "WIKI_MUTATION_CONFIRM_TOKEN": "CONFIRM_UPDATE",
        "WIKI_MUTATION_DRY_RUN": "false",
        "WIKI_ALLOWED_MUTATION_PATH_PREFIXES": "",
        "WIKI_HTTP_TIMEOUT_MS": "15000",
        "WIKI_HTTP_MAX_RETRIES": "2"
      }
    }
  }
}

通过本地路径注册MCP（无需npm Publish）

您可以直接从本地项目路径注册此MCP服务器，而无需从npm发布/安装。

1. 在此存储库中构建

npm install
npm run build

1. 在中注册本地绝对路径 ~/.mcp.json

{
  "mcpServers": {
    "requarks-wiki-local": {
      "command": "node",
      "args": ["/absolute/path/to/requarks-wiki-mcp/dist/index.js"],
      "env": {
        "WIKI_BASE_URL": "https://wiki.your-domain.dev",
        "WIKI_API_TOKEN": "your_wikijs_api_key_jwt",
        "WIKI_GRAPHQL_PATH": "/graphql",
        "WIKI_DEFAULT_LOCALE": "en",
        "WIKI_DEFAULT_EDITOR": "markdown",
        "WIKI_MUTATIONS_ENABLED": "true",
        "WIKI_MUTATION_CONFIRM_TOKEN": "",
        "WIKI_MUTATION_DRY_RUN": "false",
        "WIKI_ALLOWED_MUTATION_PATH_PREFIXES": "",
        "WIKI_HTTP_TIMEOUT_MS": "15000",
        "WIKI_HTTP_MAX_RETRIES": "2"
      }
    }
  }
}

笔记：

• 始终使用绝对路径。
• 重新运行 npm run build 代码更改后 dist/index.js 保持最新状态。

跑

发展：

npm run dev

构建+运行：

npm run build
npm start

MCP工具

阅读工具（19）

页：

标签：

评论：

系统和导航：

资产：

用户：

写入工具（10，禁用，除非 WIKI_MUTATIONS_ENABLED=true)

页面突变：

评论突变：

标签突变：

突变安全性

• 当 WIKI_MUTATION_CONFIRM_TOKEN 已设置，变异工具需要匹配 confirm 争论。
• 当 WIKI_MUTATION_DRY_RUN=true，编写工具返回预览，不要修改Wiki.js。
• 如果 WIKI_ALLOWED_MUTATION_PATH_PREFIXES 设置后，页面和注释创建突变仅限于这些路径前缀。
• 所有突变尝试都会向stderr写入结构化审计行。

MCP资源

权限说明（Wiki.js）

对于API密钥来说，Wiki.js的权限行为可能令人惊讶。特别地：

• 某些操作可能需要 manage:pages/delete:pages 页面规则级别的规则。
• 阅读 content 可能需要 read:source 这取决于模式/字段级别的检查。
• 评论操作需要 read:comments, write:comments，或 manage:comments.
• 系统信息和导航需要管理员级别的API密钥权限。

常见错误代码：

有关更多详细信息，请阅读 wikijs://api-permissions-guide 资源。

建议的最低API密钥权限

对于读取量大的KB使用：

• read:pages, read:source
• read:comments （用于评论浏览）
• 允许对预期路径/区域设置进行这些权限的页面规则

对于写入工作流：

• write:pages （创建和更新）
• manage:pages 或 delete:pages （用于删除/移动操作）
• write:comments, manage:comments （用于评论突变）
• manage:system （用于标签管理）

安全指导

• 仅保留API令牌服务器端。
• 从只读权限开始。
• 保持 WIKI_MUTATIONS_ENABLED=false 除非需要更新。
• 可选硬化：设置强随机 WIKI_MUTATION_CONFIRM_TOKEN 并通过匹配 confirm 用于写电话。
• 保持 WIKI_MUTATION_DRY_RUN=true 直到你准备好进行真正的写作。
• 使用 WIKI_ALLOWED_MUTATION_PATH_PREFIXES 以限制写入范围。
• wikijs_get_system_info 默认情况下过滤敏感的基础结构字段（dbHost、configFile等）。
• scriptJs/scriptCss 页面创建/更新中的字段长度有限（10000个字符），并包含浏览器执行警告。