@embd/mcp 0.1.1 → 0.7.2
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 +118 -1
- package/dist/bin-1kg1p38g.js +70 -0
- package/dist/bin-664r3a08.js +17 -0
- package/dist/bin-xwy2gh0w.js +14 -0
- package/dist/bin-yxe31hyp.js +77 -0
- package/dist/bin-z48kbcz0.js +4 -0
- package/dist/bin.js +2 -4
- package/dist/documents-bin.js +2 -0
- package/dist/http-bin.js +1 -1
- package/dist/index.js +1 -1
- package/package.json +15 -7
- package/dist/bin-vgwnqx96.js +0 -92
- package/dist/bin-zpwsygeh.js +0 -14
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 seven `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.
|