@dinoxx/dinox-cli 1.0.15 → 1.0.17

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

@@ -2,7 +2,11 @@ import { Command } from 'commander';
 import { registerAuthCommands } from './commands/auth/index.js';
 import { registerBoxesCommand } from './commands/boxes/index.js';
 import { registerConfigCommands } from './commands/config/index.js';
+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';
@@ -25,7 +29,11 @@ export function createCli() {
     registerAuthCommands(program);
     registerBoxesCommand(program);
     registerConfigCommands(program);
+    registerDaemonCommands(program);
+    registerGraphCommands(program);
     registerInfoCommand(program);
+    registerMCPCommands(program);
+    registerMetaCommands(program);
     registerSyncCommand(program);
     registerUpdateCommand(program);
     registerPromptCommands(program);

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

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

package/dist/commands/graph/index.js

@@ -0,0 +1,113 @@
+import { printYaml } from '../../utils/output.js';
+import { sendDaemonRequest } from '../../daemon/client.js';
+import { ensureDaemonRunning } from '../../daemon/ensure.js';
+import { DinoxError } from '../../utils/errors.js';
+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, getGraphStats, getOutlinks, getRelatedNotes } from './repo.js';
+function parseDepth(value) {
+    if (value === undefined || value === null || value === '') {
+        return 2;
+    }
+    if (typeof value !== 'string') {
+        throw new DinoxError('--depth must be a positive integer');
+    }
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        throw new DinoxError('--depth must be a positive integer');
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 5) {
+        throw new DinoxError('--depth must be between 1 and 5');
+    }
+    return Math.trunc(parsed);
+}
+async function withOfflineDb(command, fn) {
+    const globals = command.optsWithGlobals?.() ?? {};
+    const offline = Boolean(globals.offline);
+    if (!offline) {
+        throw new DinoxError('withOfflineDb called without --offline');
+    }
+    const config = resolveConfig(await loadConfig());
+    const timeoutMs = parseSyncTimeoutMs(globals.syncTimeout) ?? config.sync.timeoutMs;
+    const { db } = await connectPowerSync({ config, offline: true, timeoutMs });
+    try {
+        return await fn(db);
+    }
+    finally {
+        await db.close().catch(() => undefined);
+    }
+}
+export function registerGraphCommands(program) {
+    const graph = program.command('graph').description('Query knowledge graph');
+    graph
+        .command('backlinks')
+        .description('Get notes that link to this note')
+        .argument('<id>', 'note id')
+        .action(async (id, _options, command) => {
+        const globals = command.optsWithGlobals?.() ?? {};
+        const offline = Boolean(globals.offline);
+        if (offline) {
+            const result = await withOfflineDb(command, (db) => getBacklinks(db, id));
+            printYaml(result);
+            return;
+        }
+        await ensureDaemonRunning();
+        const result = await sendDaemonRequest('graph.backlinks', { id });
+        printYaml(result);
+    });
+    graph
+        .command('outlinks')
+        .description('Get notes that this note links to')
+        .argument('<id>', 'note id')
+        .action(async (id, _options, command) => {
+        const globals = command.optsWithGlobals?.() ?? {};
+        const offline = Boolean(globals.offline);
+        if (offline) {
+            const result = await withOfflineDb(command, (db) => getOutlinks(db, id));
+            printYaml(result);
+            return;
+        }
+        await ensureDaemonRunning();
+        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')
+        .argument('<id>', 'note id')
+        .option('--depth <n>', 'degrees of separation (1-5, default: 2)')
+        .action(async (id, options, command) => {
+        const depth = parseDepth(options.depth);
+        const globals = command.optsWithGlobals?.() ?? {};
+        const offline = Boolean(globals.offline);
+        if (offline) {
+            const result = await withOfflineDb(command, (db) => getRelatedNotes(db, id, depth));
+            printYaml(result);
+            return;
+        }
+        await ensureDaemonRunning();
+        const result = await sendDaemonRequest('graph.related', { id, depth });
+        printYaml(result);
+    });
+    graph.action((_options, command) => {
+        command.outputHelp();
+    });
+}

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

@@ -0,0 +1,40 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+export type NoteLinkRecord = {
+    id: string;
+    src_note_id: string;
+    dst_note_id: string;
+    relation: string | null;
+    created_at: string;
+};
+export type LinkedNote = {
+    note_id: string;
+    title: string;
+    relation: string | null;
+    link_created_at: string;
+};
+export type GraphBacklinksResult = {
+    note_id: string;
+    backlinks: LinkedNote[];
+    count: number;
+};
+export type GraphOutlinksResult = {
+    note_id: string;
+    outlinks: LinkedNote[];
+    count: number;
+};
+export type GraphRelatedResult = {
+    note_id: string;
+    related: LinkedNote[];
+    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

@@ -0,0 +1,126 @@
+export async function getBacklinks(db, noteId) {
+    const rows = await db.getAll(`SELECT
+      l.id,
+      l.src_note_id,
+      l.dst_note_id,
+      l.relation,
+      l.created_at,
+      n.title
+    FROM c_note_link l
+    LEFT JOIN c_note n ON l.src_note_id = n.id
+    WHERE l.dst_note_id = ? AND l.is_del = 0 AND (n.is_del = 0 OR n.is_del IS NULL)
+    ORDER BY l.created_at DESC`, [noteId]);
+    const backlinks = rows.map((row) => ({
+        note_id: row.src_note_id,
+        title: row.title || '',
+        relation: row.relation,
+        link_created_at: row.created_at,
+    }));
+    return {
+        note_id: noteId,
+        backlinks,
+        count: backlinks.length,
+    };
+}
+export async function getOutlinks(db, noteId) {
+    const rows = await db.getAll(`SELECT
+      l.id,
+      l.src_note_id,
+      l.dst_note_id,
+      l.relation,
+      l.created_at,
+      n.title
+    FROM c_note_link l
+    LEFT JOIN c_note n ON l.dst_note_id = n.id
+    WHERE l.src_note_id = ? AND l.is_del = 0 AND (n.is_del = 0 OR n.is_del IS NULL)
+    ORDER BY l.created_at DESC`, [noteId]);
+    const outlinks = rows.map((row) => ({
+        note_id: row.dst_note_id,
+        title: row.title || '',
+        relation: row.relation,
+        link_created_at: row.created_at,
+    }));
+    return {
+        note_id: noteId,
+        outlinks,
+        count: outlinks.length,
+    };
+}
+export async function getRelatedNotes(db, noteId, depth = 2) {
+    const visited = new Set([noteId]);
+    const related = new Map();
+    async function traverse(currentId, currentDepth) {
+        if (currentDepth > depth)
+            return;
+        const [backlinks, outlinks] = await Promise.all([
+            getBacklinks(db, currentId),
+            getOutlinks(db, currentId),
+        ]);
+        for (const link of [...backlinks.backlinks, ...outlinks.outlinks]) {
+            if (!visited.has(link.note_id)) {
+                visited.add(link.note_id);
+                related.set(link.note_id, link);
+                if (currentDepth < depth) {
+                    await traverse(link.note_id, currentDepth + 1);
+                }
+            }
+        }
+    }
+    await traverse(noteId, 1);
+    return {
+        note_id: noteId,
+        related: Array.from(related.values()),
+        count: related.size,
+        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/auth.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingHttpHeaders } from 'node:http';
+export declare function isLoopbackHost(host: string): boolean;
+export declare function resolveMCPAuthToken(tokenOption: unknown, envToken?: string | undefined): string | undefined;
+export declare function isAuthorizedMCPRequest(headers: IncomingHttpHeaders, expectedToken?: string): boolean;

package/dist/commands/mcp/auth.js

@@ -0,0 +1,75 @@
+import { timingSafeEqual } from 'node:crypto';
+import { DinoxError } from '../../utils/errors.js';
+const AUTH_HEADER_RE = /^Bearer\s+(.+)$/i;
+export function isLoopbackHost(host) {
+    const normalized = host.trim().toLowerCase();
+    return normalized === '127.0.0.1' || normalized === 'localhost' || normalized === '::1';
+}
+export function resolveMCPAuthToken(tokenOption, envToken = process.env.DINOX_MCP_TOKEN) {
+    if (tokenOption !== undefined && tokenOption !== null) {
+        if (typeof tokenOption !== 'string') {
+            throw new DinoxError('--token must be a non-empty string');
+        }
+        const parsed = tokenOption.trim();
+        if (!parsed) {
+            throw new DinoxError('--token must be a non-empty string');
+        }
+        return parsed;
+    }
+    const fromEnv = envToken?.trim() ?? '';
+    return fromEnv || undefined;
+}
+function readHeaderTokenValue(value) {
+    if (typeof value === 'string') {
+        const parsed = value.trim();
+        return parsed || undefined;
+    }
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    for (const item of value) {
+        const parsed = item.trim();
+        if (parsed) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+function readBearerToken(headers) {
+    const authorization = readHeaderTokenValue(headers.authorization);
+    if (!authorization) {
+        return undefined;
+    }
+    const match = authorization.match(AUTH_HEADER_RE);
+    if (!match) {
+        return undefined;
+    }
+    const token = match[1]?.trim() ?? '';
+    return token || undefined;
+}
+function readMCPToken(headers) {
+    const bearer = readBearerToken(headers);
+    if (bearer) {
+        return bearer;
+    }
+    const raw = readHeaderTokenValue(headers['x-dinox-token']);
+    return raw?.trim() || undefined;
+}
+function secureTokenEquals(left, right) {
+    const leftBuffer = Buffer.from(left);
+    const rightBuffer = Buffer.from(right);
+    if (leftBuffer.length !== rightBuffer.length) {
+        return false;
+    }
+    return timingSafeEqual(leftBuffer, rightBuffer);
+}
+export function isAuthorizedMCPRequest(headers, expectedToken) {
+    if (!expectedToken) {
+        return true;
+    }
+    const provided = readMCPToken(headers);
+    if (!provided) {
+        return false;
+    }
+    return secureTokenEquals(provided, expectedToken);
+}

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

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

package/dist/commands/mcp/index.js

@@ -0,0 +1,85 @@
+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 DEFAULT_MCP_PORT;
+    }
+    if (typeof value !== 'string') {
+        throw new DinoxError('--port must be a valid port number');
+    }
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        throw new DinoxError('--port must be a valid port number');
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) {
+        throw new DinoxError('--port must be between 1 and 65535');
+    }
+    return Math.trunc(parsed);
+}
+function parseHost(value) {
+    if (value === undefined || value === null || value === '') {
+        return '127.0.0.1';
+    }
+    if (typeof value !== 'string') {
+        throw new DinoxError('--host must be a valid hostname or IP address');
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new DinoxError('--host must be a valid hostname or IP address');
+    }
+    return trimmed;
+}
+export function registerMCPCommands(program) {
+    const mcp = program.command('mcp').description('MCP (Model Context Protocol) server');
+    mcp
+        .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: ${DEFAULT_MCP_PORT})`)
+        .option('--token <string>', 'auth token (or DINOX_MCP_TOKEN env var)')
+        .action(async (options) => {
+        const port = parsePort(options.port);
+        const host = parseHost(options.host);
+        const token = resolveMCPAuthToken(options.token);
+        const loopback = isLoopbackHost(host);
+        if (!loopback && !token) {
+            throw new DinoxError('--token (or DINOX_MCP_TOKEN) is required when --host is non-loopback');
+        }
+        console.log('Starting Dinox MCP server...');
+        console.log(`Host: ${host}`);
+        console.log(`Port: ${port}`);
+        console.log(`Auth: ${token ? 'enabled' : 'disabled (loopback only)'}`);
+        console.log('Protocol: Model Context Protocol (MCP)');
+        if (!loopback) {
+            console.log('warning: binding to a non-loopback host may expose your local data; use firewall/auth as needed');
+        }
+        console.log('');
+        console.log('Available tools:');
+        for (const tool of mcpTools) {
+            console.log(`  - ${tool.name}`);
+        }
+        console.log('');
+        const { server, mcpServer } = await startMCPServer(port, host, token);
+        let shuttingDown = false;
+        const shutdown = async () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            await new Promise((resolve) => server.close(() => resolve()));
+            await mcpServer.close();
+        };
+        process.on('SIGINT', () => {
+            void shutdown().finally(() => process.exit(0));
+        });
+        process.on('SIGTERM', () => {
+            void shutdown().finally(() => process.exit(0));
+        });
+    });
+    mcp.action((_options, command) => {
+        command.outputHelp();
+    });
+}

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

@@ -0,0 +1,31 @@
+import type { IncomingMessage, Server } from 'node:http';
+type JsonRpcId = string | number | null;
+type MCPRequest = {
+    jsonrpc: '2.0';
+    id?: JsonRpcId;
+    method: string;
+    params?: any;
+};
+type MCPResponse = {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result?: any;
+    error?: {
+        code: number;
+        message: string;
+    };
+};
+export declare class MCPServer {
+    private db;
+    initialize(): Promise<void>;
+    handleRequest(req: MCPRequest): Promise<MCPResponse | null>;
+    private handleInitialize;
+    private handleToolsList;
+    private handleToolsCall;
+    close(): Promise<void>;
+}
+export declare function startMCPServer(port?: number, host?: string, authToken?: string): Promise<{
+    server: Server<typeof IncomingMessage, typeof import("http").ServerResponse>;
+    mcpServer: MCPServer;
+}>;
+export {};