# wikijs-graphql-mcp

唯讀的 [Wiki.js](https://js.wiki/) 2.x [MCP](https://modelcontextprotocol.io/) server。透過 Wiki.js GraphQL API **搜尋、瀏覽與讀取**頁面，讓 AI 助理能查詢公司知識庫。

- **只提供唯讀 tools**：沒有任何建立、更新、移動或刪除頁面的能力；GraphQL client 也會拒絕送出 mutation／subscription。
- **不需要登入流程**：在 MCP 設定中直接提供 Wiki.js API Key 即可。

> npm 套件名稱為 `wikijs-graphql-mcp`，GitHub repository 為 `vanisoul/wikijs-mcp`。registry `npx` 範例需等套件實際發布到 npm 後才能使用；原始碼開發與 tarball 驗證不需要先發布。

## 快速開始：npx 設定 MCP

需求：Node.js **22 或更新版本**，以及支援 stdio 的 MCP Client。

```json
{
  "mcpServers": {
    "wikijs": {
      "command": "npx",
      "args": ["--yes", "wikijs-graphql-mcp@0.1.0"],
      "env": {
        "WIKIJS_BASE_URL": "https://wiki.example.com",
        "WIKIJS_API_TOKEN": "YOUR_WIKIJS_API_KEY",
        "WIKIJS_LOCALE": "zh-tw"
      }
    }
  }
}
```

| 環境變數 | 必填 | 說明 |
| --- | --- | --- |
| `WIKIJS_BASE_URL` | 是 | Wiki.js 站台網址，例如 `https://wiki.example.com`。不要附加 `/graphql`；若 Wiki.js 架設在子路徑下可包含該路徑。正式站台必須使用 HTTPS，僅 loopback 本機測試允許 HTTP。 |
| `WIKIJS_API_TOKEN` | 是 | Wiki.js 管理後台 → **API 存取** 所建立的 API Key，以 `Authorization: Bearer` 送出。 |
| `WIKIJS_LOCALE` | 否 | tools 未指定 `locale` 時使用的預設語系，預設 `zh-tw`。 |

完整設定範例位於 [`examples/mcp.json`](examples/mcp.json)。

### 取得 API Key

1. 以管理員登入 Wiki.js，進入 **管理 → API 存取**，確認 API 已啟用。
2. 建立新的 API Key，**群組請選擇只有讀取權限的群組**（例如僅具 `read:pages`、`read:source` 的群組），落實最小權限。
3. 將 Key 填入 MCP 設定的 `WIKIJS_API_TOKEN`。API Key 的頁面可見範圍依所屬群組的頁面規則而定。

### Pi

把設定放在使用者的 `~/.pi/agent/mcp.json`，或受信任專案的 `.pi/mcp.json`（已列入 `.gitignore`，避免 API Key 進入版本控制）。也可以執行：

```bash
pi mcp add wikijs \
  --env WIKIJS_BASE_URL=https://wiki.example.com \
  --env WIKIJS_API_TOKEN=YOUR_WIKIJS_API_KEY \
  -- npx --yes wikijs-graphql-mcp@0.1.0
```

專案限定設定使用 `pi mcp add -l`。設定完成後執行 `/reload` 或重新啟動 Pi。

### 其他 MCP Client

使用相同的 `command`、`args` 與 `env`。設定檔路徑與重新載入方式依 Client 而定。Windows Client 若無法直接找到 `npx`，可依該 Client 的程序啟動方式改用 `npx.cmd`。

## CLI

```text
wikijs-graphql-mcp               啟動 stdio MCP server
wikijs-graphql-mcp serve         啟動 stdio MCP server
wikijs-graphql-mcp --version     顯示套件版本
wikijs-graphql-mcp --help        顯示用法與環境變數
```

缺少 `WIKIJS_BASE_URL` 或 `WIKIJS_API_TOKEN` 時，server 會在啟動時以錯誤訊息結束。

## Tools

所有 tools 都標記 `readOnlyHint: true`、`destructiveHint: false`。

| Tool | 用途 | 主要參數 |
| --- | --- | --- |
| `wikijs_search_pages` | 關鍵字搜尋頁面，回傳標題、描述、路徑與網址 | `query`、`pathPrefix?`、`locale?`、`limit?`（預設 20）、`offset?` |
| `wikijs_get_page` | 依路徑讀取頁面 Markdown 原始內容與中繼資料 | `path`（路徑或同站台頁面網址）、`locale?`、`maxChars?`、`contentOffset?` |
| `wikijs_get_page_by_id` | 依頁面 ID 讀取頁面 | `id`、`maxChars?`、`contentOffset?` |
| `wikijs_list_pages` | 列出頁面中繼資料（不含內容），可篩選與排序 | `pathPrefix?`、`tags?`、`locale?`、`orderBy?`（預設 `UPDATED`）、`orderByDirection?`（預設 `DESC`）、`limit?`（預設 50） |
| `wikijs_browse_tree` | 瀏覽目錄結構：根層或指定目錄的直接子項目 | `path?`、`locale?`、`mode?`（`ALL`／`FOLDERS`／`PAGES`） |
| `wikijs_list_tags` | 列出所有頁面標籤 | `query?` |

建議流程：先用 `wikijs_search_pages` 或 `wikijs_browse_tree` 找到頁面路徑，再用 `wikijs_get_page` 讀取內容。

### 行為說明

- **頁面路徑**：不含開頭斜線與 `.md`，可含中文，例如 `RD部/Projects/690_整合式專利檢索系統/資料轉置/DOCDB/docdb-status`。工具會自動移除多餘的斜線、`.md` 與 URL 編碼；也可以直接貼上同站台網址，如 `https://wiki.example.com/zh-tw/RD部/...`，網址中的語系段會自動套用。
- **找不到頁面**：Wiki.js 對不存在的頁面會回傳 GraphQL 錯誤（code 6003）而非 `null`；本 server 會轉成 `{ "found": false, ... }` 的一般結果，不視為錯誤。API Key 沒有讀取權限的頁面也會呈現為找不到。
- **長頁面**：`wikijs_get_page` 預設最多回傳 100,000 字元，並提供 `contentLength`、`truncated`、`nextContentOffset`；以 `contentOffset` 接續讀取下一段。
- **路徑前綴過濾**：Wiki.js `search(path)` 參數實測並非前綴比對，因此 `pathPrefix` 一律在取得結果後於本地端以路徑段落比對（不分大小寫）。`wikijs_list_pages` 指定 `pathPrefix` 時需要取得完整頁面清單再過濾，大型站台會稍慢。
- **搜尋結果不含頁面 ID**：實測 Wiki.js 搜尋索引回傳的 ID 可能與實際頁面 ID 不一致（索引未同步），因此搜尋結果只提供可靠的 `path`／`locale`，讀取時以路徑為準。
- **頁面樹**：Wiki.js 的 `tree(path)` 回傳的是節點的「同層」項目，本 server 會先定位節點，再查詢其子項目。資料夾若本身也有頁面，`hasPage` 為 `true`。

## 設定與安全性

- API Key 只透過 `Authorization: Bearer` header 送往 `WIKIJS_BASE_URL/graphql`，不會出現在 tool 結果或錯誤訊息中。
- 請求停用 redirect，並設有逾時；`WIKIJS_BASE_URL` 不接受帳密、查詢參數或錨點。
- 所有 GraphQL 操作皆為寫死在程式中的 query，executor 另外會拒絕任何非 query 的操作，作為唯讀的第二道防線。
- 無效或權限不足的 API Key 會收到 `Forbidden`，錯誤訊息會提示檢查 `WIKIJS_API_TOKEN`。
- 建議為 MCP 建立專用、只具讀取權限的 API Key，並設定到期日。

## 相容性與限制

- 適用 Wiki.js 2.x GraphQL API（`pages.search`、`pages.singleByPath`、`pages.single`、`pages.list`、`pages.tree`、`pages.tags`）。Wiki.js 3.x 的 API 不同，未支援。
- 搜尋品質與結果數量取決於站台設定的搜尋引擎（Basic DB、PostgreSQL、Elasticsearch 等），Wiki.js 搜尋 API 不支援伺服器端分頁。
- 不提供頁面建立、編輯、移動、刪除、渲染或歷史版本還原等寫入能力。

## 原始碼開發與發布

```bash
npm ci
npm run check
npm run test:package
npm run check:release
```

開發時可使用 `node dist/cli.js` 啟動 MCP，並在 Client 的 `env` 設定 `WIKIJS_BASE_URL` 與 `WIKIJS_API_TOKEN`。`examples/mcp.json` 是可公開的設定範例；個人 `.pi/mcp.json` 不納入版本控制。

測試包含：

- `test/wikijs.test.mjs`：設定驗證、路徑工具、唯讀保護、GraphQL 錯誤處理與 client 行為。
- `test/server.test.mjs`：以 stdio 啟動 MCP，對模擬 Wiki.js GraphQL server 驗證所有 tools，並確認只提供唯讀 tools、所有請求皆為 query。
- `test/release*.test.mjs`、`test-package/`：發布流程與 npm 套件 manifest 檢查。

npm 只打包 `dist/`、`examples/`、README、LICENSE 等明確允許的檔案。`prepack` 會建置，`prepublishOnly` 會檢查必須在 `main`、執行測試；使用者安裝 registry 套件時不需要 TypeScript 開發依賴。

### GitHub Trusted Publishing

正式發布從已合併至 `main` 的版本 Tag 進行，workflow 位於 `.github/workflows/publish.yml`。推送符合 `v*` 的 Tag 後，流程會：

1. 驗證 Tag 與 `package.json` 版本一致、Tag commit 位於 `main` 歷史中。
2. 在沒有 OIDC 發布權限的 verify job 執行測試、建置及打包。
3. 記錄 tarball 的 SHA-512、來源 commit、名稱與版本，並上傳 artifact。
4. 在獨立 publish job 下載同一份 artifact，重新檢查中繼資料與 SHA-512。
5. 清除長效 Token 與既有 npm config，改用暫存設定及工作目錄。
6. 使用 GitHub OIDC 短期憑證執行 `npm publish VERIFIED_TARBALL --access=public --provenance=true`，直接正式上架 npm。

npm Trusted Publisher 設定：

- GitHub repository：`vanisoul/wikijs-mcp`，workflow filename：`publish.yml`。
- npm 套件：`wikijs-graphql-mcp`。
- Environment name 留空；Allowed action 必須允許直接 `npm publish`。
- publish job 使用 `id-token: write` 與 GitHub-hosted runner；不需要 `NPM_TOKEN` secret。

Trusted Publisher 設定是逐套件管理，全新套件需先確認該帳號支援的初始化方式。

### 發布版本

```text
package.json 0.1.0 → git tag v0.1.0
```

本機先驗證：

```bash
git switch main
npm ci
npm run check
npm run test:package
npm run check:release
npm pack --dry-run
```

確認發布權限後再建立並推送 Tag：

```bash
git tag -a v0.1.0 -m "release: v0.1.0"
git push origin main
git push origin v0.1.0
```

不要移動或強制覆寫已推送的 Tag；修正請使用新版本號。

## 授權

MIT，詳見 [LICENSE](LICENSE)。