@dudamel/mcp-agents 2026.917.2

package/dist/index.js

@@ -0,0 +1,753 @@
+// ../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) {
+    const url = this.buildUrl(path);
+    return this.request(url, {
+      method: "POST",
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+  }
+  async put(path, body) {
+    const url = this.buildUrl(path);
+    return this.request(url, {
+      method: "PUT",
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+  }
+  async delete(path) {
+    const url = this.buildUrl(path);
+    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";
+function createSurfaceServer(opts) {
+  const { config } = opts;
+  const server = new McpServer({ name: opts.name, version: "0.1.0" }, {
+    capabilities: { tools: {} },
+    instructions: opts.instructions
+  });
+  const client = new DudamelApiClient(config.apiUrl, config.apiKey, config.authScheme);
+  const ctx = {
+    role: config.role,
+    readOnly: config.readOnly ?? false,
+    agentName: config.agentName,
+    callChain: config.callChain,
+    turnId: config.turnId,
+    rootTurnId: config.rootTurnId,
+    conversationId: config.conversationId,
+    requesterUserId: config.requesterUserId,
+    responseTarget: config.responseTarget
+  };
+  const host = withReadOnlyFilter(server, ctx.readOnly);
+  for (const register of opts.registrars)
+    register(host, client, ctx);
+  return server;
+}
+
+// ../common/dist/util.js
+function jsonResult(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+
+// src/tools/agents.ts
+import { z } from "zod";
+function registerAgentTools(server, client, ctx) {
+  server.registerTool(
+    "list-agents",
+    {
+      description: "List all agent definitions. Returns name, description, status, and config for each agent.",
+      annotations: { readOnlyHint: true }
+    },
+    async () => {
+      const page = await client.get("/api/agents");
+      return jsonResult({ items: page.items, total: page.total });
+    }
+  );
+  server.registerTool(
+    "get-agent",
+    {
+      description: "Get detailed information about a specific agent, including prompt sections, system prompt, and config.",
+      inputSchema: {
+        id: z.string().describe("Agent ID (UUID)")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ id }) => {
+      const agent = await client.get(`/api/agents/${id}`);
+      return jsonResult(agent);
+    }
+  );
+  server.registerTool(
+    "get-agent-logs",
+    {
+      description: "Get the agent's recent conversational turns, newest first \u2014 status, duration, model, tokens, the MCP servers the turn brought up, and the failure reason when it failed. This is the way to debug an agent that is not answering: a `failed` turn carries the error code and the CLI stderr tail. Returns metadata only, never the conversation text.",
+      inputSchema: {
+        id: z.string().describe("Agent ID (UUID)"),
+        status: z.enum(["completed", "failed"]).optional().describe("Only return turns with this outcome"),
+        limit: z.number().int().min(1).max(200).optional().describe("Number of turns to return (default: 50)"),
+        offset: z.number().int().min(0).optional().describe("Pagination offset")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ id, status, limit, offset }) => {
+      const params = {};
+      if (status !== void 0) params.status = status;
+      if (limit !== void 0) params.limit = String(limit);
+      if (offset !== void 0) params.offset = String(offset);
+      const page = await client.get(
+        `/api/agents/${id}/turns`,
+        params
+      );
+      return jsonResult({
+        items: page.items,
+        total: page.total,
+        offset: page.offset,
+        limit: page.limit,
+        consecutiveFailures: page.consecutiveFailures
+      });
+    }
+  );
+  server.registerTool(
+    "get-agent-stats",
+    {
+      description: "Get token usage statistics per agent over a time window. Useful for monitoring costs.",
+      inputSchema: {
+        windowHours: z.number().int().min(1).optional().describe("Time window in hours (default: 24)")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ windowHours }) => {
+      const params = {};
+      if (windowHours !== void 0) params.window = String(windowHours);
+      const page = await client.get("/api/agents/stats/tokens", params);
+      return jsonResult({ items: page.items, total: page.total });
+    }
+  );
+  server.registerTool(
+    "get-agent-sub-agents",
+    {
+      description: "List the sub-agents assigned to a specific (parent) agent.",
+      inputSchema: {
+        id: z.string().describe("Parent agent ID (UUID)")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ id }) => {
+      const page = await client.get(`/api/agents/${id}/sub-agents`);
+      return jsonResult({ items: page.items, total: page.total });
+    }
+  );
+  server.registerTool(
+    "download-agent",
+    {
+      description: "Download an agent definition (persona + skills) as files in the target tool's on-disk layout (e.g. .claude/agents/<name>.md + .claude/skills/ for Claude Code). Returns {agentName, files: [{path, content, skipIfExists?}]} \u2014 write each file at its path relative to the current working directory; do NOT overwrite existing files marked skipIfExists. Iterate locally, then push changes back with update-agent/update-skill.",
+      inputSchema: {
+        id: z.string().describe("Agent ID (UUID)"),
+        format: z.enum(["claude-code", "codex", "kimi-code", "opencode", "raw"]).optional().describe(
+          "Target tool layout \u2014 defaults to 'claude-code'; 'raw' is a dudamel-native <name>/AGENT.md layout"
+        )
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ id, format }) => {
+      const result = await client.get(`/api/agents/${id}/export?format=${format ?? "claude-code"}`);
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "send-message-to-agent",
+    {
+      description: "Send a message to a PEER Dudamel agent and get their response. Peers are the agents listed in the Peer Agents section of your system prompt: separate agents with their own tools, memory and history, running in their own process. This is the ONLY way to reach them \u2014 your coding tool's own agent-messaging tool (e.g. SendMessage) sees only subagents spawned inside your session and cannot reach a peer. Use this to delegate tasks to or ask questions of another Dudamel agent.",
+      inputSchema: {
+        agentName: z.string().describe("Target agent name (as shown in the peer agents list)"),
+        message: z.string().describe("Message to send to the target agent")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ agentName, message }) => {
+      const result = await client.post(
+        `/api/agents/by-name/${encodeURIComponent(agentName)}/message`,
+        // The chain this turn arrived with, plus ourselves (Plan 43 C1). This used to send a
+        // hardcoded `depth: 0`, which made the server's depth guard decorative: nothing ever
+        // reported being deeper than zero, so A→B→C→D was unbounded and A→B→A unnoticed.
+        {
+          message,
+          callChain: [...ctx.callChain ?? [], ...ctx.agentName ? [ctx.agentName] : []],
+          fromAgent: ctx.agentName,
+          // Plan 43 C3: the callee's turn records WHICH turn asked, so a multi-agent
+          // interaction can be reconstructed as a tree instead of guessed from timestamps.
+          parentTurnId: ctx.turnId,
+          rootTurnId: ctx.rootTurnId ?? ctx.turnId
+        }
+      );
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "notify-agent",
+    {
+      description: "Hand control back to the conversation that launched THIS workflow run. Use it to report an outcome or to ask the user something through the agent, from a workflow step. Only works from inside a workflow execution, and only for the conversation that launched it \u2014 pass the ids from `{{ trigger.callback }}`. Nobody is blocked waiting: the message is delivered and the agent answers in its own channel.",
+      inputSchema: {
+        conversationId: z.string().describe("From `{{ trigger.callback.conversationId }}` \u2014 the conversation to resume"),
+        message: z.string().describe("What to tell the agent (it will act on it, not echo it)")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ conversationId, message }) => {
+      const executionWorkflowId = process.env["DUDAMEL_WORKFLOW_ID"];
+      if (!executionWorkflowId) {
+        throw new Error(
+          "notify-agent requires a workflow execution context (DUDAMEL_WORKFLOW_ID) \u2014 it only works from a workflow step, not from an agent conversation."
+        );
+      }
+      const result = await client.post("/api/agents/notify", {
+        conversationId,
+        executionWorkflowId,
+        message,
+        callChain: ctx.callChain
+      });
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "ask-agent",
+    {
+      description: 'Ask the human a question THROUGH the agent, from a workflow step, and park this run until they answer. Pair it with a `waitForSignal` step on the same `signalName`. Unlike a fixed approval prompt, the agent turns a free-form answer ("s\xED dale, pero solo staging") into the structured payload your signal expects. Only works inside a workflow execution, and only for the conversation that launched it \u2014 pass the id from `{{ trigger.callback.conversationId }}`.',
+      inputSchema: {
+        conversationId: z.string().describe("From `{{ trigger.callback.conversationId }}` \u2014 where to ask"),
+        question: z.string().describe("What to ask the human, in their language"),
+        signalName: z.string().optional().describe("Signal your waitForSignal step listens on (default: humanApproval)")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ conversationId, question, signalName }) => {
+      const executionWorkflowId = process.env["DUDAMEL_WORKFLOW_ID"];
+      if (!executionWorkflowId) {
+        throw new Error(
+          "ask-agent requires a workflow execution context (DUDAMEL_WORKFLOW_ID) \u2014 it only works from a workflow step, not from an agent conversation."
+        );
+      }
+      const result = await client.post("/api/conversation-waits", {
+        conversationId,
+        executionWorkflowId,
+        question,
+        signalName: signalName ?? "humanApproval",
+        callChain: ctx.callChain
+      });
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "answer-workflow",
+    {
+      description: "Unblock a workflow that is waiting on the human, with the answer turned into the payload it expects. Call it once you actually have the answer \u2014 translating what the person said into structured fields is your job here, and the reason a workflow asks through you instead of posting a fixed form.",
+      inputSchema: {
+        waitId: z.string().describe("The waitId the workflow gave you when it asked"),
+        payload: z.record(z.unknown()).optional().describe('Structured answer for the signal, e.g. {"approved": true, "env": "staging"}')
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ waitId, payload }) => {
+      const result = await client.post("/api/conversation-waits/answer", { waitId, payload });
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "update-agent",
+    {
+      description: "Update an agent definition. Requires edit permission on the agent (business-role permission or admin).",
+      inputSchema: {
+        id: z.string().describe("Agent ID (UUID)"),
+        name: z.string().optional().describe("New name"),
+        displayName: z.string().optional().describe("New display name"),
+        description: z.string().optional().describe("New description"),
+        identity: z.string().optional().describe("New identity"),
+        instructions: z.string().optional().describe("New instructions"),
+        systemPrompt: z.string().optional().describe("New system prompt"),
+        model: z.string().optional().describe("New model identifier"),
+        skipPermissions: z.boolean().optional().describe("Skip permission prompts"),
+        driverProvider: z.string().optional().describe("New AI provider instance name"),
+        driverMode: z.enum(["api", "cli"]).optional().describe("New driver mode"),
+        kind: z.enum(["system", "user"]).optional().describe(
+          "Agent kind \u2014 set to 'user' to convert a disk-seeded 'system' agent into a normal editable user agent"
+        )
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ id, ...updates }) => {
+      const result = await client.put(`/api/agents/${id}`, updates);
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "set-agent-sub-agents",
+    {
+      description: "Set the sub-agent assignments for a (parent) agent. Replaces existing assignments. Each sub-agent id must be an agent created with isSubAgent=true. Requires edit permission on the parent agent.",
+      inputSchema: {
+        id: z.string().describe("Parent agent ID (UUID)"),
+        subAgentIds: z.array(z.string()).describe("Sub-agent IDs (UUIDs) to assign")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ id, subAgentIds }) => {
+      const page = await client.put(`/api/agents/${id}/sub-agents`, {
+        subAgentIds
+      });
+      return jsonResult({ subAgentIds: page.items });
+    }
+  );
+  if (ctx.role !== "admin") return;
+  server.registerTool(
+    "create-agent",
+    {
+      description: "Create a new agent definition.",
+      inputSchema: {
+        name: z.string().describe("Agent name (unique, kebab-case)"),
+        displayName: z.string().optional().describe("Display name shown in the UI"),
+        description: z.string().optional().describe("Agent description"),
+        identity: z.string().optional().describe('Agent identity (e.g. "senior backend developer")'),
+        instructions: z.string().optional().describe("Agent instructions (appended to system prompt)"),
+        systemPrompt: z.string().optional().describe("System prompt for the agent"),
+        model: z.string().optional().describe('Model identifier (e.g. "claude-sonnet-4-6")'),
+        skipPermissions: z.boolean().optional().describe("Skip permission prompts in coding agents"),
+        driverProvider: z.string().optional().describe("AI provider instance name for the driver"),
+        driverMode: z.enum(["api", "cli"]).optional().describe("Driver mode: api (conversational) or cli (coding)"),
+        isSubAgent: z.boolean().optional().describe("Mark as a sub-agent (not shown in top-level lists)")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ name, ...rest }) => {
+      const result = await client.post("/api/agents", { name, ...rest });
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "activate-agent",
+    {
+      description: "Activate an agent so it starts receiving and answering messages.",
+      inputSchema: {
+        id: z.string().describe("Agent ID (UUID)")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ id }) => {
+      const result = await client.post(`/api/agents/${id}/activate`);
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "deactivate-agent",
+    {
+      description: "Deactivate an agent \u2014 it stops receiving messages (Slack, dashboard chat) until reactivated. The definition is kept; this is the way to silence an agent without deleting it.",
+      inputSchema: {
+        id: z.string().describe("Agent ID (UUID)")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ id }) => {
+      const result = await client.post(`/api/agents/${id}/deactivate`);
+      return jsonResult(result);
+    }
+  );
+}
+
+// src/tools/skills.ts
+import { z as z2 } from "zod";
+function registerSkillTools(server, client, ctx) {
+  server.registerTool(
+    "list-skills",
+    {
+      description: "List skill definitions (active by default). Returns id, name, description, status, origin, version, and timestamps.",
+      inputSchema: {
+        status: z2.enum(["active", "archived"]).optional().describe("Lifecycle filter \u2014 defaults to 'active'; pass 'archived' for archived skills")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ status }) => {
+      const query = status ? `?status=${status}` : "";
+      const page = await client.get(`/api/skills${query}`);
+      return jsonResult({ items: page.items, total: page.total });
+    }
+  );
+  server.registerTool(
+    "get-skill",
+    {
+      description: "Get detailed information about a specific skill, including content, allowed tools, files, and version info.",
+      inputSchema: {
+        id: z2.string().describe("Skill ID (UUID)")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ id }) => {
+      const skill = await client.get(`/api/skills/${id}`);
+      return jsonResult(skill);
+    }
+  );
+  server.registerTool(
+    "get-skill-versions",
+    {
+      description: "List version history for a skill. Returns version numbers, change summaries, and creation dates.",
+      inputSchema: {
+        id: z2.string().describe("Skill ID (UUID)")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ id }) => {
+      const page = await client.get(`/api/skills/${id}/versions`);
+      return jsonResult({ items: page.items, total: page.total });
+    }
+  );
+  server.registerTool(
+    "download-skill",
+    {
+      description: "Download a skill as files in the target tool's on-disk layout (e.g. .claude/skills/<name>/SKILL.md for Claude Code). Returns {files: [{path, content}]} \u2014 write each file at its path relative to the current working directory. Iterate locally, then push changes back with update-skill.",
+      inputSchema: {
+        id: z2.string().describe("Skill ID (UUID)"),
+        format: z2.enum(["claude-code", "codex", "kimi-code", "opencode", "raw"]).optional().describe(
+          "Target tool layout \u2014 defaults to 'claude-code'; 'raw' is the dudamel-native <name>/SKILL.md layout"
+        )
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ id, format }) => {
+      const result = await client.get(`/api/skills/${id}/export?format=${format ?? "claude-code"}`);
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "get-agent-skills",
+    {
+      description: "Get the skill definitions assigned to a specific agent.",
+      inputSchema: {
+        agentId: z2.string().describe("Agent ID (UUID)")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ agentId }) => {
+      const page = await client.get(`/api/agents/${agentId}/skills`);
+      return jsonResult({ items: page.items, total: page.total });
+    }
+  );
+  if (ctx.readOnly) return;
+  server.registerTool(
+    "create-skill",
+    {
+      description: "Create a new skill definition. The creator becomes the owner and can edit it and share edition with business roles via set-skill-roles.",
+      inputSchema: {
+        name: z2.string().describe("Skill name (unique, kebab-case)"),
+        content: z2.string().describe("Skill content (markdown body)"),
+        description: z2.string().optional().describe("Skill description"),
+        disableModelInvocation: z2.boolean().optional().describe("Disable model-triggered invocation"),
+        userInvocable: z2.boolean().optional().describe("Allow user to invoke via slash command"),
+        model: z2.string().optional().describe("Model identifier or tier"),
+        allowedTools: z2.array(z2.string()).optional().describe("List of allowed tool names"),
+        currentVersion: z2.string().optional().describe("Initial version string"),
+        files: z2.array(
+          z2.object({
+            path: z2.string().describe("Relative file path within the skill"),
+            content: z2.string().describe("File content")
+          })
+        ).optional().describe("Embedded skill files")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({
+      name,
+      content,
+      description,
+      disableModelInvocation,
+      userInvocable,
+      model,
+      allowedTools,
+      currentVersion,
+      files
+    }) => {
+      const result = await client.post("/api/skills", {
+        name,
+        content,
+        description,
+        disableModelInvocation,
+        userInvocable,
+        model,
+        allowedTools,
+        currentVersion,
+        files
+      });
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "update-skill",
+    {
+      description: "Update a skill definition. Creates a new version entry.",
+      inputSchema: {
+        id: z2.string().describe("Skill ID (UUID)"),
+        name: z2.string().optional().describe(
+          "New skill name (unique, kebab-case) \u2014 rename the skill; agent assignments are by id and survive the rename"
+        ),
+        content: z2.string().optional().describe("New skill content"),
+        description: z2.string().optional().describe("New description"),
+        disableModelInvocation: z2.boolean().optional().describe("Disable model-triggered invocation"),
+        userInvocable: z2.boolean().optional().describe("Allow user to invoke via slash command"),
+        model: z2.string().optional().describe("Model identifier or tier"),
+        allowedTools: z2.array(z2.string()).optional().describe("List of allowed tool names"),
+        currentVersion: z2.string().optional().describe("Version string for this update"),
+        changeSummary: z2.string().optional().describe("Summary of what changed in this version"),
+        files: z2.array(
+          z2.object({
+            path: z2.string().describe("Relative file path within the skill"),
+            content: z2.string().describe("File content")
+          })
+        ).optional().describe("Embedded skill files")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ id, ...updates }) => {
+      const result = await client.put(`/api/skills/${id}`, updates);
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "archive-skill",
+    {
+      description: "Archive a skill (logical delete \u2014 versions and files are kept; it disappears from default listings and cannot be assigned). Fails with SKILL_IN_USE while assigned to agents: unassign it first.",
+      inputSchema: {
+        id: z2.string().describe("Skill ID (UUID)")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ id }) => {
+      const result = await client.post(`/api/skills/${id}/archive`);
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "unarchive-skill",
+    {
+      description: "Restore an archived skill to active, making it assignable again.",
+      inputSchema: {
+        id: z2.string().describe("Skill ID (UUID)")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ id }) => {
+      const result = await client.post(`/api/skills/${id}/unarchive`);
+      return jsonResult(result);
+    }
+  );
+  server.registerTool(
+    "get-skill-roles",
+    {
+      description: "List the business roles that can edit a skill. Requires edit permission on the skill (owner, permitted role, or admin).",
+      inputSchema: {
+        id: z2.string().describe("Skill ID (UUID)")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ id }) => {
+      const page = await client.get(`/api/skills/${id}/permissions`);
+      return jsonResult({ items: page.items, total: page.total });
+    }
+  );
+  server.registerTool(
+    "set-skill-roles",
+    {
+      description: "Replace the set of business roles that can edit a skill. The owner uses this to share (or revoke) edition with team roles. Requires edit permission on the skill.",
+      inputSchema: {
+        id: z2.string().describe("Skill ID (UUID)"),
+        roleIds: z2.array(z2.string()).describe("Business role IDs that may edit the skill")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ id, roleIds }) => {
+      const page = await client.put(`/api/skills/${id}/permissions`, {
+        roleIds
+      });
+      return jsonResult({ items: page.items });
+    }
+  );
+  server.registerTool(
+    "set-agent-skills",
+    {
+      description: "Set the skill assignments for an agent. Replaces existing assignments.",
+      inputSchema: {
+        agentId: z2.string().describe("Agent ID (UUID)"),
+        skills: z2.array(
+          z2.object({
+            skillName: z2.string().describe("Skill name to assign")
+          })
+        ).describe("List of skills to assign")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ agentId, skills }) => {
+      const page = await client.put(`/api/agents/${agentId}/skills`, {
+        skills
+      });
+      return jsonResult({ skills: page.items });
+    }
+  );
+}
+
+// src/tools/agent-mcp.ts
+import { z as z3 } from "zod";
+function registerAgentMcpTools(server, client, ctx) {
+  server.registerTool(
+    "get-agent-mcp-servers",
+    {
+      description: "List MCP servers assigned to a specific agent.",
+      inputSchema: {
+        agentId: z3.string().describe("Agent ID (UUID)")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ agentId }) => {
+      const page = await client.get(`/api/agents/${agentId}/mcp-servers`);
+      return jsonResult({ items: page.items, total: page.total });
+    }
+  );
+  if (ctx.readOnly || ctx.role !== "admin") return;
+  server.registerTool(
+    "set-agent-mcp-servers",
+    {
+      description: "Set the MCP server assignments for an agent. Replaces existing assignments. Optionally set per-server access mode via `modes` (keyed by MCP server id); ids omitted from `modes` default to 'write' (read-write).",
+      inputSchema: {
+        agentId: z3.string().describe("Agent ID (UUID)"),
+        mcpServerIds: z3.array(z3.string()).describe("List of MCP Server IDs (UUIDs) to assign"),
+        modes: z3.record(z3.enum(["read", "write"])).optional().describe(
+          "Per-server access mode keyed by MCP server id: 'read' (read-only tools) or 'write' (all tools). Omitted ids default to 'write'."
+        )
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false }
+    },
+    async ({ agentId, mcpServerIds, modes }) => {
+      const page = await client.put(`/api/agents/${agentId}/mcp-servers`, {
+        mcpServerIds,
+        modes
+      });
+      return jsonResult({ mcpServerIds: page.items });
+    }
+  );
+}
+
+// src/server.ts
+function createServer(config) {
+  return createSurfaceServer({
+    name: "dudamel-agents",
+    instructions: `Dudamel Agents MCP \u2014 manage agents, skills, and their skill/MCP assignments (plus agent-to-agent messaging). Running as role=${config.role}, readOnly=${config.readOnly ?? false}.`,
+    registrars: [registerAgentTools, registerSkillTools, registerAgentMcpTools],
+    config
+  });
+}
+export {
+  createServer
+};