exovault-mcp-server 1.2.0 → 1.4.0

package/dist/gateway-client.d.ts

@@ -62,8 +62,14 @@ export declare class GatewayClient {
         includeArchived?: boolean;
         entity?: string;
         compact?: boolean;
+        decayHalfLife?: number;
+        diversity?: number;
+        searchMode?: "auto" | "hybrid" | "bm25" | "semantic";
+        graphWeight?: number;
+        graphSeeds?: number;
+        graphMaxHops?: number;
     }): Promise<string>;
-    readMemories(memoryIds: string[]): Promise<string>;
+    readMemories(memoryIds: string[], includeMediaContent?: boolean): Promise<string>;
     updateMemory(params: {
         memoryId: string;
         content?: string;
@@ -130,8 +136,8 @@ export declare class GatewayClient {
         limit?: number;
         folderId?: string;
     }): Promise<string>;
-    readNote(noteId: string): Promise<string>;
-    readNotes(noteIds: string[]): Promise<string>;
+    readNote(noteId: string, includeMediaContent?: boolean): Promise<string>;
+    readNotes(noteIds: string[], includeMediaContent?: boolean): Promise<string>;
     searchNotes(params: {
         query: string;
         topK?: number;
@@ -338,5 +344,21 @@ export declare class GatewayClient {
         embeddingStatus: string;
         base64Content: string;
     }>;
+    viewMedia(params: {
+        attachmentId: string;
+    }): Promise<{
+        attachmentId: string;
+        memoryId: string | null;
+        noteId: string | null;
+        modality: string;
+        mimeType: string;
+        fileName: string | null;
+        fileSizeBytes: number;
+        embeddingStatus: string;
+        extractionStatus: string;
+        extractedText: string | null;
+        base64Content: string | null;
+        contentNote: string | null;
+    }>;
     deleteMedia(attachmentId: string, vaultId?: string): Promise<string>;
 }

package/dist/gateway-client.js

@@ -102,8 +102,8 @@ export class GatewayClient {
         const result = await this.request("POST", "/api/agent/search-memories", params);
         return JSON.stringify(result);
     }
-    async readMemories(memoryIds) {
-        const result = await this.request("POST", "/api/agent/read-memories", { memoryIds });
+    async readMemories(memoryIds, includeMediaContent) {
+        const result = await this.request("POST", "/api/agent/read-memories", { memoryIds, includeMediaContent });
         return JSON.stringify(result);
     }
     async updateMemory(params) {
@@ -145,12 +145,12 @@ export class GatewayClient {
         const result = await this.request("POST", "/api/agent/list-notes", params);
         return JSON.stringify(result);
     }
-    async readNote(noteId) {
-        const result = await this.request("POST", "/api/agent/read-note", { noteId });
+    async readNote(noteId, includeMediaContent) {
+        const result = await this.request("POST", "/api/agent/read-note", { noteId, includeMediaContent });
         return JSON.stringify(result);
     }
-    async readNotes(noteIds) {
-        const result = await this.request("POST", "/api/agent/read-notes", { noteIds });
+    async readNotes(noteIds, includeMediaContent) {
+        const result = await this.request("POST", "/api/agent/read-notes", { noteIds, includeMediaContent });
         return JSON.stringify(result);
     }
     async searchNotes(params) {
@@ -323,6 +323,9 @@ export class GatewayClient {
     async downloadMedia(params) {
         return this.request("POST", "/api/agent/download-media", params);
     }
+    async viewMedia(params) {
+        return this.request("POST", "/api/agent/view-media", params);
+    }
     async deleteMedia(attachmentId, vaultId) {
         const body = { attachmentId };
         if (vaultId)

package/dist/index.js

@@ -30,6 +30,7 @@ import { exploreGraph } from "./tools/explore-graph.js";
 import { recall } from "./tools/recall.js";
 import { search } from "./tools/search.js";
 import { sendMessage, ackMessage, readMessages } from "./tools/agent-messages.js";
+import { viewMedia } from "./tools/view-media.js";
 // Task tools are thin wrappers around memory tools — no separate agent-tasks import needed
 import { resolveVaultId } from "./tools/resolve-vault-id.js";
 import { GatewayClient } from "./gateway-client.js";
@@ -430,10 +431,11 @@ async function main() {
         description: "Read the full decrypted content of a note, including title, tags, and vault name",
         inputSchema: {
             noteId: s(z.string().uuid().describe("The note ID to read")),
+            includeMediaContent: s(z.boolean().optional().describe("When true, includes base64 image content for images under 500KB. Gateway mode only. Default: false.")),
         },
     }, auto.wrap(wrapToolHandler(async (args) => {
-        const { noteId } = args;
-        return gw ? await gw.readNote(noteId) : await readNote(ctx, noteId);
+        const { noteId, includeMediaContent } = args;
+        return gw ? await gw.readNote(noteId, includeMediaContent) : await readNote(ctx, noteId, includeMediaContent);
     })));
     // ─── search_notes ─────────────────────────────────────────────────────────
     server.registerTool("search_notes", {
@@ -548,10 +550,11 @@ async function main() {
         description: "Read the full decrypted content of multiple notes at once. Returns all notes with their titles, content, tags, and vault names. Reports any IDs that were not found.",
         inputSchema: {
             noteIds: s(z.array(z.string().uuid()).min(1).max(20).describe("Array of note IDs to read (max 20)")),
+            includeMediaContent: s(z.boolean().optional().describe("When true, includes base64 image content for images under 500KB. Gateway mode only. Default: false.")),
         },
     }, auto.wrap(wrapToolHandler(async (args) => {
-        const { noteIds } = args;
-        return gw ? await gw.readNotes(noteIds) : await readNotes(ctx, noteIds);
+        const { noteIds, includeMediaContent } = args;
+        return gw ? await gw.readNotes(noteIds, includeMediaContent) : await readNotes(ctx, noteIds, includeMediaContent);
     })));
     // ─── write_memory ───────────────────────────────────────────────────────────
     server.registerTool("write_memory", {
@@ -605,6 +608,9 @@ async function main() {
             compact: s(z.boolean().optional().describe("Return truncated content previews (200 chars) instead of full content. Use read_memories for full content on specific IDs.")),
             decayHalfLife: s(z.number().int().min(1).max(365).optional().describe("Temporal decay half-life in days (default 30). Older memories score lower unless importance >= 4.")),
             diversity: s(z.number().min(0).max(1).optional().describe("MMR diversity balance 0-1 (default 0.7). Higher = more relevance, lower = more diversity.")),
+            graphWeight: s(z.number().min(0).max(1.5).optional().describe("RRF weight for graph signal (default 0.6). Set 0 to disable graph expansion.")),
+            graphSeeds: s(z.number().int().min(0).max(15).optional().describe("How many top results to use as graph expansion seeds (default 5)")),
+            graphMaxHops: s(z.number().int().min(1).max(2).optional().describe("Max hops for graph traversal (default 1)")),
         },
     }, auto.wrap(wrapToolHandler(async (args) => {
         const input = args;
@@ -643,10 +649,11 @@ async function main() {
         description: "Read and decrypt full memory entries by IDs.",
         inputSchema: {
             memoryIds: s(z.array(z.string().uuid()).min(1).max(50).describe("Array of memory IDs to read")),
+            includeMediaContent: s(z.boolean().optional().describe("When true, includes base64 image content for images under 500KB. Gateway mode only. Default: false.")),
         },
     }, auto.wrap(wrapToolHandler(async (args) => {
-        const { memoryIds } = args;
-        return gw ? await gw.readMemories(memoryIds) : await readMemories(ctx, memoryIds);
+        const { memoryIds, includeMediaContent } = args;
+        return gw ? await gw.readMemories(memoryIds, includeMediaContent) : await readMemories(ctx, memoryIds, includeMediaContent);
     })));
     // ─── archive_memory ─────────────────────────────────────────────────────────
     server.registerTool("archive_memory", {
@@ -1257,6 +1264,23 @@ async function main() {
         const result = await gw.downloadMedia({ attachmentId });
         return JSON.stringify(result);
     })));
+    // ─── view_media ─────────────────────────────────────────────────────────
+    server.registerTool("view_media", {
+        description: "View a media attachment intelligently. Returns extracted text for all modalities, " +
+            "plus base64 image content for images under 500KB. For non-image files (PDFs, audio, " +
+            "video), returns the extracted text/transcription instead of raw bytes. " +
+            "Use download_media if you need the actual file bytes regardless of size.",
+        inputSchema: {
+            attachmentId: s(z.string().uuid().describe("Media attachment ID to view")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { attachmentId } = args;
+        if (gw) {
+            const result = await gw.viewMedia({ attachmentId });
+            return JSON.stringify(result);
+        }
+        return viewMedia(ctx, attachmentId);
+    })));
     // ─── delete_media ───────────────────────────────────────────────────────
     server.registerTool("delete_media", {
         description: "Delete a media attachment and its embedding. Permanently removes the file from storage.",

package/dist/tools/read-memories.d.ts

@@ -1,2 +1,2 @@
 import type { McpContext } from "../auth.js";
-export declare function readMemories(ctx: McpContext, memoryIds: string[]): Promise<string>;
+export declare function readMemories(ctx: McpContext, memoryIds: string[], _includeMediaContent?: boolean): Promise<string>;

package/dist/tools/read-memories.js

@@ -2,7 +2,7 @@ import { getMemoriesByIds, touchMemories, getAttachmentsForMemories, formatAttac
 import { decrypt } from "../crypto.js";
 import { logMcpUsageEvent } from "../usage.js";
 import { decryptMemoryFields } from "./decrypt-helpers.js";
-export async function readMemories(ctx, memoryIds) {
+export async function readMemories(ctx, memoryIds, _includeMediaContent) {
     const memories = await getMemoriesByIds(ctx.supabase, ctx.userId, memoryIds);
     const foundIds = new Set(memories.map((m) => m.id));
     const notFound = memoryIds.filter((id) => !foundIds.has(id));

package/dist/tools/read-note.d.ts

@@ -1,2 +1,2 @@
 import type { McpContext } from "../auth.js";
-export declare function readNote(ctx: McpContext, noteId: string): Promise<string>;
+export declare function readNote(ctx: McpContext, noteId: string, _includeMediaContent?: boolean): Promise<string>;

package/dist/tools/read-note.js

@@ -2,7 +2,7 @@ import { getNote, getVault, getAttachmentsForNotes, formatAttachmentWithExtracti
 import { decrypt } from "../crypto.js";
 import { logMcpUsageEvent } from "../usage.js";
 import { decryptNoteFields } from "./decrypt-helpers.js";
-export async function readNote(ctx, noteId) {
+export async function readNote(ctx, noteId, _includeMediaContent) {
     const note = await getNote(ctx.supabase, ctx.userId, noteId);
     if (!note) {
         return JSON.stringify({ error: "Note not found" });

package/dist/tools/read-notes.d.ts

@@ -3,4 +3,4 @@ import type { McpContext } from "../auth.js";
  * Batch-reads multiple notes by ID. Returns full decrypted content for each,
  * plus a list of any IDs that were not found.
  */
-export declare function readNotes(ctx: McpContext, noteIds: string[]): Promise<string>;
+export declare function readNotes(ctx: McpContext, noteIds: string[], _includeMediaContent?: boolean): Promise<string>;

package/dist/tools/read-notes.js

@@ -5,7 +5,7 @@ import { decryptNoteFields } from "./decrypt-helpers.js";
  * Batch-reads multiple notes by ID. Returns full decrypted content for each,
  * plus a list of any IDs that were not found.
  */
-export async function readNotes(ctx, noteIds) {
+export async function readNotes(ctx, noteIds, _includeMediaContent) {
     const notes = await getNotesByIds(ctx.supabase, ctx.userId, noteIds);
     // Build a set of found IDs to report missing ones
     const foundIds = new Set(notes.map((n) => n.id));

package/dist/tools/search-memories.d.ts

@@ -11,4 +11,7 @@ export declare function searchMemories(ctx: McpContext, input: {
     decayHalfLife?: number;
     diversity?: number;
     searchMode?: "auto" | "hybrid" | "bm25" | "semantic";
+    graphWeight?: number;
+    graphSeeds?: number;
+    graphMaxHops?: number;
 }): Promise<string>;

package/dist/tools/search-memories.js

@@ -12,13 +12,27 @@ import { applyImportanceBoostBatch } from "./importance-boost.js";
 import { applyConfidenceDampenBatch } from "./confidence-dampen.js";
 const FALLBACK_CONTENT_PREVIEW_CHARS = 500;
 const COMPACT_CONTENT_CHARS = 200;
+function buildSignalsMap(lists) {
+    const map = new Map();
+    for (const [signal, ids] of Object.entries(lists)) {
+        if (!ids)
+            continue;
+        for (const id of ids) {
+            const existing = map.get(id);
+            if (existing)
+                existing.push(signal);
+            else
+                map.set(id, [signal]);
+        }
+    }
+    return map;
+}
 // RRF signal weights
 const WEIGHT_SEMANTIC = 1.0;
 const WEIGHT_BM25 = 0.9;
 const WEIGHT_BLIND_INDEX = 0.4;
-const WEIGHT_GRAPH = 0.6;
-// Graph expansion: how many initial results to expand, and relation weights
-const GRAPH_EXPAND_TOP_N = 5;
+// WEIGHT_GRAPH and GRAPH_EXPAND_TOP_N are now configurable via input params (defaults applied inline)
+// Graph relation weights for scoring neighbor relevance
 const GRAPH_RELATION_WEIGHTS = {
     refines: 1.0,
     derived_from: 0.9,
@@ -90,6 +104,7 @@ export async function searchMemories(ctx, input) {
                 supersededById: m.superseded_by_id,
                 entities: m.entities,
                 updatedAt: m.updated_at,
+                signals: ["entity"],
                 ...(attachmentLines.length > 0 ? { attachments: attachmentLines } : {}),
             };
         }));
@@ -187,30 +202,47 @@ export async function searchMemories(ctx, input) {
     await Promise.all([semanticPromise, blindPromise, bm25Promise]);
     // ── Signal 3: Graph expansion on top-N unique results from all signals ─
     const graphIds = [];
-    const initialHits = new Set([...semanticIds, ...blindIds, ...bm25Ids]);
-    const seedIds = [...initialHits].slice(0, GRAPH_EXPAND_TOP_N);
-    if (seedIds.length > 0) {
-        try {
-            const graphResults = await Promise.all(seedIds.map((id) => getKnowledgeGraph(ctx.supabase, ctx.userId, "memory", id, 1, 10)));
-            // Collect neighbor memory IDs ranked by relation weight
-            const neighborScores = new Map();
-            for (const neighbors of graphResults) {
-                for (const n of neighbors) {
-                    if (n.node_type !== "memory" || initialHits.has(n.node_id))
-                        continue;
-                    const weight = GRAPH_RELATION_WEIGHTS[n.relation] ?? 0.5;
-                    const current = neighborScores.get(n.node_id) ?? 0;
-                    neighborScores.set(n.node_id, Math.max(current, weight));
+    const graphWeight = input.graphWeight ?? 0.6;
+    // Graph expansion — skip entirely when graphWeight=0
+    if (graphWeight > 0) {
+        const initialHits = new Set([...semanticIds, ...blindIds, ...bm25Ids]);
+        const graphSeedCount = input.graphSeeds ?? 5;
+        const seedIds = [...initialHits].slice(0, graphSeedCount);
+        if (seedIds.length > 0) {
+            try {
+                const graphMaxHops = input.graphMaxHops ?? 1;
+                const maxNodesPerSeed = graphMaxHops >= 2 ? 25 : 10;
+                const graphResults = await Promise.all(seedIds.map((id) => getKnowledgeGraph(ctx.supabase, ctx.userId, "memory", id, graphMaxHops, maxNodesPerSeed)));
+                // Collect neighbor memory IDs ranked by relation weight
+                const neighborScores = new Map();
+                for (const neighbors of graphResults) {
+                    for (const n of neighbors) {
+                        if (n.node_type !== "memory")
+                            continue;
+                        // Only exclude seed IDs — allow boosting of already-found results (aligned with gateway)
+                        if (seedIds.includes(n.node_id))
+                            continue;
+                        const weight = GRAPH_RELATION_WEIGHTS[n.relation] ?? 0.5;
+                        const current = neighborScores.get(n.node_id) ?? 0;
+                        neighborScores.set(n.node_id, Math.max(current, weight));
+                    }
                 }
+                graphIds.push(...Array.from(neighborScores.entries())
+                    .sort((a, b) => b[1] - a[1])
+                    .map(([id]) => id));
+            }
+            catch (err) {
+                process.stderr.write(`[search-memories] Graph expansion error: ${err instanceof Error ? err.message : String(err)}\n`);
             }
-            graphIds.push(...Array.from(neighborScores.entries())
-                .sort((a, b) => b[1] - a[1])
-                .map(([id]) => id));
-        }
-        catch (err) {
-            process.stderr.write(`[search-memories] Graph expansion error: ${err instanceof Error ? err.message : String(err)}\n`);
         }
     }
+    // ── Signal attribution ──────────────────────────────────────────────
+    const signalsMap = buildSignalsMap({
+        semantic: semanticIds,
+        bm25: bm25Ids,
+        blind: blindIds,
+        graph: graphIds,
+    });
     // ── RRF Fusion + Temporal Decay ──────────────────────────────────────
     let rankedIds = [];
     let searchMode = "hybrid";
@@ -225,7 +257,7 @@ export async function searchMemories(ctx, input) {
         if (blindIds.length > 0)
             lists.push({ ids: blindIds, weight: WEIGHT_BLIND_INDEX });
         if (graphIds.length > 0)
-            lists.push({ ids: graphIds, weight: WEIGHT_GRAPH });
+            lists.push({ ids: graphIds, weight: graphWeight });
         // Get scored candidates — fetch topK*2 for decay re-ranking headroom, with top-rank bonus
         const rrfScored = fuseWithRRFScored(lists, 60, true).slice(0, topK * 2);
         searchMode = effectiveSearchMode === "bm25" ? "bm25"
@@ -336,6 +368,7 @@ export async function searchMemories(ctx, input) {
             supersededById: m.superseded_by_id,
             entities: m.entities,
             updatedAt: m.updated_at,
+            signals: signalsMap.get(m.id) ?? [],
             ...(attachmentLines.length > 0 ? { attachments: attachmentLines } : {}),
         };
     }));

package/dist/tools/search-notes.d.ts

@@ -1,4 +1,13 @@
 import type { McpContext } from "../auth.js";
+/**
+ * Direct-mode note search: keyword matching via blind-index pre-filter (when mekHex
+ * is available) or full client-side scan. Scores by weighted term frequency
+ * (title 3x, tags 2x, content 1x).
+ *
+ * NOTE: `searchMode`, `threshold`, and `diversity` are accepted for API compatibility
+ * but are IGNORED in direct mode. Hybrid/semantic/graph search modes and MMR
+ * diversity re-ranking require gateway mode (POST /api/agent/search-notes).
+ */
 export declare function searchNotes(ctx: McpContext, input: {
     query: string;
     topK?: number;

package/dist/tools/search-notes.js

@@ -42,6 +42,15 @@ function scoreNote(terms, title, tags, content) {
 }
 const COMPACT_PREVIEW_CHARS = 200;
 const FULL_PREVIEW_CHARS = 500;
+/**
+ * Direct-mode note search: keyword matching via blind-index pre-filter (when mekHex
+ * is available) or full client-side scan. Scores by weighted term frequency
+ * (title 3x, tags 2x, content 1x).
+ *
+ * NOTE: `searchMode`, `threshold`, and `diversity` are accepted for API compatibility
+ * but are IGNORED in direct mode. Hybrid/semantic/graph search modes and MMR
+ * diversity re-ranking require gateway mode (POST /api/agent/search-notes).
+ */
 export async function searchNotes(ctx, input) {
     const topK = input.topK ?? 10;
     const vaultId = input.vaultId;

package/dist/tools/search.d.ts

@@ -1,4 +1,5 @@
 import type { McpContext } from "../auth.js";
+import { GatewayClient } from "../gateway-client.js";
 interface SearchParams {
     query: string;
     topK?: number;
@@ -7,7 +8,6 @@ interface SearchParams {
     diversity?: number;
     vaultId?: string;
     includeContent?: boolean;
-    compact?: boolean;
     scope?: "all" | "memories" | "notes";
     memoryType?: string;
     includeArchived?: boolean;
@@ -16,12 +16,13 @@ interface SearchParams {
 /**
  * Universal search tool — searches memories, notes, or both.
  *
- * In direct mode: best-effort — calls searchMemories and/or searchNotes
- * independently and interleaves results (no cross-type MMR).
+ * In gateway mode: delegates to POST /api/agent/search which performs full
+ * cross-type MMR re-ranking server-side (hybrid semantic + keyword, all modes).
  *
- * Note: In gateway mode, the MCP server's `search` tool registration in index.ts
- * delegates to the gateway `/api/agent/search` endpoint which performs full
- * cross-type MMR re-ranking server-side. This function is only used in direct mode.
+ * In direct mode: best-effort — calls searchMemories and/or searchNotes
+ * independently and interleaves results (no cross-type MMR). searchMode,
+ * threshold, and diversity are passed through but only partially honoured
+ * (notes fall back to keyword+blind-index only; see searchNotes).
  */
-export declare function search(ctx: McpContext, params: SearchParams): Promise<string>;
+export declare function search(ctx: McpContext, params: SearchParams, gw?: GatewayClient): Promise<string>;
 export {};

package/dist/tools/search.js

@@ -3,14 +3,19 @@ import { searchNotes } from "./search-notes.js";
 /**
  * Universal search tool — searches memories, notes, or both.
  *
- * In direct mode: best-effort — calls searchMemories and/or searchNotes
- * independently and interleaves results (no cross-type MMR).
+ * In gateway mode: delegates to POST /api/agent/search which performs full
+ * cross-type MMR re-ranking server-side (hybrid semantic + keyword, all modes).
  *
- * Note: In gateway mode, the MCP server's `search` tool registration in index.ts
- * delegates to the gateway `/api/agent/search` endpoint which performs full
- * cross-type MMR re-ranking server-side. This function is only used in direct mode.
+ * In direct mode: best-effort — calls searchMemories and/or searchNotes
+ * independently and interleaves results (no cross-type MMR). searchMode,
+ * threshold, and diversity are passed through but only partially honoured
+ * (notes fall back to keyword+blind-index only; see searchNotes).
  */
-export async function search(ctx, params) {
+export async function search(ctx, params, gw) {
+    // Gateway mode: full cross-type MMR re-ranking server-side
+    if (gw) {
+        return gw.search(params);
+    }
     const scope = params.scope ?? "all";
     const topK = params.topK ?? 10;
     const searchMemoriesParams = {
@@ -20,7 +25,6 @@ export async function search(ctx, params) {
         vaultId: params.vaultId,
         memoryType: params.memoryType,
         includeArchived: params.includeArchived,
-        compact: params.compact,
         decayHalfLife: params.decayHalfLife,
         diversity: params.diversity,
         searchMode: params.searchMode,
@@ -33,7 +37,6 @@ export async function search(ctx, params) {
         diversity: params.diversity,
         vaultId: params.vaultId,
         includeContent: params.includeContent,
-        compact: params.compact,
     };
     try {
         if (scope === "memories") {

package/dist/tools/view-media.d.ts

@@ -0,0 +1,6 @@
+import type { McpContext } from "../auth.js";
+/**
+ * View a media attachment intelligently.
+ * Direct mode: returns extracted text only (no storage access).
+ */
+export declare function viewMedia(ctx: McpContext, attachmentId: string): Promise<string>;

package/dist/tools/view-media.js

@@ -0,0 +1,53 @@
+/**
+ * View a media attachment intelligently.
+ * Direct mode: returns extracted text only (no storage access).
+ */
+export async function viewMedia(ctx, attachmentId) {
+    const { data, error } = await ctx.supabase
+        .from("media_attachments")
+        .select("id, memory_id, note_id, vault_id, modality, mime_type, file_name, file_size_bytes, embedding_status, extraction_status, extracted_text, extracted_text_iv")
+        .eq("id", attachmentId)
+        .eq("user_id", ctx.userId)
+        .maybeSingle();
+    if (error)
+        return JSON.stringify({ error: "Failed to fetch attachment" });
+    if (!data)
+        return JSON.stringify({ error: "Attachment not found" });
+    let extractedText = null;
+    if (data.extracted_text && data.extracted_text_iv && ctx.masterKey) {
+        const { decrypt } = await import("../crypto.js");
+        try {
+            extractedText = await decrypt(data.extracted_text, data.extracted_text_iv, ctx.masterKey);
+        }
+        catch {
+            extractedText = null;
+        }
+    }
+    let contentNote = null;
+    if (data.modality === "image") {
+        contentNote = "base64 unavailable in direct mode — use gateway mode or download_media";
+    }
+    else {
+        const label = data.modality.charAt(0).toUpperCase() + data.modality.slice(1);
+        const verb = (data.modality === "audio" || data.modality === "video") ? "transcription" : "extracted text";
+        contentNote = `${label} — returning ${verb}. Use download_media for raw bytes.`;
+    }
+    if (!extractedText && data.extraction_status !== "completed") {
+        const note = `Extraction ${data.extraction_status} — no text content available yet.`;
+        contentNote = contentNote ? `${contentNote} ${note}` : note;
+    }
+    return JSON.stringify({
+        attachmentId: data.id,
+        memoryId: data.memory_id,
+        noteId: data.note_id,
+        modality: data.modality,
+        mimeType: data.mime_type,
+        fileName: data.file_name,
+        fileSizeBytes: data.file_size_bytes,
+        embeddingStatus: data.embedding_status,
+        extractionStatus: data.extraction_status,
+        extractedText,
+        base64Content: null,
+        contentNote,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exovault-mcp-server",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "MCP server for ExoVault — read, search, and manage encrypted notes from Claude Code",
   "main": "dist/index.js",