rote-toolkit 0.3.3 → 0.4.0

package/README.md

@@ -1,79 +1,103 @@
+<p align="right">English | <a href="./README.zh-CN.md">中文</a></p>
+
 # Rote Toolkit
 
-Rote Toolkit 是一个基于 TypeScript 的增强工具包，主要用于在终端或 AI Agents 侧连接和增强你的 [Rote](https://rote.ink) 笔记系统。基于 Rote OpenKey API 授权，即插即用，无需繁复的登录流程。
+Rote Toolkit is a TypeScript toolkit for connecting to and extending your [Rote](https://rote.ink) note system from terminal workflows and AI agents. It uses the Rote OpenKey API for simple, reusable authentication.
+
+Main project repository: [`Rabithua/rote`](https://github.com/Rabithua/rote).
 
-## 特性
+## Features
 
-- **CLI 模式**：通过终端快速记笔记、搜索笔记。
-- **MCP 模式**：作为 Model Context Protocol 服务端，让 AI (Claude/Cursor) 能够安全、规范地读写 Rote 笔记。
-- **无感鉴权**：只需一次配置 OpenKey 即可长期使用。
+- **CLI mode**: quickly create and search notes from terminal.
+- **MCP mode**: run as a Model Context Protocol server so AI tools (Claude/Cursor/VS Code) can safely read and write Rote notes.
+- **Simple auth**: configure OpenKey once and reuse it.
 
-## 安装
+## Install
 
-> 要求 Node.js v18 或更高版本。
+> Node.js v18 or higher is required.
 
 ```bash
 npm install -g rote-toolkit
 ```
 
-## 配置鉴权
+## Configure Auth
 
-运行以下命令进行全局配置：
+Run this command once:
 
 ```bash
 rote config
 ```
 
-系统会提示你输入：
+You will be prompted for:
 
-1. **Rote API URL**：例如 `https://your-rote-domain.com`
-2. **OpenKey**：你的 API 密钥
+1. **Rote API URL**: for example `https://your-rote-domain.com`
+2. **OpenKey**: your API key
 
-凭证会保存在本地：`~/.rote-toolkit/config.json`。
+Credentials are stored at: `~/.rote-toolkit/config.json`.
 
-## CLI 模式使用指南
+## CLI Usage
 
-### 1) 快速记录笔记
+### 1) Create a note
 
 ```bash
-rote add "今天学到了 MCP 协议，非常有趣！"
+rote add "Today I learned MCP and it is great"
 ```
 
-附带标签、设为公开并置顶：
+Add tags, publish as public, and pin:
 
 ```bash
-rote add "实现了一个新的前端组件" -t "代码,前端,React" --public --pin
+rote add "Built a new frontend component" -t "code,frontend,React" --public --pin
 ```
 
-### 2) 搜索和获取笔记
+### 2) Search and list notes
 
-搜索包含 "MCP" 的笔记：
+Search notes containing `MCP`:
 
 ```bash
 rote search "MCP"
 ```
 
-获取最近的笔记（支持过滤归档和标签）：
+List recent notes (with archive/tag filters):
+
+```bash
+rote list --limit 5 --archived -t "knowledge"
+```
+
+List explore notes (no auth required):
 
 ```bash
-rote list --limit 5 --archived -t "知识管理"
+rote explore --limit 5
 ```
 
-## MCP 模式使用指南
+## MCP Usage
 
-启动 MCP Server：
+### Do I need pre-installation?
+
+No.
+If you configure MCP with `npx` or `bunx`, the package is downloaded and run automatically when the MCP server starts.
+
+Global install is only needed when you want to run commands directly on your machine:
 
 ```bash
-rote mcp
+npm install -g rote-toolkit
+```
+
+### 1) Configure credentials first (one time)
+
+```bash
+rote config
 ```
 
-或独立命令：
+### 2) Manual local start (optional, for debugging)
+
+These two commands are equivalent:
 
 ```bash
+rote mcp
 rote-mcp
 ```
 
-### Claude Desktop / VS Code 配置示例（推荐）
+### 3) Claude Desktop example
 
 ```json
 {
@@ -86,28 +110,42 @@ rote-mcp
 }
 ```
 
-使用 Bun 也可以：
+### 4) VS Code example
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "rote-toolkit": {
+      "type": "stdio",
       "command": "bunx",
-      "args": ["-y", "rote-toolkit@latest", "rote-mcp"]
+      "args": ["-y", "--package", "rote-toolkit@latest", "rote-mcp"]
     }
   }
 }
 ```
 
-### AI 可使用的能力 (Tools)
+### Version strategy
+
+- Track latest: `rote-toolkit@latest`
+- Reproducible setup: pin a version, for example `rote-toolkit@0.3.3`
+
+### Common errors
+
+- `could not determine executable to run`: usually incorrect `npx` args, use `-p rote-toolkit@... rote-mcp`.
+- `unknown command 'rote-mcp'` (bunx): include `--package`, for example `bunx -y --package rote-toolkit@latest rote-mcp`.
+
+### Available AI Tools
 
 - `rote_create_note`
+- `rote_update_note`
+- `rote_delete_note`
 - `rote_search_notes`
 - `rote_list_notes`
+- `rote_explore_notes`
 
-## 本地开发
+## Local Development
 
-[text](../../../Downloads/API-KEY-GUIDE.md)
+[API Key Usage Guide](./API-KEY-GUIDE.md)
 
 ```bash
 npm install
@@ -115,31 +153,31 @@ npm run build
 npm run dev -- --help
 ```
 
-## 发布到 npm
+## Publish to npm
 
-首次发布前先登录：
+Login first:
 
 ```bash
 npm login
 ```
 
-自动构建 + 自动升级版本 + 发布：
+Build + bump version + publish:
 
 ```bash
 npm run release:patch
 ```
 
-也支持：
+Also available:
 
 ```bash
 npm run release:minor
 npm run release:major
 ```
 
-发布脚本会执行：
+Release script steps:
 
-1. 检查 git 工作区是否干净
-2. 检查 npm 登录状态
+1. Ensure git workspace is clean
+2. Check npm login state
 3. `npm run build`
 4. `npm pack --dry-run`
 5. `npm version <patch|minor|major>`

package/README.zh-CN.md

@@ -0,0 +1,184 @@
+<p align="right"><a href="./README.md">English</a> | 中文</p>
+
+# Rote Toolkit
+
+Rote Toolkit 是一个基于 TypeScript 的增强工具包，主要用于在终端或 AI Agents 侧连接和增强你的 [Rote](https://rote.ink) 笔记系统。基于 Rote OpenKey API 授权，即插即用，无需繁复的登录流程。
+
+主项目仓库：[`Rabithua/rote`](https://github.com/Rabithua/rote)。
+
+## 特性
+
+- **CLI 模式**：通过终端快速记笔记、搜索笔记。
+- **MCP 模式**：作为 Model Context Protocol 服务端，让 AI (Claude/Cursor) 能够安全、规范地读写 Rote 笔记。
+- **无感鉴权**：只需一次配置 OpenKey 即可长期使用。
+
+## 安装
+
+> 要求 Node.js v18 或更高版本。
+
+```bash
+npm install -g rote-toolkit
+```
+
+## 配置鉴权
+
+运行以下命令进行全局配置：
+
+```bash
+rote config
+```
+
+系统会提示你输入：
+
+1. **Rote API URL**：例如 `https://your-rote-domain.com`
+2. **OpenKey**：你的 API 密钥
+
+凭证会保存在本地：`~/.rote-toolkit/config.json`。
+
+## CLI 模式使用指南
+
+### 1) 快速记录笔记
+
+```bash
+rote add "今天学到了 MCP 协议，非常有趣！"
+```
+
+附带标签、设为公开并置顶：
+
+```bash
+rote add "实现了一个新的前端组件" -t "代码,前端,React" --public --pin
+```
+
+### 2) 搜索和获取笔记
+
+搜索包含 "MCP" 的笔记：
+
+```bash
+rote search "MCP"
+```
+
+获取最近的笔记（支持过滤归档和标签）：
+
+```bash
+rote list --limit 5 --archived -t "知识管理"
+```
+
+获取探索页面的笔记（无需配置 OpenKey）：
+
+```bash
+rote explore --limit 5
+```
+
+## MCP 模式使用指南
+
+### 是否需要提前安装？
+
+不需要。  
+在 VS Code / Claude Desktop 里使用 `npx` 或 `bunx` 配置时，会在启动 MCP Server 时自动下载并运行 `rote-toolkit`。
+
+仅当你希望本机直接运行命令时，才需要全局安装：
+
+```bash
+npm install -g rote-toolkit
+```
+
+### 1) 先完成凭证配置（一次即可）
+
+```bash
+rote config
+```
+
+### 2) 本机手动启动（可选，用于调试）
+
+以下两条命令等价：
+
+```bash
+rote mcp
+rote-mcp
+```
+
+### 3) Claude Desktop 配置示例
+
+```json
+{
+  "mcpServers": {
+    "rote-toolkit": {
+      "command": "npx",
+      "args": ["-y", "-p", "rote-toolkit@latest", "rote-mcp"]
+    }
+  }
+}
+```
+
+### 4) VS Code 配置示例
+
+```json
+{
+  "servers": {
+    "rote-toolkit": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["-y", "--package", "rote-toolkit@latest", "rote-mcp"]
+    }
+  }
+}
+```
+
+### 版本建议
+
+- 追踪最新版：`rote-toolkit@latest`
+- 需要稳定可复现：固定版本号，例如 `rote-toolkit@0.3.3`
+
+### 常见问题
+
+- 报错 `could not determine executable to run`：通常是 `npx` 参数写法不对，确认使用 `-p rote-toolkit@... rote-mcp`。
+- 报错 `unknown command 'rote-mcp'`（bunx）：需要 `--package`，例如 `bunx -y --package rote-toolkit@latest rote-mcp`。
+
+### AI 可使用的能力 (Tools)
+
+- `rote_create_note`
+- `rote_update_note`
+- `rote_delete_note`
+- `rote_search_notes`
+- `rote_list_notes`
+- `rote_explore_notes`
+
+## 本地开发
+
+[API Key Usage Guide](./API-KEY-GUIDE.md)
+
+```bash
+npm install
+npm run build
+npm run dev -- --help
+```
+
+## 发布到 npm
+
+首次发布前先登录：
+
+```bash
+npm login
+```
+
+自动构建 + 自动升级版本 + 发布：
+
+```bash
+npm run release:patch
+```
+
+也支持：
+
+```bash
+npm run release:minor
+npm run release:major
+```
+
+发布脚本会执行：
+
+1. 检查 git 工作区是否干净
+2. 检查 npm 登录状态
+3. `npm run build`
+4. `npm pack --dry-run`
+5. `npm version <patch|minor|major>`
+6. `npm publish`

package/dist/api.d.ts

@@ -1,11 +1,14 @@
-import type { AddReactionInput, CreateArticleInput, CreateNoteInput, ListNotesInput, RemoveReactionInput, RemoveReactionResponse, RoteArticle, RoteNote, RotePermissions, RoteProfile, RoteReaction, SearchNotesInput, ToolkitConfig, UpdateProfileInput } from "./types.js";
+import type { AddReactionInput, CreateArticleInput, CreateNoteInput, ExploreNotesInput, ListNotesInput, RemoveReactionInput, RemoveReactionResponse, RoteArticle, RoteNote, RotePermissions, RoteProfile, RoteReaction, SearchNotesInput, ToolkitConfig, UpdateNoteInput, UpdateProfileInput } from "./types.js";
 export declare class RoteClient {
     private readonly apiUrl;
     private readonly openKey;
     constructor(config?: ToolkitConfig);
     createNote(input: CreateNoteInput): Promise<RoteNote>;
+    updateNote(input: UpdateNoteInput): Promise<RoteNote>;
+    deleteNote(noteId: string): Promise<unknown>;
     searchNotes(input: SearchNotesInput): Promise<RoteNote[]>;
     listNotes(input?: ListNotesInput): Promise<RoteNote[]>;
+    exploreNotes(input?: ExploreNotesInput): Promise<RoteNote[]>;
     createArticle(input: CreateArticleInput): Promise<RoteArticle>;
     addReaction(input: AddReactionInput): Promise<RoteReaction>;
     removeReaction(input: RemoveReactionInput): Promise<RemoveReactionResponse>;

package/dist/api.js

@@ -26,6 +26,59 @@ export class RoteClient {
             body: JSON.stringify(body),
         });
     }
