@superdurable/dex-agents 0.0.0-stage → 0.2.0

package/dist/src/mcp/mcp-resource-and-prompt-tools.js

@@ -0,0 +1,185 @@
+// Copyright (c) 2026 Super Durable, Inc.
+//
+// Licensed under the Sustainable Use License 1.0.
+// You may not use this file except in compliance with the License.
+// See the LICENSE file in the repository root.
+//
+// SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { ToolExecutionError } from "../agent-framework-runner.js";
+/** Name of the read tool that lists a server's resources, resource templates, and prompts. */
+export const mcpListResourcesAndPromptsToolName = "mcp_list_resources_and_prompts";
+/** Name of the read tool that reads one resource of a server. */
+export const mcpReadResourceToolName = "mcp_read_resource";
+/** Name of the read tool that gets one prompt of a server. */
+export const mcpGetPromptToolName = "mcp_get_prompt";
+export const resourceAndPromptToolNames = new Set([
+    mcpListResourcesAndPromptsToolName,
+    mcpReadResourceToolName,
+    mcpGetPromptToolName,
+]);
+const listingPageLimit = 100;
+/** Returns the three read tools; the `server` argument names one of `serverNames`. */
+export function buildResourceAndPromptToolDefinitions(serverNames) {
+    const server = { type: "string", enum: [...serverNames], description: "Name of a configured MCP server." };
+    const definitions = [
+        [
+            mcpListResourcesAndPromptsToolName,
+            "List the resources, resource templates, and prompts of a configured MCP server.",
+            { server },
+        ],
+        [
+            mcpReadResourceToolName,
+            "Read one resource of a configured MCP server by its URI.",
+            { server, uri: { type: "string", description: "URI of the resource, as the server lists it." } },
+        ],
+        [
+            mcpGetPromptToolName,
+            "Get one prompt of a configured MCP server, rendered with its arguments.",
+            {
+                server,
+                name: { type: "string", description: "Name of the prompt, as the server lists it." },
+                arguments: {
+                    type: "object",
+                    additionalProperties: { type: "string" },
+                    description: "Prompt arguments by name. Defaults to none.",
+                },
+            },
+        ],
+    ];
+    return definitions.map(([name, description, properties]) => ({
+        name,
+        description,
+        inputSchema: {
+            type: "object",
+            properties,
+            required: Object.keys(properties).filter((key) => key !== "arguments"),
+            additionalProperties: false,
+        },
+    }));
+}
+/** Returns the `server` argument, or throws the {@link ToolExecutionError} the model sees. */
+export function readServerName(toolArguments) {
+    const serverName = toolArguments["server"];
+    if (typeof serverName !== "string") {
+        throw new ToolExecutionError("the server argument must be a string");
+    }
+    return serverName;
+}
+/** Sends one read tool's requests on an open connection and returns the output JSON text. */
+export async function runResourceAndPromptTool(client, toolName, toolArguments, requestOptions) {
+    let output;
+    try {
+        if (toolName === mcpListResourcesAndPromptsToolName) {
+            output = {
+                resources: await listAll((cursor) => client.listResources(cursorParams(cursor), requestOptions), "resources"),
+                resource_templates: await listAll((cursor) => client.listResourceTemplates(cursorParams(cursor), requestOptions), "resourceTemplates"),
+                prompts: await listAll((cursor) => client.listPrompts(cursorParams(cursor), requestOptions), "prompts"),
+            };
+        }
+        else if (toolName === mcpReadResourceToolName) {
+            const uri = toolArguments["uri"];
+            if (typeof uri !== "string") {
+                throw new ToolExecutionError("the uri argument must be a string");
+            }
+            const read = await client.readResource({ uri }, requestOptions);
+            output = { contents: read.contents };
+        }
+        else {
+            const name = toolArguments["name"];
+            if (typeof name !== "string") {
+                throw new ToolExecutionError("the name argument must be a string");
+            }
+            const promptArguments = toolArguments["arguments"];
+            if (promptArguments !== undefined &&
+                promptArguments !== null &&
+                (typeof promptArguments !== "object" ||
+                    Array.isArray(promptArguments) ||
+                    !Object.values(promptArguments).every((value) => typeof value === "string"))) {
+                throw new ToolExecutionError("the arguments argument must map names to strings");
+            }
+            const prompt = await client.getPrompt({
+                name,
+                ...(promptArguments === undefined || promptArguments === null
+                    ? {}
+                    : { arguments: promptArguments }),
+            }, requestOptions);
+            output = { messages: prompt.messages };
+            if (prompt.description !== undefined) {
+                output["description"] = prompt.description;
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof McpError) {
+            throw new ToolExecutionError(`MCP error ${error.code}: ${readMcpErrorMessage(error)}`, { cause: error });
+        }
+        throw error;
+    }
+    return serializeToolOutputJson(output);
+}
+/**
+ * Serializes with sorted keys and spaced separators, as the Python core's `json.dumps(sort_keys=True)`.
+ * Keys sort by code point while the text is written, never through an object, because JavaScript objects
+ * put integer-like keys first.
+ */
+export function serializeToolOutputJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => serializeToolOutputJson(item === undefined ? null : item)).join(", ")}]`;
+    }
+    if (typeof value === "object" && value !== null) {
+        const entries = Object.entries(value)
+            .filter(([, nested]) => nested !== undefined)
+            .sort(([left], [right]) => compareByCodePoint(left, right));
+        return `{${entries.map(([key, nested]) => `${JSON.stringify(key)}: ${serializeToolOutputJson(nested)}`).join(", ")}}`;
+    }
+    const text = JSON.stringify(value);
+    if (text === undefined) {
+        throw new TypeError(`a ${typeof value} value cannot be serialized as JSON`);
+    }
+    return text;
+}
+/** JavaScript's `<` compares UTF-16 code units, which orders characters above U+FFFF before U+E000. */
+function compareByCodePoint(left, right) {
+    const leftCodePoints = Array.from(left, (character) => character.codePointAt(0) ?? 0);
+    const rightCodePoints = Array.from(right, (character) => character.codePointAt(0) ?? 0);
+    for (let index = 0; index < Math.min(leftCodePoints.length, rightCodePoints.length); index += 1) {
+        const difference = (leftCodePoints[index] ?? 0) - (rightCodePoints[index] ?? 0);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return leftCodePoints.length - rightCodePoints.length;
+}
+async function listAll(listPage, fieldName) {
+    const items = [];
+    let cursor;
+    for (let page = 0; page < listingPageLimit; page += 1) {
+        let result;
+        try {
+            result = await listPage(cursor);
+        }
+        catch (error) {
+            if (error instanceof McpError && error.code === ErrorCode.MethodNotFound) {
+                // The server does not offer this kind of item.
+                return items;
+            }
+            throw error;
+        }
+        items.push(...result[fieldName]);
+        cursor = result.nextCursor;
+        if (cursor === undefined || cursor === "") {
+            break;
+        }
+    }
+    return items;
+}
+function cursorParams(cursor) {
+    return cursor === undefined ? {} : { cursor };
+}
+/** The SDK prefixes `MCP error <code>: ` to the server's message; the Python core shows the bare message. */
+function readMcpErrorMessage(error) {
+    const prefix = `MCP error ${error.code}: `;
+    return error.message.startsWith(prefix) ? error.message.slice(prefix.length) : error.message;
+}
+//# sourceMappingURL=mcp-resource-and-prompt-tools.js.map

package/dist/src/mcp/mcp-resource-and-prompt-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-resource-and-prompt-tools.js","sourceRoot":"","sources":["../../../src/mcp/mcp-resource-and-prompt-tools.ts"],"names":[],"mappings":"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"}

package/dist/src/mcp/mcp-server-config.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Launches one MCP server as a child process and talks to it over stdio.
+ *
+ * Build it from Worker configuration, never from Flow input, a user message, or a browser: the command
+ * runs with the Worker's privileges. Every request starts a new process, so a server that keeps state
+ * between calls must keep it outside the process.
+ *
+ * @example
+ * ```ts
+ * const files: McpStdioServerConfig = {
+ *   transport: "stdio",
+ *   name: "files",
+ *   command: "npx",
+ *   args: ["-y", "@modelcontextprotocol/server-filesystem", "/srv/reports"],
+ * };
+ * ```
+ */
+export interface McpStdioServerConfig {
+    /** Discriminator. */
+    readonly transport: "stdio";
+    /**
+     * Server name, unique within one {@link McpToolSource}. It prefixes the agent tool names, so it may
+     * contain only letters, digits, `_`, and `-`.
+     */
+    readonly name: string;
+    /** Executable to run. */
+    readonly command: string;
+    /** Command-line arguments. Defaults to none. */
+    readonly args?: readonly string[];
+    /**
+     * Environment variables merged over the MCP SDK's default environment, which keeps only variables
+     * such as `PATH` and `HOME`. Defaults to none. An inspected {@link McpToolSource} shows the variable
+     * names with every value replaced by `***`.
+     */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Working directory. Defaults to the Worker's. */
+    readonly cwd?: string;
+    /**
+     * Whether the server's `readOnlyHint`, `idempotentHint`, and `destructiveHint` annotations pick a
+     * tool's effect. Defaults to `true`; set `false` for a server whose hints you do not trust, so its
+     * tools keep the session default unless a {@link ToolPolicy} names them.
+     */
+    readonly trustsToolAnnotations?: boolean;
+}
+/**
+ * Connects to one MCP server over the Streamable HTTP transport.
+ *
+ * Build it from Worker configuration, never from Flow input, a user message, or a browser. Read
+ * credentials such as bearer tokens from the Worker's environment or secret store and pass them in
+ * {@link headers}. Every request opens a new connection and protocol session, so a server restart
+ * between two calls is harmless.
+ *
+ * @example
+ * ```ts
+ * const tickets: McpStreamableHttpServerConfig = {
+ *   transport: "streamable_http",
+ *   name: "tickets",
+ *   url: "https://tickets.example.com/mcp",
+ *   headers: { Authorization: `Bearer ${process.env.TICKETS_TOKEN}` },
+ * };
+ * ```
+ */
+export interface McpStreamableHttpServerConfig {
+    /** Discriminator. */
+    readonly transport: "streamable_http";
+    /**
+     * Server name, unique within one {@link McpToolSource}. It prefixes the agent tool names, so it may
+     * contain only letters, digits, `_`, and `-`.
+     */
+    readonly name: string;
+    /** The server's MCP endpoint, an `http` or `https` URL. */
+    readonly url: string;
+    /**
+     * HTTP headers sent with every request, such as `Authorization`. Defaults to none. An inspected
+     * {@link McpToolSource} shows the header names with every value replaced by `***`.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Whether the server's annotations pick a tool's effect. Defaults to `true`. */
+    readonly trustsToolAnnotations?: boolean;
+}
+/** One MCP server configuration: stdio or Streamable HTTP. */
+export type McpServerConfig = McpStdioServerConfig | McpStreamableHttpServerConfig;
+/** Returns a copy whose environment and header values are `***`, safe to print or log. */
+export declare function redactMcpServerConfigSecrets(server: McpServerConfig): McpServerConfig;
+/** Throws a `TypeError` for an invalid configuration. */
+export declare function validateMcpServerConfig(server: McpServerConfig): void;

package/dist/src/mcp/mcp-server-config.js

@@ -0,0 +1,38 @@
+// Copyright (c) 2026 Super Durable, Inc.
+//
+// Licensed under the Sustainable Use License 1.0.
+// You may not use this file except in compliance with the License.
+// See the LICENSE file in the repository root.
+//
+// SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+const serverNamePattern = /^[A-Za-z0-9_-]+$/;
+/** Returns a copy whose environment and header values are `***`, safe to print or log. */
+export function redactMcpServerConfigSecrets(server) {
+    if (server.transport === "stdio") {
+        return server.env === undefined ? { ...server } : { ...server, env: redactValues(server.env) };
+    }
+    return server.headers === undefined ? { ...server } : { ...server, headers: redactValues(server.headers) };
+}
+function redactValues(values) {
+    return Object.fromEntries(Object.keys(values).map((key) => [key, "***"]));
+}
+/** Throws a `TypeError` for an invalid configuration. */
+export function validateMcpServerConfig(server) {
+    if (!serverNamePattern.test(server.name)) {
+        throw new TypeError(`MCP server name ${JSON.stringify(server.name)} must be non-empty letters, digits, '_', or '-'`);
+    }
+    if (server.transport === "stdio") {
+        if (server.command === "") {
+            throw new TypeError(`MCP server ${server.name} needs a command`);
+        }
+        return;
+    }
+    if (server.transport !== "streamable_http") {
+        throw new TypeError(`MCP server ${server.name} has an unknown transport`);
+    }
+    const protocol = URL.canParse(server.url) ? new URL(server.url).protocol : "";
+    if (protocol !== "http:" && protocol !== "https:") {
+        throw new TypeError(`MCP server ${server.name} needs an http or https URL`);
+    }
+}
+//# sourceMappingURL=mcp-server-config.js.map

package/dist/src/mcp/mcp-server-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server-config.js","sourceRoot":"","sources":["../../../src/mcp/mcp-server-config.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAuF1D,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAE7C,0FAA0F;AAC1F,MAAM,UAAU,4BAA4B,CAAC,MAAuB;IAClE,IAAI,MAAM,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACjG,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;AAC7G,CAAC;AAED,SAAS,YAAY,CAAC,MAAwC;IAC5D,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,uBAAuB,CAAC,MAAuB;IAC7D,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,SAAS,CAAC,mBAAmB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC;IACvH,CAAC;IACD,IAAI,MAAM,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;QACjC,IAAI,MAAM,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;YAC1B,MAAM,IAAI,SAAS,CAAC,cAAc,MAAM,CAAC,IAAI,kBAAkB,CAAC,CAAC;QACnE,CAAC;QACD,OAAO;IACT,CAAC;IACD,IAAI,MAAM,CAAC,SAAS,KAAK,iBAAiB,EAAE,CAAC;QAC3C,MAAM,IAAI,SAAS,CAAC,cAAe,MAAoC,CAAC,IAAI,2BAA2B,CAAC,CAAC;IAC3G,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,SAAS,CAAC,cAAc,MAAM,CAAC,IAAI,6BAA6B,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC"}