@abraca/mcp 2.3.0 → 2.5.0

package/README.md

@@ -0,0 +1,32 @@
+# @abraca/mcp
+
+A Model Context Protocol server that exposes an Abracadabra space to AI tooling — documents, tree, content, metadata, files, chat, and presence over stdio. Bin: `abracadabra-mcp`.
+
+## Documentation
+
+Full, code-derived documentation lives in [`docs/`](docs/) — a numbered Nuxt-Content
+site covering startup/transport, every env var, all 27 tools, the 3 resources, schema
+validation, and the channel/dispatch model + gotchas. It is the source of truth.
+
+## Quick start
+
+```bash
+ABRA_URL=https://my-server.example.com abracadabra-mcp
+```
+
+Identity is an Ed25519 key file (`ABRA_KEY_FILE`, default `~/.abracadabra/agent.key`); the agent auto-registers on first run (`ABRA_INVITE_CODE` optional). See [`docs/1.getting-started/configuration`](docs/1.getting-started/2.configuration.md) for every variable.
+
+## Highlights
+
+- **27 tools** — tree/documents, content/meta, files, channel (`reply`, `send_chat_message`), awareness, SVG, hooks.
+- **3 resources** — `agent-guide` (the authoritative in-band reference), `server-info`, `tree`.
+- **Opt-in schema validation** via `ABRA_MCP_SCHEMA_BUNDLE` (a `@abraca/schema` bundle).
+- **Hook bridge** mirrors Claude Code tool activity into the agent's presence.
+
+::
+
+> Plain text is invisible to users — chat replies go via `send_chat_message`, ai:task answers via `reply`. `read_document`'s body is **not** full content (children are content). See [`docs/4.reference/`](docs/4.reference/1.auth-channel-gotchas.md).
+
+## License
+
+MIT.

package/dist/abracadabra-mcp.cjs

