pi-knowledge 0.15.0 → 0.16.1

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 (61) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/README.md +61 -23
  3. package/dist/index.d.ts +10 -4
  4. package/dist/index.js +145 -166
  5. package/dist/src/coverage-snapshot.d.ts +23 -0
  6. package/dist/src/coverage-snapshot.js +53 -0
  7. package/dist/src/daemon/client.d.ts +60 -0
  8. package/dist/src/daemon/client.js +360 -0
  9. package/dist/src/daemon/main.d.ts +2 -0
  10. package/dist/src/daemon/main.js +109 -0
  11. package/dist/src/daemon/protocol.d.ts +71 -0
  12. package/dist/src/daemon/protocol.js +170 -0
  13. package/dist/src/daemon/runtime.d.ts +26 -0
  14. package/dist/src/daemon/runtime.js +192 -0
  15. package/dist/src/daemon/server.d.ts +46 -0
  16. package/dist/src/daemon/server.js +500 -0
  17. package/dist/src/daemon/service.d.ts +49 -0
  18. package/dist/src/daemon/service.js +527 -0
  19. package/dist/src/diagnostics/health.d.ts +6 -0
  20. package/dist/src/diagnostics/health.js +135 -2
  21. package/dist/src/engine.d.ts +13 -8
  22. package/dist/src/engine.js +569 -100
  23. package/dist/src/filesystem-access.d.ts +9 -0
  24. package/dist/src/filesystem-access.js +100 -0
  25. package/dist/src/indexer/chunker.d.ts +12 -0
  26. package/dist/src/indexer/chunker.js +307 -9
  27. package/dist/src/mcp/http.d.ts +47 -0
  28. package/dist/src/mcp/http.js +564 -0
  29. package/dist/src/mcp/main.d.ts +2 -0
  30. package/dist/src/mcp/main.js +97 -0
  31. package/dist/src/mcp/protocol.d.ts +81 -0
  32. package/dist/src/mcp/protocol.js +444 -0
  33. package/dist/src/mcp/server.d.ts +42 -0
  34. package/dist/src/mcp/server.js +378 -0
  35. package/dist/src/model-worker-client.js +9 -0
  36. package/dist/src/model-worker-contract.d.ts +3 -0
  37. package/dist/src/model-worker-contract.js +8 -0
  38. package/dist/src/model-worker.js +76 -4
  39. package/dist/src/network/safe-fetch.d.ts +7 -0
  40. package/dist/src/network/safe-fetch.js +199 -0
  41. package/dist/src/node-runtime.d.ts +3 -0
  42. package/dist/src/node-runtime.js +78 -0
  43. package/dist/src/profiles.d.ts +15 -0
  44. package/dist/src/profiles.js +160 -0
  45. package/dist/src/runtime-config.js +5 -6
  46. package/dist/src/secure-files.d.ts +17 -0
  47. package/dist/src/secure-files.js +183 -0
  48. package/dist/src/status.js +12 -7
  49. package/dist/src/storage/sqlite.d.ts +4 -1
  50. package/dist/src/storage/sqlite.js +46 -3
  51. package/dist/src/type-guards.d.ts +1 -0
  52. package/dist/src/type-guards.js +3 -0
  53. package/dist/src/watcher/file-watcher.d.ts +3 -1
  54. package/dist/src/watcher/file-watcher.js +166 -32
  55. package/dist/src/windows-security.d.ts +4 -0
  56. package/dist/src/windows-security.js +67 -0
  57. package/docs/configuration.md +40 -9
  58. package/docs/daemon-profiles.md +302 -0
  59. package/docs/mcp-clients.md +266 -0
  60. package/docs/offline-mode.md +6 -6
  61. package/package.json +28 -2
