zhicun2-mcp 0.3.2

package/README.md

@@ -0,0 +1,59 @@
+# zhicun2-mcp
+
+智存 2.0 的 MCP 服务：AI 通过 `zhi` 工具在扩展侧边栏与用户交互，并阻塞等待回复。
+
+需配合 [智存 2.0 Cursor 扩展](https://github.com/zhicun/zhicun2.0)（`.vsix`）使用。
+
+## 安装（给最终用户）
+
+### 1. 安装扩展
+
+Cursor → **扩展** → `...` → **从 VSIX 安装…** → 选择 `zhicun2-x.x.x.vsix`
+
+### 2. 配置 MCP
+
+在 `~/.cursor/mcp.json`（Windows: `C:\Users\<用户名>\.cursor\mcp.json`）或项目 `.cursor/mcp.json` 中加入：
+
+```json
+{
+  "mcpServers": {
+    "zhicun2": {
+      "command": "npx",
+      "args": ["-y", "zhicun2-mcp"],
+      "env": {
+        "ZHICUN2_WORKSPACE": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+### 3. 重载 Cursor
+
+**Developer: Reload Window**，确认 MCP 面板中 `zhicun2` 已连接。
+
+### 4. 验证
+
+让 Agent 调用 `ping`，应返回 `✅ 智存扩展在线`。
+
+## 环境变量（可选）
+
+| 变量 | 说明 |
+|------|------|
+| `ZHICUN2_WORKSPACE` | 当前工作区路径，多窗口时路由到对应扩展（推荐 `${workspaceFolder}`） |
+| `ZHICUN2_PORT` | 强制指定扩展 HTTP 端口 |
+| `ZHICUN2_WINDOW_ID` | 强制指定 Cursor 窗口 ID |
+
+## 工具
+
+- `zhi` — 向侧边栏发消息并阻塞等待用户回复
+- `ping` — 检测扩展是否在线
+- `mem_read` / `mem_write` — 读写工作区 `.zhicun2/memory/`
+
+## 开发
+
+```bash
+npm install
+npm run build
+npm publish   # 需 npm 登录
+```

package/dist/bridge.d.ts

@@ -0,0 +1,24 @@
+import { resolveBaseUrl, resolveBaseUrlAsync } from "./registry.js";
+export interface PromptPayload {
+    id: string;
+    session_id: string;
+    session_label?: string;
+    message: string;
+    predefined_options?: string[];
+    is_markdown?: boolean;
+}
+export interface WaitResult {
+    status: "answered" | "pending" | "timeout" | "error";
+    response?: string;
+    error?: string;
+}
+export declare function submitPrompt(baseUrl: string, payload: PromptPayload): Promise<void>;
+export declare function waitForResponse(baseUrl: string, sessionId: string, id: string, timeoutMs: number): Promise<WaitResult>;
+export declare function readMemory(baseUrl: string, key: string): Promise<unknown>;
+export declare function writeMemory(baseUrl: string, key: string, value: unknown): Promise<void>;
+export declare function waitForUserReply(payload: PromptPayload, options?: {
+    pollTimeoutMs?: number;
+    maxWaitMs?: number;
+    baseUrl?: string;
+}): Promise<string>;
+export { resolveBaseUrl, resolveBaseUrlAsync };

package/dist/bridge.js

@@ -0,0 +1,62 @@
+import { resolveBaseUrl, resolveBaseUrlAsync } from "./registry.js";
+export async function submitPrompt(baseUrl, payload) {
+    const res = await fetch(`${baseUrl}/api/prompt`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`提交对话失败 (${res.status}): ${text}`);
+    }
+}
+export async function waitForResponse(baseUrl, sessionId, id, timeoutMs) {
+    const qs = new URLSearchParams({
+        timeout: String(timeoutMs),
+        session_id: sessionId,
+    });
+    const res = await fetch(`${baseUrl}/api/prompt/${encodeURIComponent(id)}/wait?${qs.toString()}`, { method: "GET" });
+    if (!res.ok) {
+        const text = await res.text();
+        return { status: "error", error: `等待回复失败 (${res.status}): ${text}` };
+    }
+    return (await res.json());
+}
+export async function readMemory(baseUrl, key) {
+    const res = await fetch(`${baseUrl}/api/memory/${encodeURIComponent(key)}`);
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`读取记忆失败 (${res.status}): ${text}`);
+    }
+    const data = (await res.json());
+    return data.found ? data.value : undefined;
+}
+export async function writeMemory(baseUrl, key, value) {
+    const res = await fetch(`${baseUrl}/api/memory/${encodeURIComponent(key)}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ value }),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`写入记忆失败 (${res.status}): ${text}`);
+    }
+}
+export async function waitForUserReply(payload, options) {
+    const baseUrl = options?.baseUrl ?? resolveBaseUrl();
+    const pollTimeoutMs = options?.pollTimeoutMs ?? 30000;
+    const maxWaitMs = options?.maxWaitMs ?? 24 * 60 * 60 * 1000;
+    const deadline = Date.now() + maxWaitMs;
+    await submitPrompt(baseUrl, payload);
+    while (Date.now() < deadline) {
+        const result = await waitForResponse(baseUrl, payload.session_id, payload.id, pollTimeoutMs);
+        if (result.status === "answered" && result.response !== undefined) {
+            return result.response;
+        }
+        if (result.status === "error") {
+            throw new Error(result.error ?? "未知错误");
+        }
+    }
+    throw new Error("等待用户回复超时");
+}
+export { resolveBaseUrl, resolveBaseUrlAsync };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { randomUUID } from "crypto";
+import { waitForUserReply, readMemory, writeMemory, resolveBaseUrlAsync } from "./bridge.js";
+import { normalizeSessionId } from "./session-id.js";
+const server = new Server({ name: "zhicun2", version: "0.3.2" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "zhi",
+            description: "【必读 zhicun2-interaction 规则】智存交互工具：向指定 session 的用户展示消息并阻塞等待回复。禁止在 Cursor 聊天中做确认/提问。同一 Agent 对话线程必须使用稳定的 session_id（格式：项目名/任务名）。完成任何请求前必须调用。",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    message: {
+                        type: "string",
+                        description: "展示给用户的消息",
+                    },
+                    session_id: {
+                        type: "string",
+                        description: "会话隔离 ID。同一对话线程保持不变，如「格力app/Unpack」「zhicun2/架构」",
+                    },
+                    session_label: {
+                        type: "string",
+                        description: "侧边栏 Tab 显示名（可选，首次创建 session 时生效）",
+                    },
+                    predefined_options: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "预定义选项（可选）",
+                    },
+                    is_markdown: {
+                        type: "boolean",
+                        description: "message 是否为 Markdown，默认 true",
+                    },
+                },
+                required: ["message", "session_id"],
+            },
+        },
+        {
+            name: "mem_read",
+            description: "读取工作区 .zhicun2/memory/ 下的持久化记忆（JSON）",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: {
+                        type: "string",
+                        description: "记忆键名，如 preferences、user_notes",
+                    },
+                },
+                required: ["key"],
+            },
+        },
+        {
+            name: "mem_write",
+            description: "写入工作区 .zhicun2/memory/ 下的持久化记忆（JSON）",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: {
+                        type: "string",
+                        description: "记忆键名",
+                    },
+                    value: {
+                        description: "任意 JSON 可序列化值",
+                    },
+                },
+                required: ["key", "value"],
+            },
+        },
+        {
+            name: "ping",
+            description: "检测智存扩展 HTTP 服务是否在线，返回窗口与会话信息",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    if (name === "ping") {
+        const { baseUrl, matched, allInstances } = await resolveBaseUrlAsync();
+        try {
+            const res = await fetch(`${baseUrl}/api/health`);
+            const data = (await res.json());
+            const instanceLines = allInstances
+                .map((i) => `  · ${i.windowId.slice(0, 8)} :${i.port} [${i.workspaceFolders.join(", ") || "无工作区"}]`)
+                .join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: data.ok
+                            ? `✅ 智存扩展在线 (${baseUrl})\n` +
+                                `窗口: ${data.windowId ?? "?"}\n` +
+                                `工作区: ${data.workspaceRoot ?? "?"}\n` +
+                                `活跃会话: ${data.sessionCount ?? 0}\n` +
+                                `路由命中: ${matched ? matched.windowId.slice(0, 8) + " :" + matched.port : "默认/legacy"}\n` +
+                                `存活实例 (${allInstances.length}):\n${instanceLines || "  (无)"}`
+                            : `⚠️ 扩展响应异常 (${baseUrl})`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ 无法连接智存扩展 (${baseUrl})\n` +
+                            `请确认对应 Cursor 窗口已加载扩展。\n` +
+                            `存活实例: ${allInstances.length}\n` +
+                            `${String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    if (name === "mem_read") {
+        const key = String(args.key ?? "").trim();
+        if (!key) {
+            return { content: [{ type: "text", text: "key 不能为空" }], isError: true };
+        }
+        const { baseUrl } = await resolveBaseUrlAsync();
+        try {
+            const value = await readMemory(baseUrl, key);
+            if (value === undefined) {
+                return { content: [{ type: "text", text: `key "${key}" 不存在` }] };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `❌ 读取失败: ${String(err)}` }],
+                isError: true,
+            };
+        }
+    }
+    if (name === "mem_write") {
+        const key = String(args.key ?? "").trim();
+        if (!key) {
+            return { content: [{ type: "text", text: "key 不能为空" }], isError: true };
+        }
+        const { baseUrl } = await resolveBaseUrlAsync();
+        try {
+            await writeMemory(baseUrl, key, args.value);
+            return { content: [{ type: "text", text: `✅ 已写入 key "${key}"` }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `❌ 写入失败: ${String(err)}` }],
+                isError: true,
+            };
+        }
+    }
+    if (name === "zhi") {
+        const message = String(args.message ?? "");
+        const sessionId = normalizeSessionId(args.session_id ? String(args.session_id) : undefined);
+        if (!message.trim()) {
+            return {
+                content: [{ type: "text", text: "message 不能为空" }],
+                isError: true,
+            };
+        }
+        if (!sessionId.trim()) {
+            return {
+                content: [{ type: "text", text: "session_id 不能为空" }],
+                isError: true,
+            };
+        }
+        const predefinedOptions = Array.isArray(args.predefined_options)
+            ? args.predefined_options.map(String)
+            : undefined;
+        const sessionLabel = args.session_label ? String(args.session_label) : undefined;
+        const isMarkdown = args.is_markdown !== false;
+        const id = randomUUID();
+        const { baseUrl } = await resolveBaseUrlAsync();
+        try {
+            const response = await waitForUserReply({
+                id,
+                session_id: sessionId,
+                session_label: sessionLabel,
+                message,
+                predefined_options: predefinedOptions,
+                is_markdown: isMarkdown,
+            }, { baseUrl });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `[session: ${sessionId}]\n${response}`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ 智存交互失败: ${String(err)}\n\nsession: ${sessionId}\n请确认对应 Cursor 窗口已加载扩展。`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    return {
+        content: [{ type: "text", text: `未知工具: ${name}` }],
+        isError: true,
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/registry.d.ts

@@ -0,0 +1,18 @@
+export interface WindowInstance {
+    windowId: string;
+    port: number;
+    pid: number;
+    workspaceFolders: string[];
+    updatedAt: number;
+}
+declare function normalizePath(p: string): string;
+declare function readInstances(): WindowInstance[];
+export declare function listAliveInstances(): Promise<WindowInstance[]>;
+export declare function resolveBaseUrlSync(): string;
+export declare function resolveBaseUrl(): string;
+export declare function resolveBaseUrlAsync(): Promise<{
+    baseUrl: string;
+    matched?: WindowInstance;
+    allInstances: WindowInstance[];
+}>;
+export { readInstances, normalizePath };

package/dist/registry.js

@@ -0,0 +1,133 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+const CONFIG_DIR = path.join(os.homedir(), ".zhicun2");
+const INSTANCES_FILE = path.join(CONFIG_DIR, "instances.json");
+const PORT_FILE = path.join(CONFIG_DIR, "port.json");
+const DEFAULT_PORT = 47382;
+const PROBE_TIMEOUT_MS = 800;
+function normalizePath(p) {
+    return path.resolve(p).replace(/\\/g, "/").toLowerCase();
+}
+function readInstances() {
+    try {
+        if (!fs.existsSync(INSTANCES_FILE)) {
+            return [];
+        }
+        const data = JSON.parse(fs.readFileSync(INSTANCES_FILE, "utf-8"));
+        return Array.isArray(data.instances) ? data.instances : [];
+    }
+    catch {
+        return [];
+    }
+}
+function readLegacyPort() {
+    try {
+        if (!fs.existsSync(PORT_FILE)) {
+            return null;
+        }
+        const data = JSON.parse(fs.readFileSync(PORT_FILE, "utf-8"));
+        return typeof data.port === "number" ? data.port : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function probeHealth(port) {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+        const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!res.ok) {
+            return false;
+        }
+        const data = (await res.json());
+        return data.ok === true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function listAliveInstances() {
+    const instances = readInstances();
+    const alive = [];
+    for (const inst of instances) {
+        if (await probeHealth(inst.port)) {
+            alive.push(inst);
+        }
+    }
+    return alive;
+}
+function pickBestMatch(candidates) {
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    return [...candidates].sort((a, b) => b.updatedAt - a.updatedAt)[0];
+}
+export function resolveBaseUrlSync() {
+    if (process.env.ZHICUN2_PORT) {
+        return `http://127.0.0.1:${process.env.ZHICUN2_PORT}`;
+    }
+    const windowId = process.env.ZHICUN2_WINDOW_ID;
+    if (windowId) {
+        const matched = readInstances().find((i) => i.windowId === windowId);
+        if (matched) {
+            return `http://127.0.0.1:${matched.port}`;
+        }
+    }
+    const workspace = process.env.ZHICUN2_WORKSPACE;
+    if (workspace) {
+        const target = normalizePath(workspace);
+        const matches = readInstances().filter((i) => i.workspaceFolders.some((f) => normalizePath(f) === target));
+        const best = pickBestMatch(matches);
+        if (best) {
+            return `http://127.0.0.1:${best.port}`;
+        }
+    }
+    const legacy = readLegacyPort();
+    if (legacy) {
+        return `http://127.0.0.1:${legacy}`;
+    }
+    return `http://127.0.0.1:${DEFAULT_PORT}`;
+}
+export function resolveBaseUrl() {
+    return resolveBaseUrlSync();
+}
+export async function resolveBaseUrlAsync() {
+    const allInstances = await listAliveInstances();
+    if (process.env.ZHICUN2_PORT) {
+        return {
+            baseUrl: `http://127.0.0.1:${process.env.ZHICUN2_PORT}`,
+            allInstances,
+        };
+    }
+    const windowId = process.env.ZHICUN2_WINDOW_ID;
+    if (windowId) {
+        const matched = allInstances.find((i) => i.windowId === windowId);
+        if (matched) {
+            return { baseUrl: `http://127.0.0.1:${matched.port}`, matched, allInstances };
+        }
+    }
+    const workspace = process.env.ZHICUN2_WORKSPACE;
+    if (workspace) {
+        const target = normalizePath(workspace);
+        const matches = allInstances.filter((i) => i.workspaceFolders.some((f) => normalizePath(f) === target));
+        const best = pickBestMatch(matches);
+        if (best) {
+            return { baseUrl: `http://127.0.0.1:${best.port}`, matched: best, allInstances };
+        }
+    }
+    if (allInstances.length === 1) {
+        const only = allInstances[0];
+        return { baseUrl: `http://127.0.0.1:${only.port}`, matched: only, allInstances };
+    }
+    const legacy = readLegacyPort();
+    if (legacy) {
+        return { baseUrl: `http://127.0.0.1:${legacy}`, allInstances };
+    }
+    return { baseUrl: `http://127.0.0.1:${DEFAULT_PORT}`, allInstances };
+}
+export { readInstances, normalizePath };

package/dist/session-id.d.ts

@@ -0,0 +1,5 @@
+import { normalizePath } from "./registry.js";
+export declare function deriveDefaultSessionId(workspacePath?: string): string;
+export declare function normalizeSessionId(sessionId: string | undefined): string;
+export declare function resolveDefaultSessionId(): string;
+export { normalizePath };

package/dist/session-id.js

@@ -0,0 +1,32 @@
+import * as path from "path";
+import { normalizePath } from "./registry.js";
+export function deriveDefaultSessionId(workspacePath) {
+    if (workspacePath && workspacePath.trim()) {
+        const base = path.basename(path.resolve(workspacePath.trim()));
+        if (base) {
+            return `${base}/main`;
+        }
+    }
+    return "global/main";
+}
+export function normalizeSessionId(sessionId) {
+    const trimmed = String(sessionId ?? "").trim();
+    if (!trimmed || trimmed === "default") {
+        const workspace = process.env.ZHICUN2_WORKSPACE;
+        if (workspace) {
+            return deriveDefaultSessionId(workspace);
+        }
+        return "global/main";
+    }
+    return trimmed;
+}
+export function resolveDefaultSessionId() {
+    if (process.env.ZHICUN2_SESSION) {
+        return process.env.ZHICUN2_SESSION;
+    }
+    if (process.env.ZHICUN2_WORKSPACE) {
+        return deriveDefaultSessionId(process.env.ZHICUN2_WORKSPACE);
+    }
+    return "global/main";
+}
+export { normalizePath };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "zhicun2-mcp",
+  "version": "0.3.2",
+  "description": "智存 2.0 MCP — 阻塞等待用户在 Cursor 扩展侧边栏中交互",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "zhicun2-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "cursor",
+    "zhicun2",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zhicun/zhicun2.0.git",
+    "directory": "mcp"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  }
+}