+    async updateNote(input) {
+        const noteId = input.noteId?.trim();
+        if (!noteId) {
+            throw new Error("noteId is required");
+        }
+        const hasUpdates = input.content !== undefined ||
+            input.title !== undefined ||
+            input.tags !== undefined ||
+            input.isPublic !== undefined ||
+            input.pin !== undefined ||
+            input.archived !== undefined ||
+            input.articleId !== undefined;
+        if (!hasUpdates) {
+            throw new Error("at least one field to update is required");
+        }
+        const body = {
+            openkey: this.openKey,
+        };
+        if (input.content !== undefined) {
+            body.content = input.content;
+        }
+        if (input.title !== undefined) {
+            body.title = input.title;
+        }
+        if (input.tags !== undefined) {
+            body.tags = input.tags;
+        }
+        if (input.isPublic !== undefined) {
+            body.state = input.isPublic ? "public" : "private";
+        }
+        if (input.pin !== undefined) {
+            body.pin = input.pin;
+        }
+        if (input.archived !== undefined) {
+            body.archived = input.archived;
+        }
+        if (input.articleId !== undefined) {
+            body.articleId = input.articleId;
+        }
+        return this.request(`/v2/api/openkey/notes/${encodeURIComponent(noteId)}`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    async deleteNote(noteId) {
+        const resolved = noteId?.trim();
+        if (!resolved) {
+            throw new Error("noteId is required");
+        }
+        const params = new URLSearchParams({ openkey: this.openKey });
+        return this.request(`/v2/api/openkey/notes/${encodeURIComponent(resolved)}?${params.toString()}`, { method: "DELETE" });
+    }
     async searchNotes(input) {
         if (!input.keyword?.trim()) {
             throw new Error("keyword is required");
@@ -58,6 +111,13 @@ export class RoteClient {
         }
         return this.request(`/v2/api/openkey/notes?${params.toString()}`);
     }
+    async exploreNotes(input = {}) {
+        const params = new URLSearchParams({
+            limit: String(input.limit ?? 20),
+            skip: String(input.skip ?? 0),
+        });
+        return this.request(`/v2/api/notes/public?${params.toString()}`);
+    }
     async createArticle(input) {
         if (!input.content?.trim()) {
             throw new Error("content is required");

package/dist/cli.js

@@ -159,6 +159,19 @@ program
     });
     printNotes(notes);
 });
+program
+    .command("explore")
+    .description("List explore notes (no authentication required)")
+    .option("-l, --limit <limit>", "max results", parseInt, 20)
+    .option("-s, --skip <skip>", "offset", parseInt, 0)
+    .action(async (options) => {
+    const client = new RoteClient();
+    const notes = await client.exploreNotes({
+        limit: options.limit,
+        skip: options.skip,
+    });
+    printNotes(notes);
+});
 program
     .command("mcp")
     .description("Start MCP server over stdio")

package/dist/mcp.js

@@ -40,6 +40,60 @@ export async function startMcpServer() {
             ],
         };
     });
