@pairsystems/goodmem-mcp 0.1.15 → 0.1.17

package/README.md

@@ -167,11 +167,13 @@ Memory spaces are containers that associate a set of memories with an embedder.
 | `goodmem_memories_batch_create` | Create multiple memories in a batch |
 | `goodmem_memories_batch_delete` | Delete memories in batch |
 | `goodmem_memories_batch_get` | Get multiple memories by ID |
+| `goodmem_memories_content` | Download memory content |
 | `goodmem_memories_create` | Create a new memory |
 | `goodmem_memories_delete` | Delete a memory |
 | `goodmem_memories_get` | Get a memory by ID |
 | `goodmem_memories_list` | List memories in a space |
 | `goodmem_memories_pages` | List memory page images |
+| `goodmem_memories_pages_image` | Download memory page image content |
 | `goodmem_memories_retrieve` | Advanced semantic memory retrieval with JSON |
 
 ### OCR
@@ -223,6 +225,45 @@ Memory spaces are containers that associate a set of memories with an embedder.
 | `goodmem_ping_stream` | Stream ping probe results |
 
 <!-- AUTO-GENERATED MCP TOOL TABLE END -->
+## Binary content delivery
+
+Two memory tools return raw binary payloads:
+
+- `goodmem_memories_content` — original ingested bytes (text, image, PDF, …)
+- `goodmem_memories_pages_image` — one rendered page image as bytes
+
+The MCP server wraps the response in the appropriate MCP content block
+based on the response MIME type:
+
+| Server `Content-Type` | MCP block | What the agent gets |
+|---|---|---|
+| `image/*` | `image` block | base64 data + `mimeType`; Claude reads as vision input. |
+| `text/*`, `application/json` | embedded `resource` with `text` | MIME-signaled text — preserves `text/markdown`, `text/x-python`, etc. |
+| anything else (PDF, octet-stream, …) | embedded `resource` with `blob` | base64 blob + `mimeType`. Forward-compatible; current Claude models cannot natively render PDF bytes from an MCP block. |
+
+### Size cap
+
+Both tools accept an optional `max_inline_bytes` parameter (units:
+bytes) so the agent can self-limit per call:
+
+| Knob | Value | Notes |
+|---|---|---|
+| **Hard server ceiling** | 64 MB (67,108,864 bytes) | Baked into the MCP server source. Above this, the tool always errors regardless of `max_inline_bytes`. |
+| **Default cap** | 8 MB (8,388,608 bytes) | Used when the agent doesn't pass `max_inline_bytes`. |
+| **Per-call override** | `max_inline_bytes` argument | The agent can raise it up to the hard ceiling, or lower it for tighter context-budget control. |
+
+When the payload exceeds the effective cap, the tool throws an error
+naming both the actual size and the ceiling — the agent can read the
+error, retry with a larger `max_inline_bytes`, and succeed. Above the
+hard ceiling, the only path is to fetch the content via REST directly
+(`GET /v1/memories/{id}/content` or `/pages/{idx}/image`) rather than
+through MCP.
+
+These constants are not currently configurable via environment
+variables. If you need to tune them per deployment, edit
+`_clients_gen/mcp/emitter.py` (`ABSOLUTE_MAX_INLINE_BYTES`,
+`DEFAULT_MAX_INLINE_BYTES`) and regenerate.
+
 ## Auto-inference
 
 When creating embedders, LLMs, or rerankers, provide `model_identifier` and the MCP server fills in `provider_type`, `endpoint_url`, dimensions, and other fields automatically from the built-in registry of 79 models. Inference happens client-side in the MCP layer before the request is sent.
