From d601b7c6493d93a01384c77a12253df5fd535c7e Mon Sep 17 00:00:00 2001 From: Jasen Han Date: Sun, 28 Jun 2026 19:20:03 +0800 Subject: [PATCH] docs: add kb_add tool to README and site documentation --- README.md | 6 ++++-- docs/site/guide/mcp-server.md | 1 + docs/site/reference/mcp-tools.md | 27 +++++++++++++++++++++++++- docs/site/zh-CN/guide/mcp-server.md | 1 + docs/site/zh-CN/reference/mcp-tools.md | 17 +++++++++++++++- 5 files changed, 48 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3e0ea7c..e2f3b06 100644 --- a/README.md +++ b/README.md @@ -51,12 +51,14 @@ wikiloop-kb/ ## How Agents Use WikiLoop -Agents interact with WikiLoop through two MCP tools: +Agents interact with WikiLoop through three MCP tools: **`kb_search(query, limit?)`** — Search with a keyword or phrase. Returns up to 5 source-notes and 3 concept/comparison/decision pages per call. Each result includes a `related` field listing linked documents for navigation. Use multiple searches with different keywords to cover a topic from multiple angles. **`kb_page(ids, full?)`** — Fetch full content of one or more pages by ID (from `kb_search` results). Pass up to 5 IDs to scan several documents at once, or `full=true` with a single ID to get the complete untruncated text. +**`kb_add(filename, content, source_url?)`** — Add a text document to the knowledge base. Writes content to `raw/` and triggers incremental indexing. Distillation runs asynchronously in the background. Use the `converted/` prefix for agent-extracted PDF/Word/Excel/EPUB content. + The recommended agent workflow: ```text @@ -232,7 +234,7 @@ All commands accept a global `--kb ` flag (defaults to `$WIKILOOP_KB`, the WikiLoop exposes KB tools via the MCP protocol. -**Available tools:** `kb_search`, `kb_page` +**Available tools:** `kb_search`, `kb_page`, `kb_add` Admin operations (`status`, `reindex`, `lint`) are available via the Web UI or CLI (`wikiloop status`, `wikiloop index`, `wikiloop lint`). diff --git a/docs/site/guide/mcp-server.md b/docs/site/guide/mcp-server.md index 141ccf7..4146625 100644 --- a/docs/site/guide/mcp-server.md +++ b/docs/site/guide/mcp-server.md @@ -58,5 +58,6 @@ The KB directory is created automatically on first launch. No manual `init` need |---|---| | `kb_search` | FTS keyword search, returns ranked results with related links | | `kb_page` | Fetch full page content by ID | +| `kb_add` | Add a text document to the KB; triggers incremental indexing and async distillation | Admin operations (`status`, `reindex`, `lint`) are available via the Web UI or CLI. diff --git a/docs/site/reference/mcp-tools.md b/docs/site/reference/mcp-tools.md index 2446336..3d282c5 100644 --- a/docs/site/reference/mcp-tools.md +++ b/docs/site/reference/mcp-tools.md @@ -1,6 +1,6 @@ # MCP Tools Reference -WikiLoop exposes two MCP tools for agents. +WikiLoop exposes three MCP tools for agents. ## kb_search @@ -30,6 +30,31 @@ Search the knowledge base with a keyword or phrase. } ``` +## kb_add + +Add a text document to the knowledge base. + +**Parameters:** + +| Parameter | Type | Required | Description | +|---|---|---|---| +| `filename` | string | yes | Path relative to `raw/`. Use any subdirectory structure (e.g. `references/article.md`, `converted/report.md`). Use `converted/` prefix for agent-extracted PDF/Word/Excel/EPUB content. | +| `content` | string | yes | File content (Markdown or plain text) | +| `source_url` | string | no | Original source URL, written as a comment at the top of the file | +| `overwrite` | boolean | no | Overwrite if file already exists (default false) | + +Writes content to `raw/` and triggers incremental indexing. Distillation runs asynchronously in the background. + +**Example:** + +```json +{ + "filename": "references/my-article.md", + "content": "# My Article\n\nContent here...", + "source_url": "https://example.com/article" +} +``` + ## kb_page Fetch full content of one or more pages by ID. diff --git a/docs/site/zh-CN/guide/mcp-server.md b/docs/site/zh-CN/guide/mcp-server.md index c9c466b..6c1bc39 100644 --- a/docs/site/zh-CN/guide/mcp-server.md +++ b/docs/site/zh-CN/guide/mcp-server.md @@ -58,5 +58,6 @@ wikiloop serve |---|---| | `kb_search` | FTS 关键词搜索，返回带 related 链接的排序结果 | | `kb_page` | 通过 ID 获取完整页面内容 | +| `kb_add` | 向知识库添加文本文档，触发增量索引和异步提炼 | 管理操作（`status`、`reindex`、`lint`）可通过 Web UI 或 CLI 执行。 diff --git a/docs/site/zh-CN/reference/mcp-tools.md b/docs/site/zh-CN/reference/mcp-tools.md index 67e9359..b60a1c9 100644 --- a/docs/site/zh-CN/reference/mcp-tools.md +++ b/docs/site/zh-CN/reference/mcp-tools.md @@ -1,6 +1,6 @@ # MCP 工具参考 -WikiLoop 为 Agent 暴露两个 MCP 工具。 +WikiLoop 为 Agent 暴露三个 MCP 工具。 ## kb_search @@ -21,6 +21,21 @@ WikiLoop 为 Agent 暴露两个 MCP 工具。 - `kind`、`layer` — 页面分类 - `related` — 关联文档，用于图谱导航 +## kb_add + +向知识库添加文本文档。 + +**参数：** + +| 参数 | 类型 | 必填 | 描述 | +|---|---|---|---| +| `filename` | string | 是 | 相对于 `raw/` 的路径，支持任意子目录结构（如 `references/article.md`、`converted/report.md`）。Agent 提取的 PDF/Word/Excel/EPUB 内容使用 `converted/` 前缀。 | +| `content` | string | 是 | 文件内容（Markdown 或纯文本） | +| `source_url` | string | 否 | 原始来源 URL，写入文件顶部注释 | +| `overwrite` | boolean | 否 | 文件已存在时是否覆盖（默认 false） | + +将内容写入 `raw/` 并触发增量索引。提炼在后台异步运行。 + ## kb_page 通过 ID 获取一个或多个页面的完整内容。