@pairsystems/goodmem-mcp 0.1.14 → 0.1.16

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
@@ -208,11 +210,12 @@ Memory spaces are containers that associate a set of memories with an embedder.
 | Tool | Description |
 |------|-------------|
 | `goodmem_admin_background_jobs_purge` | Purge completed background jobs |
-| `goodmem_admin_delete` | Delete a RetrieveMemory log policy |
 | `goodmem_admin_drain` | Request the server to enter drain mode |
-| `goodmem_admin_get` | Get a RetrieveMemory log policy |
 | `goodmem_admin_license_reload` | Reload the active license from disk |
-| `goodmem_admin_retrieve_memory_log_policies` | List RetrieveMemory log policies |
+| `goodmem_admin_retrieve_memory_log_policies_create` | Create a RetrieveMemory log policy |
+| `goodmem_admin_retrieve_memory_log_policies_delete` | Delete a RetrieveMemory log policy |
+| `goodmem_admin_retrieve_memory_log_policies_get` | Get a RetrieveMemory log policy |
+| `goodmem_admin_retrieve_memory_log_policies_list` | List RetrieveMemory log policies |
 
 ### Ping
 
@@ -222,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.
@@ -246,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 = "b5f17ba5a019b3b11860f70609a994b6d2ade6ad";
 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.14"
+  version: "0.1.16"
 });
 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.14",
+    mcp_version: "0.1.16",
     based_on_goodmem_commit: BASED_ON_GOODMEM_COMMIT
   }, null, 2) }] };
 });
@@ -21948,19 +21981,6 @@ function registerTools() {
     const result = await callApi("POST", `/v1/admin/background-jobs:purge`, body);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   });
-  server.tool("goodmem_admin_delete", "Delete a RetrieveMemory log policy\n\nIdempotently tombstones an immutable RetrieveMemory log policy.", {
-    id: external_exports.string().describe("The UUID of the policy to delete"),
-    reason: external_exports.string().describe("Optional tombstone reason.").optional()
-  }, async (args) => {
-    if (typeof args.id !== "string" || args.id === "") {
-      throw new Error("'id' must be a non-empty string");
-    }
-    const body = {};
-    if (args.reason !== void 0)
-      body["reason"] = args.reason;
-    await callApi("DELETE", `/v1/admin/retrieve-memory-log-policies/${encodeURIComponent(String(args.id))}`, body);
-    return { content: [{ type: "text", text: "Deleted successfully." }] };
-  });
   server.tool("goodmem_admin_drain", "Request the server to enter drain mode\n\nInitiates drain mode and optionally waits for the server to quiesce.", {
     timeout_sec: external_exports.number().int().describe("Maximum seconds to wait for the server to quiesce before returning.").optional(),
     reason: external_exports.string().describe("Human-readable reason for initiating drain mode.").optional(),
@@ -21976,7 +21996,60 @@ function registerTools() {
     const result = await callApi("POST", `/v1/admin:drain`, body, void 0, ((args.timeout_sec ?? 900) + 30) * 1e3);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   });
-  server.tool("goodmem_admin_get", "Get a RetrieveMemory log policy\n\nRetrieves a live RetrieveMemory log policy by UUID, or a tombstoned policy when include_deleted is true.", {
+  server.tool("goodmem_admin_license_reload", "Reload the active license from disk\n\nTriggers the server to reload its license file from the configured directory and returns metadata about the currently active license.", {}, async (args) => {
+    const result = await callApi("POST", `/v1/admin/license:reload`, void 0);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  });
+  server.tool("goodmem_admin_retrieve_memory_log_policies_create", "Create a RetrieveMemory log policy\n\nCreates an immutable administrative policy that can automatically enable durable RetrieveMemory request logging.", {
+    policy_id: external_exports.string().describe("Optional client-provided policy UUID.").optional(),
+    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. 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 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(),
+    labels: external_exports.record(external_exports.string(), external_exports.string()).describe("Operator labels for listing and administration.").optional()
+  }, async (args) => {
+    const body = {};
+    if (args.policy_id !== void 0)
+      body["policyId"] = args.policy_id;
+    if (args.display_name !== void 0)
+      body["displayName"] = args.display_name;
+    if (args.description !== void 0)
+      body["description"] = args.description;
+    if (args.condition !== void 0)
+      body["condition"] = args.condition;
+    if (args.active_from !== void 0)
+      body["activeFrom"] = args.active_from;
+    if (args.active_until !== void 0)
+      body["activeUntil"] = args.active_until;
+    if (args.labels !== void 0)
+      body["labels"] = args.labels;
+    const result = await callApi("POST", `/v1/admin/retrieve-memory-log-policies`, body);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  });
+  server.tool("goodmem_admin_retrieve_memory_log_policies_delete", "Delete a RetrieveMemory log policy\n\nIdempotently tombstones an immutable RetrieveMemory log policy.", {
+    id: external_exports.string().describe("The UUID of the policy to delete"),
+    reason: external_exports.string().describe("Optional tombstone reason.").optional()
+  }, async (args) => {
+    if (typeof args.id !== "string" || args.id === "") {
+      throw new Error("'id' must be a non-empty string");
+    }
+    const body = {};
+    if (args.reason !== void 0)
+      body["reason"] = args.reason;
+    await callApi("DELETE", `/v1/admin/retrieve-memory-log-policies/${encodeURIComponent(String(args.id))}`, body);
+    return { content: [{ type: "text", text: "Deleted successfully." }] };
+  });
+  server.tool("goodmem_admin_retrieve_memory_log_policies_get", "Get a RetrieveMemory log policy\n\nRetrieves a live RetrieveMemory log policy by UUID, or a tombstoned policy when include_deleted is true.", {
     id: external_exports.string().describe("The UUID of the policy to retrieve"),
     include_deleted: external_exports.boolean().describe("Whether to include tombstoned policies. Also accepts include_deleted.").optional()
   }, async (args) => {
@@ -21989,11 +22062,7 @@ function registerTools() {
     const result = await callApi("GET", `/v1/admin/retrieve-memory-log-policies/${encodeURIComponent(String(args.id))}`, void 0, query);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   });
-  server.tool("goodmem_admin_license_reload", "Reload the active license from disk\n\nTriggers the server to reload its license file from the configured directory and returns metadata about the currently active license.", {}, async (args) => {
-    const result = await callApi("POST", `/v1/admin/license:reload`, void 0);
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-  });
-  server.tool("goodmem_admin_retrieve_memory_log_policies", "List RetrieveMemory log policies\n\nLists RetrieveMemory log policies with optional tombstone, active-time, name, label, sort, and pagination filters. LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).", {
+  server.tool("goodmem_admin_retrieve_memory_log_policies_list", "List RetrieveMemory log policies\n\nLists RetrieveMemory log policies with optional tombstone, active-time, name, label, sort, and pagination filters. LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).", {
     include_deleted: external_exports.boolean().describe("Whether to include tombstoned policies. Also accepts include_deleted.").optional(),
     name_filter: external_exports.string().describe("Case-insensitive substring filter on policy display names. Also accepts name_filter.").optional(),
     active_at: external_exports.number().int().describe("Only return policies active at this millisecond epoch timestamp. Also accepts active_at.").optional(),
@@ -22550,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"),
@@ -22696,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({

package/package.json

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