fix(mcp): keep binary reads and large pages client-safe (#133)

## Summary
- treat binary Vana envelopes as binary metadata in bounded blocks
instead of indexing base64 content
- reduce default read_scope page size to 64 KiB while preserving
explicit larger maxBytes and nextCursor paging
- avoid duplicating large MCP tool results into structuredContent
- return only canonical search results, not a duplicate matches alias

## Validation
- npm test -- packages/core/src/storage/blocks/build.test.ts
packages/core/src/mcp/tools.test.ts
- npm run lint
- npm run build

Author: tnunamak

package-lock.json

@@ -126,8 +126,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opendatalabs/vana-sdk": "^3.4.0",
+    "@opendatalabs/vana-sdk": "^3.4.1",
     "minisearch": "^7.2.0",
+    "unpdf": "^1.6.2",
     "viem": "^2.48.11",
     "zod": "^4.4.3"
   }

packages/core/package.json

@@ -6,7 +6,7 @@ import {
 } from "@opendatalabs/vana-sdk/browser";
 import { type WriteResult } from "../storage/hierarchy/index.js";
 import { buildBinaryEnvelopeData, sha256Hex } from "./binary.js";
-import { buildDataBlocks } from "../storage/blocks/build.js";
+import { buildDataBlocksAsync } from "../storage/blocks/build.js";
 
 export type DataContractErrorCode =
   | "INVALID_SCOPE"
