@cup319/mmpl 2.5.1 → 2.7.1

package/README.md

@@ -1,9 +1,9 @@
 # MMPL MCP
 
-[![npm version](https://img.shields.io/npm/v/mmpl)](https://www.npmjs.com/package/mmpl)
-[![license](https://img.shields.io/npm/l/mmpl)](https://github.com/cnb-t/mmpl/blob/main/LICENSE)
+[![npm version](https://img.shields.io/npm/v/@cup319/mmpl)](https://www.npmjs.com/package/@cup319/mmpl)
+[![license](https://img.shields.io/npm/l/@cup319/mmpl)](https://cnb.cool/cnb-t/mmpl/-/blob/main/LICENSE)
 
-基于 DuckDB 的向量记忆系统，具备完整的记忆生命周期管理，以常驻 HTTP MCP Server 形式运行（v2.5.1+，多 client 共享单进程，避免 DuckDB 文件锁冲突）���
+基于 DuckDB 的向量记忆系统，具备完整的记忆生命周期管理，以常驻 HTTP MCP Server 形式运行（v2.5.1+，多 client 共享单进程，避免 DuckDB 文件锁冲突）。���
 
 ## 核心特性
 
@@ -18,76 +18,153 @@
 
 ## 安装
 
+### 方式一：全局安装（推荐，自带 `mmpl` 命令）
+
+```bash
+npm install -g @cup319/mmpl
+```
+
+装完即可直接用 `mmpl` 命令启动 server（详见下文「快速上手」）。
+
+### 方式二：项目内安装
+
 ```bash
 npm install @cup319/mmpl
 ```
 
-安装后在 `node_modules/mmpl/dist/index.js`。作为 MCP Server 使用时，在配置中指向这个路径即可。
+安装后入口在 `node_modules/@cup319/mmpl/dist/index.js`。作为 MCP Server 使用时，在 client 配置中指向这个路径，或用 `node ./node_modules/@cup319/mmpl/dist/index.js` 启动。
 
-或从 Git 源码构建：
+### 方式三：从源码构建
 
 ```bash
 git clone https://cnb.cool/cnb-t/mmpl.git
 cd mmpl
 npm install
-npm run build
+npm run build      # 产物在 dist/index.js
+node dist/index.js
 ```
 
-## 配置
+## 快速上手（5 分钟教程）
 
-### 部署：常驻 HTTP MCP Server（推荐 — 多 client 共享）
+这一节带你从零跑通：安装 → 启动 → 连接 client → 写入/检索第一条记忆。
 
-v2.5.1 起，mmpl 默认作为 **Streamable HTTP MCP server** 运行：一个常驻进程独占 DuckDB，被多个 MCP client（ZCode / Claude Desktop / IDE 等）共享。这从根本上避免了 stdio 模式下多 client 各自 spawn 进程、争抢同一个 `.duckdb` 文件导致的 `Connection closed` 错误。
+> **前置条件**：Node.js ≥ 20。首次启动会从 HuggingFace 自动下载 ONNX 模型（默认 `all-MiniLM-L6-v2`，~90MB，国内网络会自动切到 `hf-mirror.com` 镜像）。
 
-**第一步：启动 server（一次）**
+### Step 1：启动 server
+
+全局安装后，任意终端执行：
 
 ```bash
-node ./node_modules/mmpl/dist/index.js
-# MMPL MCP Server v2.5.1 listening on http://127.0.0.1:7680/mcp
+mmpl
+# 等价于：node ./node_modules/@cup319/mmpl/dist/index.js
+```
+
+看到类似输出即成功（首启会多花 5–10 秒加载 ONNX 模型）：
+
+```
+MMPL (Memory Palace) MCP Server v2.7.0 listening on http://127.0.0.1:7680/mcp
 ```
 
-启动时通过环境变量配置 embedding / DB / LLM：
+> **重要**：mmpl 只有 HTTP 一种模式，**没有 stdio、没有 CLI flag**。所有配置（host/port/path、DB 路径、模型路径、LLM key）都走环境变量。多个 client 共享这同一个进程，**不要起第二个 server**——DuckDB 文件是单进程独占的。
+
+### Step 2：验证 server 活着
 
 ```bash
-EMBEDDING_PROVIDER=onnx \
-DB_PATH=./data/memory.duckdb \
-ONNX_MODEL_PATH=./models/all-MiniLM-L6-v2.onnx \
-ANALYZER_API_URL=https://api.z.ai/api/paas/v4/chat/completions \
-ANALYZER_API_KEY=<your-api-key> \
-ANALYZER_MODEL=glm-4-flash \
-node ./node_modules/mmpl/dist/index.js
+curl http://127.0.0.1:7680/
+# {"status":"ok","server":"mmpl","sessions":0}
 ```
 
-**第二步：client 配置（每个 client 一份，只填 URL）**
+### Step 3：在 client 里连接
 
-ZCode (`~/.zcode/cli/config.json`):
+ZCode (`~/.zcode/cli/config.json`)：
 
 ```json
 {
   "mcp": {
     "servers": {
-      "mmpl": {
-        "type": "http",
-        "url": "http://127.0.0.1:7680/mcp"
-      }
+      "mmpl": { "type": "http", "url": "http://127.0.0.1:7680/mcp" }
     }
   }
 }
 ```
 
-Claude Desktop / Claude Code (`claude_desktop_config.json` 或 `~/.claude.json`):
+Claude Desktop / Claude Code（`claude_desktop_config.json` 或 `~/.claude.json`）：
 
 ```json
 {
   "mcpServers": {
-    "mmpl": {
-      "type": "http",
-      "url": "http://127.0.0.1:7680/mcp"
-    }
+    "mmpl": { "type": "http", "url": "http://127.0.0.1:7680/mcp" }
   }
 }
 ```
 
+重连 client 后，`sessions` 会 +1：
+
+```bash
+curl http://127.0.0.1:7680/
+# {"status":"ok","server":"mmpl","sessions":1}
+```
+
+### Step 4：写入第一条记忆
+
+在连接好的 client 里让 AI 调用 `memory_write`（以 encode 模式写入一条 fact）：
+
+```jsonc
+// 工具名: memory_write
+{
+  "action": "encode",
+  "input": "用户的本地时区是 Asia/Shanghai (UTC+8)，工作时间 09:00-18:00。",
+  "type": "preference",
+  "tags": ["timezone", "work-hours"]
+}
+```
+
+返回 `memory_id` 即写入成功。
+
+### Step 5：检索记忆
+
+```jsonc
+// 工具名: memory_search
+{
+  "mode": "quick",
+  "query": "用户在哪个时区？几点上班？"
+}
+```
+
+会命中刚才写入的那条，返回内容及相似度评分。`mode` 可选 `quick` / `deep` / `hybrid` / `keyword`。
+
+### Step 6：看统计
+
+```jsonc
+// 工具名: memory_stats
+{ "type": "summary" }
+```
+
+到这里你已经跑通了完整闭环。8 个工具的完整说明见下文「工具一览」。
+
+> **常驻保活**：HTTP server 自身不会自我守护。Windows 推荐 `nssm install MMPL node D:\path\to\dist\index.js`，Linux/macOS 推荐 `systemd` 或 `pm2 start dist/index.js --name mmpl`。
+
+## 配置
+
+### 部署：常驻 HTTP MCP Server（推荐 — 多 client 共享）
+
+v2.5.1 起，mmpl 默认作为 **Streamable HTTP MCP server** 运行：一个常驻进程独占 DuckDB，被多个 MCP client（ZCode / Claude Desktop / IDE 等）共享。这从根本上避免了 stdio 模式下多 client 各自 spawn 进程、争抢同一个 `.duckdb` 文件导致的 `Connection closed` 错误。
+
+启动命令见上文「快速上手 · Step 1」。完整启动示例（带环境变量）：
+
+```bash
+EMBEDDING_PROVIDER=onnx \
+DB_PATH=./data/memory.duckdb \
+ONNX_MODEL_PATH=./models/all-MiniLM-L6-v2.onnx \
+ANALYZER_API_URL=https://api.z.ai/api/paas/v4/chat/completions \
+ANALYZER_API_KEY=<your-api-key> \
+ANALYZER_MODEL=glm-4-flash \
+node ./node_modules/@cup319/mmpl/dist/index.js
+# 或全局安装后直接：mmpl
+```
+
+client 配置（每个 client 一份，只填 URL）见「快速上手 · Step 3」。
+
 **Health check（确认 server 活着）**
 
 ```bash
@@ -104,6 +181,29 @@ HTTP server 启动后不自我守护，靠外部保活：
 
 > server 默认只绑 `127.0.0.1`（本机访问）。多 client 共享时**不要**起第二个 server 进程——DuckDB 文件是单进程独占的，第二个进程会启动失败；多个 client 都连同一个 HTTP URL 即可。
 
+### ZCode 集成：常驻 + 无弹窗（开箱即用）
+
+如果你在 ZCode 里用 mmpl，推荐用仓库自带的部署示例 [`examples/zcode-deploy/`](./examples/zcode-deploy/)。它通过 SessionStart/Stop hook 实现：
+
+- **常驻运行**：server 启动一次后一直留在后台，切换 ZCode session 不重启（避免每次等 5–10s ONNX 加载）
+- **无 node.exe 黑窗**：所有 `spawn` 配 `windowsHide: true`（修复了 Windows 上启动时弹 `C:\...\node.exe` 窗口的问题）
+- **日志落盘**：server 的 stdout/stderr 重定向到 `.mmpl-server.log`，排查启动失败有据可查
+
+一键安装：
+
+```bash
+# 1. 准备部署目录
+mkdir D:\mmpl-deploy && cd D:\mmpl-deploy
+npm init -y && npm install @cup319/mmpl
+# 2. 复制示例脚本
+cp /path/to/examples/zcode-deploy/*.mjs .
+# 3. 按示例 README 配置 ~/.zcode/cli/config.json 的 hook
+```
+
+完整步骤、配置示例、运行机制、弹窗 bug 修复历史详见 [`examples/zcode-deploy/README.md`](./examples/zcode-deploy/README.md)。
+
+> **澄清**：`@cup319/mmpl` npm 包本身不 spawn 子进程，**不存在弹窗问题**。弹窗只发生在用 `start-mmpl.mjs` 包装启动时（该脚本 spawn 子进程的方式在 Windows 上需要 `windowsHide`），示例脚本已修复。
+
 ### 遗留：stdio 模式
 
 v2.5.1 之前默认走 stdio，每个 client 各 spawn 一个进程。该模式已在 v2.5.1 移除（多 client 场景下 DuckDB 文件锁无法解决）。如确需单 client stdio，可 git checkout v2.4.4 标签。

package/dist/index.js

@@ -21748,7 +21748,7 @@ async function main() {
   const createMcpServer = () => {
     const server = new McpServer({
       name: "MMPL",
-      version: "2.5.1"
+      version: "2.7.1"
     });
     registerMemoryWrite(server, deps);
     registerMemorySearch(server, deps);
@@ -21771,7 +21771,7 @@ async function main() {
   void embeddingService.ready().catch((err) => {
     console.error("[startup] embedding service init failed:", err);
   });
-  console.error(`MMPL (Memory Palace) MCP Server v2.5.1 listening on http://${httpHost}:${httpPort}${httpPath}`);
+  console.error(`MMPL (Memory Palace) MCP Server v2.7.1 listening on http://${httpHost}:${httpPort}${httpPath}`);
   const gracefulShutdown = async (signal) => {
     console.error(`
 [shutdown] Received ${signal}, gracefully shutting down...`);