@dudamel/mcp-memory 2026.1005.3 → 2026.1015.1

package/dist/index.d.ts

@@ -1,4 +1,3 @@
 export { createMemoryServer } from './server.js';
-export { DudamelApiClient, DudamelApiError } from './http-client.js';
 export type { McpMemoryConfig } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,3 +1,533 @@
-export { createMemoryServer } from './server.js';
-export { DudamelApiClient, DudamelApiError } from './http-client.js';
-//# sourceMappingURL=index.js.map
+// src/server.ts
+import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// ../common/dist/http-client.js
+function parseApiErrorBody(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (typeof parsed !== "object" || parsed === null || !("error" in parsed))
+      return void 0;
+    const error = parsed.error;
+    if (typeof error === "object" && error !== null && typeof error.code === "string" && typeof error.message === "string") {
+      return error;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+var DudamelApiError = class extends Error {
+  status;
+  statusText;
+  body;
+  /** Stable machine-readable code from the API error body, or 'UNKNOWN' for non-conforming bodies. */
+  code;
+  /** Per-field validation errors, when the API provided them. */
+  details;
+  /** Extra machine-readable data (e.g. `inputsSchema` on execute validation failures). */
+  context;
+  constructor(status, statusText, body) {
+    const apiError = parseApiErrorBody(body);
+    const lines = [
+      apiError ? `Dudamel API error ${status} ${statusText}: ${apiError.code}: ${apiError.message}` : `Dudamel API error ${status} ${statusText}: ${body}`
+    ];
+    if (apiError?.details?.length) {
+      lines.push(...apiError.details.map((d) => `  - ${d.path}: ${d.message}`));
+    }
+    if (apiError?.context?.["inputsSchema"] !== void 0) {
+      lines.push(`Expected inputs schema: ${JSON.stringify(apiError.context["inputsSchema"])}`);
+    }
+    super(lines.join("\n"));
+    this.status = status;
+    this.statusText = statusText;
+    this.body = body;
+    this.name = "DudamelApiError";
+    this.code = apiError?.code ?? "UNKNOWN";
+    this.details = apiError?.details;
+    this.context = apiError?.context;
+  }
+};
+var DudamelApiClient = class {
+  baseUrl;
+  headers;
+  constructor(baseUrl, apiKey, authScheme) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.headers = {
+      Authorization: `${authScheme ?? "ApiKey"} ${apiKey}`,
+      "Content-Type": "application/json"
+    };
+  }
+  async get(path, params) {
+    const url = this.buildUrl(path, params);
+    return this.request(url, { method: "GET" });
+  }
+  async post(path, body, params) {
+    const url = this.buildUrl(path, params);
+    return this.request(url, {
+      method: "POST",
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+  }
+  async put(path, body, params) {
+    const url = this.buildUrl(path, params);
+    return this.request(url, {
+      method: "PUT",
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+  }
+  async delete(path, params) {
+    const url = this.buildUrl(path, params);
+    return this.request(url, { method: "DELETE" });
+  }
+  buildUrl(path, params) {
+    const url = new URL(path, this.baseUrl);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0 && value !== "") {
+          url.searchParams.set(key, value);
+        }
+      }
+    }
+    return url.toString();
+  }
+  async request(url, init) {
+    const response = await fetch(url, {
+      ...init,
+      headers: this.headers
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new DudamelApiError(response.status, response.statusText, body);
+    }
+    const text = await response.text();
+    if (!text) {
+      return void 0;
+    }
+    return JSON.parse(text);
+  }
+};
+
+// ../common/dist/read-only-filter.js
+function withReadOnlyFilter(server, readOnly) {
+  if (!readOnly)
+    return server;
+  const original = server.registerTool.bind(server);
+  const filtered = (...args) => {
+    const config = args[1];
+    if (config?.annotations?.readOnlyHint === false) {
+      return void 0;
+    }
+    return original(...args);
+  };
+  return new Proxy(server, {
+    get(target, prop, receiver) {
+      if (prop === "registerTool")
+        return filtered;
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+
+// ../common/dist/create-server.js
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// ../common/dist/util.js
+function jsonResult(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+function errorResult(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true
+  };
+}
+
+// src/tools/memories.ts
+import { z as z2 } from "zod";
+
+// src/util.ts
+import { z } from "zod";
+var AGENT_NAME_FIELD = z.string().optional().describe(
+  'The Dudamel agent you are acting as (e.g. "dudamel-expert"). Pass it on every call when you are one \u2014 it is what scopes memories, files and conversations to that agent. Omit it only when you are not acting as any Dudamel agent.'
+);
+function agentNameInput(ctx) {
+  return ctx.agentName === null ? { agentName: AGENT_NAME_FIELD } : {};
+}
+function effectiveAgent(ctx, requested) {
+  return ctx.agentName ?? (requested?.trim() || null);
+}
+function agentParams(ctx, requested) {
+  const agent = effectiveAgent(ctx, requested);
+  return agent ? { agent } : {};
+}
+function agentBody(ctx, requested) {
+  const agent = effectiveAgent(ctx, requested);
+  return agent ? { agentName: agent } : {};
+}
+
+// src/tools/memories.ts
+var SCOPE_HEADER = "Scope of the memory \u2014 this is WHO WILL BE ABLE TO READ IT. Pick the NARROWEST that fits:\n";
+var RELATIONAL_LINE = "- 'relational': you (this agent) + this one user. Nobody else. The default for a preference or fact about the person you are talking to.\n";
+var PROFILE_LINE = "- 'profile': this one user, across ALL agents \u2014 every agent they talk to sees it. For facts about them that any agent should know (their role, timezone, how to reach them).\n";
+var AGENT_LINE = "- 'agent': you (this agent), across ALL users \u2014 everyone who talks to you sees it. For your own working knowledge; never for something about a particular person.\n";
+var ORG_LINE = "- 'org': EVERY agent and EVERY user in the organisation. The widest reach there is \u2014 only for a fact true of the whole organisation that you would be comfortable showing anyone in it.\n";
+function scopeDescription(unbound) {
+  return SCOPE_HEADER + RELATIONAL_LINE + PROFILE_LINE + AGENT_LINE + ORG_LINE + (unbound ? "'relational' and 'agent' need agentName \u2014 without an agent they have no one to belong to. " : "") + "Ask, in order: is this about ONE person (relational/profile) or about nobody in particular (agent/org)? Then: does it really need to be visible beyond this conversation?";
+}
+var AGENT_SCOPES = /* @__PURE__ */ new Set(["relational", "agent"]);
+function registerMemoryTools(server, client, ctx) {
+  const unbound = ctx.agentName === null;
+  const scopes = z2.enum(["relational", "profile", "agent", "org"]);
+  const agentInput = agentNameInput(ctx);
+  server.registerTool(
+    "list-memories",
+    {
+      description: "List memories relevant to the current user (summaries only, NOT full content). Returns the union of everything you know that applies here: your notes on this user, their profile, and your/org general knowledge" + (unbound ? " (without agentName: only their profile and org knowledge). " : ". ") + "Call this at the start of an interaction. You MUST call this before creating a memory. Use get-memory to read a full entry.",
+      inputSchema: {
+        q: z2.string().optional().describe("Keyword filter over summary + content (omit to list all)"),
+        scope: scopes.optional().describe("Filter to a single scope"),
+        ...agentInput
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ q, scope, agentName }) => {
+      try {
+        const params = agentParams(ctx, agentName);
+        if (q) params["q"] = q;
+        if (scope) params["scope"] = scope;
+        const rows = await client.get("/api/chat/memories", params);
+        if (Array.isArray(rows)) {
+          for (const r of rows) if (r.id) ctx.seenIds.add(r.id);
+        }
+        ctx.hasListed = true;
+        return jsonResult(rows);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "get-memory",
+    {
+      description: "Get the full content of a single memory by id. You MUST call this before updating a memory (so you edit its real content, not blindly). Ids come from list-memories.",
+      inputSchema: { id: z2.string().describe("Memory id (from list-memories)"), ...agentInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ id, agentName }) => {
+      try {
+        const memory = await client.get(
+          `/api/chat/memories/${id}`,
+          agentParams(ctx, agentName)
+        );
+        if (memory?.id) {
+          ctx.fetchedIds.add(memory.id);
+          ctx.seenIds.add(memory.id);
+        }
+        return jsonResult(memory);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "create-memory",
+    {
+      description: "Create a NEW memory. Requires a prior list-memories call this session (to avoid duplicates \u2014 if a similar memory exists, use update-memory instead). Content can be multi-line markdown. A one-line summary is generated automatically; if the summary service is unavailable the memory is NOT saved and you should retry later.",
+      inputSchema: {
+        scope: scopes.describe(scopeDescription(unbound)),
+        content: z2.string().describe("Full memory text (multi-line markdown allowed)"),
+        ...agentInput
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ scope, content, agentName }) => {
+      if (!ctx.hasListed) {
+        return errorResult(
+          new Error(
+            "Call list-memories first (to check for an existing memory to update instead of duplicating)."
+          )
+        );
+      }
+      if (AGENT_SCOPES.has(scope) && !effectiveAgent(ctx, agentName)) {
+        return errorResult(
+          new Error(
+            `Scope '${scope}' belongs to an agent: pass agentName (the agent you are acting as), or use 'profile' / 'org'.`
+          )
+        );
+      }
+      try {
+        const result = await client.post("/api/chat/memories", {
+          ...agentBody(ctx, agentName),
+          scope,
+          content
+        });
+        if (result?.id) ctx.seenIds.add(result.id);
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "update-memory",
+    {
+      description: "Update an existing memory's content (its summary is regenerated). You MUST call get-memory on this id first, so you edit its real content. If the summary service is unavailable the memory is NOT updated and you should retry later.",
+      inputSchema: {
+        id: z2.string().describe("Memory id to update"),
+        content: z2.string().describe("New full memory text (replaces the old content)"),
+        ...agentInput
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ id, content, agentName }) => {
+      if (!ctx.fetchedIds.has(id)) {
+        return errorResult(
+          new Error(`Call get-memory("${id}") first so you update its real content, not a guess.`)
+        );
+      }
+      try {
+        const result = await client.put(
+          `/api/chat/memories/${id}`,
+          { content },
+          agentParams(ctx, agentName)
+        );
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "delete-memory",
+    {
+      description: "Delete a memory by id. Requires the id to have been seen via list-memories or get-memory.",
+      inputSchema: { id: z2.string().describe("Memory id to delete"), ...agentInput },
+      annotations: { readOnlyHint: false, destructiveHint: true }
+    },
+    async ({ id, agentName }) => {
+      if (!ctx.seenIds.has(id)) {
+        return errorResult(
+          new Error(`Cannot delete ${id}: not seen in a prior list/get. Call list-memories first.`)
+        );
+      }
+      try {
+        await client.delete(`/api/chat/memories/${id}`, agentParams(ctx, agentName));
+        ctx.seenIds.delete(id);
+        ctx.fetchedIds.delete(id);
+        return jsonResult({ deleted: true, id });
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "mark-memory-useful",
+    {
+      description: "Mark a memory as useful now (bumps its recency ranking). Requires the id to have been seen via list-memories or get-memory.",
+      inputSchema: { id: z2.string().describe("Memory id to mark as useful"), ...agentInput },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ id, agentName }) => {
+      if (!ctx.seenIds.has(id)) {
+        return errorResult(
+          new Error(`Cannot mark ${id}: not seen in a prior list/get. Call list-memories first.`)
+        );
+      }
+      try {
+        const result = await client.post(
+          `/api/chat/memories/${id}/useful`,
+          void 0,
+          agentParams(ctx, agentName)
+        );
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+}
+
+// src/tools/conversations.ts
+import { z as z3 } from "zod";
+function registerConversationTools(server, client, ctx) {
+  server.registerTool(
+    "list-conversations",
+    {
+      description: "List your past conversations. Scoped to the current agent when one is in context; otherwise every conversation you have had, with any agent. Returns conversation metadata including ids, timestamps, and summaries.",
+      inputSchema: { ...agentNameInput(ctx) },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ agentName }) => {
+      try {
+        const result = await client.get("/api/chat/conversations", agentParams(ctx, agentName));
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "get-conversation-messages",
+    {
+      description: "Get the full message history for a specific conversation. Returns all messages in chronological order.",
+      inputSchema: {
+        conversationId: z3.string().describe("The conversation ID to retrieve messages for")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ conversationId }) => {
+      try {
+        const result = await client.get(`/api/chat/conversations/${conversationId}/messages`);
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+}
+
+// src/tools/files.ts
+import { z as z4 } from "zod";
+function registerFileTools(server, client, ctx) {
+  const agentInput = agentNameInput(ctx);
+  server.registerTool(
+    "save-file",
+    {
+      description: "Store a file so it survives this turn. The turn workspace is wiped when the turn ends, so anything you want to keep \u2014 a report, a diff, a generated CSV \u2014 has to be saved here. Returns an id you can hand back to the user or use in a later turn. Content goes base64-encoded.",
+      inputSchema: {
+        fileName: z4.string().describe('Name for the file, e.g. "informe-q3.csv"'),
+        mimeType: z4.string().describe('MIME type, e.g. "text/csv" or "application/pdf"'),
+        contentBase64: z4.string().describe("File content, base64-encoded"),
+        conversationId: z4.string().optional().describe("Conversation this belongs to. Defaults to the current one."),
+        ...agentInput
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ fileName, mimeType, contentBase64, conversationId, agentName }) => {
+      try {
+        return jsonResult(
+          await client.post("/api/chat/files", {
+            fileName,
+            mimeType,
+            contentBase64,
+            // The current conversation unless told otherwise, so the common case needs no
+            // argument and the file is findable where it was produced.
+            conversationId: conversationId ?? ctx.conversationId,
+            ...agentBody(ctx, agentName)
+          })
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "list-files",
+    {
+      description: "List stored files for this conversation (default) or for this agent across conversations. Returns metadata only \u2014 ids, names, types, sizes \u2014 not content.",
+      inputSchema: {
+        conversationId: z4.string().optional().describe("Conversation to list. Defaults to the current one."),
+        allConversations: z4.boolean().optional().describe("List everything this agent saved, not just this conversation's"),
+        limit: z4.number().optional().describe("Max files to return (default 50)"),
+        ...agentInput
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ conversationId, allConversations, limit, agentName }) => {
+      try {
+        const params = agentParams(ctx, agentName);
+        if (!allConversations) {
+          const target = conversationId ?? ctx.conversationId;
+          if (target) params.conversationId = target;
+        }
+        if (limit) params.limit = String(limit);
+        return jsonResult(await client.get("/api/chat/files", params));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "get-file",
+    {
+      description: "Read a stored file by id. Small text files come back with their content inline; anything large or binary returns metadata only, and you should pass the id along rather than trying to read the bytes \u2014 they would not fit in your context anyway.",
+      inputSchema: {
+        id: z4.string().describe("File id from save-file or list-files")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ id }) => {
+      try {
+        return jsonResult(await client.get(`/api/chat/files/${encodeURIComponent(id)}`));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "send-file",
+    {
+      description: "Hand a stored file to the user in this conversation. Use it after save-file when the user should actually receive the file \u2014 saving alone only keeps it. It is delivered right after your reply, through whatever channel you are talking on; you do not need to know which.",
+      inputSchema: {
+        id: z4.string().describe("File id from save-file or list-files")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ id }) => {
+      try {
+        return jsonResult(await client.post(`/api/chat/files/${encodeURIComponent(id)}/send`, {}));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "delete-file",
+    {
+      description: "Delete a stored file permanently. Use it for things you produced and no longer need \u2014 not for files a user uploaded, unless they asked.",
+      inputSchema: {
+        id: z4.string().describe("File id from save-file or list-files")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true }
+    },
+    async ({ id }) => {
+      try {
+        await client.delete(`/api/chat/files/${encodeURIComponent(id)}`);
+        return jsonResult({ deleted: true, id });
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+}
+
+// src/server.ts
+function createMemoryServer(config) {
+  const server = new McpServer2(
+    { name: "dudamel-memory", version: "0.1.0" },
+    {
+      capabilities: { tools: {} },
+      instructions: "Dudamel Memory MCP \u2014 query and manage your memories and past conversations. Always search before creating or updating a memory to avoid duplicates. Write tools require a prior search in the same session. Files: the turn workspace is wiped when the turn ends, so use save-file for anything that must outlive it."
+    }
+  );
+  const client = new DudamelApiClient(config.apiUrl, config.apiKey, config.authScheme);
+  const ctx = {
+    userId: config.userId,
+    agentName: config.agentName,
+    seenIds: /* @__PURE__ */ new Set(),
+    fetchedIds: /* @__PURE__ */ new Set(),
+    hasListed: false,
+    conversationId: config.conversationId
+  };
+  const host = withReadOnlyFilter(server, config.readOnly ?? false);
+  registerMemoryTools(host, client, ctx);
+  registerConversationTools(host, client, ctx);
+  registerFileTools(host, client, ctx);
+  return server;
+}
+export {
+  createMemoryServer
+};

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,YAAY,CAAC;AAE/D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CA6BrE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,YAAY,CAAC;AAE/D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CA+BrE"}