+    server.registerTool("rote_update_note", {
+        description: "Update an existing note in Rote via OpenKey API.",
+        inputSchema: {
+            noteId: z.string().min(1).describe("Note ID"),
+            content: z.string().optional().describe("Updated note content"),
+            title: z.string().optional().describe("Updated note title"),
+            tags: z.array(z.string()).optional().describe("Updated list of tags"),
+            isPublic: z
+                .boolean()
+                .optional()
+                .describe("Set note visibility (public/private)"),
+            pin: z.boolean().optional().describe("Whether to pin the note"),
+            archived: z.boolean().optional().describe("Whether to archive the note"),
+            articleId: z
+                .string()
+                .optional()
+                .describe("Optional article ID to bind to"),
+        },
+    }, async ({ noteId, content, title, tags, isPublic, pin, archived, articleId }) => {
+        const note = await client.updateNote({
+            noteId,
+            content,
+            title,
+            tags,
+            isPublic,
+            pin,
+            archived,
+            articleId,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Updated note ${note.id}: ${truncateSingleLine(note.content, 100)}`,
+                },
+            ],
+        };
+    });
+    server.registerTool("rote_delete_note", {
+        description: "Delete a note in Rote via OpenKey API.",
+        inputSchema: {
+            noteId: z.string().min(1).describe("Note ID"),
+        },
+    }, async ({ noteId }) => {
+        await client.deleteNote(noteId);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Deleted note ${noteId}`,
+                },
+            ],
+        };
+    });
     server.registerTool("rote_create_article", {
         description: "Create an article in Rote via OpenKey API.",
         inputSchema: {
@@ -217,6 +271,35 @@ export async function startMcpServer() {
             ],
         };
     });
