@pairsystems/goodmem-mcp 0.1.1 → 0.1.3

package/README.md

@@ -1,44 +1,56 @@
 # @pairsystems/goodmem-mcp
 
-[GoodMem](https://docs.goodmem.ai) MCP server — gives AI agents direct access to GoodMem memory infrastructure via the [Model Context Protocol](https://modelcontextprotocol.io).
+[GoodMem](https://goodmem.ai/) MCP server — gives AI agents direct access to GoodMem memory infrastructure via the [Model Context Protocol](https://modelcontextprotocol.io).
 
-41 tools across 10 namespaces: embedders, LLMs, rerankers, spaces, memories, retrieval, OCR, users, API keys, and system administration.
+Tools across namespaces: embedders, LLMs, rerankers, spaces, memories, retrieval, OCR, users, API keys, and system administration.
 
 ## Prerequisites
 
 - A running [GoodMem](https://github.com/PAIR-Systems-Inc/goodmem) server
 - Node.js 18+
 
-## Installation
+## Configuration
 
-### Claude Desktop
+### What you need to configure
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+**GoodMem credentials** (required):
 
-```json
-{
-  "mcpServers": {
-    "goodmem": {
-      "command": "npx",
-      "args": ["-y", "@pairsystems/goodmem-mcp"],
-      "env": {
-        "GOODMEM_BASE_URL": "https://your-server.example.com",
-        "GOODMEM_API_KEY": "gm_..."
-      }
-    }
-  }
-}
-```
+- `GOODMEM_BASE_URL` — GoodMem server URL (e.g., `https://your-server.example.com`)
+- `GOODMEM_API_KEY` — GoodMem API key (starts with `gm_`)
+
+**TLS / self-signed certificates** (optional):
+
+This is an advanced topic. If you do not even know what that is, skip this section. 
+
+If the GoodMem server uses self-signed CA certificates, set one and only one of the following:
+
+- `NODE_EXTRA_CA_CERTS=/path/to/rootCA.pem` — adds the CA to the trusted store. More secure, but requires you to copy the certificate file from the GoodMem server to the machine where the MCP server is running.
+- `NODE_TLS_REJECT_UNAUTHORIZED=0` — disables certificate verification entirely. Easy and hassle-free, but not recommended for production.
 
-### Claude Code
+### How to configure
+
+**1. In English from chat** (GoodMem credentials only; TLS variables cannot be set this way)
+
+Just tell the MCP server your server details — it will call `goodmem_configure` automatically:
+
+> "Configure GoodMem with base URL https://my-server.com and API key gm_abc123"
+
+Credentials persist for the session. You can reconfigure anytime to switch servers. 
+
+**2. Shell export** (before launching the MCP server; works for all configurations)
 
 ```bash
-claude mcp add goodmem -- env GOODMEM_BASE_URL=https://your-server.example.com env GOODMEM_API_KEY=gm_... npx -y @pairsystems/goodmem-mcp
+export GOODMEM_BASE_URL="https://your-server.example.com"
+export GOODMEM_API_KEY="gm_..."
+export NODE_EXTRA_CA_CERTS="/path/to/rootCA.pem"  # only if needed for self-signed certs
+export NODE_TLS_REJECT_UNAUTHORIZED=0              # only if you want to skip cert verification
 ```
 
-Or add to `.claude/mcp.json` in your project:
+**3. MCP client JSON config**
+
+Add an `env` block in your MCP client's JSON configuration:
 
-```json
+```jsonc
 {
   "mcpServers": {
     "goodmem": {
@@ -46,33 +58,38 @@ Or add to `.claude/mcp.json` in your project:
       "args": ["-y", "@pairsystems/goodmem-mcp"],
       "env": {
         "GOODMEM_BASE_URL": "https://your-server.example.com",
-        "GOODMEM_API_KEY": "gm_..."
+        "GOODMEM_API_KEY": "gm_...",
+        "NODE_EXTRA_CA_CERTS": "/path/to/rootCA.pem", // only if needed for self-signed certs
+        "NODE_TLS_REJECT_UNAUTHORIZED": "0"            // only if you want to skip cert verification
       }
     }
   }
 }
 ```
 
-### VS Code / Cursor / Other MCP clients
+The JSON file location depends on your MCP client:
 
-Use the same `npx -y @pairsystems/goodmem-mcp` command pattern with `GOODMEM_BASE_URL` and `GOODMEM_API_KEY` set in the environment.
+- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+- **Claude Code**: `.claude/mcp.json` in your project
+- **VS Code / Cursor**: see your client's MCP server configuration docs
 
-### Global install
+**4. App launcher CLI** (only works for apps that support configuration environment variables in is launcher)
+
+For example, in Claude Code:
 
 ```bash
-npm install -g @pairsystems/goodmem-mcp
-goodmem-mcp
+claude mcp add goodmem -- \
+  env GOODMEM_BASE_URL=https://your-server.example.com \
+  env GOODMEM_API_KEY=gm_... \
+  env NODE_EXTRA_CA_CERTS=/path/to/rootCA.pem
 ```
 
-## Runtime configuration
-
-If you can't set environment variables before launch, call `goodmem_configure` from chat:
+## Global install
 
+```bash
+npm install -g @pairsystems/goodmem-mcp
+goodmem-mcp
 ```
-Configure GoodMem with base URL https://my-server.com and API key gm_abc123
-```
-
-Credentials set this way persist for the session and override environment variables.
 
 ## Quick start
 

package/dist/index.js

@@ -21009,6 +21009,7 @@ async function callApi(method, path, body, query) {
   const resp = await fetch(url.toString(), {
     method,
     headers,
+    signal: AbortSignal.timeout(3e4),
     ...body ? { body: JSON.stringify(body) } : {}
   });
   if (!resp.ok) {
@@ -21040,6 +21041,7 @@ async function callApiNdjson(method, path, body, query) {
   const resp = await fetch(url.toString(), {
     method,
     headers,
+    signal: AbortSignal.timeout(2e5),
     ...body ? { body: JSON.stringify(body) } : {}
   });
   if (!resp.ok) {
@@ -21879,7 +21881,7 @@ function checkCredentialRequired(args) {
     return;
   }
   if (requiredHosts.includes(host)) {
-    throw new Error(`Provider '${provider}' at '${endpointUrl}' requires credentials. Pass credentials with your API key.`);
+    throw new Error(`Provider '${provider}' at '${endpointUrl}' requires credentials. Pass credentials: { kind: "CREDENTIAL_KIND_API_KEY", apiKey: { inlineSecret: "your-key-here" } }`);
   }
 }
 function autoInferFromRegistry(registryType, args) {
@@ -21889,18 +21891,12 @@ function autoInferFromRegistry(registryType, args) {
     return result;
   const registry2 = MODEL_REGISTRY[registryType] ?? {};
   const entry = registry2[modelId];
-  const camelToSnake = {
-    providerType: "provider_type",
-    endpointUrl: "endpoint_url",
-    dimensionality: "dimensionality",
-    distributionType: "distribution_type",
-    supportedModalities: "supported_modalities",
-    maxSequenceLength: "max_sequence_length",
-    maxContextLength: "max_context_length"
-  };
+  function camelToSnake(s) {
+    return s.replace(/([A-Z]+)([A-Z][a-z]{2,})/g, "$1_$2").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+  }
   if (entry) {
     for (const [key, value] of Object.entries(entry)) {
-      const snakeKey = camelToSnake[key] ?? key;
+      const snakeKey = camelToSnake(key);
       if (key === "dimensions") {
         const dims = value;
         if (dims?.default !== void 0 && result.dimensionality === void 0) {
@@ -21923,18 +21919,22 @@ function autoInferFromRegistry(registryType, args) {
 }
 var server = new McpServer({
   name: "goodmem",
-  version: "0.1.1"
+  version: "0.1.3"
 });
 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.", {
   base_url: external_exports.string().describe("GoodMem server URL (e.g., https://your-server.example.com)"),
   api_key: external_exports.string().describe("GoodMem API key (starts with gm_)")
 }, async (args) => {
+  if (!/^https?:\/\//i.test(args.base_url)) {
+    return { content: [{ type: "text", text: `base_url must include a scheme (e.g., http://${args.base_url} or https://${args.base_url}).` }] };
+  }
   goodmemBaseUrl = args.base_url;
   goodmemApiKey = args.api_key;
   try {
     const url = new URL("/v1/system/info", goodmemBaseUrl);
     const resp = await fetch(url.toString(), {
-      headers: { "x-api-key": goodmemApiKey }
+      headers: { "x-api-key": goodmemApiKey },
+      signal: AbortSignal.timeout(1e4)
     });
     if (!resp.ok) {
       const text = await resp.text();
@@ -22121,13 +22121,18 @@ function registerTools() {
   });
   server.tool("goodmem_embedders_list", "List embedders", {
     owner_id: external_exports.string().describe("Filter embedders by owner ID. With LIST_EMBEDDER_ANY permission, omitting this shows all accessible embedders; providing it filters by that owner. With LIST_EMBEDDER_OWN permission, only your own embedders are shown regardless of this parameter.").optional(),
-    provider_type: external_exports.enum(["OPENAI", "VLLM", "TEI", "LLAMA_CPP", "VOYAGE", "COHERE", "JINA"]).describe("Filter embedders by provider type. Allowed values match the ProviderType schema.").optional()
+    provider_type: external_exports.enum(["OPENAI", "VLLM", "TEI", "LLAMA_CPP", "VOYAGE", "COHERE", "JINA"]).describe("Filter embedders by provider type. Allowed values match the ProviderType schema.").optional(),
+    labels: external_exports.record(external_exports.string(), external_exports.string()).describe("Filter by labels. Each key-value pair is sent as a label.<key>=<value> query parameter.").optional()
   }, async (args) => {
     const query = {};
     if (args.owner_id !== void 0)
       query["ownerId"] = String(args.owner_id);
     if (args.provider_type !== void 0)
       query["providerType"] = String(args.provider_type);
+    if (args.labels) {
+      for (const [k, v] of Object.entries(args.labels))
+        query[`label.${k}`] = v;
+    }
     const result = await callApi("GET", `/v1/embedders`, void 0, query);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   });
@@ -22217,7 +22222,7 @@ function registerTools() {
       stopSequences: external_exports.any().describe("Generation stop sequences (\u226410 sequences; each \u2264100 chars; generation halts on exact match)").optional()
     }).passthrough().describe("Default sampling parameters for generation requests").optional(),
     max_context_length: external_exports.number().int().describe("Maximum context window size in tokens").optional(),
-    client_config: external_exports.record(external_exports.string(), external_exports.string()).describe("Provider-specific client configuration as flexible JSON structure").optional(),
+    client_config: external_exports.record(external_exports.string(), external_exports.unknown()).describe("Provider-specific client configuration as flexible JSON structure").optional(),
     owner_id: external_exports.string().describe("Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_LLM_ANY permission if specified.").optional(),
     llm_id: external_exports.string().describe("Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.").optional()
   }, async (args) => {
@@ -22275,13 +22280,18 @@ function registerTools() {
   });
   server.tool("goodmem_llms_list", "List LLMs", {
     owner_id: external_exports.string().describe("Filter LLMs by owner ID. With LIST_LLM_ANY permission, omitting this shows all accessible LLMs; providing it filters by that owner. With LIST_LLM_OWN permission, only your own LLMs are shown regardless of this parameter.").optional(),
-    provider_type: external_exports.enum(["OPENAI", "LITELLM_PROXY", "OPEN_ROUTER", "VLLM", "OLLAMA", "LLAMA_CPP", "CUSTOM_OPENAI_COMPATIBLE"]).describe("Filter LLMs by provider type. Allowed values match the LLMProviderType schema.").optional()
+    provider_type: external_exports.enum(["OPENAI", "LITELLM_PROXY", "OPEN_ROUTER", "VLLM", "OLLAMA", "LLAMA_CPP", "CUSTOM_OPENAI_COMPATIBLE"]).describe("Filter LLMs by provider type. Allowed values match the LLMProviderType schema.").optional(),
+    labels: external_exports.record(external_exports.string(), external_exports.string()).describe("Filter by labels. Each key-value pair is sent as a label.<key>=<value> query parameter.").optional()
   }, async (args) => {
     const query = {};
     if (args.owner_id !== void 0)
       query["ownerId"] = String(args.owner_id);
     if (args.provider_type !== void 0)
       query["providerType"] = String(args.provider_type);
+    if (args.labels) {
+      for (const [k, v] of Object.entries(args.labels))
+        query[`label.${k}`] = v;
+    }
     const result = await callApi("GET", `/v1/llms`, void 0, query);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   });
@@ -22319,7 +22329,7 @@ function registerTools() {
       stopSequences: external_exports.any().describe("Generation stop sequences (\u226410 sequences; each \u2264100 chars; generation halts on exact match)").optional()
     }).passthrough().describe("Update default sampling parameters").optional(),
     max_context_length: external_exports.number().int().describe("Update maximum context window size in tokens").optional(),
-    client_config: external_exports.record(external_exports.string(), external_exports.string()).describe("Update provider-specific client configuration (replaces entire config; no merging)").optional(),
+    client_config: external_exports.record(external_exports.string(), external_exports.unknown()).describe("Update provider-specific client configuration (replaces entire config; no merging)").optional(),
     replace_labels: external_exports.record(external_exports.string(), external_exports.string()).describe("Replace all existing labels with this set. Empty map clears all labels. Cannot be used with mergeLabels.").optional(),
     merge_labels: external_exports.record(external_exports.string(), external_exports.string()).describe("Merge with existing labels: upserts with overwrite. Labels not mentioned are preserved. Cannot be used with replaceLabels.").optional()
   }, async (args) => {
@@ -22400,14 +22410,13 @@ function registerTools() {
     original_content_b64: external_exports.string().describe("Original content as base64-encoded binary data (use either this or originalContent)").optional(),
     original_content_ref: external_exports.string().describe("Reference to external content location").optional(),
     content_type: external_exports.string().describe("MIME type of the content"),
-    metadata: external_exports.record(external_exports.string(), external_exports.string()).describe("Additional metadata for the memory").optional(),
+    metadata: external_exports.record(external_exports.string(), external_exports.unknown()).describe("Additional metadata for the memory").optional(),
     chunking_config: external_exports.object({
       none: external_exports.any().describe("No chunking strategy - preserve original content as single unit").optional(),
       recursive: external_exports.any().describe("Recursive hierarchical chunking strategy with configurable separators").optional(),
       sentence: external_exports.any().describe("Sentence-based chunking strategy with language detection").optional()
     }).passthrough().describe("Chunking strategy for this memory (if not provided, uses space default)").optional(),
-    extract_page_images: external_exports.boolean().describe("Optional hint to extract page images for eligible document types (for example, PDFs)").optional(),
-    file_field: external_exports.string().describe("Optional multipart file field name to bind binary content; required when multiple files are uploaded in a batch multipart request.").optional()
+    extract_page_images: external_exports.boolean().describe("Optional hint to extract page images for eligible document types (for example, PDFs)").optional()
   }, async (args) => {
     const body = {};
     if (args.memory_id !== void 0)
@@ -22428,8 +22437,6 @@ function registerTools() {
       body["chunkingConfig"] = args.chunking_config;
     if (args.extract_page_images !== void 0)
       body["extractPageImages"] = args.extract_page_images;
-    if (args.file_field !== void 0)
-      body["fileField"] = args.file_field;
     const result = await callApi("POST", `/v1/memories`, body);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   });
@@ -22530,7 +22537,7 @@ function registerTools() {
     }).passthrough().describe("Optional request-level HNSW tuning overrides. Advanced usage; available on POST retrieve.").optional(),
     post_processor: external_exports.object({
       name: external_exports.string().describe("Fully qualified factory class name of the post-processor to apply."),
-      config: external_exports.record(external_exports.string(), external_exports.string()).describe("Configuration parameters for the post-processor. Fields depend on the selected processor; see the linked documentation for the built-in ChatPostProcessor schema.").optional()
+      config: external_exports.record(external_exports.string(), external_exports.unknown()).describe("Configuration parameters for the post-processor. Fields depend on the selected processor; see the linked documentation for the built-in ChatPostProcessor schema.").optional()
     }).passthrough().describe("Optional post-processor configuration to transform retrieval results.").optional()
   }, async (args) => {
     const body = {};
@@ -22643,13 +22650,18 @@ function registerTools() {
   });
   server.tool("goodmem_rerankers_list", "List rerankers", {
     owner_id: external_exports.string().describe("Filter rerankers by owner ID. With LIST_RERANKER_ANY permission, omitting this shows all accessible rerankers; providing it filters by that owner. With LIST_RERANKER_OWN permission, only your own rerankers are shown regardless of this parameter (PERMISSION_DENIED if set to another user).").optional(),
-    provider_type: external_exports.enum(["OPENAI", "VLLM", "TEI", "LLAMA_CPP", "VOYAGE", "COHERE", "JINA"]).describe("Filter rerankers by provider type. Allowed values match the ProviderType schema.").optional()
+    provider_type: external_exports.enum(["OPENAI", "VLLM", "TEI", "LLAMA_CPP", "VOYAGE", "COHERE", "JINA"]).describe("Filter rerankers by provider type. Allowed values match the ProviderType schema.").optional(),
+    labels: external_exports.record(external_exports.string(), external_exports.string()).describe("Filter by labels. Each key-value pair is sent as a label.<key>=<value> query parameter.").optional()
   }, async (args) => {
     const query = {};
     if (args.owner_id !== void 0)
       query["ownerId"] = String(args.owner_id);
     if (args.provider_type !== void 0)
       query["providerType"] = String(args.provider_type);
+    if (args.labels) {
+      for (const [k, v] of Object.entries(args.labels))
+        query[`label.${k}`] = v;
+    }
     const result = await callApi("GET", `/v1/rerankers`, void 0, query);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   });
@@ -22750,7 +22762,8 @@ function registerTools() {
     max_results: external_exports.number().int().describe("Maximum number of results to return in a single page (defaults to 50, clamped to [1, 1000])").optional(),
     next_token: external_exports.string().describe("Pagination token for retrieving the next set of results").optional(),
     sort_by: external_exports.string().describe("Field to sort by: 'created_time', 'updated_time', or 'name' (default: 'created_time'). Unsupported values return INVALID_ARGUMENT.").optional(),
-    sort_order: external_exports.enum(["ASCENDING", "DESCENDING", "SORT_ORDER_UNSPECIFIED"]).describe("Sort order (ASCENDING or DESCENDING, default: DESCENDING)").optional()
+    sort_order: external_exports.enum(["ASCENDING", "DESCENDING", "SORT_ORDER_UNSPECIFIED"]).describe("Sort order (ASCENDING or DESCENDING, default: DESCENDING)").optional(),
+    labels: external_exports.record(external_exports.string(), external_exports.string()).describe("Filter by labels. Each key-value pair is sent as a label.<key>=<value> query parameter.").optional()
   }, async (args) => {
     const query = {};
     if (args.owner_id !== void 0)
@@ -22765,6 +22778,10 @@ function registerTools() {
       query["sortBy"] = String(args.sort_by);
     if (args.sort_order !== void 0)
       query["sortOrder"] = String(args.sort_order);
+    if (args.labels) {
+      for (const [k, v] of Object.entries(args.labels))
+        query[`label.${k}`] = v;
+    }
     const result = await callApi("GET", `/v1/spaces`, void 0, query);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   });
@@ -22799,7 +22816,12 @@ function registerTools() {
     id: external_exports.string().describe("The unique identifier of the user to retrieve").optional(),
     email: external_exports.string().describe("The email address of the user to retrieve").optional()
   }, async (args) => {
-    const result = await callApi("GET", `/v1/users/${encodeURIComponent(String(args.id))}`, void 0);
+    if (args.id && args.email)
+      throw new Error("Exactly one of 'id', 'email' must be provided, not both.");
+    if (!args.id && !args.email)
+      throw new Error("Exactly one of 'id', 'email' must be provided.");
+    const url = args.email ? `/v1/users/email/${encodeURIComponent(String(args.email))}` : `/v1/users/${encodeURIComponent(String(args.id))}`;
+    const result = await callApi("GET", url, void 0);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   });
   server.tool("goodmem_users_me", "Get current user profile", {}, async (args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pairsystems/goodmem-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "GoodMem MCP server \u2014 exposes GoodMem API as MCP tools",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist/index.js",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsc && esbuild dist/index.js --bundle --platform=node --format=esm --outfile=dist/index.js --allow-overwrite",