@dudamel/mcp-integrations 2026.930.2 → 2026.1002.1

package/dist/index.js

@@ -267,7 +267,7 @@ function registerMcpCatalogTools(server, client, _ctx) {
   server.registerTool(
     "list-mcp-catalog",
     {
-      description: "List the catalog of pre-curated MCP servers available for installation. Returns server type, connection methods, permission modes, and setup guides.",
+      description: "List the catalog of Dudamel's own MCP servers that are not tied to an integration: context, memory and the admin surfaces. MCP servers for external services (GitHub, Jira, Slack, \u2026) are not here \u2014 they come from creating an integration instance (see list-integration-types).",
       annotations: { readOnlyHint: true }
     },
     async () => {
@@ -277,12 +277,118 @@ function registerMcpCatalogTools(server, client, _ctx) {
   );
 }
 
+// src/tools/mcp-tools.ts
+import { z as z3 } from "zod";
+var SUMMARY_MAX_CHARS = 160;
+function registerMcpToolLookupTools(server, client, _ctx) {
+  const fetchTools = async () => (await client.get("/api/mcp-tools")).items;
+  server.registerTool(
+    "list-mcp-tools",
+    {
+      description: "List the tools exposed by the MCP servers available to you. Without arguments, returns one line per server (tool counts); pass `server` (name or id) for its tools, or `query` to search tool names and descriptions across servers. Each tool comes with whether it only reads (readOnly) and a one-line summary \u2014 call get-mcp-tool for its full description and argument schema before using it in a workflow step.",
+      inputSchema: {
+        server: z3.string().optional().describe("MCP server name or id"),
+        query: z3.string().optional().describe("Case-insensitive text to match in tool names and descriptions")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ server: serverRef, query }) => {
+      let tools = await fetchTools();
+      if (serverRef) {
+        tools = tools.filter((t) => matchesServer(t, serverRef));
+        if (tools.length === 0) throw new Error(noServerMessage(serverRef));
+      }
+      if (query) {
+        const q = query.toLowerCase();
+        tools = tools.filter(
+          (t) => t.name.toLowerCase().includes(q) || t.description?.toLowerCase().includes(q)
+        );
+      }
+      if (!serverRef && !query) {
+        return jsonResult({ servers: summarizeServers(tools) });
+      }
+      return jsonResult({
+        tools: tools.map((t) => ({
+          server: t.mcpServer,
+          name: t.name,
+          readOnly: isReadOnly(t),
+          summary: summarize(t.description)
+        })),
+        total: tools.length
+      });
+    }
+  );
+  server.registerTool(
+    "get-mcp-tool",
+    {
+      description: "Get one MCP tool in full: its description, the JSON schema of its arguments (inputSchema) and its annotations (readOnlyHint, destructiveHint, \u2026). Use it to write the `arguments:` of a workflow `mcp:` step instead of guessing them.",
+      inputSchema: {
+        server: z3.string().describe("MCP server name or id"),
+        tool: z3.string().describe("Tool name, as list-mcp-tools returns it")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ server: serverRef, tool }) => {
+      const ofServer = (await fetchTools()).filter((t) => matchesServer(t, serverRef));
+      if (ofServer.length === 0) throw new Error(noServerMessage(serverRef));
+      const found = ofServer.find((t) => t.name === tool);
+      if (!found) {
+        throw new Error(
+          `MCP server '${serverRef}' has no tool '${tool}'. Call list-mcp-tools with server='${serverRef}' for the names it exposes.`
+        );
+      }
+      return jsonResult({
+        server: found.mcpServer,
+        serverId: found.mcpServerId,
+        name: found.name,
+        readOnly: isReadOnly(found),
+        description: found.description ?? "",
+        inputSchema: found.inputSchema ?? { type: "object", properties: {} },
+        annotations: found.annotations ?? {}
+      });
+    }
+  );
+}
+function matchesServer(t, ref) {
+  return t.mcpServer === ref || t.mcpServerId === ref;
+}
+function isReadOnly(t) {
+  return t.annotations?.readOnlyHint === true;
+}
+function noServerMessage(ref) {
+  return `No tools found for MCP server '${ref}': it does not exist, your roles do not grant it, or its tools have not been discovered yet. Call list-mcp-tools without arguments for the servers you can use.`;
+}
+function summarize(description) {
+  const firstLine = (description ?? "").trim().split("\n")[0] ?? "";
+  return firstLine.length > SUMMARY_MAX_CHARS ? `${firstLine.slice(0, SUMMARY_MAX_CHARS - 1).trimEnd()}\u2026` : firstLine;
+}
+function summarizeServers(tools) {
+  const byServer = /* @__PURE__ */ new Map();
+  for (const t of tools) {
+    const entry = byServer.get(t.mcpServerId) ?? {
+      server: t.mcpServer,
+      serverId: t.mcpServerId,
+      tools: 0,
+      readOnlyTools: 0
+    };
+    entry.tools++;
+    if (isReadOnly(t)) entry.readOnlyTools++;
+    byServer.set(t.mcpServerId, entry);
+  }
+  return [...byServer.values()].sort((a, b) => a.server.localeCompare(b.server));
+}
+
 // src/server.ts
 function createServer(config) {
   return createSurfaceServer({
     name: "dudamel-integrations",
-    instructions: `Dudamel Integrations MCP \u2014 manage integration instances, MCP servers, and the MCP catalog. Running as role=${config.role}, readOnly=${config.readOnly ?? false}.`,
-    registrars: [registerIntegrationTools, registerMcpServerTools, registerMcpCatalogTools],
+    instructions: `Dudamel Integrations MCP \u2014 manage integration instances, MCP servers, and the MCP catalog, and look up the tools each MCP server exposes (list-mcp-tools / get-mcp-tool) before wiring them into a workflow step. Running as role=${config.role}, readOnly=${config.readOnly ?? false}.`,
+    registrars: [
+      registerIntegrationTools,
+      registerMcpServerTools,
+      registerMcpCatalogTools,
+      registerMcpToolLookupTools
+    ],
     config
   });
 }

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAK3D,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,4DASnD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAM3D,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,4DAgBnD"}

package/dist/stdio-server.js

@@ -310,7 +310,7 @@ function registerMcpCatalogTools(server2, client, _ctx) {
   server2.registerTool(
     "list-mcp-catalog",
     {
-      description: "List the catalog of pre-curated MCP servers available for installation. Returns server type, connection methods, permission modes, and setup guides.",
+      description: "List the catalog of Dudamel's own MCP servers that are not tied to an integration: context, memory and the admin surfaces. MCP servers for external services (GitHub, Jira, Slack, \u2026) are not here \u2014 they come from creating an integration instance (see list-integration-types).",
       annotations: { readOnlyHint: true }
     },
     async () => {
@@ -320,12 +320,118 @@ function registerMcpCatalogTools(server2, client, _ctx) {
   );
 }
 
+// src/tools/mcp-tools.ts
+import { z as z3 } from "zod";
+var SUMMARY_MAX_CHARS = 160;
+function registerMcpToolLookupTools(server2, client, _ctx) {
+  const fetchTools = async () => (await client.get("/api/mcp-tools")).items;
+  server2.registerTool(
+    "list-mcp-tools",
+    {
+      description: "List the tools exposed by the MCP servers available to you. Without arguments, returns one line per server (tool counts); pass `server` (name or id) for its tools, or `query` to search tool names and descriptions across servers. Each tool comes with whether it only reads (readOnly) and a one-line summary \u2014 call get-mcp-tool for its full description and argument schema before using it in a workflow step.",
+      inputSchema: {
+        server: z3.string().optional().describe("MCP server name or id"),
+        query: z3.string().optional().describe("Case-insensitive text to match in tool names and descriptions")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ server: serverRef, query }) => {
+      let tools = await fetchTools();
+      if (serverRef) {
+        tools = tools.filter((t) => matchesServer(t, serverRef));
+        if (tools.length === 0) throw new Error(noServerMessage(serverRef));
+      }
+      if (query) {
+        const q = query.toLowerCase();
+        tools = tools.filter(
+          (t) => t.name.toLowerCase().includes(q) || t.description?.toLowerCase().includes(q)
+        );
+      }
+      if (!serverRef && !query) {
+        return jsonResult({ servers: summarizeServers(tools) });
+      }
+      return jsonResult({
+        tools: tools.map((t) => ({
+          server: t.mcpServer,
+          name: t.name,
+          readOnly: isReadOnly(t),
+          summary: summarize(t.description)
+        })),
+        total: tools.length
+      });
+    }
+  );
+  server2.registerTool(
+    "get-mcp-tool",
+    {
+      description: "Get one MCP tool in full: its description, the JSON schema of its arguments (inputSchema) and its annotations (readOnlyHint, destructiveHint, \u2026). Use it to write the `arguments:` of a workflow `mcp:` step instead of guessing them.",
+      inputSchema: {
+        server: z3.string().describe("MCP server name or id"),
+        tool: z3.string().describe("Tool name, as list-mcp-tools returns it")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ server: serverRef, tool }) => {
+      const ofServer = (await fetchTools()).filter((t) => matchesServer(t, serverRef));
+      if (ofServer.length === 0) throw new Error(noServerMessage(serverRef));
+      const found = ofServer.find((t) => t.name === tool);
+      if (!found) {
+        throw new Error(
+          `MCP server '${serverRef}' has no tool '${tool}'. Call list-mcp-tools with server='${serverRef}' for the names it exposes.`
+        );
+      }
+      return jsonResult({
+        server: found.mcpServer,
+        serverId: found.mcpServerId,
+        name: found.name,
+        readOnly: isReadOnly(found),
+        description: found.description ?? "",
+        inputSchema: found.inputSchema ?? { type: "object", properties: {} },
+        annotations: found.annotations ?? {}
+      });
+    }
+  );
+}
+function matchesServer(t, ref) {
+  return t.mcpServer === ref || t.mcpServerId === ref;
+}
+function isReadOnly(t) {
+  return t.annotations?.readOnlyHint === true;
+}
+function noServerMessage(ref) {
+  return `No tools found for MCP server '${ref}': it does not exist, your roles do not grant it, or its tools have not been discovered yet. Call list-mcp-tools without arguments for the servers you can use.`;
+}
+function summarize(description) {
+  const firstLine = (description ?? "").trim().split("\n")[0] ?? "";
+  return firstLine.length > SUMMARY_MAX_CHARS ? `${firstLine.slice(0, SUMMARY_MAX_CHARS - 1).trimEnd()}\u2026` : firstLine;
+}
+function summarizeServers(tools) {
+  const byServer = /* @__PURE__ */ new Map();
+  for (const t of tools) {
+    const entry = byServer.get(t.mcpServerId) ?? {
+      server: t.mcpServer,
+      serverId: t.mcpServerId,
+      tools: 0,
+      readOnlyTools: 0
+    };
+    entry.tools++;
+    if (isReadOnly(t)) entry.readOnlyTools++;
+    byServer.set(t.mcpServerId, entry);
+  }
+  return [...byServer.values()].sort((a, b) => a.server.localeCompare(b.server));
+}
+
 // src/server.ts
 function createServer(config) {
   return createSurfaceServer({
     name: "dudamel-integrations",
-    instructions: `Dudamel Integrations MCP \u2014 manage integration instances, MCP servers, and the MCP catalog. Running as role=${config.role}, readOnly=${config.readOnly ?? false}.`,
-    registrars: [registerIntegrationTools, registerMcpServerTools, registerMcpCatalogTools],
+    instructions: `Dudamel Integrations MCP \u2014 manage integration instances, MCP servers, and the MCP catalog, and look up the tools each MCP server exposes (list-mcp-tools / get-mcp-tool) before wiring them into a workflow step. Running as role=${config.role}, readOnly=${config.readOnly ?? false}.`,
+    registrars: [
+      registerIntegrationTools,
+      registerMcpServerTools,
+      registerMcpCatalogTools,
+      registerMcpToolLookupTools
+    ],
     config
   });
 }

package/dist/tools/mcp-catalog.d.ts

@@ -3,8 +3,8 @@ import type { DudamelApiClient } from '@dudamel/mcp-common';
 import type { ToolContext } from '@dudamel/mcp-common';
 /**
  * `list-mcp-catalog` for the `integrations` surface (Plan 52 Parte C) — the
- * catalog of pre-curated MCP servers (how the platform connects to external
- * tools). Read-only, user-visible (moved out of the old `system` tool group).
+ * catalog of Dudamel-owned MCP servers not tied to an integration (context,
+ * memory, the admin surfaces). Read-only, user-visible.
  */
 export declare function registerMcpCatalogTools(server: McpServer, client: DudamelApiClient, _ctx: ToolContext): void;
 //# sourceMappingURL=mcp-catalog.d.ts.map

package/dist/tools/mcp-tools.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { DudamelApiClient } from '@dudamel/mcp-common';
+import type { ToolContext } from '@dudamel/mcp-common';
+/**
+ * Tool lookup for the `integrations` surface: what each MCP server available to the caller
+ * exposes, read from the tool lists the orchestrator discovers and caches. It is the only
+ * way an agent learns the tools of a server it does not have mounted itself — e.g. one it
+ * is writing a workflow `mcp:` step for. `GET /api/mcp-tools` filters by the caller's roles,
+ * so a user never sees the tools of a server its roles do not grant.
+ */
+export declare function registerMcpToolLookupTools(server: McpServer, client: DudamelApiClient, _ctx: ToolContext): void;
+//# sourceMappingURL=mcp-tools.d.ts.map

package/dist/tools/mcp-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tools.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-tools.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;AAMvD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,WAAW,GAChB,IAAI,CAoFN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudamel/mcp-integrations",
-  "version": "2026.930.2",
+  "version": "2026.1002.1",
   "description": "Dudamel integrations MCP — stdio client for Dudamel's integrations management surface over its REST API.",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
@@ -33,8 +33,8 @@
   "devDependencies": {
     "esbuild": "^0.25.0",
     "@dudamel/contracts": "0.1.0",
-    "@dudamel/mcp-common": "0.1.0",
-    "@dudamel/mcp-tool-contract": "0.1.0"
+    "@dudamel/mcp-tool-contract": "0.1.0",
+    "@dudamel/mcp-common": "0.1.0"
   },
   "scripts": {
     "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",