@cup319/mmpl 2.5.0 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +109 -32
  2. package/dist/index.js +2 -2
  3. package/dist/index.js.map +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,9 +1,9 @@
1
1
  # MMPL MCP
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/mmpl)](https://www.npmjs.com/package/mmpl)
4
- [![license](https://img.shields.io/npm/l/mmpl)](https://github.com/cnb-t/mmpl/blob/main/LICENSE)
3
+ [![npm version](https://img.shields.io/npm/v/@cup319/mmpl)](https://www.npmjs.com/package/@cup319/mmpl)
4
+ [![license](https://img.shields.io/npm/l/@cup319/mmpl)](https://cnb.cool/cnb-t/mmpl/-/blob/main/LICENSE)
5
5
 
6
- 基于 DuckDB 的向量记忆系统，具备完整的记忆生命周期管理，以常驻 HTTP MCP Server 形式运行（v2.5.0+，多 client 共享单进程，避免 DuckDB 文件锁冲突）���
6
+ 基于 DuckDB 的向量记忆系统，具备完整的记忆生命周期管理，以常驻 HTTP MCP Server 形式运行（v2.5.1+，多 client 共享单进程，避免 DuckDB 文件锁冲突）。���
7
7
 
8
8
  ## 核心特性
9
9
 
@@ -18,76 +18,153 @@
18
18
 
19
19
  ## 安装
20
20
 
21
+ ### 方式一：全局安装（推荐，自带 `mmpl` 命令）
22
+
23
+ ```bash
24
+ npm install -g @cup319/mmpl
25
+ ```
26
+
27
+ 装完即可直接用 `mmpl` 命令启动 server（详见下文「快速上手」）。
28
+
29
+ ### 方式二：项目内安装
30
+
21
31
  ```bash
22
32
  npm install @cup319/mmpl
23
33
  ```
24
34
 
25
- 安装后在 `node_modules/mmpl/dist/index.js`。作为 MCP Server 使用时，在配置中指向这个路径即可。
35
+ 安装后入口在 `node_modules/@cup319/mmpl/dist/index.js`。作为 MCP Server 使用时，在 client 配置中指向这个路径，或用 `node ./node_modules/@cup319/mmpl/dist/index.js` 启动。
26
36
 
27
- 或从 Git 源码构建：
37
+ ### 方式三：从源码构建
28
38
 
29
39
  ```bash
30
40
  git clone https://cnb.cool/cnb-t/mmpl.git
31
41
  cd mmpl
32
42
  npm install
33
- npm run build
43
+ npm run build # 产物在 dist/index.js
44
+ node dist/index.js
34
45
  ```
35
46
 
36
- ## 配置
47
+ ## 快速上手（5 分钟教程）
37
48
 
38
- ### 部署：常驻 HTTP MCP Server（推荐 — 多 client 共享）
49
+ 这一节带你从零跑通：安装 → 启动 → 连接 client → 写入/检索第一条记忆。
39
50
 
40
- v2.5.0 起，mmpl 默认作为 **Streamable HTTP MCP server** 运行：一个常驻进程独占 DuckDB，被多个 MCP client（ZCode / Claude Desktop / IDE 等）共享。这从根本上避免了 stdio 模式下多 client 各自 spawn 进程、争抢同一个 `.duckdb` 文件导致的 `Connection closed` 错误。
51
+ > **前置条件**：Node.js ≥ 20。首次启动会从 HuggingFace 自动下载 ONNX 模型（默认 `all-MiniLM-L6-v2`，~90MB，国内网络会自动切到 `hf-mirror.com` 镜像）。
41
52
 
42
- **第一步：启动 server（一次）**
53
+ ### Step 1：启动 server
54
+
55
+ 全局安装后，任意终端执行：
43
56
 
44
57
  ```bash
45
- node ./node_modules/mmpl/dist/index.js
46
- # MMPL MCP Server v2.5.0 listening on http://127.0.0.1:7680/mcp
58
+ mmpl
59
+ # 等价于：node ./node_modules/@cup319/mmpl/dist/index.js
60
+ ```
61
+
62
+ 看到类似输出即成功（首启会多花 5–10 秒加载 ONNX 模型）：
63
+
47
64
  ```
65
+ MMPL (Memory Palace) MCP Server v2.7.0 listening on http://127.0.0.1:7680/mcp
66
+ ```
67
+
68
+ > **重要**：mmpl 只有 HTTP 一种模式，**没有 stdio、没有 CLI flag**。所有配置（host/port/path、DB 路径、模型路径、LLM key）都走环境变量。多个 client 共享这同一个进程，**不要起第二个 server**——DuckDB 文件是单进程独占的。
48
69
 
49
- 启动时通过环境变量配置 embedding / DB / LLM：
70
+ ### Step 2：验证 server 活着
50
71
 
51
72
  ```bash
52
- EMBEDDING_PROVIDER=onnx \
53
- DB_PATH=./data/memory.duckdb \
54
- ONNX_MODEL_PATH=./models/all-MiniLM-L6-v2.onnx \
55
- ANALYZER_API_URL=https://api.z.ai/api/paas/v4/chat/completions \
56
- ANALYZER_API_KEY=<your-api-key> \
57
- ANALYZER_MODEL=glm-4-flash \
58
- node ./node_modules/mmpl/dist/index.js
73
+ curl http://127.0.0.1:7680/
74
+ # {"status":"ok","server":"mmpl","sessions":0}
59
75
  ```
60
76
 
61
- **第二步：client 配置（每个 client 一份，只填 URL）**
77
+ ### Step 3：在 client 里连接
62
78
 
63
- ZCode (`~/.zcode/cli/config.json`):
79
+ ZCode (`~/.zcode/cli/config.json`)：
64
80
 
65
81
  ```json
66
82
  {
67
83
  "mcp": {
68
84
  "servers": {
69
- "mmpl": {
70
- "type": "http",
71
- "url": "http://127.0.0.1:7680/mcp"
72
- }
85
+ "mmpl": { "type": "http", "url": "http://127.0.0.1:7680/mcp" }
73
86
  }
74
87
  }
75
88
  }
76
89
  ```
77
90
 
78
- Claude Desktop / Claude Code (`claude_desktop_config.json` 或 `~/.claude.json`):
91
+ Claude Desktop / Claude Code（`claude_desktop_config.json` 或 `~/.claude.json`）：
79
92
 
80
93
  ```json
81
94
  {
82
95
  "mcpServers": {
83
- "mmpl": {
84
- "type": "http",
85
- "url": "http://127.0.0.1:7680/mcp"
86
- }
96
+ "mmpl": { "type": "http", "url": "http://127.0.0.1:7680/mcp" }
87
97
  }
88
98
  }
89
99
  ```
90
100
 
101
+ 重连 client 后，`sessions` 会 +1：
102
+
103
+ ```bash
104
+ curl http://127.0.0.1:7680/
105
+ # {"status":"ok","server":"mmpl","sessions":1}
106
+ ```
107
+
108
+ ### Step 4：写入第一条记忆
109
+
110
+ 在连接好的 client 里让 AI 调用 `memory_write`（以 encode 模式写入一条 fact）：
111
+
112
+ ```jsonc
113
+ // 工具名: memory_write
114
+ {
115
+ "action": "encode",
116
+ "input": "用户的本地时区是 Asia/Shanghai (UTC+8)，工作时间 09:00-18:00。",
117
+ "type": "preference",
118
+ "tags": ["timezone", "work-hours"]
119
+ }
120
+ ```
121
+
122
+ 返回 `memory_id` 即写入成功。
123
+
124
+ ### Step 5：检索记忆
125
+
126
+ ```jsonc
127
+ // 工具名: memory_search
128
+ {
129
+ "mode": "quick",
130
+ "query": "用户在哪个时区？几点上班？"
131
+ }
132
+ ```
133
+
134
+ 会命中刚才写入的那条，返回内容及相似度评分。`mode` 可选 `quick` / `deep` / `hybrid` / `keyword`。
135
+
136
+ ### Step 6：看统计
137
+
138
+ ```jsonc
139
+ // 工具名: memory_stats
140
+ { "type": "summary" }
141
+ ```
142
+
143
+ 到这里你已经跑通了完整闭环。8 个工具的完整说明见下文「工具一览」。
144
+
145
+ > **常驻保活**：HTTP server 自身不会自我守护。Windows 推荐 `nssm install MMPL node D:\path\to\dist\index.js`，Linux/macOS 推荐 `systemd` 或 `pm2 start dist/index.js --name mmpl`。
146
+
147
+ ## 配置
148
+
149
+ ### 部署：常驻 HTTP MCP Server（推荐 — 多 client 共享）
150
+
151
+ v2.5.1 起，mmpl 默认作为 **Streamable HTTP MCP server** 运行：一个常驻进程独占 DuckDB，被多个 MCP client（ZCode / Claude Desktop / IDE 等）共享。这从根本上避免了 stdio 模式下多 client 各自 spawn 进程、争抢同一个 `.duckdb` 文件导致的 `Connection closed` 错误。
152
+
153
+ 启动命令见上文「快速上手 · Step 1」。完整启动示例（带环境变量）：
154
+
155
+ ```bash
156
+ EMBEDDING_PROVIDER=onnx \
157
+ DB_PATH=./data/memory.duckdb \
158
+ ONNX_MODEL_PATH=./models/all-MiniLM-L6-v2.onnx \
159
+ ANALYZER_API_URL=https://api.z.ai/api/paas/v4/chat/completions \
160
+ ANALYZER_API_KEY=<your-api-key> \
161
+ ANALYZER_MODEL=glm-4-flash \
162
+ node ./node_modules/@cup319/mmpl/dist/index.js
163
+ # 或全局安装后直接：mmpl
164
+ ```
165
+
166
+ client 配置（每个 client 一份，只填 URL）见「快速上手 · Step 3」。
167
+
91
168
  **Health check（确认 server 活着）**
92
169
 
93
170
  ```bash
@@ -106,7 +183,7 @@ HTTP server 启动后不自我守护，靠外部保活：
106
183
 
107
184
  ### 遗留：stdio 模式
108
185
 
109
- v2.5.0 之前默认走 stdio，每个 client 各 spawn 一个进程。该模式已在 v2.5.0 移除（多 client 场景下 DuckDB 文件锁无法解决）。如确需单 client stdio，可 git checkout v2.4.4 标签。
186
+ v2.5.1 之前默认走 stdio，每个 client 各 spawn 一个进程。该模式已在 v2.5.1 移除（多 client 场景下 DuckDB 文件锁无法解决）。如确需单 client stdio，可 git checkout v2.4.4 标签。
110
187
 
111
188
  ## 环境变量
112
189
 
package/dist/index.js CHANGED
@@ -21748,7 +21748,7 @@ async function main() {
21748
21748
  const createMcpServer = () => {
21749
21749
  const server = new McpServer({
21750
21750
  name: "MMPL",
21751
- version: "2.5.0"
21751
+ version: "2.7.0"
21752
21752
  });
21753
21753
  registerMemoryWrite(server, deps);
21754
21754
  registerMemorySearch(server, deps);
@@ -21771,7 +21771,7 @@ async function main() {
21771
21771
  void embeddingService.ready().catch((err) => {
21772
21772
  console.error("[startup] embedding service init failed:", err);
21773
21773
  });
21774
- console.error(`MMPL (Memory Palace) MCP Server v2.5.0 listening on http://${httpHost}:${httpPort}${httpPath}`);
21774
+ console.error(`MMPL (Memory Palace) MCP Server v2.7.0 listening on http://${httpHost}:${httpPort}${httpPath}`);
21775
21775
  const gracefulShutdown = async (signal) => {
21776
21776
  console.error(`
21777
21777
  [shutdown] Received ${signal}, gracefully shutting down...`);