@@ -0,0 +1,266 @@
1
+ # MCP Client Setup
2
+
3
+ `pi-knowledge-mcp` lets any MCP client use the same profile daemon and knowledge data as the Pi and OMP extensions. Pi and OMP integration is unchanged: their extension hooks, tool registration, prompt guidance, and optional auto-injection still run through `extension.js`. MCP is an additional client surface, not a replacement for those hooks.
4
+
5
+ ## Choose a transport
6
+
7
+ | Transport | Use it when | Process model |
8
+ |-----------|-------------|---------------|
9
+ | stdio | One local agent should launch and own its MCP adapter | The MCP client starts `pi-knowledge-mcp`; the adapter exits with that client, while the profile daemon remains running |
10
+ | Streamable HTTP | Several local agents need one stable MCP endpoint | Start one `pi-knowledge-mcp --transport http` process; clients connect to its loopback URL |
11
+
12
+ Both transports connect to the selected profile daemon. The zero-configuration profile is `default`; most users should keep it. `--profile research` selects an advanced, isolated storage/runtime domain with its own database, vectors, watchers, daemon, and `coverage.json`. This process-level knowledge profile is separate from the `knowledge_search` tuning parameter also named `profile`.
13
+
14
+ ## Install the command
15
+
16
+ Pi and OMP users can keep their existing package installation. For an external agent that needs `pi-knowledge-mcp` on `PATH`, install the npm package globally with Node 22 or newer:
17
+
18
+ ```bash
19
+ npm install -g pi-knowledge
20
+ ```
21
+
22
+ npm 12 blocks dependency install scripts unless they are explicitly approved. `pi-knowledge` uses native/runtime packages for SQLite, local embeddings, documents, and code parsers. Review the package and the skipped-script list, then install with the required package names allowed:
23
+
24
+ ```bash
25
+ npm install -g \
26
+ --allow-scripts=better-sqlite3,onnxruntime-node,protobufjs,sharp,tree-sitter,tree-sitter-bash,tree-sitter-c,tree-sitter-cpp,tree-sitter-go,tree-sitter-java,tree-sitter-javascript,tree-sitter-python,tree-sitter-qmljs,tree-sitter-rust,tree-sitter-typescript \
27
+ pi-knowledge
28
+ ```
29
+
30
+ For a repository checkout, `package.json` contains version-pinned `allowScripts` entries for the reviewed dependency versions, so `npm ci` can build them under npm 12. Re-review changed pins during dependency upgrades; do not replace the list with an unbounded approval.
31
+
32
+ Confirm the binaries and default profile daemon:
33
+
34
+ ```bash
35
+ pi-knowledge-daemon status
36
+ pi-knowledge-mcp </dev/null
37
+ ```
38
+
39
+ The second command should exit cleanly. It does not stop the daemon.
40
+
41
+ ## Default read-only capabilities
42
+
43
+ The adapter exposes only `knowledge_search`, `knowledge_symbol_search`, and `knowledge_show` unless launch flags grant more authority.
44
+
45
+ | Flag | Additional authority |
46
+ |------|----------------------|
47
+ | `--allow-root <dir>` | Repeatable, current-user-owned local roots for plan/add/import/export paths |
48
+ | `--allow-network` | Public URL planning, add, and update; private-network and redirect protections still apply |
49
+ | `--allow-write` | Add, update, import, and export, subject to root/network authority |
50
+ | `--allow-admin` | Configure, live status/doctor, remove, and clear; destructive tools still require their explicit confirmation input |
51
+
52
+ Grant only what that MCP client needs. Host tool approval is not a substitute for these server-side capabilities. A typical project writer is:
53
+
54
+ ```bash
55
+ pi-knowledge-mcp --allow-root "$PWD" --allow-write
56
+ ```
57
+
58
+ ## stdio configuration
59
+
60
+ Generic `mcpServers` configuration:
61
+
62
+ ```json
63
+ {
64
+ "mcpServers": {
65
+ "piKnowledge": {
66
+ "type": "stdio",
67
+ "command": "pi-knowledge-mcp",
68
+ "args": []
69
+ }
70
+ }
71
+ }
72
+ ```
73
+
74
+ Add capability arguments explicitly, for example `"args": ["--allow-root", "/absolute/project", "--allow-write"]`. Use an absolute, trusted path. For a named knowledge profile, add `"--profile", "research"`.
75
+
76
+ ### Claude Code
77
+
78
+ ```bash
79
+ claude mcp add --transport stdio pi-knowledge -- pi-knowledge-mcp
80
+ claude mcp get pi-knowledge
81
+ ```
82
+
83
+ Add server arguments after `pi-knowledge-mcp`. Use `--scope user` or `--scope project` according to Claude Code's configuration policy.
84
+
85
+ ### Codex CLI, desktop, and IDE
86
+
87
+ Codex clients share `~/.codex/config.toml`:
88
+
89
+ ```toml
90
+ [mcp_servers.pi_knowledge]
91
+ command = "pi-knowledge-mcp"
92
+ args = []
93
+ ```
94
+
95
+ Equivalent CLI setup:
96
+
97
+ ```bash
98
+ codex mcp add pi_knowledge -- pi-knowledge-mcp
99
+ codex mcp list
100
+ ```
101
+
102
+ ### Cursor
103
+
104
+ Put this in `~/.cursor/mcp.json` for global use or `.cursor/mcp.json` for one project:
105
+
106
+ ```json
107
+ {
108
+ "mcpServers": {
109
+ "piKnowledge": {
110
+ "type": "stdio",
111
+ "command": "pi-knowledge-mcp",
112
+ "args": []
113
+ }
114
+ }
115
+ }
116
+ ```
117
+
118
+ ### VS Code Copilot
119
+
120
+ Use **Chat: Open Customizations → MCP Servers → Add Server → Command (stdio)**, or add the generic stdio entry above to `~/.copilot/mcp-config.json` under `mcpServers`. Workspace-shared native configuration uses `.mcp.json` at the workspace root when that feature is enabled. New Copilot configurations should not use the deprecated `.vscode/mcp.json` Local-harness format.
121
+
122
+ ### Kiro CLI and ACP
123
+
124
+ Add a user-level entry to `~/.kiro/settings/mcp.json`, or the same entry to `.kiro/settings/mcp.json` for one workspace:
125
+
126
+ ```json
127
+ {
128
+ "mcpServers": {
129
+ "piKnowledge": {
130
+ "command": "pi-knowledge-mcp",
131
+ "args": []
132
+ }
133
+ }
134
+ }
135
+ ```
136
+
137
+ Run `kiro-cli mcp list global` or start a chat with `--require-mcp-startup` to fail closed when the server cannot initialize. Kiro CLI V3 validates the modern MCP cache hints, so use a current `pi-knowledge` package rather than copying an older built adapter.
138
+
139
+ Kiro's ACP support is an upstream client-to-agent transport: an ACP editor launches `kiro-cli acp`, and Kiro remains the MCP client of `pi-knowledge-mcp`. `pi-knowledge` does not need a second ACP server. A Kiro custom agent can place the same entry in its `mcpServers` field; set `includeMcpJson: true` instead when that agent should inherit Kiro's user/workspace MCP files.
140
+
141
+ Kiro CLI 3.5 may terminate descendants of a stdio MCP process when a one-shot chat exits. If Kiro starts the profile daemon for the first time, that host cleanup can stop the otherwise detached daemon; indexed data remains safe and the next session starts it again. For a daemon that must remain warm across Kiro sessions, run `pi-knowledge-daemon start [--profile <name>]` before the chat, or use the persistent HTTP adapter. A daemon started independently was verified to survive Kiro's stdio teardown.
142
+
143
+ ## Streamable HTTP configuration
144
+
145
+ HTTP mode is intentionally same-machine only. It accepts `127.0.0.1`, `::1`, or `localhost`; it does not provide TLS, OAuth, or a remote bind. A 32–512-character bearer token is mandatory.
146
+
147
+ Start one endpoint:
148
+
149
+ ```bash
150
+ export PI_KNOWLEDGE_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
151
+ pi-knowledge-mcp --transport http --host 127.0.0.1 --port 3210 --endpoint /mcp
152
+ ```
153
+
154
+ The endpoint is `http://127.0.0.1:3210/mcp`. Keep the token out of shell history, source control, chat, process arguments, and shared configuration. Supply it through the client's environment. The server rejects non-loopback binds, unauthenticated requests, mismatched protocol headers, and unapproved supplied origins. If a local MCP host sends `Origin`, add only its exact trusted origin, for example `--allow-origin http://127.0.0.1:3000`. This validates the header but does not enable browser CORS/preflight; use a native MCP client rather than direct browser JavaScript.
155
+
156
+ HTTP is useful when multiple local clients share one adapter and one capability set. If clients need different authority, start separate endpoints with different ports, tokens, and launch flags. They may still target the same profile daemon.
157
+
158
+ ### Claude Code
159
+
160
+ ```bash
161
+ claude mcp add --transport http pi-knowledge http://127.0.0.1:3210/mcp \
162
+ --header "Authorization: Bearer $PI_KNOWLEDGE_MCP_HTTP_TOKEN"
163
+ claude mcp get pi-knowledge
164
+ ```
165
+
166
+ Claude stores the expanded header in its MCP configuration. Protect that configuration as a credential, or use its dynamic-header facilities when token-at-rest policy requires them.
167
+
168
+ ### Codex CLI, desktop, and IDE
169
+
170
+ Keep the token in the environment and reference its variable name:
171
+
172
+ ```toml
173
+ [mcp_servers.pi_knowledge]
174
+ url = "http://127.0.0.1:3210/mcp"
175
+ bearer_token_env_var = "PI_KNOWLEDGE_MCP_HTTP_TOKEN"
176
+ ```
177
+
178
+ Restart the Codex client after changing MCP configuration.
179
+
180
+ ### Cursor
181
+
182
+ ```json
183
+ {
184
+ "mcpServers": {
185
+ "piKnowledge": {
186
+ "url": "http://127.0.0.1:3210/mcp",
187
+ "headers": {
188
+ "Authorization": "Bearer ${env:PI_KNOWLEDGE_MCP_HTTP_TOKEN}"
189
+ }
190
+ }
191
+ }
192
+ }
193
+ ```
194
+
195
+ Restart or reconnect the server from Cursor after changing the token or endpoint.
196
+
197
+ ### VS Code Copilot
198
+
199
+ Use **Chat: Open Customizations → MCP Servers → Add Server → HTTP**, or use native portable configuration:
200
+
201
+ ```json
202
+ {
203
+ "mcpServers": {
204
+ "piKnowledge": {
205
+ "type": "http",
206
+ "url": "http://127.0.0.1:3210/mcp",
207
+ "headers": {
208
+ "Authorization": "Bearer ${PI_KNOWLEDGE_MCP_HTTP_TOKEN}"
209
+ },
210
+ "tools": ["*"]
211
+ }
212
+ }
213
+ }
214
+ ```
215
+
216
+ Place it in `~/.copilot/mcp-config.json`, or in workspace-root `.mcp.json` only if sharing the non-secret endpoint definition is intentional. Do not commit a literal token.
217
+
218
+ ### Kiro CLI
219
+
220
+ Kiro accepts localhost HTTP MCP entries in `~/.kiro/settings/mcp.json` or a workspace MCP file:
221
+
222
+ ```json
223
+ {
224
+ "mcpServers": {
225
+ "piKnowledge": {
226
+ "url": "http://127.0.0.1:3210/mcp",
227
+ "headers": {
228
+ "Authorization": "Bearer ${PI_KNOWLEDGE_MCP_HTTP_TOKEN}"
229
+ }
230
+ }
231
+ }
232
+ }
233
+ ```
234
+
235
+ Kiro expands `${VARIABLE_NAME}` values at runtime. Keep the token in the environment, not as a literal in the JSON file.
236
+
237
+ ## Lifecycle and upgrades
238
+
239
+ - An MCP adapter automatically ensures the selected profile daemon. Closing a stdio client or HTTP adapter does not stop that daemon.
240
+ - One authenticated daemon owns each canonical profile storage directory. Concurrent Pi, OMP, stdio, and HTTP clients share it safely.
241
+ - `pi-knowledge-daemon stop [--profile <name>]` is the explicit administrative stop. A later client starts it again.
242
+ - Package/build incompatibility uses authenticated daemon retirement and replacement; clients do not kill a PID based only on a stale file.
243
+ - After upgrading `pi-knowledge`, restart Pi/OMP sessions, stdio MCP clients, and persistent HTTP adapter processes so all clients run the new package. The first compatible client replaces an older daemon when required.
244
+ - Re-run `npm install-scripts ls` under npm 12 and review any newly pending or stale install-script approval before rebuilding or publishing.
245
+
246
+ ## Protocol and verification
247
+
248
+ The server supports legacy MCP initialization for `2025-11-25`, `2025-06-18`, and `2025-03-26`, plus the stateless `2026-07-28` discovery/request contract. Modern cacheable discovery/list results include private `ttlMs` and `cacheScope` hints. HTTP uses Streamable HTTP POST responses, request-scoped SSE for tool progress/results, legacy session IDs where negotiated, and DELETE for legacy session termination. It intentionally returns `405` for GET because it does not expose a server-initiated event stream.
249
+
250
+ Verify a real tool call, not only a connected status:
251
+
252
+ ```text
253
+ Use piKnowledge to list my knowledge bases. Do not change anything.
254
+ ```
255
+
256
+ Then inspect the client tool trace and confirm it called `knowledge_show`. For troubleshooting, check `pi-knowledge-daemon status`, the MCP client's server log, the selected `--profile`, the HTTP token environment, and the adapter capability flags.
257
+
258
+ Client references:
259
+
260
+ - [Claude Code MCP](https://code.claude.com/docs/en/mcp)
261
+ - [Codex MCP](https://developers.openai.com/codex/mcp)
262
+ - [Cursor MCP](https://cursor.com/docs/mcp)
263
+ - [VS Code Copilot MCP](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
264
+ - [Kiro MCP configuration](https://kiro.dev/docs/mcp/configuration/)
265
+ - [Kiro ACP](https://kiro.dev/docs/cli/acp/)
266
+ - [npm 12 install-script approvals](https://docs.npmjs.com/cli/v12/commands/npm-install-scripts)
@@ -5,8 +5,8 @@
5
5
  ## 1. 預下載 Model
6
6
 
7
7
  ```bash
8
- # 有網路時觸發一次 knowledge_add → model 自動下載到 ~/.pi/knowledge/models/
9
- # 或手動從 https://huggingface.co/Xenova/multilingual-e5-small/tree/main/onnx 下載
8
+ # 有網路時在 selected profile觸發一次 knowledge_add,模型會下載到 <profile-storage>/models/
9
+ # 或設定 PI_KNOWLEDGE_MODEL_CACHE_DIR後,從可信來源預先填入該目錄
10
10
  ```
11
11
 
12
12
  ---
@@ -19,10 +19,10 @@ export PI_KNOWLEDGE_OFFLINE=true
19
19
  export PI_KNOWLEDGE_MODEL_CACHE_DIR=/path/to/models
20
20
  ```
21
21
 
22
- Extension 行為:
22
+ Model worker行為:
23
23
  ```typescript
24
24
  import { env } from '@huggingface/transformers';
25
- env.cacheDir = process.env.PI_KNOWLEDGE_MODEL_CACHE_DIR ?? '<knowledge-dir>/models';
25
+ env.cacheDir = process.env.PI_KNOWLEDGE_MODEL_CACHE_DIR ?? '<profile-storage>/models';
26
26
  env.allowRemoteModels = false;
27
27
  env.localModelPath = env.cacheDir;
28
28
  ```
@@ -42,8 +42,8 @@ export NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem
42
42
  ## 4. Air-Gapped 部署
43
43
 
44
44
  ```bash
45
- # Build machine (有網路): 觸發下載,打包 ~/.pi/knowledge/models/
46
- # Target machine: 解壓到同路徑,或設定 PI_KNOWLEDGE_MODEL_CACHE_DIR 指向解壓後路徑
45
+ # Build machine (有網路): 觸發下載,打包 selected profile的 models/或自訂 cache
46
+ # Target machine: 解壓到 owner-only目錄並設定 PI_KNOWLEDGE_MODEL_CACHE_DIR
47
47
  export PI_KNOWLEDGE_OFFLINE=true
48
48
  ```
49
49
 
package/package.json CHANGED
@@ -1,10 +1,14 @@
1
1
  {
2
2
  "name": "pi-knowledge",
3
- "version": "0.15.0",
4
- "description": "Local-first RAG knowledge base for Pi and OMP coding agents with hybrid code/doc search, reranking, diagnostics, and large-project indexing",
3
+ "version": "0.16.1",
4
+ "description": "Local-first RAG knowledge server for Pi, OMP, and MCP agents with hybrid code/doc search, reranking, diagnostics, and large-project indexing",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
7
  "types": "dist/index.d.ts",
8
+ "bin": {
9
+ "pi-knowledge-daemon": "./dist/src/daemon/main.js",
10
+ "pi-knowledge-mcp": "./dist/src/mcp/main.js"
11
+ },
8
12
  "pi": {
9
13
  "extensions": [
10
14
  "./extension.js"
@@ -15,6 +19,8 @@
15
19
  "dist/",
16
20
  ".pi/",
17
21
  "docs/configuration.md",
22
+ "docs/daemon-profiles.md",
23
+ "docs/mcp-clients.md",
18
24
  "docs/offline-mode.md",
19
25
  "README.md",
20
26
  "CHANGELOG.md",
@@ -28,6 +34,8 @@
28
34
  "omp-sh",
29
35
  "ai-agent",
30
36
  "coding-agent",
37
+ "mcp",
38
+ "model-context-protocol",
31
39
  "knowledge-base",
32
40
  "local-first",
33
41
  "retrieval-augmented-generation",
@@ -81,5 +89,23 @@
81
89
  "repository": {
82
90
  "type": "git",
83
91
  "url": "git+https://github.com/nczz/pi-knowledge.git"
92
+ },
93
+ "allowScripts": {
94
+ "better-sqlite3@12.11.1": true,
95
+ "esbuild@0.27.7": true,
96
+ "onnxruntime-node@1.21.0": true,
97
+ "protobufjs@7.6.4": true,
98
+ "sharp@0.34.5": true,
99
+ "tree-sitter@0.21.1": true,
100
+ "tree-sitter-bash@0.21.0": true,
101
+ "tree-sitter-c@0.21.4": true,
102
+ "tree-sitter-cpp@0.23.2": true,
103
+ "tree-sitter-go@0.21.2": true,
104
+ "tree-sitter-java@0.23.5": true,
105
+ "tree-sitter-javascript@0.23.1": true,
106
+ "tree-sitter-python@0.21.0": true,
107
+ "tree-sitter-qmljs@0.3.1": true,
108
+ "tree-sitter-rust@0.21.0": true,
109
+ "tree-sitter-typescript@0.23.2": true
84
110
  }
85
111
  }