@@ -402,7 +402,7 @@ async function writeBlockSidecars(
 ): Promise<void> {
   if (!storage.writeBlockManifest) return;
 
-  const built = buildDataBlocks({
+  const built = await buildDataBlocksAsync({
     scope: envelope.scope,
     collectedAt: envelope.collectedAt,
     schemaId: envelope.schemaId,

packages/core/src/contracts/data.ts

@@ -250,6 +250,50 @@ describe("mcp/tools", () => {
     });
   });
 
+  it("read_scope defaults to a client-safe page and does not duplicate large payloads", async () => {
+    const readClient = createMinimalReadClient({
+      readScopeBlocks: vi.fn().mockResolvedValue({
+        scope: "instagram.profile",
+        collectedAt: "2026-06-05T00:00:00Z",
+        contentKind: "json",
+        blocks: [
+          {
+            id: "b1",
+            path: "$.large",
+            mediaType: "application/json",
+            value: { text: "x".repeat(70 * 1024) },
+            sizeBytes: 70 * 1024,
+          },
+        ],
+        nextCursor: "cursor-2",
+        warnings: [],
+      }),
+    });
+
+    const result = await getTool("read_scope").handler(
+      { scope: "instagram.profile" },
+      {
+        connection: createConnection(),
+        readClient: readClient as never,
+      },
+    );
+
+    expect(readClient.readScopeBlocks).toHaveBeenCalledWith(
+      expect.objectContaining({
+        scope: "instagram.profile",
+        maxBytes: 64 * 1024,
+      }),
+    );
+    expect(JSON.parse(result.content[0].text)).toMatchObject({
+      nextCursor: "cursor-2",
+      page: {
+        hasMore: true,
+        maxBytes: 64 * 1024,
+      },
+    });
+    expect(result.structuredContent).toBeUndefined();
+  });
+
   it("read_scope attaches search guidance for large scopes and omits it for small ones", async () => {
     const block = {
       id: "b1",

packages/core/src/mcp/tools.test.ts

@@ -54,9 +54,16 @@ export interface McpToolDefinition {
   ): Promise<McpToolResult>;
 }
 
+const STRUCTURED_CONTENT_TEXT_LIMIT_BYTES = 64 * 1024;
+const resultTextEncoder = new TextEncoder();
+
 function textResult(value: unknown, isError = false): McpToolResult {
+  const text =
+    typeof value === "string" ? value : JSON.stringify(value, null, 2);
+  const textBytes = resultTextEncoder.encode(text).byteLength;
   const structuredContent =
     !isError &&
+    textBytes <= STRUCTURED_CONTENT_TEXT_LIMIT_BYTES &&
     typeof value === "object" &&
     value !== null &&
     !Array.isArray(value)
@@ -66,8 +73,7 @@ function textResult(value: unknown, isError = false): McpToolResult {
     content: [
       {
         type: "text",
-        text:
-          typeof value === "string" ? value : JSON.stringify(value, null, 2),
+        text,
       },
     ],
     ...(structuredContent ? { structuredContent } : {}),
@@ -110,7 +116,7 @@ const DEFAULT_SEARCH_TIMEOUT_MS = 30_000;
 const MAX_SEARCH_TIMEOUT_MS = 300_000;
 const DEFAULT_SEARCH_DISCOVERY_TIMEOUT_MS = 2_000;
 const MAX_SEARCH_TOTAL_TIMEOUT_MS = 300_000;
-const DEFAULT_READ_SCOPE_MAX_BYTES = 256 * 1024;
+const DEFAULT_READ_SCOPE_MAX_BYTES = 64 * 1024;
 const MAX_READ_SCOPE_MAX_BYTES = 5 * 1024 * 1024;
 const DEFAULT_READ_SCOPE_TIMEOUT_MS = 60_000;
 const MAX_READ_SCOPE_TIMEOUT_MS = 300_000;
@@ -1135,6 +1141,8 @@ const searchPersonalContext: McpToolDefinition = {
     return textResult({
       query,
       results: matches,
+      // Backward-compatible alias for existing clients/tests. `results` is the
+      // canonical field, but removing `matches` is a separate migration.
       matches,
       searchedScopes,
       skippedScopes: [

packages/core/src/mcp/tools.ts

@@ -1,7 +1,23 @@
-import { describe, expect, it } from "vitest";
-import { buildDataBlocks, type DataBlockPayload } from "./build.js";
+import { extractText } from "unpdf";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { buildBinaryEnvelopeData } from "../../contracts/binary.js";
+import {
+  buildDataBlocks,
+  buildDataBlocksAsync,
+  type DataBlockPayload,
+} from "./build.js";
+
+vi.mock("unpdf", () => ({
+  extractText: vi.fn(),
+}));
+
+const extractTextMock = vi.mocked(extractText);
 
 describe("buildDataBlocks", () => {
+  beforeEach(() => {
+    extractTextMock.mockReset();
+  });
+
   it("classifies Vana envelopes and emits metadata plus complete data blocks", () => {
     const envelope = {
       scope: "test.scope",
@@ -179,6 +195,126 @@ describe("buildDataBlocks", () => {
     expect(zip.manifest.contentKind).toBe("zip");
     expect(zip.manifest.warnings[0]?.code).toBe("zip_metadata_only");
   });
+
+  it("represents binary Vana envelopes as metadata without indexing base64 content", () => {
+    const binaryData = buildBinaryEnvelopeData({
+      bytes: new Uint8Array([0x25, 0x50, 0x44, 0x46, 0x2d, 0x31]),
+      mimeType: "application/pdf",
+      filename: "roof-report.pdf",
+      contentHash: `0x${"a".repeat(64)}`,
+      metadata: { title: "Roof report" },
+    });
+    const result = buildDataBlocks({
+      scope: "manual.document",
+      collectedAt: "2026-06-09T16:28:09Z",
+      content: {
+        scope: "manual.document",
+        collectedAt: "2026-06-09T16:28:09Z",
+        schemaId: "schema-1",
+        data: binaryData,
+      },
+    });
+
+    expect(result.manifest.contentKind).toBe("binary");
+    expect(result.manifest.warnings[0]?.code).toBe("binary_metadata_only");
+    expect(result.blocks).toHaveLength(2);
+    expect(result.blocks[0]?.path).toBe("$.__envelope");
+    expect(result.blocks[1]).toMatchObject({
+      path: "$.data",
+      mediaType: "application/json",
+      value: {
+        contentKind: "binary",
+        mimeType: "application/pdf",
+        filename: "roof-report.pdf",
+        sizeBytes: 6,
+        contentHash: `0x${"a".repeat(64)}`,
+        metadata: { title: "Roof report" },
+        searchable: false,
+        rawContentAvailable: true,
+      },
+    });
+    expect(JSON.stringify(result.blocks)).not.toContain(binaryData.content);
+  });
+
+  it("extracts searchable PDF text from binary Vana envelopes without indexing base64 content", async () => {
+    extractTextMock.mockResolvedValueOnce({
+      totalPages: 1,
+      text: "Roof report\r\nDEXA scan summary\n",
+    });
+    const binaryData = buildBinaryEnvelopeData({
+      bytes: new Uint8Array([0x25, 0x50, 0x44, 0x46, 0x2d, 0x31]),
+      mimeType: "application/pdf",
+      filename: "roof-report.pdf",
+      contentHash: `0x${"b".repeat(64)}`,
+      metadata: { title: "Roof report" },
+    });
+    const result = await buildDataBlocksAsync({
+      scope: "manual.document",
+      collectedAt: "2026-06-09T16:28:09Z",
+      content: {
+        scope: "manual.document",
+        collectedAt: "2026-06-09T16:28:09Z",
+        schemaId: "schema-1",
+        data: binaryData,
+      },
+      blockTargetBytes: 40,
+      maxBlockBytes: 120,
+    });
+
+    const metadataBlock = result.blocks.find(
+      (block) => block.path === "$.data",
+    );
+    const textBlocks = result.blocks.filter((block) =>
+      block.path.startsWith("$.data.text"),
+    );
+    expect(result.manifest.contentKind).toBe("binary");
+    expect(metadataBlock).toMatchObject({
+      mediaType: "application/json",
+      value: {
+        contentKind: "binary",
+        searchable: true,
+        extractedTextAvailable: true,
+        rawContentAvailable: true,
+      },
+    });
+    expect(rebuildString(textBlocks, "$.data.text")).toBe(
+      "Roof report\nDEXA scan summary",
+    );
+    expect(
+      result.manifest.warnings.map((warning) => warning.code),
+    ).not.toContain("binary_metadata_only");
+    expect(JSON.stringify(result.blocks)).not.toContain(binaryData.content);
+    expect(extractTextMock).toHaveBeenCalledTimes(1);
+    expect(extractTextMock.mock.calls[0]?.[0]).toBeInstanceOf(Uint8Array);
+  });
+
+  it("falls back to binary metadata when PDF text extraction fails", async () => {
+    extractTextMock.mockRejectedValueOnce(new Error("invalid pdf"));
+    const binaryData = buildBinaryEnvelopeData({
+      bytes: new Uint8Array([0x25, 0x50, 0x44, 0x46, 0x2d, 0x31]),
+      mimeType: "application/pdf",
+      filename: "broken.pdf",
+      contentHash: `0x${"c".repeat(64)}`,
+    });
+    const result = await buildDataBlocksAsync({
+      scope: "manual.document",
+      collectedAt: "2026-06-09T16:28:09Z",
+      content: {
+        scope: "manual.document",
+        collectedAt: "2026-06-09T16:28:09Z",
+        data: binaryData,
+      },
+    });
+
+    expect(
+      result.blocks.some((block) => block.path.startsWith("$.data.text")),
+    ).toBe(false);
+    expect(result.manifest.warnings.map((warning) => warning.code)).toEqual([
+      "binary_metadata_only",
+      "pdf_text_extraction_failed",
+    ]);
+    expect(JSON.stringify(result.blocks)).not.toContain(binaryData.content);
+  });
 });
 
 function rebuildArray(blocks: DataBlockPayload[], path: string): unknown[] {