+    server.registerTool("rote_explore_notes", {
+        description: "Get explore notes in Rote (no authentication required).",
+        inputSchema: {
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe("Max results, default 20"),
+            skip: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Pagination offset, default 0"),
+        },
+    }, async ({ limit, skip }) => {
+        const notes = await client.exploreNotes({ limit, skip });
+        const lines = notes.map((note, i) => `${i + 1}. ${truncateSingleLine(note.content, 100)}`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: lines.length > 0 ? lines.join("\n") : "No explore notes found.",
+                },
+            ],
+        };
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/types.d.ts

@@ -24,6 +24,16 @@ export interface CreateNoteInput {
     pin?: boolean;
     articleId?: string;
 }
+export interface UpdateNoteInput {
+    noteId: string;
+    content?: string;
+    title?: string;
+    tags?: string[];
+    isPublic?: boolean;
+    pin?: boolean;
+    archived?: boolean;
+    articleId?: string;
+}
 export interface RoteArticle {
     id: string;
     content: string;
@@ -90,3 +100,7 @@ export interface ListNotesInput {
     archived?: boolean;
     tag?: string[];
 }
+export interface ExploreNotesInput {
+    limit?: number;
+    skip?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rote-toolkit",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "CLI and MCP toolkit for Rote OpenKey API",
   "type": "module",
   "main": "dist/index.js",