@embd/mcp 0.1.1 → 0.7.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.
package/README.md CHANGED
@@ -157,7 +157,124 @@ layer (see below).
157
157
  bun test # unit + HTTP integration tests (no network; stateless tools hit real @embd/core)
158
158
  bun run typecheck
159
159
  bun run lint
160
- bun run build # bundles src/{bin,http-bin,index}.ts -> dist/ (node target; the published bins)
160
+ bun run build # bundles src/{bin,documents-bin,http-bin,index}.ts -> dist/ (node target; the published bins)
161
161
  EMBD_API_KEY=embd_sk_... bun src/bin.ts # run the stdio (hosted) server directly
162
162
  bun src/http-bin.ts # run the stateless HTTP server directly (no key)
163
163
  ```
164
+
165
+ ## Private collaborative documents (invited beta)
166
+
167
+ The separate `embd-documents-mcp` entry point works with private workspace Markdown/HTML, discussions and history. It does not publish public embeds and does not accept chart API keys.
168
+
169
+ A workspace owner opens **Workspace → Agent access**, chooses a name and read/comment/edit scope, and copies the credential once. Access is workspace-scoped, expires after 30 days and can be revoked there. Configure it as `EMBD_DOCUMENT_TOKEN`; optionally set `EMBD_DOCUMENT_ORIGIN` (default `https://app.embd.sh`). Never place the token in document source or a shared configuration file.
170
+
171
+ For the beta source build, run `bun run --filter @embd/mcp build` from the repository, then configure your MCP client to launch `node /absolute/path/to/embd/packages/mcp/dist/documents-bin.js` with that environment. This new entry point is available in the repository build; do not assume a previously published npm version contains it.
172
+
173
+ Tools list the authorized workspace's documents, read current source and discussions, create MD/HTML, submit version-checked revisions, comment/reply, and read older history/discussion pages. Read before editing and send both `expectedRevision` and `expectedEditVersion`. On 409, reread and reconcile rather than silently retrying a replacement. A human or another agent can then continue at the same document link. Agent-authored messages/revisions retain the authorizing person's identity and the agent identity. Tokens cannot invite members or manage access.
174
+
175
+ Document references inside Markdown use an `embd` fence:
176
+
177
+ ~~~md
178
+ ```embd
179
+ {"kind":"document","documentId":"the-target-document-uuid","revision":"live"}
180
+ ```
181
+ ~~~
182
+
183
+ Use an integer `revision` to pin a saved version. References require current access in the same workspace, stop at three nested documents, and show errors rather than retaining content after an access failure. Live references refresh every ten seconds while the page is visible. Pinned source does not pin external state produced by arbitrary HTML scripts.
184
+
185
+
186
+ ### Guided private-document setup
187
+
188
+ In **Workspace → Agent access**, the owner can now generate a private Codex
189
+ TOML or Claude Desktop JSON configuration. Enter the absolute path to the
190
+ source-built `packages/mcp/dist/documents-bin.js` and the Node executable.
191
+ The configuration uses the current workspace application's origin, including
192
+ preview origins. Protected Vercel previews may not be reachable by an external
193
+ client; use an accessible deployment for the real client check.
194
+
195
+ Templates intentionally contain a placeholder, never the issued credential.
196
+ Copy the credential separately and substitute it in the client’s private
197
+ configuration; merge the server entry without replacing existing entries.
198
+ Use a separate credential for each client so attribution and revocation stay
199
+ clear. Never commit a configuration containing credentials.
200
+
201
+ **Check credential read access** sends a single `getWorkspace` request with the
202
+ new agent credential, without the human browser session. It does not create or
203
+ modify documents. It verifies current access, not that a desktop MCP client
204
+ is configured. Copy the read-only prompt into each configured client to verify
205
+ its actual `workspace_documents` / `read_document` tools. After testing,
206
+ revocation is available inline in the workspace; hiding a credential is not
207
+ revocation. Existing secrets cannot be redisplayed.
208
+
209
+ Private document MCP currently uses local stdio. The key-free HTTP server
210
+ above is a different stateless product surface and cannot access private
211
+ workspaces. The guided setup does not imply a published npm release or a hosted
212
+ private-document MCP connector.
213
+
214
+ Client configuration references (checked October 1, 2026):
215
+ [Codex MCP](https://developers.openai.com/codex/mcp),
216
+ [local MCP servers in Claude Desktop](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
217
+
218
+ ## Contract and paired releases
219
+
220
+ Private-document tools and `embd workspace` are generated from the same
221
+ `@embd/documents` operation catalog. The internal package is bundled into both
222
+ public packages; it is not an npm runtime dependency. Every SQL-authorized
223
+ agent action must have a shared tool or an explicit protocol-only exclusion.
224
+ Human-only account/membership operations are deliberately excluded.
225
+
226
+ CLI and MCP versions move together. `client-release.json` fingerprints the
227
+ bundled sources and document API/migrations; CI rejects drift or a missing
228
+ version bump, verifies actual installed CLI and stdio MCP calls, and publishes
229
+ both packages from main using npm trusted publishing. A failed package publish
230
+ is a failed paired release and can be retried; npm publication is not atomic
231
+ across two packages. Existing installed clients are not silently upgraded.
232
+
233
+
234
+ ## Local knowledge-base replica (paired client 0.3.0)
235
+
236
+ Keep personal QMD collections independent. These tools maintain a separate embd SQLite FTS5 index and perform no network request for search/read/link resolution. Local tools require Node.js 22.13+ (or Bun for source development); existing remote commands retain their previous runtime support. The server must have the local-KB sync migration/API deployed.
237
+
238
+ Set `EMBD_DOCUMENT_TOKEN` to a read-scoped workspace agent credential. Do not put it in request JSON, shell history or the database. `EMBD_DOCUMENT_ORIGIN` defaults to `https://app.embd.sh`; `EMBD_KB_DIR` can override the cache root (default `~/.cache/embd/kb`). Data is isolated by origin, credential fingerprint and workspace. Explicit sync selection authorizes local storage. Offline access lasts at most one hour and never outlives credential expiry. Revocation is detected on sync; previously downloaded copies cannot be recalled remotely.
239
+
240
+ ```sh
241
+ # selection.json: {"workspaceId":"<workspace UUID>","documentIds":["<document UUID>"]}
242
+ embd workspace kb_sync --input @selection.json
243
+ # Optional background catch-up: keep this process running; Ctrl-C stops it.
244
+ embd workspace kb_sync --input @selection.json --watch 60
245
+ embd workspace kb_search --input '{"workspaceId":"<workspace UUID>","query":"authentication decision"}'
246
+ embd workspace kb_read --input '{"workspaceId":"<workspace UUID>","documentId":"<document UUID>"}'
247
+ embd workspace kb_resolve_link --input '{"workspaceId":"<workspace UUID>","documentId":"<document UUID>","href":"../decisions/auth.md#tradeoffs"}'
248
+ embd workspace kb_status --input '{"workspaceId":"<workspace UUID>"}'
249
+ embd workspace kb_forget --input '{"workspaceId":"<workspace UUID>"}'
250
+ ```
251
+
252
+ The same six `kb_*` operations are available in `embd-documents-mcp`. Call `kb_sync` explicitly there or run the CLI watch process with the same token/origin/cache directory. MCP does not silently start a daemon. `workspace tools` and each command's `--help` expose shared schemas. Search requires all literal terms, with Unicode tokenization; it is lexical, not semantic. Results contain stable document URLs, exact source versions/hashes and freshness. `kb_read` returns bounded source slices; use `nextOffset` to continue. Reads can be stale: fetch the current server document before editing. Relative links resolve only within the synced selection using retained bases and rename aliases; unresolved targets are not automatically downloaded.
253
+
254
+ Changing the selected IDs atomically replaces the local set after complete sync. Interrupted attempts retain the previous complete replica and its original expiry. A server cursor reset triggers a full reconciliation. A 401/403/404 clears the affected replica. `kb_forget` removes local content without deleting server documents. This is pull-only source sync: discussions, offline editing, automatic folder ingestion and embeddings are not included.
255
+
256
+
257
+ ### Portable document images
258
+
259
+ `export_document` returns the versioned `embd.document.v2` JSON package: exact
260
+ current source, authorized PNG/JPEG/WebP bytes, and a path manifest. It composes
261
+ existing authorized reads, so it works with the managed-image API without a new
262
+ server endpoint. CLI and MCP use the same collector and limits: at most 30 images
263
+ and 30 MB. A missing/denied/corrupt image or document edit aborts collection.
264
+ It does not contain comments, history, linked documents, or external resources.
265
+ External image URLs stay in source and are listed in `externalImages`; they are
266
+ never fetched. HTML base/srcset overrides and root-relative image paths require
267
+ conversion to ordinary relative image paths first.
268
+
269
+ The CLI can write a ZIP without overwriting an existing file:
270
+
271
+ ```sh
272
+ embd workspace export_document --input @document.json --archive-file document.zip
273
+ ```
274
+
275
+ `document.json` contains `{ "documentId": "<document UUID>" }`. Extract the ZIP
276
+ and open the source at `sourcePath` from `embd-export.json`. A moved document uses
277
+ its retained link base within `files/`, preserving exact relative image links;
278
+ its current workspace path remains in the manifest. The JSON form has each file's
279
+ encoding/content; the ZIP contains real source/image files instead of base64.
280
+ MCP returns the same JSON package and does not write to the machine's filesystem.