exovault-mcp-server 1.3.0 → 1.4.0

package/dist/gateway-client.d.ts

@@ -69,7 +69,7 @@ export declare class GatewayClient {
         graphSeeds?: number;
         graphMaxHops?: number;
     }): Promise<string>;
-    readMemories(memoryIds: string[]): Promise<string>;
+    readMemories(memoryIds: string[], includeMediaContent?: boolean): Promise<string>;
     updateMemory(params: {
         memoryId: string;
         content?: string;
@@ -136,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;
@@ -344,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", {
@@ -646,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", {
@@ -1260,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/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.3.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",