@dudamel/mcp-agents 2026.1005.2 → 2026.1008.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -153,6 +153,8 @@ function jsonResult(data) {
153
153
  }
154
154
 
155
155
  // src/tools/agents.ts
156
+ import { readFile, stat } from "node:fs/promises";
157
+ import { extname, resolve } from "node:path";
156
158
  import { z } from "zod";
157
159
  function registerAgentTools(server, client, ctx) {
158
160
  server.registerTool(
@@ -283,6 +285,22 @@ function registerAgentTools(server, client, ctx) {
283
285
  return jsonResult(result);
284
286
  }
285
287
  );
288
+ server.registerTool(
289
+ "set-agent-avatar",
290
+ {
291
+ description: "Set an agent's avatar (its picture in the Dashboard, chat and lists) from an image file on disk \u2014 typically one the user attached to the conversation, which you find under `.attachments/` in your workspace. PNG, JPEG, WebP or GIF, under 2 MB. Replaces the current avatar. Needs edit permission on the agent.",
292
+ inputSchema: {
293
+ id: z.string().describe("Agent ID (UUID)"),
294
+ imagePath: z.string().describe("Path to the image file, e.g. .attachments/selfie.png (relative to your cwd)")
295
+ },
296
+ annotations: { readOnlyHint: false, destructiveHint: false }
297
+ },
298
+ async ({ id, imagePath }) => {
299
+ const { imageData, mimeType, bytes } = await readAvatarFile(imagePath);
300
+ await client.post(`/api/agents/${id}/avatar`, { imageData, mimeType });
301
+ return jsonResult({ id, avatar: { mimeType, bytes } });
302
+ }
303
+ );
286
304
  if (ctx.role !== "admin") return;
287
305
  server.registerTool(
288
306
  "get-agent-logs",
@@ -355,14 +373,40 @@ function registerAgentTools(server, client, ctx) {
355
373
  }
356
374
  );
357
375
  }
376
+ var AVATAR_MIME_BY_EXT = {
377
+ ".png": "image/png",
378
+ ".jpg": "image/jpeg",
379
+ ".jpeg": "image/jpeg",
380
+ ".webp": "image/webp",
381
+ ".gif": "image/gif"
382
+ };
383
+ var MAX_AVATAR_BYTES = 2 * 1024 * 1024;
384
+ async function readAvatarFile(imagePath) {
385
+ const path = resolve(imagePath);
386
+ const mimeType = AVATAR_MIME_BY_EXT[extname(path).toLowerCase()];
387
+ if (!mimeType) {
388
+ throw new Error(
389
+ `Unsupported avatar format "${extname(path) || "(no extension)"}": use PNG, JPEG, WebP or GIF.`
390
+ );
391
+ }
392
+ const info = await stat(path).catch(() => void 0);
393
+ if (!info?.isFile()) throw new Error(`Avatar file not found or not readable: ${path}`);
394
+ if (info.size > MAX_AVATAR_BYTES) {
395
+ throw new Error(
396
+ `Avatar is ${(info.size / 1024 / 1024).toFixed(1)} MB; the limit is 2 MB. Ask the user for a smaller image (or a crop) \u2014 do not try to shrink it yourself.`
397
+ );
398
+ }
399
+ const buffer = await readFile(path);
400
+ return { imageData: buffer.toString("base64"), mimeType, bytes: buffer.length };
401
+ }
358
402
 
359
403
  // src/tools/skills.ts
360
404
  import { z as z2 } from "zod";
361
405
 
362
406
  // src/skill-bundle.ts
363
407
  import { createHash } from "node:crypto";
364
- import { mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
365
- import { dirname, join, relative, resolve, sep } from "node:path";
408
+ import { mkdir, readdir, readFile as readFile2, realpath, writeFile } from "node:fs/promises";
409
+ import { dirname, join, relative, resolve as resolve2, sep } from "node:path";
366
410
  var EXCLUDED = /* @__PURE__ */ new Set([".git", "node_modules", "__pycache__", ".venv", ".DS_Store"]);
367
411
  var MAX_PATH_LENGTH = 512;
368
412
  var MAX_FILES = 200;
@@ -390,7 +434,7 @@ function decodeUtf8(raw, relPath, notText) {
390
434
  }
391
435
  }
