@pairsystems/goodmem-mcp 0.1.0

package/src/index.ts

@@ -0,0 +1,1105 @@
+#!/usr/bin/env node
+// DO NOT EDIT — generated by _client_gen/mcp/emitter.py from api_ir.json.
+// Regenerate with: cd clients/v2 && python -c "from _client_gen.mcp.emitter import generate_mcp; generate_mcp()"
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Configuration — session overrides take precedence over env vars
+// ---------------------------------------------------------------------------
+
+let goodmemBaseUrl = process.env.GOODMEM_BASE_URL || "";
+let goodmemApiKey = process.env.GOODMEM_API_KEY || "";
+
+function isConfigured(): boolean {
+  return goodmemBaseUrl !== "" && goodmemApiKey !== "";
+}
+
+// ---------------------------------------------------------------------------
+// HTTP client
+// ---------------------------------------------------------------------------
+
+async function callApi(
+  method: string,
+  path: string,
+  body?: unknown,
+  query?: Record<string, string>,
+): Promise<unknown> {
+  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 = new URL(path, goodmemBaseUrl);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, v);
+    }
+  }
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "x-api-key": goodmemApiKey,
+  };
+  const resp = await fetch(url.toString(), {
+    method,
+    headers,
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`GoodMem API error ${resp.status}: ${text}`);
+  }
+  const ct = resp.headers.get("content-type") || "";
+  if (ct.includes("application/json")) {
+    return resp.json();
+  }
+  return resp.text();
+}
+
+async function callApiNdjson(
+  method: string,
+  path: string,
+  body?: unknown,
+  query?: Record<string, string>,
+): Promise<unknown[]> {
+  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 = new URL(path, goodmemBaseUrl);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, v);
+    }
+  }
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "Accept": "application/x-ndjson",
+    "x-api-key": goodmemApiKey,
+  };
+  const resp = await fetch(url.toString(), {
+    method,
+    headers,
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`GoodMem API error ${resp.status}: ${text}`);
+  }
+  const text = await resp.text();
+  return text.split("\n").filter(Boolean).map(line => JSON.parse(line));
+}
+
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+
+const server = new McpServer({
+  name: "goodmem",
+  version: "0.1.0",
+});
+
+// ---------------------------------------------------------------------------
+// Configuration tool — set credentials at runtime from chat
+// ---------------------------------------------------------------------------
+
+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: z.string().describe("GoodMem server URL (e.g., https://your-server.example.com)"),
+    api_key: z.string().describe("GoodMem API key (starts with gm_)"),
+  },
+  async (args) => {
+    goodmemBaseUrl = args.base_url;
+    goodmemApiKey = args.api_key;
+    // Verify connection
+    try {
+      const url = new URL("/v1/system/info", goodmemBaseUrl);
+      const resp = await fetch(url.toString(), {
+        headers: { "x-api-key": goodmemApiKey },
+      });
+      if (!resp.ok) {
+        const text = await resp.text();
+        return { content: [{ type: "text" as const, text: `Credentials saved but server returned error ${resp.status}: ${text}. Check your base_url and api_key.` }] };
+      }
+      const info = await resp.json() as Record<string, unknown>;
+      return { content: [{ type: "text" as const, text: `Connected to GoodMem at ${goodmemBaseUrl}. Server version: ${(info as Record<string, unknown>).version ?? "unknown"}.` }] };
+    } catch (err) {
+      return { content: [{ type: "text" as const, text: `Credentials saved but could not connect to ${goodmemBaseUrl}: ${err}. Check your base_url.` }] };
+    }
+  }
+);
+
+function registerTools() {
+  // === admin ===
+
+  server.tool(
+    "goodmem_admin_background_jobs_purge",
+    "Purge completed background jobs",
+    {
+      older_than: z.string().describe("ISO-8601 timestamp cutoff; only terminal jobs older than this instant are eligible.").optional(),
+      statuses: z.array(z.string()).describe("Optional terminal background job statuses to target for purging.").optional(),
+      dry_run: z.boolean().describe("If true, report purge counts without deleting any rows.").optional(),
+      limit: z.number().int().describe("Maximum number of jobs to purge in this request.").optional()
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.older_than !== undefined) body["olderThan"] = args.older_than;
+      if (args.statuses !== undefined) body["statuses"] = args.statuses;
+      if (args.dry_run !== undefined) body["dryRun"] = args.dry_run;
+      if (args.limit !== undefined) body["limit"] = args.limit;
+      const result = await callApi("POST", `/v1/admin/background-jobs:purge`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_admin_drain",
+    "Request the server to enter drain mode",
+    {
+      timeout_sec: z.number().int().describe("Maximum seconds to wait for the server to quiesce before returning.").optional(),
+      reason: z.string().describe("Human-readable reason for initiating drain mode.").optional(),
+      wait_for_quiesce: z.boolean().describe("If true, wait for in-flight requests to complete and the server to reach QUIESCED before responding.").optional()
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.timeout_sec !== undefined) body["timeoutSec"] = args.timeout_sec;
+      if (args.reason !== undefined) body["reason"] = args.reason;
+      if (args.wait_for_quiesce !== undefined) body["waitForQuiesce"] = args.wait_for_quiesce;
+      const result = await callApi("POST", `/v1/admin:drain`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_admin_license_reload",
+    "Reload the active license from disk",
+    {},
+    async (args) => {
+      const result = await callApi("POST", `/v1/admin/license:reload`, undefined);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+
+
+  // === apikeys ===
+
+  server.tool(
+    "goodmem_apikeys_create",
+    "Create a new API key",
+    {
+      labels: z.record(z.string(), z.string()).describe("Key-value pairs of metadata associated with the API key. Used for organization and filtering.").optional(),
+      expires_at: z.number().int().describe("Expiration timestamp in milliseconds since epoch. If not provided, the key does not expire.").optional(),
+      api_key_id: z.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) => {
+      const body: Record<string, unknown> = {};
+      if (args.labels !== undefined) body["labels"] = args.labels;
+      if (args.expires_at !== undefined) body["expiresAt"] = args.expires_at;
+      if (args.api_key_id !== undefined) body["apiKeyId"] = args.api_key_id;
+      const result = await callApi("POST", `/v1/apikeys`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_apikeys_delete",
+    "Delete an API key",
+    {
+      id: z.string().describe("The unique identifier of the API key to delete")
+    },
+    async (args) => {
+      await callApi("DELETE", `/v1/apikeys/${encodeURIComponent(String(args.id))}`, undefined);
+      return { content: [{ type: "text" as const, text: "Deleted successfully." }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_apikeys_list",
+    "List API keys",
+    {},
+    async (args) => {
+      const result = await callApi("GET", `/v1/apikeys`, undefined);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_apikeys_update",
+    "Update an API key",
+    {
+      id: z.string().describe("The unique identifier of the API key to update"),
+      status: z.string().describe("New status for the API key. Allowed values: ACTIVE, INACTIVE.").optional(),
+      replace_labels: z.record(z.string(), z.string()).describe("Replace all existing labels with this set. Mutually exclusive with mergeLabels.").optional(),
+      merge_labels: z.record(z.string(), z.string()).describe("Merge these labels with existing ones. Mutually exclusive with replaceLabels.").optional()
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.status !== undefined) body["status"] = args.status;
+      if (args.replace_labels !== undefined) body["replaceLabels"] = args.replace_labels;
+      if (args.merge_labels !== undefined) body["mergeLabels"] = args.merge_labels;
+      const result = await callApi("PUT", `/v1/apikeys/${encodeURIComponent(String(args.id))}`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+
+
+  // === embedders ===
+
+  server.tool(
+    "goodmem_embedders_create",
+    "Create a new embedder",
+    {
+      display_name: z.string().describe("User-facing name of the embedder"),
+      description: z.string().describe("Description of the embedder").optional(),
+      provider_type: z.enum(["OPENAI", "VLLM", "TEI", "LLAMA_CPP", "VOYAGE", "COHERE", "JINA"]).describe("Type of embedding provider"),
+      endpoint_url: z.string().describe("API endpoint URL"),
+      api_path: z.string().describe("API path for embeddings request (defaults: Cohere /v2/embed, TEI /embed, others /embeddings)").optional(),
+      model_identifier: z.string().describe("Model identifier"),
+      dimensionality: z.number().int().describe("Output vector dimensions"),
+      distribution_type: z.enum(["DENSE", "SPARSE"]).describe("Type of embedding distribution (DENSE or SPARSE)"),
+      max_sequence_length: z.number().int().describe("Maximum input sequence length").optional(),
+      supported_modalities: z.array(z.enum(["TEXT", "IMAGE", "AUDIO", "VIDEO"])).describe("Supported content modalities (defaults to TEXT if not provided)").optional(),
+      credentials: z.object({
+    kind: z.enum(["CREDENTIAL_KIND_UNSPECIFIED", "CREDENTIAL_KIND_API_KEY", "CREDENTIAL_KIND_GCP_ADC"]).describe("Selected credential strategy"),
+    apiKey: z.any().describe("Configuration when kind is CREDENTIAL_KIND_API_KEY").optional(),
+    gcpAdc: z.any().describe("Configuration when kind is CREDENTIAL_KIND_GCP_ADC").optional(),
+    labels: z.record(z.string(), z.string()).describe("Optional annotations to aid operators (e.g., \"owner=vertex\")").optional()
+  }).passthrough().describe("Structured credential payload describing how to authenticate with the provider. Required for SaaS providers such as COHERE, JINA, and VOYAGE; optional for local or proxy providers.").optional(),
+      labels: z.record(z.string(), z.string()).describe("User-defined labels for categorization").optional(),
+      version: z.string().describe("Version information").optional(),
+      monitoring_endpoint: z.string().describe("Monitoring endpoint URL").optional(),
+      owner_id: z.string().describe("Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_EMBEDDER_ANY permission if specified.").optional(),
+      embedder_id: z.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) => {
+      const body: Record<string, unknown> = {};
+      if (args.display_name !== undefined) body["displayName"] = args.display_name;
+      if (args.description !== undefined) body["description"] = args.description;
+      if (args.provider_type !== undefined) body["providerType"] = args.provider_type;
+      if (args.endpoint_url !== undefined) body["endpointUrl"] = args.endpoint_url;
+      if (args.api_path !== undefined) body["apiPath"] = args.api_path;
+      if (args.model_identifier !== undefined) body["modelIdentifier"] = args.model_identifier;
+      if (args.dimensionality !== undefined) body["dimensionality"] = args.dimensionality;
+      if (args.distribution_type !== undefined) body["distributionType"] = args.distribution_type;
+      if (args.max_sequence_length !== undefined) body["maxSequenceLength"] = args.max_sequence_length;
+      if (args.supported_modalities !== undefined) body["supportedModalities"] = args.supported_modalities;
+      if (args.credentials !== undefined) body["credentials"] = args.credentials;
+      if (args.labels !== undefined) body["labels"] = args.labels;
+      if (args.version !== undefined) body["version"] = args.version;
+      if (args.monitoring_endpoint !== undefined) body["monitoringEndpoint"] = args.monitoring_endpoint;
+      if (args.owner_id !== undefined) body["ownerId"] = args.owner_id;
+      if (args.embedder_id !== undefined) body["embedderId"] = args.embedder_id;
+      const result = await callApi("POST", `/v1/embedders`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_embedders_delete",
+    "Delete an embedder",
+    {
+      id: z.string().describe("The unique identifier of the embedder to delete")
+    },
+    async (args) => {
+      await callApi("DELETE", `/v1/embedders/${encodeURIComponent(String(args.id))}`, undefined);
+      return { content: [{ type: "text" as const, text: "Deleted successfully." }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_embedders_get",
+    "Get an embedder by ID",
+    {
+      id: z.string().describe("The unique identifier of the embedder to retrieve")
+    },
+    async (args) => {
+      const result = await callApi("GET", `/v1/embedders/${encodeURIComponent(String(args.id))}`, undefined);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_embedders_list",
+    "List embedders",
+    {
+      owner_id: z.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: z.enum(["OPENAI", "VLLM", "TEI", "LLAMA_CPP", "VOYAGE", "COHERE", "JINA"]).describe("Filter embedders by provider type. Allowed values match the ProviderType schema.").optional()
+    },
+    async (args) => {
+      const query: Record<string, string> = {};
+      if (args.owner_id !== undefined) query["ownerId"] = String(args.owner_id);
+      if (args.provider_type !== undefined) query["providerType"] = String(args.provider_type);
+      const result = await callApi("GET", `/v1/embedders`, undefined, query);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_embedders_update",
+    "Update an embedder",
+    {
+      id: z.string().describe("The unique identifier of the embedder to update"),
+      display_name: z.string().describe("User-facing name of the embedder").optional(),
+      description: z.string().describe("Description of the embedder").optional(),
+      endpoint_url: z.string().describe("API endpoint URL").optional(),
+      api_path: z.string().describe("API path for embeddings request").optional(),
+      model_identifier: z.string().describe("Model identifier").optional(),
+      dimensionality: z.number().int().describe("Output vector dimensions").optional(),
+      max_sequence_length: z.number().int().describe("Maximum input sequence length").optional(),
+      supported_modalities: z.array(z.enum(["TEXT", "IMAGE", "AUDIO", "VIDEO"])).describe("Supported content modalities").optional(),
+      credentials: z.object({
+    kind: z.enum(["CREDENTIAL_KIND_UNSPECIFIED", "CREDENTIAL_KIND_API_KEY", "CREDENTIAL_KIND_GCP_ADC"]).describe("Selected credential strategy"),
+    apiKey: z.any().describe("Configuration when kind is CREDENTIAL_KIND_API_KEY").optional(),
+    gcpAdc: z.any().describe("Configuration when kind is CREDENTIAL_KIND_GCP_ADC").optional(),
+    labels: z.record(z.string(), z.string()).describe("Optional annotations to aid operators (e.g., \"owner=vertex\")").optional()
+  }).passthrough().describe("Structured credential payload describing how to authenticate with the provider").optional(),
+      replace_labels: z.record(z.string(), z.string()).describe("Replace all existing labels with these (mutually exclusive with mergeLabels)").optional(),
+      merge_labels: z.record(z.string(), z.string()).describe("Merge these labels with existing ones (mutually exclusive with replaceLabels)").optional(),
+      version: z.string().describe("Version information").optional(),
+      monitoring_endpoint: z.string().describe("Monitoring endpoint URL").optional()
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.display_name !== undefined) body["displayName"] = args.display_name;
+      if (args.description !== undefined) body["description"] = args.description;
+      if (args.endpoint_url !== undefined) body["endpointUrl"] = args.endpoint_url;
+      if (args.api_path !== undefined) body["apiPath"] = args.api_path;
+      if (args.model_identifier !== undefined) body["modelIdentifier"] = args.model_identifier;
+      if (args.dimensionality !== undefined) body["dimensionality"] = args.dimensionality;
+      if (args.max_sequence_length !== undefined) body["maxSequenceLength"] = args.max_sequence_length;
+      if (args.supported_modalities !== undefined) body["supportedModalities"] = args.supported_modalities;
+      if (args.credentials !== undefined) body["credentials"] = args.credentials;
+      if (args.replace_labels !== undefined) body["replaceLabels"] = args.replace_labels;
+      if (args.merge_labels !== undefined) body["mergeLabels"] = args.merge_labels;
+      if (args.version !== undefined) body["version"] = args.version;
+      if (args.monitoring_endpoint !== undefined) body["monitoringEndpoint"] = args.monitoring_endpoint;
+      const result = await callApi("PUT", `/v1/embedders/${encodeURIComponent(String(args.id))}`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+
+
+  // === llms ===
+
+  server.tool(
+    "goodmem_llms_create",
+    "Create a new LLM",
+    {
+      display_name: z.string().describe("User-facing name of the LLM"),
+      description: z.string().describe("Description of the LLM").optional(),
+      provider_type: z.enum(["OPENAI", "LITELLM_PROXY", "OPEN_ROUTER", "VLLM", "OLLAMA", "LLAMA_CPP", "CUSTOM_OPENAI_COMPATIBLE"]).describe("Type of LLM provider"),
+      endpoint_url: z.string().describe("API endpoint base URL (OpenAI-compatible base, typically ends with /v1)"),
+      api_path: z.string().describe("API path for chat/completions request (defaults to /chat/completions if not provided)").optional(),
+      model_identifier: z.string().describe("Model identifier"),
+      supported_modalities: z.array(z.enum(["TEXT", "IMAGE", "AUDIO", "VIDEO"])).describe("Supported content modalities (defaults to TEXT if not provided)").optional(),
+      credentials: z.object({
+    kind: z.enum(["CREDENTIAL_KIND_UNSPECIFIED", "CREDENTIAL_KIND_API_KEY", "CREDENTIAL_KIND_GCP_ADC"]).describe("Selected credential strategy"),
+    apiKey: z.any().describe("Configuration when kind is CREDENTIAL_KIND_API_KEY").optional(),
+    gcpAdc: z.any().describe("Configuration when kind is CREDENTIAL_KIND_GCP_ADC").optional(),
+    labels: z.record(z.string(), z.string()).describe("Optional annotations to aid operators (e.g., \"owner=vertex\")").optional()
+  }).passthrough().describe("Structured credential payload describing how to authenticate with the provider. Omit for deployments that do not require credentials.").optional(),
+      labels: z.record(z.string(), z.string()).describe("User-defined labels for categorization").optional(),
+      version: z.string().describe("Version information").optional(),
+      monitoring_endpoint: z.string().describe("Monitoring endpoint URL").optional(),
+      capabilities: z.object({
+    supportsChat: z.boolean().describe("Supports conversational/chat completion format with message roles").optional(),
+    supportsCompletion: z.boolean().describe("Supports raw text completion with prompt continuation").optional(),
+    supportsFunctionCalling: z.boolean().describe("Supports function/tool calling with structured responses").optional(),
+    supportsSystemMessages: z.boolean().describe("Supports system prompts to define model behavior and context").optional(),
+    supportsStreaming: z.boolean().describe("Supports real-time token streaming during generation").optional(),
+    supportsSamplingParameters: z.boolean().describe("Supports sampling parameters like temperature, top_p, and top_k for generation control").optional()
+  }).passthrough().describe("LLM capabilities defining supported features and modes. Optional - server infers capabilities from model identifier if not provided.").optional(),
+      default_sampling_params: z.object({
+    maxTokens: z.number().int().describe("Maximum tokens to generate (>0 if set; provider-dependent limits apply)").optional(),
+    temperature: z.number().describe("Sampling temperature 0.0-2.0 (0.0=deterministic, 2.0=highly random)").optional(),
+    topP: z.number().describe("Nucleus sampling threshold 0.0-1.0 (smaller values focus on higher probability tokens)").optional(),
+    topK: z.number().int().describe("Top-k sampling limit (>0 if set; primarily for local/open-source models)").optional(),
+    frequencyPenalty: z.number().describe("Frequency penalty -2.0 to 2.0 (positive values reduce repetition based on frequency)").optional(),
+    presencePenalty: z.number().describe("Presence penalty -2.0 to 2.0 (positive values encourage topic diversity)").optional(),
+    stopSequences: z.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: z.number().int().describe("Maximum context window size in tokens").optional(),
+      client_config: z.record(z.string(), z.string()).describe("Provider-specific client configuration as flexible JSON structure").optional(),
+      owner_id: z.string().describe("Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_LLM_ANY permission if specified.").optional(),
+      llm_id: z.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) => {
+      const body: Record<string, unknown> = {};
+      if (args.display_name !== undefined) body["displayName"] = args.display_name;
+      if (args.description !== undefined) body["description"] = args.description;
+      if (args.provider_type !== undefined) body["providerType"] = args.provider_type;
+      if (args.endpoint_url !== undefined) body["endpointUrl"] = args.endpoint_url;
+      if (args.api_path !== undefined) body["apiPath"] = args.api_path;
+      if (args.model_identifier !== undefined) body["modelIdentifier"] = args.model_identifier;
+      if (args.supported_modalities !== undefined) body["supportedModalities"] = args.supported_modalities;
+      if (args.credentials !== undefined) body["credentials"] = args.credentials;
+      if (args.labels !== undefined) body["labels"] = args.labels;
+      if (args.version !== undefined) body["version"] = args.version;
+      if (args.monitoring_endpoint !== undefined) body["monitoringEndpoint"] = args.monitoring_endpoint;
+      if (args.capabilities !== undefined) body["capabilities"] = args.capabilities;
+      if (args.default_sampling_params !== undefined) body["defaultSamplingParams"] = args.default_sampling_params;
+      if (args.max_context_length !== undefined) body["maxContextLength"] = args.max_context_length;
+      if (args.client_config !== undefined) body["clientConfig"] = args.client_config;
+      if (args.owner_id !== undefined) body["ownerId"] = args.owner_id;
+      if (args.llm_id !== undefined) body["llmId"] = args.llm_id;
+      const result = await callApi("POST", `/v1/llms`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_llms_delete",
+    "Delete an LLM",
+    {
+      id: z.string().describe("The unique identifier of the LLM to delete")
+    },
+    async (args) => {
+      await callApi("DELETE", `/v1/llms/${encodeURIComponent(String(args.id))}`, undefined);
+      return { content: [{ type: "text" as const, text: "Deleted successfully." }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_llms_get",
+    "Get an LLM by ID",
+    {
+      id: z.string().describe("The unique identifier of the LLM to retrieve")
+    },
+    async (args) => {
+      const result = await callApi("GET", `/v1/llms/${encodeURIComponent(String(args.id))}`, undefined);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_llms_list",
+    "List LLMs",
+    {
+      owner_id: z.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: z.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()
+    },
+    async (args) => {
+      const query: Record<string, string> = {};
+      if (args.owner_id !== undefined) query["ownerId"] = String(args.owner_id);
+      if (args.provider_type !== undefined) query["providerType"] = String(args.provider_type);
+      const result = await callApi("GET", `/v1/llms`, undefined, query);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_llms_update",
+    "Update an LLM",
+    {
+      id: z.string().describe("The unique identifier of the LLM to update"),
+      display_name: z.string().describe("Update display name").optional(),
+      description: z.string().describe("Update description").optional(),
+      endpoint_url: z.string().describe("Update endpoint base URL (OpenAI-compatible base, typically ends with /v1)").optional(),
+      api_path: z.string().describe("Update API path").optional(),
+      model_identifier: z.string().describe("Update model identifier (cannot be empty)").optional(),
+      supported_modalities: z.array(z.enum(["TEXT", "IMAGE", "AUDIO", "VIDEO"])).describe("Update supported modalities (if array contains \u22651 elements, replaces stored set; if empty or omitted, no change)").optional(),
+      credentials: z.object({
+    kind: z.enum(["CREDENTIAL_KIND_UNSPECIFIED", "CREDENTIAL_KIND_API_KEY", "CREDENTIAL_KIND_GCP_ADC"]).describe("Selected credential strategy"),
+    apiKey: z.any().describe("Configuration when kind is CREDENTIAL_KIND_API_KEY").optional(),
+    gcpAdc: z.any().describe("Configuration when kind is CREDENTIAL_KIND_GCP_ADC").optional(),
+    labels: z.record(z.string(), z.string()).describe("Optional annotations to aid operators (e.g., \"owner=vertex\")").optional()
+  }).passthrough().describe("Update credentials").optional(),
+      version: z.string().describe("Update version information").optional(),
+      monitoring_endpoint: z.string().describe("Update monitoring endpoint URL").optional(),
+      capabilities: z.object({
+    supportsChat: z.boolean().describe("Supports conversational/chat completion format with message roles").optional(),
+    supportsCompletion: z.boolean().describe("Supports raw text completion with prompt continuation").optional(),
+    supportsFunctionCalling: z.boolean().describe("Supports function/tool calling with structured responses").optional(),
+    supportsSystemMessages: z.boolean().describe("Supports system prompts to define model behavior and context").optional(),
+    supportsStreaming: z.boolean().describe("Supports real-time token streaming during generation").optional(),
+    supportsSamplingParameters: z.boolean().describe("Supports sampling parameters like temperature, top_p, and top_k for generation control").optional()
+  }).passthrough().describe("Update LLM capabilities (replaces entire capability set; clients MUST send all flags)").optional(),
+      default_sampling_params: z.object({
+    maxTokens: z.number().int().describe("Maximum tokens to generate (>0 if set; provider-dependent limits apply)").optional(),
+    temperature: z.number().describe("Sampling temperature 0.0-2.0 (0.0=deterministic, 2.0=highly random)").optional(),
+    topP: z.number().describe("Nucleus sampling threshold 0.0-1.0 (smaller values focus on higher probability tokens)").optional(),
+    topK: z.number().int().describe("Top-k sampling limit (>0 if set; primarily for local/open-source models)").optional(),
+    frequencyPenalty: z.number().describe("Frequency penalty -2.0 to 2.0 (positive values reduce repetition based on frequency)").optional(),
+    presencePenalty: z.number().describe("Presence penalty -2.0 to 2.0 (positive values encourage topic diversity)").optional(),
+    stopSequences: z.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: z.number().int().describe("Update maximum context window size in tokens").optional(),
+      client_config: z.record(z.string(), z.string()).describe("Update provider-specific client configuration (replaces entire config; no merging)").optional(),
+      replace_labels: z.record(z.string(), z.string()).describe("Replace all existing labels with this set. Empty map clears all labels. Cannot be used with mergeLabels.").optional(),
+      merge_labels: z.record(z.string(), z.string()).describe("Merge with existing labels: upserts with overwrite. Labels not mentioned are preserved. Cannot be used with replaceLabels.").optional()
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.display_name !== undefined) body["displayName"] = args.display_name;
+      if (args.description !== undefined) body["description"] = args.description;
+      if (args.endpoint_url !== undefined) body["endpointUrl"] = args.endpoint_url;
+      if (args.api_path !== undefined) body["apiPath"] = args.api_path;
+      if (args.model_identifier !== undefined) body["modelIdentifier"] = args.model_identifier;
+      if (args.supported_modalities !== undefined) body["supportedModalities"] = args.supported_modalities;
+      if (args.credentials !== undefined) body["credentials"] = args.credentials;
+      if (args.version !== undefined) body["version"] = args.version;
+      if (args.monitoring_endpoint !== undefined) body["monitoringEndpoint"] = args.monitoring_endpoint;
+      if (args.capabilities !== undefined) body["capabilities"] = args.capabilities;
+      if (args.default_sampling_params !== undefined) body["defaultSamplingParams"] = args.default_sampling_params;
+      if (args.max_context_length !== undefined) body["maxContextLength"] = args.max_context_length;
+      if (args.client_config !== undefined) body["clientConfig"] = args.client_config;
+      if (args.replace_labels !== undefined) body["replaceLabels"] = args.replace_labels;
+      if (args.merge_labels !== undefined) body["mergeLabels"] = args.merge_labels;
+      const result = await callApi("PUT", `/v1/llms/${encodeURIComponent(String(args.id))}`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+
+
+  // === memories ===
+
+  server.tool(
+    "goodmem_memories_batch_create",
+    "Create multiple memories in a batch",
+    {
+      requests: z.array(z.record(z.string(), z.unknown()).describe("JsonMemoryCreationRequest object")).describe("Array of memory creation requests.")
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.requests !== undefined) body["requests"] = args.requests;
+      const result = await callApi("POST", `/v1/memories:batchCreate`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_memories_batch_delete",
+    "Delete memories in batch",
+    {
+      requests: z.array(z.object({
+    memoryId: z.string().describe("Deletes one specific memory by UUID").optional(),
+    filterSelector: z.any().describe("Deletes a filtered set of memories within a specific space").optional()
+  }).passthrough()).describe("Array of delete selectors")
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.requests !== undefined) body["requests"] = args.requests;
+      const result = await callApi("POST", `/v1/memories:batchDelete`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_memories_batch_get",
+    "Get multiple memories by ID",
+    {
+      memory_ids: z.array(z.string()).describe("Array of memory IDs to retrieve"),
+      include_content: z.boolean().describe("Whether to include the original content in the response").optional(),
+      include_processing_history: z.boolean().describe("Whether to include background job processing history for each memory").optional()
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.memory_ids !== undefined) body["memoryIds"] = args.memory_ids;
+      if (args.include_content !== undefined) body["includeContent"] = args.include_content;
+      if (args.include_processing_history !== undefined) body["includeProcessingHistory"] = args.include_processing_history;
+      const result = await callApi("POST", `/v1/memories:batchGet`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_memories_create",
+    "Create a new memory",
+    {
+      memory_id: z.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: z.string().describe("ID of the space where this memory will be stored"),
+      original_content: z.string().describe("Original content as plain text (use either this or originalContentB64)").optional(),
+      original_content_b64: z.string().describe("Original content as base64-encoded binary data (use either this or originalContent)").optional(),
+      original_content_ref: z.string().describe("Reference to external content location").optional(),
+      content_type: z.string().describe("MIME type of the content"),
+      metadata: z.record(z.string(), z.string()).describe("Additional metadata for the memory").optional(),
+      chunking_config: z.object({
+    none: z.any().describe("No chunking strategy - preserve original content as single unit").optional(),
+    recursive: z.any().describe("Recursive hierarchical chunking strategy with configurable separators").optional(),
+    sentence: z.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: z.boolean().describe("Optional hint to extract page images for eligible document types (for example, PDFs)").optional(),
+      file_field: z.string().describe("Optional multipart file field name to bind binary content; required when multiple files are uploaded in a batch multipart request.").optional()
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.memory_id !== undefined) body["memoryId"] = args.memory_id;
+      if (args.space_id !== undefined) body["spaceId"] = args.space_id;
+      if (args.original_content !== undefined) body["originalContent"] = args.original_content;
+      if (args.original_content_b64 !== undefined) body["originalContentB64"] = args.original_content_b64;
+      if (args.original_content_ref !== undefined) body["originalContentRef"] = args.original_content_ref;
+      if (args.content_type !== undefined) body["contentType"] = args.content_type;
+      if (args.metadata !== undefined) body["metadata"] = args.metadata;
+      if (args.chunking_config !== undefined) body["chunkingConfig"] = args.chunking_config;
+      if (args.extract_page_images !== undefined) body["extractPageImages"] = args.extract_page_images;
+      if (args.file_field !== undefined) body["fileField"] = args.file_field;
+      const result = await callApi("POST", `/v1/memories`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_memories_delete",
+    "Delete a memory",
+    {
+      id: z.string().describe("The unique identifier of the memory to delete")
+    },
+    async (args) => {
+      await callApi("DELETE", `/v1/memories/${encodeURIComponent(String(args.id))}`, undefined);
+      return { content: [{ type: "text" as const, text: "Deleted successfully." }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_memories_get",
+    "Get a memory by ID",
+    {
+      id: z.string().describe("The unique identifier of the memory to retrieve"),
+      include_content: z.boolean().describe("Whether to include the original content in the response (defaults to false). The snake_case alias include_content is also accepted.").optional(),
+      include_processing_history: z.boolean().describe("Whether to include background job processing history in the response (defaults to false). The snake_case alias include_processing_history is also accepted.").optional()
+    },
+    async (args) => {
+      const query: Record<string, string> = {};
+      if (args.include_content !== undefined) query["includeContent"] = String(args.include_content);
+      if (args.include_processing_history !== undefined) query["includeProcessingHistory"] = String(args.include_processing_history);
+      const result = await callApi("GET", `/v1/memories/${encodeURIComponent(String(args.id))}`, undefined, query);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_memories_list",
+    "List memories in a space",
+    {
+      space_id: z.string().describe("The unique identifier of the space containing the memories"),
+      include_content: z.boolean().describe("Whether to include the original content in the response (defaults to false). The snake_case alias include_content is also accepted.").optional(),
+      include_processing_history: z.boolean().describe("Whether to include background job processing history in the response (defaults to false). The snake_case alias include_processing_history is also accepted.").optional(),
+      status_filter: z.string().describe("Filter memories by processing status (PENDING, PROCESSING, COMPLETED, FAILED). The snake_case alias status_filter is also accepted.").optional(),
+      filter: z.string().describe("Optional metadata filter expression for list results").optional(),
+      max_results: z.number().int().describe("Maximum number of results per page (defaults to 50, clamped to [1, 500]). The snake_case alias max_results is also accepted.").optional(),
+      next_token: z.string().describe("Opaque pagination token for the next page. URL-safe Base64 without padding; do not parse or construct it. The snake_case alias next_token is also accepted.").optional(),
+      sort_by: z.string().describe("Field to sort by (e.g., 'created_at'). The snake_case alias sort_by is also accepted.").optional(),
+      sort_order: z.enum(["ASCENDING", "DESCENDING", "SORT_ORDER_UNSPECIFIED"]).describe("Sort direction (ASCENDING or DESCENDING). The snake_case alias sort_order is also accepted.").optional()
+    },
+    async (args) => {
+      const query: Record<string, string> = {};
+      if (args.include_content !== undefined) query["includeContent"] = String(args.include_content);
+      if (args.include_processing_history !== undefined) query["includeProcessingHistory"] = String(args.include_processing_history);
+      if (args.status_filter !== undefined) query["statusFilter"] = String(args.status_filter);
+      if (args.filter !== undefined) query["filter"] = String(args.filter);
+      if (args.max_results !== undefined) query["maxResults"] = String(args.max_results);
+      if (args.next_token !== undefined) query["nextToken"] = String(args.next_token);
+      if (args.sort_by !== undefined) query["sortBy"] = String(args.sort_by);
+      if (args.sort_order !== undefined) query["sortOrder"] = String(args.sort_order);
+      const result = await callApi("GET", `/v1/spaces/${encodeURIComponent(String(args.space_id))}/memories`, undefined, query);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_memories_pages",
+    "List memory page images",
+    {
+      id: z.string().describe("Memory UUID"),
+      start_page_index: z.number().int().describe("Optional lower bound for returned page indices, inclusive. The snake_case alias start_page_index is also accepted.").optional(),
+      end_page_index: z.number().int().describe("Optional upper bound for returned page indices, inclusive. The snake_case alias end_page_index is also accepted.").optional(),
+      dpi: z.number().int().describe("Optional rendition filter for page-image DPI.").optional(),
+      content_type: z.string().describe("Optional rendition filter for page-image MIME type, such as image/png. The snake_case alias content_type is also accepted.").optional(),
+      max_results: z.number().int().describe("Maximum number of results per page. The snake_case alias max_results is also accepted.").optional(),
+      next_token: z.string().describe("Opaque pagination token for the next page. The snake_case alias next_token is also accepted. Do not parse or construct it.").optional()
+    },
+    async (args) => {
+      const query: Record<string, string> = {};
+      if (args.start_page_index !== undefined) query["startPageIndex"] = String(args.start_page_index);
+      if (args.end_page_index !== undefined) query["endPageIndex"] = String(args.end_page_index);
+      if (args.dpi !== undefined) query["dpi"] = String(args.dpi);
+      if (args.content_type !== undefined) query["contentType"] = String(args.content_type);
+      if (args.max_results !== undefined) query["maxResults"] = String(args.max_results);
+      if (args.next_token !== undefined) query["nextToken"] = String(args.next_token);
+      const result = await callApi("GET", `/v1/memories/${encodeURIComponent(String(args.id))}/pages`, undefined, query);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_memories_retrieve",
+    "Advanced semantic memory retrieval with JSON",
+    {
+      message: z.string().describe("Primary query/message for semantic search."),
+      context: z.array(z.object({
+    text: z.string().describe("Text content for this context item.").optional(),
+    binary: z.any().describe("Binary content for this context item.").optional()
+  }).passthrough()).describe("Optional context items (text or binary) to provide additional context for the search.").optional(),
+      space_keys: z.array(z.object({
+    spaceId: z.string().describe("The unique identifier for the space to search."),
+    embedderWeights: z.any().describe("Optional per-embedder weight overrides for this space. If not specified, database defaults are used.").optional(),
+    filter: z.string().describe("Optional filter expression that must evaluate to true for memories in this space.").optional()
+  }).passthrough()).describe("List of spaces to search with optional per-embedder weight overrides."),
+      requested_size: z.number().int().describe("Maximum number of memories to retrieve.").optional(),
+      fetch_memory: z.boolean().describe("Whether to include full Memory objects in the response.").optional(),
+      fetch_memory_content: z.boolean().describe("Whether to include memory content in the response. Requires fetchMemory=true.").optional(),
+      hnsw: z.object({
+    efSearch: z.number().int().describe("HNSW candidate list size (1..1000).").optional(),
+    iterativeScan: z.enum(["ITERATIVE_SCAN_UNSPECIFIED", "ITERATIVE_SCAN_OFF", "ITERATIVE_SCAN_RELAXED_ORDER", "ITERATIVE_SCAN_STRICT_ORDER"]).describe("HNSW iterative scan mode. Use POST retrieve for this advanced tuning control.").optional(),
+    maxScanTuples: z.number().int().describe("Maximum tuples to scan during iterative filtering (1..2147483647).").optional(),
+    scanMemMultiplier: z.number().describe("Multiplier on work_mem for iterative scanning (1.0..1000.0).").optional()
+  }).passthrough().describe("Optional request-level HNSW tuning overrides. Advanced usage; available on POST retrieve.").optional(),
+      post_processor: z.object({
+    name: z.string().describe("Fully qualified factory class name of the post-processor to apply."),
+    config: z.record(z.string(), z.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()
+  }).passthrough().describe("Optional post-processor configuration to transform retrieval results.").optional()
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.message !== undefined) body["message"] = args.message;
+      if (args.context !== undefined) body["context"] = args.context;
+      if (args.space_keys !== undefined) body["spaceKeys"] = args.space_keys;
+      if (args.requested_size !== undefined) body["requestedSize"] = args.requested_size;
+      if (args.fetch_memory !== undefined) body["fetchMemory"] = args.fetch_memory;
+      if (args.fetch_memory_content !== undefined) body["fetchMemoryContent"] = args.fetch_memory_content;
+      if (args.hnsw !== undefined) body["hnsw"] = args.hnsw;
+      if (args.post_processor !== undefined) body["postProcessor"] = args.post_processor;
+      const result = await callApiNdjson("POST", `/v1/memories:retrieve`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+
+
+  // === ocr ===
+
+  server.tool(
+    "goodmem_ocr_document",
+    "Run OCR on a document or image",
+    {
+      content: z.string().describe("Base64-encoded document bytes"),
+      format: z.enum(["AUTO", "PDF", "TIFF", "PNG", "JPEG", "BMP"]).describe("Input format hint (AUTO, PDF, TIFF, PNG, JPEG, BMP)").optional(),
+      include_raw_json: z.boolean().describe("Include raw OCR JSON payload in the response").optional(),
+      include_markdown: z.boolean().describe("Include markdown rendering in the response").optional(),
+      start_page: z.number().int().describe("0-based inclusive start page").optional(),
+      end_page: z.number().int().describe("0-based inclusive end page").optional()
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.content !== undefined) body["content"] = args.content;
+      if (args.format !== undefined) body["format"] = args.format;
+      if (args.include_raw_json !== undefined) body["includeRawJson"] = args.include_raw_json;
+      if (args.include_markdown !== undefined) body["includeMarkdown"] = args.include_markdown;
+      if (args.start_page !== undefined) body["startPage"] = args.start_page;
+      if (args.end_page !== undefined) body["endPage"] = args.end_page;
+      const result = await callApi("POST", `/v1/ocr:document`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+
+
+  // === rerankers ===
+
+  server.tool(
+    "goodmem_rerankers_create",
+    "Create a new reranker",
+    {
+      display_name: z.string().describe("User-facing name of the reranker"),
+      description: z.string().describe("Description of the reranker").optional(),
+      provider_type: z.enum(["OPENAI", "VLLM", "TEI", "LLAMA_CPP", "VOYAGE", "COHERE", "JINA"]).describe("Type of reranking provider"),
+      endpoint_url: z.string().describe("API endpoint URL"),
+      api_path: z.string().describe("API path for reranking request (defaults: Cohere /v2/rerank, Jina /v1/rerank, others /rerank)").optional(),
+      model_identifier: z.string().describe("Model identifier"),
+      supported_modalities: z.array(z.enum(["TEXT", "IMAGE", "AUDIO", "VIDEO"])).describe("Supported content modalities (defaults to TEXT if not provided)").optional(),
+      credentials: z.object({
+    kind: z.enum(["CREDENTIAL_KIND_UNSPECIFIED", "CREDENTIAL_KIND_API_KEY", "CREDENTIAL_KIND_GCP_ADC"]).describe("Selected credential strategy"),
+    apiKey: z.any().describe("Configuration when kind is CREDENTIAL_KIND_API_KEY").optional(),
+    gcpAdc: z.any().describe("Configuration when kind is CREDENTIAL_KIND_GCP_ADC").optional(),
+    labels: z.record(z.string(), z.string()).describe("Optional annotations to aid operators (e.g., \"owner=vertex\")").optional()
+  }).passthrough().describe("Structured credential payload describing how to authenticate with the provider. Required for SaaS providers; optional for local deployments.").optional(),
+      labels: z.record(z.string(), z.string()).describe("User-defined labels for categorization").optional(),
+      version: z.string().describe("Version information").optional(),
+      monitoring_endpoint: z.string().describe("Monitoring endpoint URL").optional(),
+      owner_id: z.string().describe("Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_RERANKER_ANY permission if specified.").optional(),
+      reranker_id: z.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) => {
+      const body: Record<string, unknown> = {};
+      if (args.display_name !== undefined) body["displayName"] = args.display_name;
+      if (args.description !== undefined) body["description"] = args.description;
+      if (args.provider_type !== undefined) body["providerType"] = args.provider_type;
+      if (args.endpoint_url !== undefined) body["endpointUrl"] = args.endpoint_url;
+      if (args.api_path !== undefined) body["apiPath"] = args.api_path;
+      if (args.model_identifier !== undefined) body["modelIdentifier"] = args.model_identifier;
+      if (args.supported_modalities !== undefined) body["supportedModalities"] = args.supported_modalities;
+      if (args.credentials !== undefined) body["credentials"] = args.credentials;
+      if (args.labels !== undefined) body["labels"] = args.labels;
+      if (args.version !== undefined) body["version"] = args.version;
+      if (args.monitoring_endpoint !== undefined) body["monitoringEndpoint"] = args.monitoring_endpoint;
+      if (args.owner_id !== undefined) body["ownerId"] = args.owner_id;
+      if (args.reranker_id !== undefined) body["rerankerId"] = args.reranker_id;
+      const result = await callApi("POST", `/v1/rerankers`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_rerankers_delete",
+    "Delete a reranker",
+    {
+      id: z.string().describe("The unique identifier of the reranker to delete")
+    },
+    async (args) => {
+      await callApi("DELETE", `/v1/rerankers/${encodeURIComponent(String(args.id))}`, undefined);
+      return { content: [{ type: "text" as const, text: "Deleted successfully." }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_rerankers_get",
+    "Get a reranker by ID",
+    {
+      id: z.string().describe("The unique identifier of the reranker to retrieve")
+    },
+    async (args) => {
+      const result = await callApi("GET", `/v1/rerankers/${encodeURIComponent(String(args.id))}`, undefined);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_rerankers_list",
+    "List rerankers",
+    {
+      owner_id: z.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: z.enum(["OPENAI", "VLLM", "TEI", "LLAMA_CPP", "VOYAGE", "COHERE", "JINA"]).describe("Filter rerankers by provider type. Allowed values match the ProviderType schema.").optional()
+    },
+    async (args) => {
+      const query: Record<string, string> = {};
+      if (args.owner_id !== undefined) query["ownerId"] = String(args.owner_id);
+      if (args.provider_type !== undefined) query["providerType"] = String(args.provider_type);
+      const result = await callApi("GET", `/v1/rerankers`, undefined, query);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_rerankers_update",
+    "Update a reranker",
+    {
+      id: z.string().describe("The unique identifier of the reranker to update"),
+      display_name: z.string().describe("User-facing name of the reranker").optional(),
+      description: z.string().describe("Description of the reranker").optional(),
+      endpoint_url: z.string().describe("API endpoint URL").optional(),
+      api_path: z.string().describe("API path for reranking request").optional(),
+      model_identifier: z.string().describe("Model identifier").optional(),
+      supported_modalities: z.array(z.enum(["TEXT", "IMAGE", "AUDIO", "VIDEO"])).describe("Supported content modalities").optional(),
+      credentials: z.object({
+    kind: z.enum(["CREDENTIAL_KIND_UNSPECIFIED", "CREDENTIAL_KIND_API_KEY", "CREDENTIAL_KIND_GCP_ADC"]).describe("Selected credential strategy"),
+    apiKey: z.any().describe("Configuration when kind is CREDENTIAL_KIND_API_KEY").optional(),
+    gcpAdc: z.any().describe("Configuration when kind is CREDENTIAL_KIND_GCP_ADC").optional(),
+    labels: z.record(z.string(), z.string()).describe("Optional annotations to aid operators (e.g., \"owner=vertex\")").optional()
+  }).passthrough().describe("Structured credential payload describing how to authenticate with the provider. Omit to keep existing credentials.").optional(),
+      replace_labels: z.record(z.string(), z.string()).describe("Replace all existing labels with these (mutually exclusive with mergeLabels)").optional(),
+      merge_labels: z.record(z.string(), z.string()).describe("Merge these labels with existing ones (mutually exclusive with replaceLabels)").optional(),
+      version: z.string().describe("Version information").optional(),
+      monitoring_endpoint: z.string().describe("Monitoring endpoint URL").optional()
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.display_name !== undefined) body["displayName"] = args.display_name;
+      if (args.description !== undefined) body["description"] = args.description;
+      if (args.endpoint_url !== undefined) body["endpointUrl"] = args.endpoint_url;
+      if (args.api_path !== undefined) body["apiPath"] = args.api_path;
+      if (args.model_identifier !== undefined) body["modelIdentifier"] = args.model_identifier;
+      if (args.supported_modalities !== undefined) body["supportedModalities"] = args.supported_modalities;
+      if (args.credentials !== undefined) body["credentials"] = args.credentials;
+      if (args.replace_labels !== undefined) body["replaceLabels"] = args.replace_labels;
+      if (args.merge_labels !== undefined) body["mergeLabels"] = args.merge_labels;
+      if (args.version !== undefined) body["version"] = args.version;
+      if (args.monitoring_endpoint !== undefined) body["monitoringEndpoint"] = args.monitoring_endpoint;
+      const result = await callApi("PUT", `/v1/rerankers/${encodeURIComponent(String(args.id))}`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+
+
+  // === spaces ===
+
+  server.tool(
+    "goodmem_spaces_create",
+    "Create a new Space",
+    {
+      name: z.string().describe("The desired name for the space. Must be unique within the user's scope."),
+      labels: z.record(z.string(), z.string()).describe("A set of key-value pairs to categorize or tag the space. Used for filtering and organizational purposes.").optional(),
+      space_embedders: z.array(z.object({
+    embedderId: z.string().describe("The unique identifier for the embedder to associate with the space."),
+    defaultRetrievalWeight: z.number().describe("Relative weight for this embedder used by default during retrieval. If omitted, defaults to 1.0; values need not sum to 1 and can be overridden per request.").optional()
+  }).passthrough()).describe("List of embedder configurations to associate with this space. Each specifies an embedder ID and a relative default retrieval weight used when no per-request overrides are provided."),
+      public_read: z.boolean().describe("Indicates if the space and its memories can be read by unauthenticated users or users other than the owner. Defaults to false.").optional(),
+      owner_id: z.string().describe("Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_SPACE_ANY permission if specified.").optional(),
+      default_chunking_config: z.object({
+    none: z.any().describe("No chunking strategy - preserve original content as single unit").optional(),
+    recursive: z.any().describe("Recursive hierarchical chunking strategy with configurable separators").optional(),
+    sentence: z.any().describe("Sentence-based chunking strategy with language detection").optional()
+  }).passthrough().describe("Default chunking strategy for memories in this space"),
+      space_id: z.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) => {
+      const body: Record<string, unknown> = {};
+      if (args.name !== undefined) body["name"] = args.name;
+      if (args.labels !== undefined) body["labels"] = args.labels;
+      if (args.space_embedders !== undefined) body["spaceEmbedders"] = args.space_embedders;
+      if (args.public_read !== undefined) body["publicRead"] = args.public_read;
+      if (args.owner_id !== undefined) body["ownerId"] = args.owner_id;
+      if (args.default_chunking_config !== undefined) body["defaultChunkingConfig"] = args.default_chunking_config;
+      if (args.space_id !== undefined) body["spaceId"] = args.space_id;
+      const result = await callApi("POST", `/v1/spaces`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_spaces_delete",
+    "Delete a space",
+    {
+      id: z.string().describe("The unique identifier of the space to delete")
+    },
+    async (args) => {
+      await callApi("DELETE", `/v1/spaces/${encodeURIComponent(String(args.id))}`, undefined);
+      return { content: [{ type: "text" as const, text: "Deleted successfully." }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_spaces_get",
+    "Get a space by ID",
+    {
+      id: z.string().describe("The unique identifier of the space to retrieve")
+    },
+    async (args) => {
+      const result = await callApi("GET", `/v1/spaces/${encodeURIComponent(String(args.id))}`, undefined);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_spaces_list",
+    "List spaces",
+    {
+      owner_id: z.string().describe("Filter spaces by owner ID. With LIST_SPACE_ANY permission and ownerId omitted, returns all visible spaces. Otherwise returns caller-owned spaces only. Specifying ownerId without LIST_SPACE_ANY returns PERMISSION_DENIED.").optional(),
+      name_filter: z.string().describe("Filter spaces by name using glob pattern matching").optional(),
+      max_results: z.number().int().describe("Maximum number of results to return in a single page (defaults to 50, clamped to [1, 1000])").optional(),
+      next_token: z.string().describe("Pagination token for retrieving the next set of results").optional(),
+      sort_by: z.string().describe("Field to sort by: 'created_time', 'updated_time', or 'name' (default: 'created_time'). Unsupported values return INVALID_ARGUMENT.").optional(),
+      sort_order: z.enum(["ASCENDING", "DESCENDING", "SORT_ORDER_UNSPECIFIED"]).describe("Sort order (ASCENDING or DESCENDING, default: DESCENDING)").optional()
+    },
+    async (args) => {
+      const query: Record<string, string> = {};
+      if (args.owner_id !== undefined) query["ownerId"] = String(args.owner_id);
+      if (args.name_filter !== undefined) query["nameFilter"] = String(args.name_filter);
+      if (args.max_results !== undefined) query["maxResults"] = String(args.max_results);
+      if (args.next_token !== undefined) query["nextToken"] = String(args.next_token);
+      if (args.sort_by !== undefined) query["sortBy"] = String(args.sort_by);
+      if (args.sort_order !== undefined) query["sortOrder"] = String(args.sort_order);
+      const result = await callApi("GET", `/v1/spaces`, undefined, query);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_spaces_update",
+    "Update a space",
+    {
+      id: z.string().describe("The unique identifier of the space to update"),
+      name: z.string().describe("The new name for the space.").optional(),
+      public_read: z.boolean().describe("Whether the space is publicly readable by all users.").optional(),
+      replace_labels: z.record(z.string(), z.string()).describe("Labels to replace all existing labels. Mutually exclusive with mergeLabels.").optional(),
+      merge_labels: z.record(z.string(), z.string()).describe("Labels to merge with existing labels. Mutually exclusive with replaceLabels.").optional()
+    },
+    async (args) => {
+      const body: Record<string, unknown> = {};
+      if (args.name !== undefined) body["name"] = args.name;
+      if (args.public_read !== undefined) body["publicRead"] = args.public_read;
+      if (args.replace_labels !== undefined) body["replaceLabels"] = args.replace_labels;
+      if (args.merge_labels !== undefined) body["mergeLabels"] = args.merge_labels;
+      const result = await callApi("PUT", `/v1/spaces/${encodeURIComponent(String(args.id))}`, body);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+
+
+  // === system ===
+
+  server.tool(
+    "goodmem_system_info",
+    "Retrieve server build metadata",
+    {},
+    async (args) => {
+      const result = await callApi("GET", `/v1/system/info`, undefined);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_system_init",
+    "Initialize the system",
+    {},
+    async (args) => {
+      const result = await callApi("POST", `/v1/system/init`, undefined);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+
+
+  // === users ===
+
+  server.tool(
+    "goodmem_users_get",
+    "Get a user by ID",
+    {
+      id: z.string().describe("The unique identifier of the user to retrieve").optional(),
+      email: z.string().describe("The email address of the user to retrieve").optional()
+    },
+    async (args) => {
+      const result = await callApi("GET", `/v1/users/${encodeURIComponent(String(args.id))}`, undefined);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    "goodmem_users_me",
+    "Get current user profile",
+    {},
+    async (args) => {
+      const result = await callApi("GET", `/v1/users/me`, undefined);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
+
+}
+
+registerTools();
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});