@abraca/mcp 2.8.0 → 2.9.0

package/dist/index.d.ts

@@ -78,6 +78,31 @@ declare class AbracadabraMCPServer {
    * Clears the child provider cache (children belong to the previous space).
    */
   switchSpace(docId: string): Promise<void>;
+  /**
+   * Make the space that OWNS `targetId` the active connection before a tree
+   * read/write, so the op targets the right space's `doc-tree` map.
+   *
+   * Without this, every tree tool used `getTreeMap()` (the single active
+   * space) and treated `rootId`/`parentId` as a mere filter — so reading a
+   * non-active space returned stale/empty trees, and *writing* to one
+   * silently orphaned the entry into the active space's map (a real
+   * data-loss path: docs built "in Ideas" while Development was active
+   * landed in Development under a non-node parent and never reached Ideas).
+   *
+   * Resolution order:
+   *  - falsy or already the active root → no-op.
+   *  - a known Space id → connect/activate it (cheap; `_spaceConnections`
+   *    caches the provider so re-activation is free).
+   *  - present in the active space's tree → no-op (a normal child doc).
+   *  - present in an already-connected *other* space's tree → activate that.
+   *  - otherwise unresolved → returns `false`; callers decide (reads report
+   *    not-found/empty, writes refuse rather than orphan).
+   *
+   * Switching uses {@link _connectToSpace} (not {@link switchSpace}) so the
+   * child-content provider cache survives — content docs are keyed by global
+   * guid, independent of which space is active.
+   */
+  ensureSpaceActive(targetId: string | null | undefined): Promise<boolean>;
   /** Get the root doc-tree Y.Map of the active space. */
   getTreeMap(): Y.Map<any> | null;
   /**
@@ -198,6 +223,17 @@ declare class AbracadabraMCPServer {
     target?: string;
     detail?: unknown;
   } | null): void;
+  /**
+   * Attach expandable `detail` (arguments + result summary) to the most recent
+   * tool-history entry for `toolName`, then re-broadcast `toolHistory`.
+   *
+   * Called by the central tool wrapper in index.ts *after* a tool resolves, so
+   * the dashboard's tool cards can expand to show what the tool was called with
+   * and what it returned — the same affordance built-in Claude tools (bash /
+   * read / edit) already get via the hook-bridge. Tools that never emitted a
+   * pill (no `setActiveToolCall`) have no entry to attach to, so this no-ops.
+   */
+  recordToolDetail(toolName: string, detail: unknown): void;
   /**
    * Send a typing indicator to a chat channel. Pass the channel doc id
    * (or for legacy callers, a `group:<docId>` string — we strip the prefix).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/mcp",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "MCP server for Abracadabra — AI agent collaboration on CRDT documents",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "y-protocols": "^1.0.6",
     "yjs": "^13.6.8",
     "zod": "^4.3.6",
-    "@abraca/convert": "2.8.0"
+    "@abraca/convert": "2.9.0"
   },
   "scripts": {
     "test": "node --no-warnings --conditions=source --experimental-transform-types --test 'tests/*.test.ts'"

package/src/index.ts

@@ -33,6 +33,7 @@ import { registerTreeResource } from "./resources/tree-resource.ts";
 import { loadSchemaBundle, SchemaBundleLoadError } from "./schema/loader.ts";
 import type { SchemaBundleValidator } from "./schema/validator.ts";
 import { AbracadabraMCPServer, type TriggerMode } from "./server.ts";
+import { wrapToolsWithDetail } from "./tool-detail.ts";
 import { registerAwarenessTools } from "./tools/awareness.ts";
 import { registerChannelTools } from "./tools/channel.ts";
 import { registerContentTools } from "./tools/content.ts";
@@ -149,6 +150,15 @@ Read the resource at abracadabra://agent-guide for the complete guide covering p
 		},
 	);
 
+	// Wrap mcp.tool ONCE so every tool invocation records an expandable detail
+	// (the arguments it was called with + the text it returned) onto its
+	// tool-history entry. This is what lets the cou-sh chat cards expand to show
+	// "which doc / which tree / what it found" — the same way built-in Claude
+	// tools (bash / read / edit) already expand via the hook-bridge. The pill
+	// itself is still emitted by each tool's own setActiveToolCall; we only
+	// enrich it after the handler resolves. Must run before the register* calls.
+	wrapToolsWithDetail(mcp, server);
+
 	// Register tools
 	registerTreeTools(mcp, server, schemaValidator);
 	registerContentTools(mcp, server);

package/src/server.ts

@@ -311,6 +311,58 @@ export class AbracadabraMCPServer {
 		console.error(`[abracadabra-mcp] Switched active space to ${docId}`);
 	}
 
+	/**
+	 * Make the space that OWNS `targetId` the active connection before a tree
+	 * read/write, so the op targets the right space's `doc-tree` map.
+	 *
+	 * Without this, every tree tool used `getTreeMap()` (the single active
+	 * space) and treated `rootId`/`parentId` as a mere filter — so reading a
+	 * non-active space returned stale/empty trees, and *writing* to one
+	 * silently orphaned the entry into the active space's map (a real
+	 * data-loss path: docs built "in Ideas" while Development was active
+	 * landed in Development under a non-node parent and never reached Ideas).
+	 *
+	 * Resolution order:
+	 *  - falsy or already the active root → no-op.
+	 *  - a known Space id → connect/activate it (cheap; `_spaceConnections`
+	 *    caches the provider so re-activation is free).
+	 *  - present in the active space's tree → no-op (a normal child doc).
+	 *  - present in an already-connected *other* space's tree → activate that.
+	 *  - otherwise unresolved → returns `false`; callers decide (reads report
+	 *    not-found/empty, writes refuse rather than orphan).
+	 *
+	 * Switching uses {@link _connectToSpace} (not {@link switchSpace}) so the
+	 * child-content provider cache survives — content docs are keyed by global
+	 * guid, independent of which space is active.
+	 */
+	async ensureSpaceActive(
+		targetId: string | null | undefined,
+	): Promise<boolean> {
+		if (!targetId || targetId === this._rootDocId) return true;
+
+		// A top-level Space id — activate it directly (handles the common
+		// `list_spaces` → operate-on-space-id flow that triggered the bug).
+		if (this._spaces.some((s) => s.id === targetId)) {
+			await this._connectToSpace(targetId);
+			return true;
+		}
+
+		// A normal doc already in the active space's tree — nothing to do.
+		if (this.getTreeMap()?.has(targetId)) return true;
+
+		// A doc in another space we've already connected to — activate it.
+		for (const [spaceId, conn] of this._spaceConnections) {
+			if (spaceId === this._rootDocId) continue;
+			if (conn.doc.getMap("doc-tree").has(targetId)) {
+				await this._connectToSpace(spaceId);
+				return true;
+			}
+		}
+
+		// Unresolved: not a space, not in any connected tree. Caller guards.
+		return false;
+	}
+
 	/** Get the root doc-tree Y.Map of the active space. */
 	getTreeMap(): Y.Map<any> | null {
 		return this._activeConnection?.doc.getMap("doc-tree") ?? null;
@@ -1122,6 +1174,33 @@ export class AbracadabraMCPServer {
 		}
 	}
 
+	/**
+	 * Attach expandable `detail` (arguments + result summary) to the most recent
+	 * tool-history entry for `toolName`, then re-broadcast `toolHistory`.
+	 *
+	 * Called by the central tool wrapper in index.ts *after* a tool resolves, so
+	 * the dashboard's tool cards can expand to show what the tool was called with
+	 * and what it returned — the same affordance built-in Claude tools (bash /
+	 * read / edit) already get via the hook-bridge. Tools that never emitted a
+	 * pill (no `setActiveToolCall`) have no entry to attach to, so this no-ops.
+	 */
+	recordToolDetail(toolName: string, detail: unknown): void {
+		const provider = this._activeConnection?.provider;
+		if (!provider) return;
+		// The matching pill was pushed at the start of this tool's handler, so the
+		// last detail-less entry for this name is this invocation's entry.
+		for (let i = this._toolHistory.length - 1; i >= 0; i--) {
+			const h = this._toolHistory[i];
+			if (h.tool === toolName && h.detail == null) {
+				h.detail = detail;
+				provider.awareness.setLocalStateField("toolHistory", [
+					...this._toolHistory,
+				]);
+				return;
+			}
+		}
+	}
+
 	/**
 	 * Send a typing indicator to a chat channel. Pass the channel doc id
 	 * (or for legacy callers, a `group:<docId>` string — we strip the prefix).

package/src/tool-detail.ts

@@ -0,0 +1,147 @@
+/**
+ * tool-detail — central enrichment of abracadabra MCP tool cards.
+ *
+ * Built-in Claude tools (Bash/Read/Edit/…) flow through the hook-bridge, which
+ * attaches an expandable `detail` (command text, file path, diff) that the
+ * cou-sh chat renders as a click-to-expand block. abracadabra's own MCP tools
+ * are explicitly skipped by the hook-bridge and only ever emitted a bare
+ * name+target pill — so their cards had nothing to expand ("no idea what docs
+ * it sees or what the tree was").
+ *
+ * `wrapToolsWithDetail` patches `McpServer.tool` ONCE, before any tool is
+ * registered, so every tool invocation records an expandable detail onto its
+ * tool-history entry (via `server.recordToolDetail`). The detail leads with the
+ * human-readable title + id of any document the call referenced (resolved from
+ * the live tree), then the remaining arguments, then the text the tool returned
+ * (e.g. the full document tree for `get_document_tree`). The pill itself is
+ * still emitted by each tool's own `setActiveToolCall`; this only fills in the
+ * expandable detail afterwards.
+ */
+import { toPlain } from "@abraca/dabra";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AbracadabraMCPServer } from "./server.ts";
+
+/** Per-field cap (chars) — keeps the awareness payload bounded. Mirrors the
+ *  hook-bridge's DETAIL_MAX so built-in and MCP tool cards behave alike. */
+const DETAIL_MAX = 4000;
+
+/** Argument keys that hold a document id, in the order we surface them. */
+const DOC_ID_KEYS = [
+	"docId",
+	"id",
+	"rootId",
+	"parentId",
+	"newParentId",
+	"uploadId",
+] as const;
+
+function cap(s: string): string {
+	return s.length > DETAIL_MAX ? `${s.slice(0, DETAIL_MAX)}\n… (truncated)` : s;
+}
+
+function safeJson(value: unknown): string {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+
+/** Pull the joined text content out of a tool result, if any. */
+function resultText(result: unknown): string {
+	const content = (result as { content?: unknown })?.content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((c) => c && (c as { type?: string }).type === "text")
+		.map((c) => (c as { text?: string }).text ?? "")
+		.join("\n")
+		.trim();
+}
+
+/**
+ * Build the expandable detail shown when a tool card is clicked:
+ *   1. one `id — "Title"` line per document the args referenced (title resolved
+ *      from the live tree when available),
+ *   2. the remaining arguments as compact JSON,
+ *   3. the text the tool returned (document tree, content, confirmation, …).
+ * Rendered by cou-sh's ChatActionCard as a `kind: "text"` block.
+ */
+export function buildToolDetail(
+	toolArgs: unknown,
+	result: unknown,
+	resolveLabel?: (id: string) => string | undefined,
+): { kind: "text"; text: string } {
+	const lines: string[] = [];
+	const rest: Record<string, unknown> =
+		toolArgs && typeof toolArgs === "object"
+			? { ...(toolArgs as Record<string, unknown>) }
+			: {};
+
+	// Headline: each referenced doc as "id — title" (title when resolvable).
+	for (const key of DOC_ID_KEYS) {
+		const v = rest[key];
+		if (typeof v === "string" && v.length > 0) {
+			const label = resolveLabel?.(v);
+			lines.push(label ? `${key}: ${v} — "${label}"` : `${key}: ${v}`);
+			delete rest[key];
+		}
+	}
+
+	// Remaining arguments (depth, type, label, meta, content, query, …).
+	const restStr = Object.keys(rest).length > 0 ? safeJson(rest) : "";
+	if (restStr && restStr !== "{}") lines.push(`args: ${restStr}`);
+	if (lines.length === 0) lines.push("args: (no arguments)");
+
+	const text = resultText(result);
+	if (text) {
+		lines.push("");
+		lines.push(text);
+	}
+	return { kind: "text", text: cap(lines.join("\n")) };
+}
+
+/**
+ * Monkey-patch `mcp.tool` so each registered tool's handler is wrapped to record
+ * arguments + result detail after it resolves. Call once at startup, before the
+ * register* functions run. Errors in detail-recording are swallowed — they must
+ * never break the underlying tool.
+ */
+export function wrapToolsWithDetail(
+	mcp: McpServer,
+	server: AbracadabraMCPServer,
+): void {
+	// Resolve a document id to its current label from the live tree, if loaded.
+	const resolveLabel = (id: string): string | undefined => {
+		try {
+			const raw = server.getTreeMap()?.get(id);
+			if (!raw) return undefined;
+			const label = (toPlain(raw) as { label?: unknown })?.label;
+			return typeof label === "string" && label.length > 0 ? label : undefined;
+		} catch {
+			return undefined;
+		}
+	};
+
+	const original = mcp.tool.bind(mcp) as (...args: unknown[]) => unknown;
+	(mcp as { tool: unknown }).tool = (...args: unknown[]) => {
+		const name = args[0];
+		const cbIndex = args.length - 1;
+		const cb = args[cbIndex];
+		if (typeof name === "string" && typeof cb === "function") {
+			const handler = cb as (...a: unknown[]) => unknown;
+			args[cbIndex] = async (...handlerArgs: unknown[]) => {
+				const result = await handler(...handlerArgs);
+				try {
+					server.recordToolDetail(
+						name,
+						buildToolDetail(handlerArgs[0], result, resolveLabel),
+					);
+				} catch {
+					/* detail recording must never break a tool */
+				}
+				return result;
+			};
+		}
+		return original(...args);
+	};
+}

package/src/tools/content.ts

@@ -21,6 +21,7 @@ export function registerContentTools(mcp: McpServer, server: AbracadabraMCPServe
         server.setAutoStatus('reading', docId)
         server.setActiveToolCall({ name: 'read_document', target: docId })
 
+        await server.ensureSpaceActive(docId)
         const provider = await server.getChildProvider(docId)
         const fragment = provider.document.getXmlFragment('default')
 
@@ -90,6 +91,7 @@ export function registerContentTools(mcp: McpServer, server: AbracadabraMCPServe
         server.setAutoStatus('writing', docId)
         server.setActiveToolCall({ name: 'write_document', target: docId })
 
+        await server.ensureSpaceActive(docId)
         const writeMode = mode ?? 'replace'
         const provider = await server.getChildProvider(docId)
         const doc = provider.document
@@ -127,9 +129,21 @@ export function registerContentTools(mcp: McpServer, server: AbracadabraMCPServe
           })
         }
 
-        // Write new content
+        // Write new content.
+        //
+        // ROOT-CAUSE FIX for the "card title silently becomes Untitled" bug:
+        // when the markdown carries neither a frontmatter `title:` nor a
+        // leading `# H1`, populateYDocFromMarkdown seeds the body
+        // `documentHeader` with `fallbackTitle`. Passing the literal
+        // 'Untitled' baked the placeholder string into the header — which a
+        // client's title-sync (cou-sh) then read back and propagated into
+        // the tree `label`, destroying the real title. Seed from the doc's
+        // ACTUAL label instead so the header agrees with the tree from the
+        // start (header === label → title-sync is a no-op). Only fall back
+        // to 'Untitled' when the doc genuinely has no label yet.
         const contentToWrite = body || markdown
-        const fallbackTitle = title || 'Untitled'
+        const existingLabel = server.getDocSummary(docId)?.label
+        const fallbackTitle = title || existingLabel || 'Untitled'
         populateYDocFromMarkdown(fragment, contentToWrite, fallbackTitle)
 
         // Auto-update presence: mark this doc as focused and place cursor at end

package/src/tools/meta.ts

@@ -21,6 +21,7 @@ export function registerMetaTools(
     async ({ docId }) => {
       server.setAutoStatus('reading', docId)
       server.setActiveToolCall({ name: 'get_metadata', target: docId })
+      await server.ensureSpaceActive(docId)
       const treeMap = server.getTreeMap()
       if (!treeMap) {
         return { content: [{ type: 'text', text: 'Not connected' }] }
@@ -55,6 +56,7 @@ export function registerMetaTools(
     async ({ docId, meta }) => {
       server.setAutoStatus('writing', docId)
       server.setActiveToolCall({ name: 'update_metadata', target: docId })
+      await server.ensureSpaceActive(docId)
       const treeMap = server.getTreeMap()
       if (!treeMap) {
         return { content: [{ type: 'text', text: 'Not connected' }] }