392
436
  async function readSkillDir(skillDir) {
393
- const root = resolve(skillDir);
437
+ const root = resolve2(skillDir);
394
438
  let realRoot;
395
439
  try {
396
440
  realRoot = await realpath(root);
@@ -399,7 +443,7 @@ async function readSkillDir(skillDir) {
399
443
  }
400
444
  let content;
401
445
  try {
402
- content = await readFile(join(realRoot, SKILL_MD), "utf8");
446
+ content = await readFile2(join(realRoot, SKILL_MD), "utf8");
403
447
  } catch {
404
448
  throw new Error(
405
449
  `${SKILL_MD} not found at the root of ${root}. A skill directory must contain ${SKILL_MD}; use download-skill with outDir to get the expected layout.`
@@ -438,7 +482,7 @@ async function readSkillDir(skillDir) {
438
482
  tooLongPath.push(relPath);
439
483
  continue;
440
484
  }
441
- const text = decodeUtf8(await readFile(resolved), relPath, notText);
485
+ const text = decodeUtf8(await readFile2(resolved), relPath, notText);
442
486
  if (text !== void 0) files.push({ path: relPath, content: text });
443
487
  }
444
488
  }
@@ -482,11 +526,11 @@ async function isDirectory(path) {
482
526
  }
483
527
  }
484
528
  async function writeSkillFiles(outDir, files, opts) {
485
- const root = resolve(outDir);
529
+ const root = resolve2(outDir);
486
530
  await mkdir(root, { recursive: true });
487
531
  const realRoot = await realpath(root);
488
532
  const targets = files.map((file) => {
489
- const target = resolve(realRoot, file.path);
533
+ const target = resolve2(realRoot, file.path);
490
534
  if (target !== realRoot && !target.startsWith(realRoot + sep)) {
491
535
  throw new Error(`Refusing to write outside outDir: ${file.path}`);
492
536
  }
@@ -495,7 +539,7 @@ async function writeSkillFiles(outDir, files, opts) {
495
539
  if (!opts.overwrite) {
496
540
  const conflicts = [];
497
541
  for (const { file, target } of targets) {
498
- const existing = await readFile(target, "utf8").catch(() => void 0);
542
+ const existing = await readFile2(target, "utf8").catch(() => void 0);
499
543
  if (existing !== void 0 && existing !== file.content) conflicts.push(file.path);
500
544
  }
501
545
  if (conflicts.length > 0) {
@@ -196,6 +196,8 @@ function jsonResult(data) {
196
196
  }
197
197
 
198
198
  // src/tools/agents.ts
199
+ import { readFile, stat } from "node:fs/promises";
200
+ import { extname, resolve } from "node:path";
199
201
  import { z } from "zod";
200
202
  function registerAgentTools(server2, client, ctx2) {
201
203
  server2.registerTool(
@@ -326,6 +328,22 @@ function registerAgentTools(server2, client, ctx2) {
326
328
  return jsonResult(result);
327
329
  }
328
330
  );
331
+ server2.registerTool(
332
+ "set-agent-avatar",
333
+ {
334
+ description: "Set an agent's avatar (its picture in the Dashboard, chat and lists) from an image file on disk \u2014 typically one the user attached to the conversation, which you find under `.attachments/` in your workspace. PNG, JPEG, WebP or GIF, under 2 MB. Replaces the current avatar. Needs edit permission on the agent.",
335
+ inputSchema: {
336
+ id: z.string().describe("Agent ID (UUID)"),
337
+ imagePath: z.string().describe("Path to the image file, e.g. .attachments/selfie.png (relative to your cwd)")
338
+ },
339
+ annotations: { readOnlyHint: false, destructiveHint: false }
340
+ },
341
+ async ({ id, imagePath }) => {
342
+ const { imageData, mimeType, bytes } = await readAvatarFile(imagePath);
343
+ await client.post(`/api/agents/${id}/avatar`, { imageData, mimeType });
344
+ return jsonResult({ id, avatar: { mimeType, bytes } });
345
+ }
346
+ );
329
347
  if (ctx2.role !== "admin") return;
330
348
  server2.registerTool(
331
349
  "get-agent-logs",
@@ -398,14 +416,40 @@ function registerAgentTools(server2, client, ctx2) {
398
416
  }
399
417
  );
400
418
  }
419
+ var AVATAR_MIME_BY_EXT = {
420
+ ".png": "image/png",
421
+ ".jpg": "image/jpeg",
422
+ ".jpeg": "image/jpeg",
423
+ ".webp": "image/webp",
424
+ ".gif": "image/gif"
425
+ };
426
+ var MAX_AVATAR_BYTES = 2 * 1024 * 1024;
427
+ async function readAvatarFile(imagePath) {
428
+ const path = resolve(imagePath);
429
+ const mimeType = AVATAR_MIME_BY_EXT[extname(path).toLowerCase()];
430
+ if (!mimeType) {
431
+ throw new Error(
432
+ `Unsupported avatar format "${extname(path) || "(no extension)"}": use PNG, JPEG, WebP or GIF.`
433
+ );
434
+ }
435
+ const info = await stat(path).catch(() => void 0);
436
+ if (!info?.isFile()) throw new Error(`Avatar file not found or not readable: ${path}`);
437
+ if (info.size > MAX_AVATAR_BYTES) {
438
+ throw new Error(
439
+ `Avatar is ${(info.size / 1024 / 1024).toFixed(1)} MB; the limit is 2 MB. Ask the user for a smaller image (or a crop) \u2014 do not try to shrink it yourself.`
440
+ );
441
+ }
442
+ const buffer = await readFile(path);
443
+ return { imageData: buffer.toString("base64"), mimeType, bytes: buffer.length };
444
+ }
401
445
 
402
446
  // src/tools/skills.ts
403
447
  import { z as z2 } from "zod";
404
448
 
405
449
  // src/skill-bundle.ts
406
450
  import { createHash } from "node:crypto";
407
- import { mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
408
- import { dirname, join, relative, resolve, sep } from "node:path";
451
+ import { mkdir, readdir, readFile as readFile2, realpath, writeFile } from "node:fs/promises";
452
+ import { dirname, join, relative, resolve as resolve2, sep } from "node:path";
409
453
  var EXCLUDED = /* @__PURE__ */ new Set([".git", "node_modules", "__pycache__", ".venv", ".DS_Store"]);
410
454
  var MAX_PATH_LENGTH = 512;
411
455
  var MAX_FILES = 200;
@@ -433,7 +477,7 @@ function decodeUtf8(raw, relPath, notText) {
433
477
  }
434
478
  }
435
479
  async function readSkillDir(skillDir) {
436
- const root = resolve(skillDir);
480
+ const root = resolve2(skillDir);
437
481
  let realRoot;
438
482
  try {
439
483
  realRoot = await realpath(root);
@@ -442,7 +486,7 @@ async function readSkillDir(skillDir) {
442
486
  }
443
487
  let content;
444
488
  try {
445
- content = await readFile(join(realRoot, SKILL_MD), "utf8");
489
+ content = await readFile2(join(realRoot, SKILL_MD), "utf8");
446
490
  } catch {
447
491
  throw new Error(
448
492
  `${SKILL_MD} not found at the root of ${root}. A skill directory must contain ${SKILL_MD}; use download-skill with outDir to get the expected layout.`
@@ -481,7 +525,7 @@ async function readSkillDir(skillDir) {
481
525
  tooLongPath.push(relPath);
482
526
  continue;
483
527
  }
484
- const text = decodeUtf8(await readFile(resolved), relPath, notText);
528
+ const text = decodeUtf8(await readFile2(resolved), relPath, notText);
485
529
  if (text !== void 0) files.push({ path: relPath, content: text });
486
530
  }
487
531
  }
@@ -525,11 +569,11 @@ async function isDirectory(path) {
525
569
  }
526
570
  }
527
571
  async function writeSkillFiles(outDir, files, opts) {
528
- const root = resolve(outDir);
572
+ const root = resolve2(outDir);
529
573
  await mkdir(root, { recursive: true });
530
574
  const realRoot = await realpath(root);
531
575
  const targets = files.map((file) => {
532
- const target = resolve(realRoot, file.path);
576
+ const target = resolve2(realRoot, file.path);
533
577
  if (target !== realRoot && !target.startsWith(realRoot + sep)) {
534
578
  throw new Error(`Refusing to write outside outDir: ${file.path}`);
535
579
  }
@@ -538,7 +582,7 @@ async function writeSkillFiles(outDir, files, opts) {
538
582
  if (!opts.overwrite) {
539
583
  const conflicts = [];
540
584
  for (const { file, target } of targets) {
541
- const existing = await readFile(target, "utf8").catch(() => void 0);
585
+ const existing = await readFile2(target, "utf8").catch(() => void 0);
542
586
  if (existing !== void 0 && existing !== file.content) conflicts.push(file.path);
543
587
  }
544
588
  if (conflicts.length > 0) {
@@ -2,4 +2,14 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
2
  import type { DudamelApiClient } from '@dudamel/mcp-common';
3
3
  import type { ToolContext } from '@dudamel/mcp-common';
4
4
  export declare function registerAgentTools(server: McpServer, client: DudamelApiClient, ctx: ToolContext): void;
5
+ /**
6
+ * Read an avatar from disk. Like skill bundles, the file never travels through the model's
7
+ * context: the agent names a path, this process reads it. Fails loudly — an avatar the user
8
+ * believes was set and was not is exactly the silent drop this tool exists to remove.
9
+ */
10
+ export declare function readAvatarFile(imagePath: string): Promise<{
11
+ imageData: string;
12
+ mimeType: string;
13
+ bytes: number;
14
+ }>;
5
15
  //# sourceMappingURL=agents.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/tools/agents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,WAAW,GACf,IAAI,CAoRN"}
1
+ {"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/tools/agents.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,WAAW,GACf,IAAI,CA2SN;AAYD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBjE"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dudamel/mcp-agents",
3
- "version": "2026.1005.2",
3
+ "version": "2026.1008.1",
4
4
  "description": "Dudamel agents MCP — stdio client for Dudamel's agents management surface over its REST API.",
5
5
  "license": "SEE LICENSE IN LICENSE.md",
6
6
  "type": "module",
@@ -27,17 +27,17 @@
27
27
  "access": "public"
28
28
  },
29
29
  "dependencies": {
30
- "@modelcontextprotocol/sdk": "^1.12.1",
30
+ "@modelcontextprotocol/sdk": "^1.31.0",
31
31
  "zod": "^3.24.4"
32
32
  },
33
33
  "devDependencies": {
34
34
  "esbuild": "^0.25.0",
35
35
  "@dudamel/contracts": "0.1.0",
36
- "@dudamel/mcp-tool-contract": "0.1.0",
37
- "@dudamel/mcp-common": "0.1.0"
36
+ "@dudamel/mcp-common": "0.1.0",
37
+ "@dudamel/mcp-tool-contract": "0.1.0"
38
38
  },
39
39
  "scripts": {
40
- "build": "esbuild src/stdio-server.ts src/index.ts --bundle --platform=node --target=node20 --format=esm --outdir=dist --external:@modelcontextprotocol/sdk --external:zod && tsc --emitDeclarationOnly",
40
+ "build": "esbuild src/stdio-server.ts src/index.ts --bundle --platform=node --target=node22 --format=esm --outdir=dist --external:@modelcontextprotocol/sdk --external:zod && tsc --emitDeclarationOnly",
41
41
  "lint": "eslint src/",
42
42
  "lint:fix": "eslint src/ --fix",
43
43
  "test": "vitest run --passWithNoTests",