@@ -247,3 +288,4 @@ For self-hosted or local providers (vLLM, TEI, Ollama, custom endpoints), creden
 - [GoodMem on GitHub](https://github.com/PAIR-Systems-Inc/goodmem)
 - [Python SDK on PyPI](https://pypi.org/project/goodmem/)
 - [Claude Code Plugin](https://github.com/PAIR-Systems-Inc/goodmem-claude-code-plugin)
+

package/dist/index.js

@@ -20988,7 +20988,7 @@ var StdioServerTransport = class {
 // dist/index.js
 var goodmemBaseUrl = process.env.GOODMEM_BASE_URL || "";
 var goodmemApiKey = process.env.GOODMEM_API_KEY || "";
-var BASED_ON_GOODMEM_COMMIT = "62c6d77befdfab1bfe38ef917c6a202f4569eec7";
+var BASED_ON_GOODMEM_COMMIT = "d15028640e4a884f3a648db9b25aee4cdfab719d";
 function isConfigured() {
   return goodmemBaseUrl !== "";
 }
@@ -21002,6 +21002,8 @@ function _buildUrl(base, path) {
   return baseUrl;
 }
 var DEFAULT_TIMEOUT_MS = 6e4;
+var ABSOLUTE_MAX_INLINE_BYTES = 67108864;
+var DEFAULT_MAX_INLINE_BYTES = 8388608;
 function _trimBody(text) {
   return text.length > 500 ? text.slice(0, 500) + "...[truncated]" : text;
 }
@@ -21044,6 +21046,37 @@ async function callApi(method, path, body, query, timeoutMs) {
   }
   return resp.text();
 }
+async function callApiBinary(method, path, query, timeoutMs) {
+  if (!isConfigured()) {
+    throw new Error("GoodMem is not configured. Call the goodmem_configure tool first with your base_url and api_key, or set GOODMEM_BASE_URL and GOODMEM_API_KEY environment variables.");
+  }
+  const url = _buildUrl(goodmemBaseUrl, path);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== void 0 && v !== null && v !== "")
+        url.searchParams.set(k, v);
+    }
+  }
+  const headers = {};
+  if (goodmemApiKey !== "") {
+    headers["x-api-key"] = goodmemApiKey;
+  }
+  const resp = await fetch(url.toString(), {
+    method,
+    headers,
+    signal: AbortSignal.timeout(timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    // See callApi for the redirect-policy rationale.
+    redirect: "error"
+  });
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`GoodMem API error ${resp.status}: ${_trimBody(text)}`);
+  }
+  const buf = await resp.arrayBuffer();
+  const bytes = new Uint8Array(buf);
+  const mimeType = (resp.headers.get("content-type") || "application/octet-stream").split(";")[0].trim();
+  return { bytes, mimeType, sizeBytes: bytes.byteLength };
+}
 async function callApiNdjson(method, path, body, query, timeoutSec) {
   if (!isConfigured()) {
     throw new Error("GoodMem is not configured. Call the goodmem_configure tool first with your base_url and api_key, or set GOODMEM_BASE_URL and GOODMEM_API_KEY environment variables.");
@@ -21843,7 +21876,7 @@ function autoInferFromRegistry(registryType, args) {
 }
 var server = new McpServer({
   name: "goodmem",
-  version: "0.1.15"
+  version: "0.1.17"
 });
 server.tool("goodmem_configure", "Configure GoodMem server connection. Call this before using other GoodMem tools if GOODMEM_BASE_URL and GOODMEM_API_KEY environment variables are not set. Session credentials override environment variables. For bootstrap workflows that need to call /v1/system/info or /v1/system/init before keys exist, api_key may be omitted; most other tools will return AuthenticationException until a real key is provided.", {
   base_url: external_exports.string().describe("GoodMem server URL (e.g., https://your-server.example.com)"),
@@ -21925,7 +21958,7 @@ ${allModels.join("\n")}` }] };
 });
 server.tool("goodmem_client_info", "Return the MCP client package version and the goodmem server commit it was built against. No server connection required.", {}, async () => {
   return { content: [{ type: "text", text: JSON.stringify({
-    mcp_version: "0.1.15",
+    mcp_version: "0.1.17",
     based_on_goodmem_commit: BASED_ON_GOODMEM_COMMIT
   }, null, 2) }] };
 });
@@ -21972,14 +22005,14 @@ function registerTools() {
     display_name: external_exports.string().describe("Human-readable policy name."),
     description: external_exports.string().describe("Optional operator description.").optional(),
     condition: external_exports.object({
-      matchAll: external_exports.boolean().describe("When true, match every authenticated RetrieveMemory request. Defaults to false when omitted.").optional(),
+      matchAll: external_exports.boolean().describe("When true, match every authenticated RetrieveMemory request. Must be omitted or false when anyOf contains clauses. Defaults to false when omitted.").optional(),
       anyOf: external_exports.array(external_exports.object({
         requestorUserIds: external_exports.array(external_exports.string()).describe("Authenticated requestor user UUID strings.").optional(),
         apiKeyIds: external_exports.array(external_exports.string()).describe("API key UUID strings used to authenticate RetrieveMemory requests.").optional(),
         spaceIds: external_exports.array(external_exports.string()).describe("Post-permission accessible space UUID strings.").optional(),
         apiKeyLabelSelectors: external_exports.record(external_exports.string(), external_exports.string()).describe("Exact API-key label selectors that must all match.").optional(),
         spaceLabelSelectors: external_exports.record(external_exports.string(), external_exports.string()).describe("Exact space label selectors that must match at least one accessible space.").optional()
-      }).passthrough()).describe("OR clauses used for scoped matching. Required when matchAll is false or omitted, and must contain at least one non-empty clause.").optional()
+      }).passthrough()).describe("OR clauses used for scoped matching. Required and non-empty when matchAll is false or omitted. Must be omitted or empty when matchAll is true. Each clause must include at least one match dimension.").optional()
     }).passthrough().describe("Policy match condition."),
     active_from: external_exports.number().int().describe("Inclusive activation time in milliseconds since epoch.").optional(),
     active_until: external_exports.number().int().describe("Exclusive deactivation time in milliseconds since epoch.").optional(),
@@ -22586,6 +22619,29 @@ function registerTools() {
     const result = await callApi("POST", `/v1/memories:batchGet`, body);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   });
+  server.tool("goodmem_memories_content", "Download memory content\n\nReturns the original binary payload for a memory. The response uses the memory's stored content type when available. Returns 404 when the memory does not have inline content; clients can check originalContentRef from the metadata endpoint to locate external content.", {
+    id: external_exports.string().describe("The UUID of the memory to download"),
+    max_inline_bytes: external_exports.number().int().positive().describe("Maximum bytes to deliver inline as a content block. Defaults to 8388608. Hard server ceiling: 67108864. If the payload exceeds this cap the tool errors with the actual size \u2014 retry with a larger value (up to the ceiling) to receive it.").optional()
+  }, async (args) => {
+    if (typeof args.id !== "string" || args.id === "") {
+      throw new Error("'id' must be a non-empty string");
+    }
+    const _cap = Math.min(args.max_inline_bytes ?? DEFAULT_MAX_INLINE_BYTES, ABSOLUTE_MAX_INLINE_BYTES);
+    const { bytes: _bytes, mimeType: _mimeType, sizeBytes: _sizeBytes } = await callApiBinary("GET", `/v1/memories/${encodeURIComponent(String(args.id))}/content`, void 0);
+    if (_sizeBytes > _cap) {
+      throw new Error(`Content is ${_sizeBytes} bytes, exceeded the inline cap of ${_cap} bytes (cap = min(max_inline_bytes ?? ${DEFAULT_MAX_INLINE_BYTES}, server absolute maximum ${ABSOLUTE_MAX_INLINE_BYTES})). Retry with max_inline_bytes=${_sizeBytes} or higher (up to ${ABSOLUTE_MAX_INLINE_BYTES}) to receive it inline.`);
+    }
+    const _uri = `goodmem://v1/memories/${encodeURIComponent(String(args.id))}/content`;
+    const _b64 = Buffer.from(_bytes).toString("base64");
+    if (_mimeType.startsWith("image/")) {
+      return { content: [{ type: "image", data: _b64, mimeType: _mimeType }] };
+    }
+    if (_mimeType.startsWith("text/") || _mimeType === "application/json") {
+      const _text = new TextDecoder("utf-8").decode(_bytes);
+      return { content: [{ type: "resource", resource: { uri: _uri, mimeType: _mimeType, text: _text } }] };
+    }
+    return { content: [{ type: "resource", resource: { uri: _uri, mimeType: _mimeType, blob: _b64 } }] };
+  });
   server.tool("goodmem_memories_create", "Create a memory from text content or base64-encoded binary content. Provide exactly one of `original_content` or `original_content_b64` per call; if `original_content_b64`, `content_type` is required. `original_content_ref` is a metadata URL pointer (the server does NOT fetch it) and may be set alongside the content source.", {
     memory_id: external_exports.string().describe("Optional client-provided UUID for the memory. If omitted, the server generates one. Returns ALREADY_EXISTS if the ID is already in use.").optional(),
     space_id: external_exports.string().describe("ID of the space where this memory will be stored"),
@@ -22732,6 +22788,40 @@ function registerTools() {
     const result = await callApi("GET", `/v1/memories/${encodeURIComponent(String(args.id))}/pages`, void 0, query);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   });
+  server.tool("goodmem_memories_pages_image", "Download memory page image content\n\nDownloads inline bytes for one page image. The page index is required. The optional dpi and content type query parameters act as rendition filters; if omitted, the server returns the unique rendition for that page or rejects ambiguous matches.", {
+    id: external_exports.string().describe("Memory UUID"),
+    page_index: external_exports.number().int().describe("0-based page index"),
+    dpi: external_exports.number().int().describe("Optional rendition filter. If omitted, the unique page-image rendition for the page is returned; if multiple renditions exist, specify dpi and/or content_type.").optional(),
+    content_type: external_exports.string().describe("Optional rendition filter. MIME type of the desired page image, such as image/png.").optional(),
+    max_inline_bytes: external_exports.number().int().positive().describe("Maximum bytes to deliver inline as a content block. Defaults to 8388608. Hard server ceiling: 67108864. If the payload exceeds this cap the tool errors with the actual size \u2014 retry with a larger value (up to the ceiling) to receive it.").optional()
+  }, async (args) => {
+    if (typeof args.id !== "string" || args.id === "") {
+      throw new Error("'id' must be a non-empty string");
+    }
+    if (typeof args.page_index !== "number" || !Number.isFinite(args.page_index)) {
+      throw new Error("'page_index' must be a finite number");
+    }
+    const query = {};
+    if (args.dpi !== void 0)
+      query["dpi"] = String(args.dpi);
+    if (args.content_type !== void 0)
+      query["contentType"] = String(args.content_type);
+    const _cap = Math.min(args.max_inline_bytes ?? DEFAULT_MAX_INLINE_BYTES, ABSOLUTE_MAX_INLINE_BYTES);
+    const { bytes: _bytes, mimeType: _mimeType, sizeBytes: _sizeBytes } = await callApiBinary("GET", `/v1/memories/${encodeURIComponent(String(args.id))}/pages/${encodeURIComponent(String(args.page_index))}/image`, query);
+    if (_sizeBytes > _cap) {
+      throw new Error(`Content is ${_sizeBytes} bytes, exceeded the inline cap of ${_cap} bytes (cap = min(max_inline_bytes ?? ${DEFAULT_MAX_INLINE_BYTES}, server absolute maximum ${ABSOLUTE_MAX_INLINE_BYTES})). Retry with max_inline_bytes=${_sizeBytes} or higher (up to ${ABSOLUTE_MAX_INLINE_BYTES}) to receive it inline.`);
+    }
+    const _uri = `goodmem://v1/memories/${encodeURIComponent(String(args.id))}/pages/${encodeURIComponent(String(args.page_index))}/image`;
+    const _b64 = Buffer.from(_bytes).toString("base64");
+    if (_mimeType.startsWith("image/")) {
+      return { content: [{ type: "image", data: _b64, mimeType: _mimeType }] };
+    }
+    if (_mimeType.startsWith("text/") || _mimeType === "application/json") {
+      const _text = new TextDecoder("utf-8").decode(_bytes);
+      return { content: [{ type: "resource", resource: { uri: _uri, mimeType: _mimeType, text: _text } }] };
+    }
+    return { content: [{ type: "resource", resource: { uri: _uri, mimeType: _mimeType, blob: _b64 } }] };
+  });
   server.tool("goodmem_memories_retrieve", "Performs a streaming semantic search across one or more memory spaces and returns matching chunks ranked by relevance as well as LLM-postprocessed results (like summarization, question-answering, etc.).", {
     message: external_exports.string().describe("Primary query/message for semantic search."),
     context: external_exports.array(external_exports.object({
@@ -23206,14 +23296,18 @@ async function healthCheck() {
   }
   try {
     const url = _buildUrl(goodmemBaseUrl, "/v1/system/info");
+    const healthHeaders = {};
+    if (goodmemApiKey !== "") {
+      healthHeaders["x-api-key"] = goodmemApiKey;
+    }
     const resp = await fetch(url.toString(), {
-      headers: { "x-api-key": goodmemApiKey },
+      headers: healthHeaders,
       signal: AbortSignal.timeout(1e4),
       // See callApi for the redirect-policy rationale.
       redirect: "error"
     });
     if (resp.ok) {
-      const info = await resp.json();
+      const info = await resp.json().catch(() => ({}));
       console.error(`[goodmem-mcp] Connected to ${goodmemBaseUrl} (server ${info.version ?? "unknown"}).`);
     } else {
       const text = await resp.text();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pairsystems/goodmem-mcp",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "GoodMem MCP server \u2014 exposes GoodMem API as MCP tools",
   "type": "module",
   "main": "dist/index.js",