@dinoxx/dinox-cli 1.0.16 → 1.0.18

package/README.md

@@ -656,7 +656,103 @@ sync.timeoutMs    (必须为正整数)
 
 ---
 
-## 9. 查看帮助
+## 9. MCP Server 与 Cursor 配置
+
+`dino mcp serve` 会启动一个 HTTP JSON-RPC 服务，提供 Dinox 的 MCP tools 给 AI 客户端调用。
+
+### 9.1 启动 MCP 服务
+
+默认监听本机 `127.0.0.1:45137`：
+
+```bash
+dino mcp serve
+```
+
+手动指定端口：
+
+```bash
+dino mcp serve --host 127.0.0.1 --port 45137
+```
+
+### 9.2 局域网访问与鉴权
+
+当 `--host` 为非回环地址（例如 `0.0.0.0`）时，必须提供 token：
+
+```bash
+dino mcp serve --host 0.0.0.0 --port 45137 --token "<your-token>"
+```
+
+也可以使用环境变量：
+
+```bash
+export DINOX_MCP_TOKEN="<your-token>"
+dino mcp serve --host 0.0.0.0 --port 45137
+```
+
+请求头支持：
+
+1. `Authorization: Bearer <token>`
+2. `x-dinox-token: <token>`
+
+### 9.3 快速连通性验证（curl）
+
+初始化握手：
+
+```bash
+curl -X POST http://127.0.0.1:45137 \
+  -H 'content-type: application/json' \
+  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
+```
+
+列出 tools：
+
+```bash
+curl -X POST http://127.0.0.1:45137 \
+  -H 'content-type: application/json' \
+  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
+```
+
+调用 tools（示例：搜索笔记）：
+
+```bash
+curl -X POST http://127.0.0.1:45137 \
+  -H 'content-type: application/json' \
+  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"dinox_search_notes","arguments":{"query":"dinox","limit":5}}}'
+```
+
+### 9.4 Cursor 配置示例
+
+可在以下位置创建 MCP 配置文件（任选其一）：
+
+1. 项目级：`.cursor/mcp.json`
+2. 全局：`~/.cursor/mcp.json`
+
+推荐配置（带 token）：
+
+```json
+{
+  "mcpServers": {
+    "dinox": {
+      "url": "http://127.0.0.1:45137",
+      "headers": {
+        "Authorization": "Bearer ${env:DINOX_MCP_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+若本地仅回环访问且不启用 token，可去掉 `headers` 字段。
+
+### 9.5 常见问题
+
+- 报错 `--token (or DINOX_MCP_TOKEN) is required when --host is non-loopback`：表示你使用了非回环 host，但没提供 token。
+- 返回 `401 Unauthorized`：检查请求头 token 是否与启动服务时一致。
+- 端口冲突：改用 `--port` 指定其他高位端口。
+
+---
+
+## 10. 查看帮助
 
 随时可以看帮助：
 
@@ -675,17 +771,17 @@ dino note create --help
 
 ---
 
-## 10. GitHub Action 自动发布 npm
+## 11. GitHub Action 自动发布 npm
 
 仓库已内置工作流：`/Users/shanks/Documents/GitHub/dinox-cli/.github/workflows/publish-npm.yml`
 
-### 10.1 先配置 Secret
+### 11.1 先配置 Secret
 
 在 GitHub 仓库设置里添加：
 
 - `NPM_TOKEN`：npm 的 publish token（建议使用 granular token，并开启 bypass 2FA）
 
-### 10.2 手动触发发布
+### 11.2 手动触发发布
 
 1. 打开 GitHub 仓库 → **Actions** → **Publish NPM**
 2. 点击 **Run workflow**
@@ -693,13 +789,13 @@ dino note create --help
    - `dry_run`：`true` 只做演练，不真正发布
    - `run_tests`：`true` 时会先执行测试
 
-### 10.3 Push 自动触发
+### 11.3 Push 自动触发
 
 - 每次 push 到默认分支（当前为 `main`）会自动触发发布流程
 - 为兼容分支命名迁移，workflow 也监听 `master`，但发布阶段会只允许默认分支执行
 - 为防止递归触发，workflow 会跳过 `github-actions[bot]` 自己提交的版本 bump commit
 
-### 10.4 工作流行为
+### 11.4 工作流行为
 
 - 只允许在仓库默认分支执行发布（默认分支改名后无需改 workflow 逻辑）
 - 调用仓库脚本 `publish-npm.sh` 自动递增 patch 版本并发布

package/dist/cli.js

@@ -6,6 +6,7 @@ import { registerDaemonCommands } from './daemon/index.js';
 import { registerGraphCommands } from './commands/graph/index.js';
 import { registerInfoCommand } from './commands/info/index.js';
 import { registerMCPCommands } from './commands/mcp/index.js';
+import { registerMetaCommands } from './commands/meta/index.js';
 import { registerNoteCommands } from './commands/notes/index.js';
 import { registerPromptCommands } from './commands/prompt/index.js';
 import { registerSyncCommand } from './commands/sync.js';
@@ -32,6 +33,7 @@ export function createCli() {
     registerGraphCommands(program);
     registerInfoCommand(program);
     registerMCPCommands(program);
+    registerMetaCommands(program);
     registerSyncCommand(program);
     registerUpdateCommand(program);
     registerPromptCommands(program);

package/dist/commands/graph/index.js

@@ -6,7 +6,7 @@ import { loadConfig } from '../../config/store.js';
 import { resolveConfig } from '../../config/resolve.js';
 import { connectPowerSync } from '../../powersync/runtime.js';
 import { parseSyncTimeoutMs } from '../../utils/syncTimeout.js';
-import { getBacklinks, getOutlinks, getRelatedNotes } from './repo.js';
+import { getBacklinks, getGraphStats, getOutlinks, getRelatedNotes } from './repo.js';
 function parseDepth(value) {
     if (value === undefined || value === null || value === '') {
         return 2;
@@ -74,6 +74,21 @@ export function registerGraphCommands(program) {
         const result = await sendDaemonRequest('graph.outlinks', { id });
         printYaml(result);
     });
+    graph
+        .command('stats')
+        .description('Get graph statistics')
+        .action(async (_options, command) => {
+        const globals = command.optsWithGlobals?.() ?? {};
+        const offline = Boolean(globals.offline);
+        if (offline) {
+            const result = await withOfflineDb(command, (db) => getGraphStats(db));
+            printYaml(result);
+            return;
+        }
+        await ensureDaemonRunning();
+        const result = await sendDaemonRequest('graph.stats');
+        printYaml(result);
+    });
     graph
         .command('related')
         .description('Get related notes within N degrees of separation')

package/dist/commands/graph/repo.d.ts

@@ -28,6 +28,13 @@ export type GraphRelatedResult = {
     count: number;
     depth: number;
 };
+export type GraphStatsResult = {
+    notes_count: number;
+    links_count: number;
+    connected_notes_count: number;
+    isolated_notes_count: number;
+};
 export declare function getBacklinks(db: AbstractPowerSyncDatabase, noteId: string): Promise<GraphBacklinksResult>;
 export declare function getOutlinks(db: AbstractPowerSyncDatabase, noteId: string): Promise<GraphOutlinksResult>;
 export declare function getRelatedNotes(db: AbstractPowerSyncDatabase, noteId: string, depth?: number): Promise<GraphRelatedResult>;
+export declare function getGraphStats(db: AbstractPowerSyncDatabase): Promise<GraphStatsResult>;

package/dist/commands/graph/repo.js

@@ -74,3 +74,53 @@ export async function getRelatedNotes(db, noteId, depth = 2) {
         depth,
     };
 }
+export async function getGraphStats(db) {
+    const [notesCountRow, linksCountRow, connectedCountRow] = await Promise.all([
+        db.getOptional(`
+      SELECT COUNT(1) AS count
+      FROM c_note n
+      WHERE n.is_del IS NULL OR n.is_del = 0
+      `, []),
+        db.getOptional(`
+      SELECT COUNT(1) AS count
+      FROM c_note_link l
+      JOIN c_note src ON src.id = l.src_note_id
+      JOIN c_note dst ON dst.id = l.dst_note_id
+      WHERE l.is_del = 0
+        AND (src.is_del IS NULL OR src.is_del = 0)
+        AND (dst.is_del IS NULL OR dst.is_del = 0)
+      `, []),
+        db.getOptional(`
+      SELECT COUNT(1) AS count
+      FROM (
+        SELECT DISTINCT note_id
+        FROM (
+          SELECT l.src_note_id AS note_id
+          FROM c_note_link l
+          JOIN c_note src ON src.id = l.src_note_id
+          JOIN c_note dst ON dst.id = l.dst_note_id
+          WHERE l.is_del = 0
+            AND (src.is_del IS NULL OR src.is_del = 0)
+            AND (dst.is_del IS NULL OR dst.is_del = 0)
+          UNION
+          SELECT l.dst_note_id AS note_id
+          FROM c_note_link l
+          JOIN c_note src ON src.id = l.src_note_id
+          JOIN c_note dst ON dst.id = l.dst_note_id
+          WHERE l.is_del = 0
+            AND (src.is_del IS NULL OR src.is_del = 0)
+            AND (dst.is_del IS NULL OR dst.is_del = 0)
+        ) all_linked
+      ) linked_notes
+      `, []),
+    ]);
+    const notesCount = Number(notesCountRow?.count ?? 0);
+    const linksCount = Number(linksCountRow?.count ?? 0);
+    const connectedNotesCount = Number(connectedCountRow?.count ?? 0);
+    return {
+        notes_count: notesCount,
+        links_count: linksCount,
+        connected_notes_count: connectedNotesCount,
+        isolated_notes_count: Math.max(notesCount - connectedNotesCount, 0),
+    };
+}

package/dist/commands/mcp/index.js

@@ -1,10 +1,11 @@
 import { startMCPServer } from './server.js';
 import { mcpTools } from './tools.js';
 import { isLoopbackHost, resolveMCPAuthToken } from './auth.js';
+import { DEFAULT_MCP_PORT } from './types.js';
 import { DinoxError } from '../../utils/errors.js';
 function parsePort(value) {
     if (value === undefined || value === null || value === '') {
-        return 3000;
+        return DEFAULT_MCP_PORT;
     }
     if (typeof value !== 'string') {
         throw new DinoxError('--port must be a valid port number');
@@ -38,7 +39,7 @@ export function registerMCPCommands(program) {
         .command('serve')
         .description('Start MCP server for AI agent integration')
         .option('--host <string>', 'bind address (default: 127.0.0.1)')
-        .option('--port <number>', 'server port (default: 3000)')
+        .option('--port <number>', `server port (default: ${DEFAULT_MCP_PORT})`)
         .option('--token <string>', 'auth token (or DINOX_MCP_TOKEN env var)')
         .action(async (options) => {
         const port = parsePort(options.port);

package/dist/commands/mcp/server.d.ts

@@ -1,13 +1,14 @@
 import type { IncomingMessage, Server } from 'node:http';
+type JsonRpcId = string | number | null;
 type MCPRequest = {
     jsonrpc: '2.0';
-    id: string | number;
+    id?: JsonRpcId;
     method: string;
     params?: any;
 };
 type MCPResponse = {
     jsonrpc: '2.0';
-    id: string | number;
+    id: JsonRpcId;
     result?: any;
     error?: {
         code: number;
@@ -17,7 +18,7 @@ type MCPResponse = {
 export declare class MCPServer {
     private db;
     initialize(): Promise<void>;
-    handleRequest(req: MCPRequest): Promise<MCPResponse>;
+    handleRequest(req: MCPRequest): Promise<MCPResponse | null>;
     private handleInitialize;
     private handleToolsList;
     private handleToolsCall;

package/dist/commands/mcp/server.js

@@ -1,4 +1,5 @@
 import { createServer } from 'node:http';
+import { DEFAULT_MCP_PORT } from './types.js';
 import { mcpTools } from './tools.js';
 import { isAuthorizedMCPRequest } from './auth.js';
 import { resolveAuthIdentity } from '../../auth/userInfo.js';
@@ -6,8 +7,9 @@ import { loadConfig } from '../../config/store.js';
 import { resolveConfig } from '../../config/resolve.js';
 import { connectPowerSync } from '../../powersync/runtime.js';
 import { parseCreatedAtRange } from '../notes/searchTime.js';
+import { parseNoteSearchFields, projectNoteSearchFields } from '../notes/searchOutput.js';
 import { createNote, getNoteDetails, resolveZettelBoxIdsForCreate, resolveZettelBoxIdsForSearch, searchNotes, validateTagsForCreate, } from '../notes/repo.js';
-import { getBacklinks, getOutlinks, getRelatedNotes } from '../graph/repo.js';
+import { getBacklinks, getGraphStats, getOutlinks, getRelatedNotes } from '../graph/repo.js';
 import { searchTodoTasks } from '../todo/repo.js';
 import { convertMarkdownToNoteContent } from '../../utils/tiptapMarkdown.js';
 import { generateId } from '../../utils/id.js';
@@ -33,6 +35,24 @@ function normalizeLimit(value) {
     }
     return Math.min(int, MAX_SEARCH_LIMIT);
 }
+function normalizeOffset(value) {
+    if (value === undefined || value === null) {
+        return 0;
+    }
+    const raw = typeof value === 'number'
+        ? value
+        : typeof value === 'string'
+            ? Number(value)
+            : NaN;
+    if (!Number.isFinite(raw)) {
+        return 0;
+    }
+    const int = Math.trunc(raw);
+    if (int < 0) {
+        return 0;
+    }
+    return int;
+}
 function normalizeStringArray(value) {
     if (!Array.isArray(value)) {
         return [];
@@ -59,6 +79,40 @@ function parseBoxFilter(value) {
         .filter(Boolean);
     return { names, matchEmpty: false };
 }
+function isJsonRpcId(value) {
+    return value === null || typeof value === 'string' || typeof value === 'number';
+}
+function parseMCPRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Invalid JSON-RPC request');
+    }
+    const record = value;
+    if (record.jsonrpc !== '2.0') {
+        throw new Error('Invalid JSON-RPC request: jsonrpc must be "2.0"');
+    }
+    if (typeof record.method !== 'string' || !record.method.trim()) {
+        throw new Error('Invalid JSON-RPC request: method is required');
+    }
+    if (record.id !== undefined && !isJsonRpcId(record.id)) {
+        throw new Error('Invalid JSON-RPC request: id must be a string, number, or null');
+    }
+    return {
+        jsonrpc: '2.0',
+        id: record.id,
+        method: record.method.trim(),
+        params: record.params,
+    };
+}
+function hasRequestId(req) {
+    return req.id !== undefined;
+}
+function buildResponse(req, payload) {
+    return {
+        jsonrpc: '2.0',
+        id: req.id ?? null,
+        ...payload,
+    };
+}
 async function readJsonBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -91,44 +145,61 @@ export class MCPServer {
         this.db = db;
     }
     async handleRequest(req) {
+        if (req.method === 'notifications/initialized') {
+            return hasRequestId(req) ? buildResponse(req, { result: {} }) : null;
+        }
+        const shouldRespond = hasRequestId(req);
         try {
             switch (req.method) {
                 case 'initialize':
+                    if (!shouldRespond) {
+                        return null;
+                    }
                     return this.handleInitialize(req);
                 case 'tools/list':
+                    if (!shouldRespond) {
+                        return null;
+                    }
                     return this.handleToolsList(req);
                 case 'tools/call':
+                    if (!shouldRespond) {
+                        await this.handleToolsCall(req);
+                        return null;
+                    }
                     return await this.handleToolsCall(req);
                 default:
-                    return {
-                        jsonrpc: '2.0',
-                        id: req.id,
+                    if (!shouldRespond) {
+                        return null;
+                    }
+                    return buildResponse(req, {
                         error: { code: -32601, message: 'Method not found' },
-                    };
+                    });
             }
         }
         catch (error) {
-            return {
-                jsonrpc: '2.0',
-                id: req.id,
+            if (!shouldRespond) {
+                return null;
+            }
+            return buildResponse(req, {
                 error: { code: -32603, message: error.message || 'Internal error' },
-            };
+            });
         }
     }
     handleInitialize(req) {
-        const serverInfo = {
-            name: 'dinox-mcp-server',
-            version: getPackageVersion(),
+        const result = {
             protocolVersion: '2024-11-05',
             capabilities: {
-                tools: true,
-                resources: false,
+                tools: {},
+            },
+            serverInfo: {
+                name: 'dinox-mcp-server',
+                version: getPackageVersion(),
             },
         };
-        return { jsonrpc: '2.0', id: req.id, result: serverInfo };
+        return buildResponse(req, { result });
     }
     handleToolsList(req) {
-        return { jsonrpc: '2.0', id: req.id, result: { tools: mcpTools } };
+        return buildResponse(req, { result: { tools: mcpTools } });
     }
     async handleToolsCall(req) {
         if (!this.db) {
@@ -152,6 +223,8 @@ export class MCPServer {
                     days: daysInput,
                 });
                 const limit = normalizeLimit(args.limit);
+                const offset = normalizeOffset(args.offset);
+                const fields = parseNoteSearchFields(args.fields, 'dinox_search_notes.fields');
                 const rows = await searchNotes(this.db, keyword, {
                     includeDeleted: false,
                     tagsExpression: tagsExpression || undefined,
@@ -160,13 +233,21 @@ export class MCPServer {
                     zettelBoxIds,
                     matchEmptyZettelBoxes: matchEmptyBoxes,
                 });
-                const result = rows.slice(0, limit);
-                const text = JSON.stringify(result);
-                return {
-                    jsonrpc: '2.0',
-                    id: req.id,
-                    result: { content: [{ type: 'text', text }] },
-                };
+                const totalCount = rows.length;
+                const paged = rows.slice(offset, offset + limit);
+                const result = projectNoteSearchFields(paged, fields);
+                const text = JSON.stringify({
+                    meta: {
+                        total_count: totalCount,
+                        returned_count: result.length,
+                        limit,
+                        offset,
+                        has_more: offset + result.length < totalCount,
+                        fields: fields ?? null,
+                    },
+                    notes: result,
+                });
+                return buildResponse(req, { result: { content: [{ type: 'text', text }] } });
             }
             case 'dinox_get_note': {
                 if (typeof args.id !== 'string' || !args.id.trim()) {
@@ -174,11 +255,7 @@ export class MCPServer {
                 }
                 const notes = await getNoteDetails(this.db, [args.id.trim()]);
                 const text = JSON.stringify(notes[0] ?? null);
-                return {
-                    jsonrpc: '2.0',
-                    id: req.id,
-                    result: { content: [{ type: 'text', text }] },
-                };
+                return buildResponse(req, { result: { content: [{ type: 'text', text }] } });
             }
             case 'dinox_create_note': {
                 const title = typeof args.title === 'string' ? args.title.trim() : '';
@@ -208,11 +285,7 @@ export class MCPServer {
                     userId: identity.userId,
                 });
                 const text = JSON.stringify({ id });
-                return {
-                    jsonrpc: '2.0',
-                    id: req.id,
-                    result: { content: [{ type: 'text', text }] },
-                };
+                return buildResponse(req, { result: { content: [{ type: 'text', text }] } });
             }
             case 'dinox_graph_backlinks': {
                 if (typeof args.id !== 'string' || !args.id.trim()) {
@@ -220,11 +293,7 @@ export class MCPServer {
                 }
                 const result = await getBacklinks(this.db, args.id.trim());
                 const text = JSON.stringify(result);
-                return {
-                    jsonrpc: '2.0',
-                    id: req.id,
-                    result: { content: [{ type: 'text', text }] },
-                };
+                return buildResponse(req, { result: { content: [{ type: 'text', text }] } });
             }
             case 'dinox_graph_outlinks': {
                 if (typeof args.id !== 'string' || !args.id.trim()) {
@@ -232,11 +301,7 @@ export class MCPServer {
                 }
                 const result = await getOutlinks(this.db, args.id.trim());
                 const text = JSON.stringify(result);
-                return {
-                    jsonrpc: '2.0',
-                    id: req.id,
-                    result: { content: [{ type: 'text', text }] },
-                };
+                return buildResponse(req, { result: { content: [{ type: 'text', text }] } });
             }
             case 'dinox_graph_related': {
                 if (typeof args.id !== 'string' || !args.id.trim()) {
@@ -248,11 +313,12 @@ export class MCPServer {
                 const depth = Math.min(Math.max(depthRaw, 1), 5);
                 const result = await getRelatedNotes(this.db, args.id.trim(), depth);
                 const text = JSON.stringify(result);
-                return {
-                    jsonrpc: '2.0',
-                    id: req.id,
-                    result: { content: [{ type: 'text', text }] },
-                };
+                return buildResponse(req, { result: { content: [{ type: 'text', text }] } });
+            }
+            case 'dinox_graph_stats': {
+                const result = await getGraphStats(this.db);
+                const text = JSON.stringify(result);
+                return buildResponse(req, { result: { content: [{ type: 'text', text }] } });
             }
             case 'dinox_search_todos': {
                 const query = typeof args.query === 'string' ? args.query : '';
@@ -268,11 +334,7 @@ export class MCPServer {
                     scanLimit: 200,
                 });
                 const text = JSON.stringify(result);
-                return {
-                    jsonrpc: '2.0',
-                    id: req.id,
-                    result: { content: [{ type: 'text', text }] },
-                };
+                return buildResponse(req, { result: { content: [{ type: 'text', text }] } });
             }
             default:
                 throw new Error(`Unknown tool: ${name}`);
@@ -284,7 +346,7 @@ export class MCPServer {
         }
     }
 }
-export async function startMCPServer(port = 3000, host = '127.0.0.1', authToken) {
+export async function startMCPServer(port = DEFAULT_MCP_PORT, host = '127.0.0.1', authToken) {
     const mcpServer = new MCPServer();
     await mcpServer.initialize();
     const server = createServer(async (req, res) => {
@@ -298,8 +360,14 @@ export async function startMCPServer(port = 3000, host = '127.0.0.1', authToken)
                 return;
             }
             try {
-                const mcpReq = await readJsonBody(req);
+                const body = await readJsonBody(req);
+                const mcpReq = parseMCPRequest(body);
                 const mcpRes = await mcpServer.handleRequest(mcpReq);
+                if (!mcpRes) {
+                    res.writeHead(204);
+                    res.end();
+                    return;
+                }
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify(mcpRes));
             }

package/dist/commands/mcp/tools.js

@@ -12,6 +12,12 @@ export const mcpTools = [
                 days: { type: 'number', description: 'Recent N days' },
                 box: { type: 'string', description: 'Zettel box name' },
                 limit: { type: 'number', description: 'Max results (default: 50)' },
+                offset: { type: 'number', description: 'Result offset (default: 0)' },
+                fields: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Returned fields: id,title,summary,tags,created_at,zettel_boxes',
+                },
             },
         },
     },
@@ -74,6 +80,14 @@ export const mcpTools = [
             required: ['id'],
         },
     },
+    {
+        name: 'dinox_graph_stats',
+        description: 'Get graph statistics for notes and links',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
     {
         name: 'dinox_search_todos',
         description: 'Search todo tasks',

package/dist/commands/mcp/types.d.ts

@@ -16,9 +16,13 @@ export type MCPResource = {
 export type MCPServerInfo = {
     name: string;
     version: string;
+};
+export type MCPInitializeResult = {
     protocolVersion: string;
     capabilities: {
-        tools?: boolean;
-        resources?: boolean;
+        tools?: Record<string, never>;
+        resources?: Record<string, never>;
     };
+    serverInfo: MCPServerInfo;
 };
+export declare const DEFAULT_MCP_PORT = 45137;

package/dist/commands/mcp/types.js

@@ -1 +1 @@
-export {};
+export const DEFAULT_MCP_PORT = 45137;

package/dist/commands/meta/index.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerMetaCommands(program: Command): void;