onekb-mcp 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WeeklyPlanner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# onekb-mcp
+
+MCP (Model Context Protocol) server for [OneKB](https://oneknowledgebase.com) — an AI-native markdown knowledge base.
+
+Provides **17 atomic tools** that give any MCP client (Claude Code, Claude Desktop, Cursor, …) the same read/write power over your knowledge base that you have in the web app — read the tree, create/edit/append docs, search, manage folders, and safely delete/restore with version history (per doc: the latest 50 versions plus everything from the last 30 days are retained).
+
+## Design
+
+**Thin client.** Every tool is a thin wrapper over the public REST API (`/api/v1/**`); all business logic lives server-side. Each call carries `Authorization: Bearer <okb_key>` plus `x-onekb-source: mcp` / `x-onekb-tool` / `x-onekb-client` headers, and the backend records one `ai_tool_runs` audit row per call (success and every failure branch).
+
+**Recovery and audit.** Content updates, appends and restores create recovery versions; deletes are soft and recoverable from trash for 30 days. Permanent deletion happens through the web trash or automatic cleanup after the trash retention period — there is no MCP purge tool. Version retention: each document keeps its latest 50 versions, and every version from the last 30 days is kept regardless of count (a version is removed only when it is **both** beyond the latest 50 **and** older than 30 days). Audit rows are retained; a cleaned version nulls the audit row's version anchor.
+
+## Configuration
+
+| Env | Required | Description |
+|-----|----------|-------------|
+| `ONEKB_API_URL` | No | API base URL (default `https://oneknowledgebase.com`; dev: `http://localhost:4066`) |
+| `ONEKB_API_KEY` | Yes | Your `okb_…` API key (scopes: `docs:read` and/or `docs:write`) |
+| `ONEKB_CLIENT_NAME` | No | Client label recorded in audit (default `onekb-mcp`) |
+
+### Claude Code
+
+```bash
+claude mcp add onekb \
+  --env ONEKB_API_URL=https://oneknowledgebase.com \
+  --env ONEKB_API_KEY=okb_your_key_here \
+  -- npx -y onekb-mcp
+```
+
+Create an API key in OneKB Settings first. Replace `okb_your_key_here` with that key and keep it private. Prefer a read-only key unless you want the assistant to change notes.
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "onekb": {
+      "command": "npx",
+      "args": ["-y", "onekb-mcp"],
+      "env": {
+        "ONEKB_API_URL": "https://oneknowledgebase.com",
+        "ONEKB_API_KEY": "okb_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### Read (`docs:read`)
+
+| Tool | Description |
+|------|-------------|
+| `list_docs` | List the document tree (folders + docs) without content_md. The REST list endpoint (`GET /api/v1/docs`) likewise returns tree fields only (id, parent_id, type, title, path, doc_date, created_at, updated_at, sort_order, revision) — fetch a document's body via `read_doc` / `GET /api/v1/docs/[id]`. |
+| `read_doc` | Read a single document's body + revision by id. |
+| `search_docs` | Keyword search over title/path/content, optionally filtered by date and/or frontmatter properties. |
+| `find_docs` | Locate documents by title, path, properties, or linked entities. |
+| `list_unresolved_entities` | List unresolved wiki-link targets and their source notes. |
+| `list_ai_writes` | Inspect the audit ledger of AI writes and their before/after version anchors. |
+| `read_versions` | List a document's version history (metadata, up to 20) or fetch one full version. Retention: latest 50 versions per doc + all versions from the last 30 days. |
+
+### Write (`docs:write`)
+
+| Tool | Description |
+|------|-------------|
+| `create_doc` | Create a document at a full path; intermediate folders auto-created. |
+| `create_folder` | Create a folder (and missing intermediates); idempotent on existing folders. |
+| `update_doc` | Overwrite a document's body with optimistic locking (`expected_revision` required). |
+| `append_to_doc` | Atomically append content (concurrency-safe; no revision needed). |
+| `rename_doc` | Rename a document/folder (title + cascading path). |
+| `move_doc` | Move a document/folder under another folder by path (`''` = root). |
+| `delete_doc` | Soft-delete a **document** to trash (rejects folder ids → `type_mismatch`). |
+| `delete_folder` | Soft-delete a **folder** and all descendants (returns `affected_count`). |
+| `restore_doc` | Restore a trashed document/folder from trash. |
+| `restore_version` | Restore a document to a past version's content (creates a new version; `expected_revision` required). |
+
+## Getting your API key
+
+A key-management **Settings → API Keys** page is available in the web app. Create a key there, copy the one-time value, and set it as `ONEKB_API_KEY`.
+
+Set the key as `ONEKB_API_KEY`. Revoke it in Settings when you no longer need it. The package runs locally over stdio; only tool requests go to your configured OneKB API.
+
+## Local development
+
+From the source repository, run `pnpm -C mcp-server build`, then use `node <repo>/mcp-server/dist/index.js` instead of `npx`. Set `ONEKB_API_URL=http://localhost:4066` and use a separate development database and test account for fixtures.
+
+## Requirements
+
+- Node.js 18+
+- A OneKB account with an API key
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,621 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/tools.ts
+import { z } from "zod";
+
+// src/api-client.ts
+var API_BASE = process.env.ONEKB_API_URL || "https://oneknowledgebase.com";
+var API_KEY = process.env.ONEKB_API_KEY || "";
+var CLIENT_NAME = process.env.ONEKB_CLIENT_NAME || "onekb-mcp";
+var REQUEST_TIMEOUT_MS = Number(process.env.ONEKB_TIMEOUT_MS) || 15e3;
+var ApiClientError = class extends Error {
+  status;
+  code;
+  details;
+  payload;
+  constructor(message, options) {
+    super(message);
+    this.name = "ApiClientError";
+    this.status = options.status;
+    this.code = options.code;
+    this.details = options.details;
+    this.payload = options.payload;
+  }
+};
+function buildHeaders(tool, extraHeaders) {
+  return {
+    Authorization: `Bearer ${API_KEY}`,
+    "x-onekb-source": "mcp",
+    "x-onekb-tool": tool,
+    "x-onekb-client": CLIENT_NAME,
+    "Content-Type": "application/json",
+    ...extraHeaders || {}
+  };
+}
+async function parseResponseBody(response) {
+  const text = await response.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+async function request(tool, path, init, params) {
+  const url = new URL(`${API_BASE}/api/v1${path}`);
+  if (params) {
+    Object.entries(params).forEach(([key, value]) => {
+      if (value) url.searchParams.set(key, value);
+    });
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  let response;
+  try {
+    response = await fetch(url.toString(), {
+      ...init,
+      headers: buildHeaders(tool, init?.headers),
+      signal: controller.signal
+    });
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new ApiClientError(`Request timed out after ${REQUEST_TIMEOUT_MS}ms`, {
+        status: 504,
+        code: "timeout"
+      });
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+  const payload = await parseResponseBody(response);
+  if (!response.ok) {
+    if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+      const errorPayload = payload;
+      throw new ApiClientError(
+        errorPayload.error || `Request failed with status ${response.status}`,
+        {
+          status: response.status,
+          code: errorPayload.code,
+          details: errorPayload.details,
+          payload
+        }
+      );
+    }
+    throw new ApiClientError(`Request failed with status ${response.status}`, {
+      status: response.status,
+      payload
+    });
+  }
+  if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+    return payload;
+  }
+  return { data: payload };
+}
+function apiGet(tool, path, params) {
+  return request(tool, path, { method: "GET" }, params);
+}
+function apiPost(tool, path, body) {
+  return request(tool, path, { method: "POST", body: JSON.stringify(body) });
+}
+function apiPut(tool, path, body) {
+  return request(tool, path, { method: "PUT", body: JSON.stringify(body) });
+}
+function apiPatch(tool, path, body) {
+  return request(tool, path, { method: "PATCH", body: JSON.stringify(body) });
+}
+function apiDelete(tool, path, params) {
+  return request(tool, path, { method: "DELETE" }, params);
+}
+
+// src/tools.ts
+var tools = [
+  {
+    name: "list_docs",
+    description: [
+      "List the document tree (folders + docs) WITHOUT content_md.",
+      "Returns { nodes: [{ id, type, title, path, parent_id }] }.",
+      "Use read_doc to fetch a single document's body."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        parent_id: { type: "string", description: "Reserved (V1 returns full tree)" },
+        depth: { type: "number", description: "Reserved (V1 returns full tree)" }
+      }
+    }
+  },
+  {
+    name: "read_doc",
+    description: [
+      "Read a single document's body + revision by id.",
+      "Returns { id, path, title, content_md, properties, revision }.",
+      "Always read before update_doc to obtain the current revision."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "Document id" } },
+      required: ["id"]
+    }
+  },
+  {
+    name: "create_doc",
+    description: [
+      "Create a document at a full path; intermediate folders are auto-created.",
+      "path last segment is the title; prefix segments are the folder chain (e.g. /\u65E5\u8BB0/2026/06-09).",
+      "Optional template_id seeds content from a template (overrides content).",
+      "Returns { id, path, revision }. Duplicate title in its parent \u2192 conflict_title."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Full target path, last segment = title" },
+        content: { type: "string", description: "Initial markdown body" },
+        template_id: { type: "string", description: "Template id to seed content" }
+      },
+      required: ["path"]
+    }
+  },
+  {
+    name: "append_to_doc",
+    description: [
+      "Atomically append content to a document (diary main path).",
+      "Concurrency-safe (single UPDATE row lock); no expected_revision needed.",
+      "Optional idempotency_key: pass a unique key per logical write to make retries safe \u2014",
+      "a repeated call with the same key returns the first result WITHOUT appending again.",
+      "Use a fresh key for each distinct write; never reuse a key across different writes.",
+      "Returns { id, revision }."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Document id" },
+        content: { type: "string", description: "Content to append" },
+        separator: {
+          type: "string",
+          description: "Separator inserted before content (default two newlines)"
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Optional unique key per logical write; retries with same key won't double-append"
+        }
+      },
+      required: ["id", "content"]
+    }
+  },
+  {
+    name: "update_doc",
+    description: [
+      "Overwrite a document's full body with optimistic locking.",
+      "expected_revision is REQUIRED; call read_doc first to obtain it.",
+      "On revision mismatch returns a conflict error with current_revision \u2014 re-read then retry.",
+      "Returns { id, revision }."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Document id" },
+        content: { type: "string", description: "Full new markdown body" },
+        expected_revision: {
+          type: "number",
+          description: "Revision from the latest read_doc"
+        }
+      },
+      required: ["id", "content", "expected_revision"]
+    }
+  },
+  {
+    name: "search_docs",
+    description: [
+      "Search documents by keyword (title/path/content) and/or date and/or frontmatter properties.",
+      "At least one of query/date/date_from/date_to/props is required.",
+      "props matches frontmatter via JSONB containment, e.g. { mood: 'anxious' }.",
+      "Returns { results: [{ id, title, path, created_at, snippet }] }."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Keyword over title/path/content_md" },
+        date: { type: "string", description: "Exact created_at date YYYY-MM-DD" },
+        date_from: { type: "string", description: "Range start YYYY-MM-DD" },
+        date_to: { type: "string", description: "Range end YYYY-MM-DD (inclusive)" },
+        props: {
+          type: "object",
+          description: "Frontmatter equality filters (string/number/boolean values)"
+        },
+        limit: { type: "number", description: "Max results 1-50 (default 20)" }
+      }
+    }
+  },
+  {
+    name: "find_docs",
+    description: [
+      "Structured retrieval: filter documents by authorship / tags / time / title.",
+      "This does NOT keyword-match content \u2014 use search_docs for content/keyword search.",
+      "created_by_ai: only docs YOU (AI/MCP) created. last_touched_by_ai: only docs whose last write was AI/MCP.",
+      "tags: doc must have ALL listed tags. updated_from/updated_to: updated_at range (ISO). title_contains: title substring.",
+      "Use for 'docs I created, tagged X, touched this week'. Sorted by updated_at desc.",
+      "Returns { results: [{ id, title, path, created_by_ai, last_touched_by_ai, tags, updated_at }] }."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        created_by_ai: { type: "boolean", description: "Only docs created by AI/MCP" },
+        last_touched_by_ai: { type: "boolean", description: "Only docs whose last write was AI/MCP" },
+        tags: { type: "array", items: { type: "string" }, description: "Doc must have ALL these tags" },
+        updated_from: { type: "string", description: "updated_at >= ISO date/datetime" },
+        updated_to: { type: "string", description: "updated_at <= ISO date/datetime" },
+        title_contains: { type: "string", description: "Title substring (case-insensitive)" },
+        limit: { type: "number", description: "Max results 1-50 (default 20)" }
+      }
+    }
+  },
+  {
+    name: "create_folder",
+    description: [
+      "Create a folder (and any missing intermediate folders) at a path; ALL path segments become folders.",
+      "Idempotent: if the folder already exists it is returned as-is (safe to retry).",
+      "To create a document WITH content use create_doc instead.",
+      "Returns { id, path }. A non-folder already occupying the path \u2192 path_conflict."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Full folder path, e.g. /Archive/2026" }
+      },
+      required: ["path"]
+    }
+  },
+  {
+    name: "delete_doc",
+    description: [
+      "Move a DOCUMENT to trash (soft delete; recoverable for 30 days via restore_doc).",
+      "For folders use delete_folder \u2014 passing a folder id here is rejected (type_mismatch) so you never trash a whole subtree by accident.",
+      "Returns { id, trashed_until }."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "Document id" } },
+      required: ["id"]
+    }
+  },
+  {
+    name: "delete_folder",
+    description: [
+      "Move a FOLDER and ALL its descendants to trash (soft delete; recoverable for 30 days).",
+      "affected_count reports how many items were trashed \u2014 use it to confirm the scale.",
+      "Passing a document id here is rejected (type_mismatch); use delete_doc instead.",
+      "Returns { id, trashed_until, affected_count }."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "Folder id" } },
+      required: ["id"]
+    }
+  },
+  {
+    name: "restore_doc",
+    description: [
+      "Restore a trashed document/folder (and its same-batch descendants) from trash.",
+      "On name conflict it is auto-suffixed or restored to root \u2014 result tells you which (restored | restored_to_root | renamed); it never silently overwrites.",
+      "Returns { result, new_path }."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "Trashed document/folder id" } },
+      required: ["id"]
+    }
+  },
+  {
+    name: "rename_doc",
+    description: [
+      "Rename a document or folder (changes its title and derived path; descendant paths cascade).",
+      "To change its LOCATION use move_doc instead.",
+      "Returns { id, new_path, revision }. Duplicate name in the same parent \u2192 conflict_title."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Document/folder id" },
+        new_title: { type: "string", description: "New title" }
+      },
+      required: ["id", "new_title"]
+    }
+  },
+  {
+    name: "move_doc",
+    description: [
+      "Move a document or folder under a different parent folder, given by path ('' = root).",
+      "To change its NAME use rename_doc instead. The target folder must already exist (create it first with create_folder) \u2014 a missing target \u2192 parent_not_found.",
+      "Returns { id, new_path }. Moving a folder into its own descendant \u2192 cycle."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Document/folder id" },
+        new_parent_path: { type: "string", description: "Destination folder path, '' for root" }
+      },
+      required: ["id", "new_parent_path"]
+    }
+  },
+  {
+    name: "read_versions",
+    description: [
+      "Inspect a document's version history. Without version_id: up to `limit` (max 20) version summaries (metadata only, newest first, no content_md).",
+      "With version_id: that single version INCLUDING content_md.",
+      "Use this to diagnose past edits before calling restore_version.",
+      "Returns a version list or a single version."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Document id" },
+        version_id: { type: "string", description: "Fetch one version's full content_md" },
+        limit: { type: "number", description: "Max version summaries 1-20 (default 20)" }
+      },
+      required: ["id"]
+    }
+  },
+  {
+    name: "restore_version",
+    description: [
+      "Restore a document to a past version's content. This creates a NEW version (history is never erased).",
+      "expected_revision is REQUIRED (same optimistic lock as update_doc): on mismatch you get a conflict with current_revision \u2014 re-read via read_doc/read_versions then retry. This prevents overwriting a concurrent human edit.",
+      "Returns { id, new_revision }."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Document id" },
+        version_id: { type: "string", description: "Version to restore from" },
+        expected_revision: { type: "number", description: "Current revision from read_doc/read_versions" }
+      },
+      required: ["id", "version_id", "expected_revision"]
+    }
+  },
+  {
+    name: "list_unresolved_entities",
+    description: [
+      "List unresolved entities: [[links]] you/AI wrote that have NO target doc yet (the to-organize queue).",
+      "Use to find what you mentioned but haven't created pages for. Each item: target_path, ref count, source docs.",
+      "By default excludes entities already marked ignored/done; pass include_dismissed:true to include them (with state).",
+      "Returns { results: [{ target_path, raw_target, count, sources:[{doc_id,title}], state }] }."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        include_dismissed: { type: "boolean", description: "Include entities already ignored/done" }
+      }
+    }
+  },
+  {
+    name: "list_ai_writes",
+    description: [
+      "List recent AI/non-interactive write events (create/append/update/restore via MCP) \u2014 the write history.",
+      "Answers 'what did AI write recently/last week' by event time (newest first). For current AI-authored docs use find_docs.",
+      "source filter: mcp | import | system. import/system are reserved and may be empty in the current implementation. limit 1-100 (default 50).",
+      "Returns { results: [{ id, source, tool_name, doc_id, doc_title, doc_path, version_after_id, revision_after, created_at }] }."
+    ].join("\n"),
+    inputSchema: {
+      type: "object",
+      properties: {
+        source: { type: "string", enum: ["mcp", "import", "system"], description: "Filter by write channel: mcp | import | system" },
+        limit: { type: "number", description: "Max results 1-100 (default 50)" }
+      }
+    }
+  }
+];
+function toText(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function toError(message, options) {
+  return {
+    content: [{ type: "text", text: options?.raw ? message : `Error: ${message}` }],
+    isError: true
+  };
+}
+function validationError(message) {
+  return toError(JSON.stringify({ status: 400, code: "validation_failed", message }, null, 2), {
+    raw: true
+  });
+}
+var UUID = z.string().uuid();
+var ID_REQUIRED_TOOLS = /* @__PURE__ */ new Set([
+  "read_doc",
+  "append_to_doc",
+  "update_doc",
+  "delete_doc",
+  "delete_folder",
+  "restore_doc",
+  "rename_doc",
+  "move_doc",
+  "read_versions",
+  "restore_version"
+]);
+function unwrap(response) {
+  return "data" in response ? response.data : response;
+}
+async function callApi(operation) {
+  return toText(unwrap(await operation()));
+}
+function formatApiClientError(error) {
+  const payload = error.payload && typeof error.payload === "object" && !Array.isArray(error.payload) ? error.payload : {};
+  const out = {
+    status: error.status,
+    code: error.code ?? null,
+    message: error.message
+  };
+  if (typeof payload.current_revision === "number") {
+    out.current_revision = payload.current_revision;
+  }
+  if (typeof payload.resets_in_seconds === "number") {
+    out.resets_in_seconds = payload.resets_in_seconds;
+  }
+  if (typeof payload.upgrade_url === "string") out.upgrade_url = payload.upgrade_url;
+  if (typeof payload.request_id === "string") out.request_id = payload.request_id;
+  return JSON.stringify(out, null, 2);
+}
+async function handleToolCall(name, args) {
+  try {
+    if (ID_REQUIRED_TOOLS.has(name) && !UUID.safeParse(args.id).success) {
+      return validationError("id must be a non-empty UUID");
+    }
+    switch (name) {
+      case "list_docs": {
+        const res = await apiGet("list_docs", "/docs");
+        const docs = unwrap(res) ?? [];
+        const nodes = docs.map((d) => ({
+          id: d.id,
+          type: d.type,
+          title: d.title,
+          path: d.path,
+          parent_id: d.parent_id
+        }));
+        return toText({ nodes });
+      }
+      case "read_doc": {
+        const res = await apiGet("read_doc", `/docs/${args.id}`);
+        const d = unwrap(res) ?? {};
+        return toText({
+          id: d.id,
+          type: d.type,
+          title: d.title,
+          path: d.path,
+          content_md: d.content_md,
+          properties: d.properties,
+          revision: d.revision,
+          updated_at: d.updated_at
+        });
+      }
+      case "create_doc":
+        return await callApi(
+          () => apiPost("create_doc", "/docs", {
+            path: args.path,
+            content: args.content,
+            template_id: args.template_id
+          })
+        );
+      case "append_to_doc":
+        return await callApi(
+          () => apiPost("append_to_doc", `/docs/${args.id}/append`, {
+            content: args.content,
+            ...args.separator !== void 0 ? { separator: args.separator } : {},
+            ...args.idempotency_key !== void 0 ? { idempotency_key: args.idempotency_key } : {}
+          })
+        );
+      case "update_doc":
+        return await callApi(
+          () => apiPut("update_doc", `/docs/${args.id}`, {
+            content_md: args.content,
+            expected_revision: args.expected_revision
+          })
+        );
+      case "search_docs": {
+        const params = {};
+        if (args.query) params.query = String(args.query);
+        if (args.date) params.date = String(args.date);
+        if (args.date_from) params.date_from = String(args.date_from);
+        if (args.date_to) params.date_to = String(args.date_to);
+        if (args.props) params.props = JSON.stringify(args.props);
+        if (args.limit) params.limit = String(args.limit);
+        const res = await apiGet("search_docs", "/docs/search", params);
+        return toText({ results: unwrap(res) ?? [] });
+      }
+      case "find_docs": {
+        const params = {};
+        if (args.created_by_ai) params.created_by_ai = "1";
+        if (args.last_touched_by_ai) params.last_touched_by_ai = "1";
+        if (Array.isArray(args.tags) && args.tags.length) params.tags = args.tags.map(String).join(",");
+        if (args.updated_from) params.updated_from = String(args.updated_from);
+        if (args.updated_to) params.updated_to = String(args.updated_to);
+        if (args.title_contains) params.title_contains = String(args.title_contains);
+        if (args.limit) params.limit = String(args.limit);
+        const res = await apiGet("find_docs", "/docs/find", params);
+        return toText({ results: unwrap(res) ?? [] });
+      }
+      case "create_folder":
+        return await callApi(() => apiPost("create_folder", "/docs", { path: args.path, type: "folder" }));
+      case "delete_doc":
+        return await callApi(() => apiDelete("delete_doc", `/docs/${args.id}`, { expected_type: "doc" }));
+      case "delete_folder":
+        return await callApi(
+          () => apiDelete("delete_folder", `/docs/${args.id}`, { expected_type: "folder" })
+        );
+      case "restore_doc":
+        return await callApi(() => apiPost("restore_doc", `/docs/${args.id}/restore`, {}));
+      case "rename_doc":
+        return await callApi(() => apiPatch("rename_doc", `/docs/${args.id}`, { title: args.new_title }));
+      case "move_doc":
+        return await callApi(
+          () => apiPatch("move_doc", `/docs/${args.id}`, { new_parent_path: args.new_parent_path })
+        );
+      case "read_versions": {
+        const params = {};
+        if (args.version_id) params.version_id = String(args.version_id);
+        if (args.limit) params.limit = String(args.limit);
+        return await callApi(() => apiGet("read_versions", `/docs/${args.id}/versions`, params));
+      }
+      case "restore_version":
+        return await callApi(
+          () => apiPost("restore_version", `/docs/${args.id}/restore-version`, {
+            version_id: args.version_id,
+            expected_revision: args.expected_revision
+          })
+        );
+      case "list_unresolved_entities": {
+        const params = {};
+        if (args.include_dismissed) params.include_dismissed = "1";
+        const res = await apiGet("list_unresolved_entities", "/entities/unresolved", params);
+        return toText({ results: unwrap(res) ?? [] });
+      }
+      case "list_ai_writes": {
+        const params = {};
+        if (args.source) params.source = String(args.source);
+        if (args.limit) params.limit = String(args.limit);
+        const res = await apiGet("list_ai_writes", "/ai-write-events", params);
+        return toText({ results: unwrap(res) ?? [] });
+      }
+      default:
+        return toError(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    if (error instanceof ApiClientError) {
+      return toError(formatApiClientError(error), { raw: true });
+    }
+    return toError(error instanceof Error ? error.message : String(error));
+  }
+}
+
+// src/index.ts
+var server = new Server(
+  {
+    name: "onekb-mcp",
+    version: "2.0.0"
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request2) => {
+  const { name, arguments: args } = request2.params;
+  return handleToolCall(name, args || {});
+});
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("OneKB MCP Server running on stdio");
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "onekb-mcp",
+  "version": "2.0.0",
+  "description": "MCP Server for OneKB (One Knowledge Base) - 17 tools for AI-native markdown knowledge management",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "onekb-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BBS6215/OneKnowledgeBase-V2.git",
+    "directory": "mcp-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "onekb",
+    "knowledge-base",
+    "markdown",
+    "ai"
+  ],
+  "license": "MIT",
+  "homepage": "https://oneknowledgebase.com",
+  "author": "OneKB",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.8"
+  }
+}