@@ -14092,6 +14092,9 @@ var AbracadabraMCPServer = class AbracadabraMCPServer {
 	static {
 		this.TOOL_HISTORY_MAX = 20;
 	}
+	static {
+		this.DEDUPE_MAX = 1e3;
+	}
 	constructor(config) {
 		this._serverInfo = null;
 		this._rootDocId = null;
@@ -14109,6 +14112,14 @@ var AbracadabraMCPServer = class AbracadabraMCPServer {
 		this._lastChatChannel = null;
 		this._signFn = null;
 		this._toolHistory = [];
+		this._inboxStarted = false;
+		this._inboxDocId = null;
+		this._inboxDoc = null;
+		this._inboxProvider = null;
+		this._inboxDisposers = [];
+		this._inboxInitialized = false;
+		this._seenInboxIds = /* @__PURE__ */ new Set();
+		this._dispatchedMessageIds = /* @__PURE__ */ new Set();
 		this.config = config;
 		this.client = new _abraca_dabra.AbracadabraClient({
 			url: config.url,
@@ -14338,6 +14349,182 @@ var AbracadabraMCPServer = class AbracadabraMCPServer {
 				this._handleStatelessChat(payload);
 			});
 			console.error("[abracadabra-mcp] Stateless chat listener attached");
+			this._startInboxNotifications();
+		}
+	}
+	/**
+	* Bootstrap inbox observation. Sends `messages:inbox_fetch` over the active
+	* provider; the server's `messages:inbox_history` reply carries the
+	* `inbox_doc_id`. We then open a dedicated provider on that doc and observe
+	* its `entries` Y.Array for live DM/mention dispatch. Mirrors the
+	* dashboard's `useNotifications` pattern.
+	*/
+	async _startInboxNotifications() {
+		if (this._inboxStarted) return;
+		const provider = this._activeConnection?.provider;
+		if (!provider) return;
+		this._inboxStarted = true;
+		provider.on("stateless", ({ payload }) => {
+			if (!payload.includes("\"messages:inbox_history\"")) return;
+			try {
+				const data = JSON.parse(payload);
+				if (data?.type !== "messages:inbox_history") return;
+				const inboxDocId = typeof data.inbox_doc_id === "string" ? data.inbox_doc_id : null;
+				if (inboxDocId) this._ensureInboxObserver(inboxDocId);
+			} catch {}
+		});
+		provider.sendStateless(JSON.stringify({
+			type: "messages:inbox_fetch",
+			limit: 50,
+			unread_only: false
+		}));
+		console.error("[abracadabra-mcp] Inbox bootstrap sent (messages:inbox_fetch)");
+	}
+	/**
+	* Open a dedicated provider on the agent's inbox doc and observe its
+	* `entries` Y.Array. The server is the only writer; we only read.
+	*/
+	async _ensureInboxObserver(inboxDocId) {
+		if (this._inboxDocId) return;
+		this._inboxDocId = inboxDocId;
+		if (!this.client.isTokenValid() && this._signFn && this._userId) await this.client.loginWithKey(this._userId, this._signFn);
+		const doc = new yjs.Doc({ guid: inboxDocId });
+		const provider = new _abraca_dabra.AbracadabraProvider({
+			name: inboxDocId,
+			document: doc,
+			client: this.client,
+			disableOfflineStore: true,
+			subdocLoading: "lazy"
+		});
+		this._inboxDoc = doc;
+		this._inboxProvider = provider;
+		try {
+			await waitForSync(provider);
+		} catch (err) {
+			console.error(`[abracadabra-mcp] Inbox sync failed: ${err?.message ?? err}`);
+			return;
+		}
+		const entriesArr = doc.getArray("entries");
+		const readMap = doc.getMap("read");
+		const onChange = () => {
+			this._pumpInbox(entriesArr, readMap);
+		};
+		entriesArr.observe(onChange);
+		readMap.observe(onChange);
+		this._inboxDisposers.push(() => entriesArr.unobserve(onChange));
+		this._inboxDisposers.push(() => readMap.unobserve(onChange));
+		await this._pumpInbox(entriesArr, readMap);
+		console.error(`[abracadabra-mcp] Inbox observer attached (${inboxDocId})`);
+	}
+	/**
+	* Diff the inbox `entries` array against what we've already seen. On the
+	* first pump we only record a baseline (don't replay history). New entries
+	* are classified by their authoritative `kind` and dispatched.
+	*/
+	async _pumpInbox(entriesArr, readMap) {
+		const entries = entriesArr.toArray().map((e) => typeof e?.toJSON === "function" ? e.toJSON() : e);
+		if (!this._inboxInitialized) {
+			for (const e of entries) if (e?.id) this._seenInboxIds.add(e.id);
+			this._inboxInitialized = true;
+			console.error(`[abracadabra-mcp] Inbox baseline: ${this._seenInboxIds.size} existing entries (not replayed)`);
+			return;
+		}
+		for (const e of entries) {
+			const id = e?.id;
+			if (!id || this._seenInboxIds.has(id)) continue;
+			this._seenInboxIds.add(id);
+			if (readMap.get(id)) continue;
+			try {
+				await this._dispatchInboxEntry(e);
+			} catch (err) {
+				console.error(`[abracadabra-mcp] Inbox dispatch failed for ${id}: ${err?.message ?? err}`);
+			}
+		}
+		this._trimSet(this._seenInboxIds);
+	}
+	/** Classify + dispatch one inbox entry as a channel notification. */
+	async _dispatchInboxEntry(entry) {
+		if (!this._serverRef) return;
+		const kind = typeof entry?.kind === "string" ? entry.kind : "";
+		const channelDocId = typeof entry?.channel_doc_id === "string" ? entry.channel_doc_id : "";
+		const messageId = typeof entry?.message_id === "string" ? entry.message_id : null;
+		const senderId = typeof entry?.sender_id === "string" ? entry.sender_id : "";
+		if (!channelDocId) return;
+		if (senderId && senderId === this._userId) return;
+		const mode = this.triggerMode;
+		if (kind === "mention" || kind === "reply") {
+			if (mode === "task") return;
+		} else if (kind !== "dm") return;
+		if (messageId && this._rememberDispatched(messageId)) return;
+		const content = await this._resolveInboxContent(channelDocId, messageId, entry?.preview);
+		this._lastChatChannel = channelDocId;
+		this._beginTurn();
+		this.setAutoStatus("thinking");
+		await this._serverRef.notification({
+			method: "notifications/claude/channel",
+			params: {
+				content,
+				instructions: `You MUST use send_chat_message with channel_doc_id="${channelDocId}" for ALL responses — both progress updates and final answers. The user CANNOT see plain text output; they only see messages sent via send_chat_message. When doing multi-step work, send brief status updates via send_chat_message (e.g. "Looking into that..." or "Found it, writing up results...") so the user knows you're working. Never output plain text as a substitute for send_chat_message.`,
+				meta: {
+					source: "abracadabra",
+					type: kind === "dm" ? "dm_message" : "chat_message",
+					channel_doc_id: channelDocId,
+					sender: entry?.sender_name ?? "Unknown",
+					sender_id: senderId,
+					doc_id: channelDocId
+				}
+			}
+		});
+		console.error(`[abracadabra-mcp] Dispatched ${kind} on ${channelDocId} from ${entry?.sender_name ?? (senderId || "unknown")}`);
+		this._activeConnection?.provider?.sendStateless(JSON.stringify({
+			type: "messages:inbox_mark_read",
+			id: entry.id
+		}));
+	}
+	/**
+	* Resolve full message content. The inbox `preview` is truncated to ≤200
+	* bytes (and null for E2E), so for fidelity we read the actual record from
+	* the channel/DM doc's active period — same shape the dashboard reads.
+	* Falls back to the preview, then a short notice.
+	*/
+	async _resolveInboxContent(channelDocId, messageId, preview) {
+		const previewStr = typeof preview === "string" && preview.length > 0 ? preview : null;
+		const root = this._activeConnection?.provider;
+		if (root && messageId) try {
+			const wrapper = await root.loadChild(channelDocId);
+			if (!wrapper.synced) await waitForSync(wrapper);
+			const periods = wrapper.document.getArray("periods");
+			const len = periods.length;
+			for (let i = len - 1; i >= 0 && i >= len - 2; i--) {
+				const p = periods.get(i);
+				const periodId = p?.id ?? p?.get?.("id");
+				if (!periodId) continue;
+				const period = await root.loadChild(periodId);
+				if (!period.synced) await waitForSync(period);
+				const hit = (0, _abraca_dabra.foldRecords)(period.document.getArray("messages").toArray().map((v) => (0, _abraca_dabra.recordFromYAny)(v)).filter((r) => r !== null)).find((f) => f.id === messageId);
+				if (hit) {
+					if ((0, _abraca_dabra.isEncryptedContent)(hit.content)) return previewStr ?? "[encrypted message — this agent is not provisioned to read this channel]";
+					return hit.content;
+				}
+			}
+		} catch (err) {
+			console.error(`[abracadabra-mcp] content read failed for ${channelDocId}/${messageId}: ${err?.message ?? err}`);
+		}
+		return previewStr ?? "[message content unavailable]";
+	}
+	_rememberDispatched(messageId) {
+		if (this._dispatchedMessageIds.has(messageId)) return true;
+		this._dispatchedMessageIds.add(messageId);
+		this._trimSet(this._dispatchedMessageIds);
+		return false;
+	}
+	_trimSet(s) {
+		if (s.size <= AbracadabraMCPServer.DEDUPE_MAX) return;
+		const excess = s.size - AbracadabraMCPServer.DEDUPE_MAX;
+		let i = 0;
+		for (const v of s) {
+			if (i++ >= excess) break;
+			s.delete(v);
 		}
 	}
 	/** Attach awareness observer to detect `ai:task` fields from human users. */
@@ -14423,6 +14610,7 @@ var AbracadabraMCPServer = class AbracadabraMCPServer {
 			if (data.sender_id && data.sender_id === this._userId) return;
 			const channelDocId = data.channel_doc_id;
 			if (!channelDocId) return;
+			if (data.id && this._rememberDispatched(data.id)) return;
 			const mode = this.triggerMode;
 			const content = typeof data.content === "string" ? data.content : "";
 			let dispatchContent = content;
@@ -14573,6 +14761,13 @@ var AbracadabraMCPServer = class AbracadabraMCPServer {
 			clearInterval(this.evictionTimer);
 			this.evictionTimer = null;
 		}
+		for (const dispose of this._inboxDisposers) try {
+			dispose();
+		} catch {}
+		this._inboxDisposers = [];
+		this._inboxProvider?.destroy();
+		this._inboxProvider = null;
+		this._inboxDoc = null;
 		for (const [, cached] of this.childCache) cached.provider.destroy();
 		this.childCache.clear();
 		for (const [, conn] of this._spaceConnections) {
@@ -15333,13 +15528,13 @@ function normalizeRootId(id, server) {
 	return id === server.rootDocId ? null : id;
 }
 /** Safely read a tree map value, converting Y.Map to plain object if needed. */
-function toPlain(val) {
+function toPlain$3(val) {
 	return val instanceof yjs.Map ? val.toJSON() : val;
 }
 function readEntries$1(treeMap) {
 	const entries = [];
 	treeMap.forEach((raw, id) => {
-		const value = toPlain(raw);
+		const value = toPlain$3(raw);
 		if (typeof value !== "object" || value === null) return;
 		entries.push({
 			id,
@@ -15536,7 +15731,7 @@ function registerTreeTools(mcp, server, validator = null) {
 		const normalizedParent = normalizeRootId(parentId, server);
 		const now = Date.now();
 		rootDoc.transact(() => {
-			treeMap.set(id, {
+			treeMap.set(id, (0, _abraca_dabra.makeEntryMap)({
 				label,
 				parentId: normalizedParent,
 				order: now,
@@ -15544,7 +15739,7 @@ function registerTreeTools(mcp, server, validator = null) {
 				meta,
 				createdAt: now,
 				updatedAt: now
-			});
+			}));
 		});
 		server.setFocusedDoc(id);
 		return { content: [{
@@ -15571,14 +15766,11 @@ function registerTreeTools(mcp, server, validator = null) {
 			type: "text",
 			text: "Not connected"
 		}] };
-		const raw = treeMap.get(id);
-		if (!raw) return { content: [{
+		if (!treeMap.get(id)) return { content: [{
 			type: "text",
 			text: `Document ${id} not found`
 		}] };
-		const entry = toPlain(raw);
-		treeMap.set(id, {
-			...entry,
+		(0, _abraca_dabra.patchEntry)(treeMap, id, {
 			label,
 			updatedAt: Date.now()
 		});
@@ -15602,14 +15794,11 @@ function registerTreeTools(mcp, server, validator = null) {
 			type: "text",
 			text: "Not connected"
 		}] };
-		const raw = treeMap.get(id);
-		if (!raw) return { content: [{
+		if (!treeMap.get(id)) return { content: [{
 			type: "text",
 			text: `Document ${id} not found`
 		}] };
-		const entry = toPlain(raw);
-		treeMap.set(id, {
-			...entry,
+		(0, _abraca_dabra.patchEntry)(treeMap, id, {
 			parentId: normalizeRootId(newParentId, server),
 			order: order ?? Date.now(),
 			updatedAt: Date.now()
@@ -15638,7 +15827,7 @@ function registerTreeTools(mcp, server, validator = null) {
 			for (const nid of toDelete) {
 				const raw = treeMap.get(nid);
 				if (!raw) continue;
-				const entry = toPlain(raw);
+				const entry = toPlain$3(raw);
 				trashMap.set(nid, {
 					label: entry.label || "Untitled",
 					parentId: entry.parentId ?? null,
@@ -15669,14 +15858,11 @@ function registerTreeTools(mcp, server, validator = null) {
 			type: "text",
 			text: "Not connected"
 		}] };
-		const raw = treeMap.get(id);
-		if (!raw) return { content: [{
+		if (!treeMap.get(id)) return { content: [{
 			type: "text",
 			text: `Document ${id} not found`
 		}] };
-		const entry = toPlain(raw);
-		treeMap.set(id, {
-			...entry,
+		(0, _abraca_dabra.patchEntry)(treeMap, id, {
 			type,
 			updatedAt: Date.now()
 		});
@@ -15719,13 +15905,13 @@ function registerTreeTools(mcp, server, validator = null) {
 			type: "text",
 			text: `Document ${id} not found`
 		}] };
-		const entry = toPlain(raw);
+		const entry = toPlain$3(raw);
 		const newId = crypto.randomUUID();
-		treeMap.set(newId, {
+		treeMap.set(newId, (0, _abraca_dabra.makeEntryMap)({
 			...entry,
 			label: (entry.label || "Untitled") + " (copy)",
 			order: Date.now()
-		});
+		}));
 		server.setFocusedDoc(newId);
 		return { content: [{
 			type: "text",
@@ -15771,31 +15957,37 @@ function registerContentTools(mcp, server) {
 				name: "read_document",
 				target: docId
 			});
-			const { title, markdown } = (0, _abraca_convert.yjsToMarkdown)((await server.getChildProvider(docId)).document.getXmlFragment("default"));
+			const fragment = (await server.getChildProvider(docId)).document.getXmlFragment("default");
 			server.setFocusedDoc(docId);
 			server.setDocCursor(docId, 0);
 			const treeMap = server.getTreeMap();
-			let label = title;
+			let label = "Untitled";
 			let type;
 			let meta;
 			let children = [];
 			if (treeMap) {
-				const entry = treeMap.get(docId);
-				if (entry) {
-					label = entry.label || title;
+				const entry = (0, _abraca_dabra.toPlain)(treeMap.get(docId));
+				if (entry && typeof entry === "object") {
+					label = entry.label || label;
 					type = entry.type;
 					meta = entry.meta;
 				}
-				treeMap.forEach((value, id) => {
-					if (value.parentId === docId) children.push({
+				const collected = [];
+				treeMap.forEach((raw, id) => {
+					const value = (0, _abraca_dabra.toPlain)(raw);
+					if (typeof value !== "object" || value === null) return;
+					if (value.parentId === docId) collected.push({
 						id,
 						label: value.label || "Untitled",
 						type: value.type,
-						meta: value.meta
+						meta: value.meta,
+						order: value.order ?? 0
 					});
 				});
-				children.sort((a, b) => (treeMap.get(a.id)?.order ?? 0) - (treeMap.get(b.id)?.order ?? 0));
+				collected.sort((a, b) => a.order - b.order);
+				children = collected.map(({ order, ...rest }) => rest);
 			}
+			const markdown = (0, _abraca_convert.yjsToMarkdown)(fragment, label, meta, type);
 			const result = {
 				label,
 				type,
@@ -15836,19 +16028,19 @@ function registerContentTools(mcp, server) {
 				const treeMap = server.getTreeMap();
 				const rootDoc = server.rootDocument;
 				if (treeMap && rootDoc) {
-					const entry = treeMap.get(docId);
-					if (entry) rootDoc.transact(() => {
-						const updates = {
-							...entry,
-							updatedAt: Date.now()
-						};
-						if (title) updates.label = title;
-						if (Object.keys(meta).length > 0) updates.meta = {
-							...entry.meta ?? {},
-							...meta
-						};
-						treeMap.set(docId, updates);
-					});
+					const rawEntry = treeMap.get(docId);
+					if (rawEntry) {
+						const cur = (0, _abraca_dabra.toPlain)(rawEntry);
+						rootDoc.transact(() => {
+							const patch = { updatedAt: Date.now() };
+							if (title) patch.label = title;
+							if (Object.keys(meta).length > 0) patch.meta = {
+								...cur.meta ?? {},
+								...meta
+							};
+							(0, _abraca_dabra.patchEntry)(treeMap, docId, patch);
+						});
+					}
 				}
 			}
 			if (writeMode === "replace") doc.transact(() => {
@@ -15916,11 +16108,12 @@ function registerMetaTools(mcp, server, validator = null) {
 			type: "text",
 			text: "Not connected"
 		}] };
-		const entry = treeMap.get(docId);
-		if (!entry) return { content: [{
+		const rawEntry = treeMap.get(docId);
+		if (!rawEntry) return { content: [{
 			type: "text",
 			text: `Document ${docId} not found`
 		}] };
+		const entry = (0, _abraca_dabra.toPlain)(rawEntry);
 		const mergedMeta = {
 			...entry.meta ?? {},
 			...meta
@@ -15938,8 +16131,7 @@ function registerMetaTools(mcp, server, validator = null) {
 				};
 			}
 		}
-		treeMap.set(docId, {
-			...entry,
+		(0, _abraca_dabra.patchEntry)(treeMap, docId, {
 			meta: mergedMeta,
 			updatedAt: Date.now()
 		});
@@ -16129,7 +16321,7 @@ function registerAwarenessTools(mcp, server) {
 				})
 			}] };
 			const resolvedInboxId = inboxId;
-			const { markdown } = (0, _abraca_convert.yjsToMarkdown)((await server.getChildProvider(resolvedInboxId)).document.getXmlFragment("default"));
+			const markdown = (0, _abraca_convert.yjsToMarkdown)((await server.getChildProvider(resolvedInboxId)).document.getXmlFragment("default"), "AI Inbox");
 			const pendingTasks = [];
 			treeMap.forEach((value, id) => {
 				if (value.parentId === resolvedInboxId) pendingTasks.push({
@@ -16215,16 +16407,16 @@ function registerChannelTools(mcp, server) {
 			const replyId = crypto.randomUUID();
 			const now = Date.now();
 			rootDoc.transact(() => {
-				treeMap.set(replyId, {
+				treeMap.set(replyId, (0, _abraca_dabra.makeEntryMap)({
 					label,
 					parentId: doc_id,
 					order: now,
 					type: "doc",
 					createdAt: now,
 					updatedAt: now
-				});
+				}));
 			});
-			(0, _abraca_convert.populateYDocFromMarkdown)((await server.getChildProvider(replyId)).document, text);
+			(0, _abraca_convert.populateYDocFromMarkdown)((await server.getChildProvider(replyId)).document.getXmlFragment("default"), text);
 			if (task_id) server.clearAiTask(task_id);
 			return { content: [{
 				type: "text",
@@ -16998,9 +17190,14 @@ function registerAgentGuide(mcp) {
 
 //#endregion
 //#region packages/mcp/src/resources/tree-resource.ts
+/**
+* Dynamic resource: document tree as navigable JSON.
+*/
 function readEntries(treeMap) {
 	const entries = [];
-	treeMap.forEach((value, id) => {
+	treeMap.forEach((raw, id) => {
+		const value = (0, _abraca_dabra.toPlain)(raw);
+		if (typeof value !== "object" || value === null) return;
 		entries.push({
 			id,
 			label: value.label || "Untitled",