@mxf-dev/core 1.0.1 → 2.0.0

package/dist/protocols/mcp/defineTool.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+import { McpToolDefinition, McpToolHandlerResult, McpToolResultContent } from './McpServerTypes.js';
+import { McpToolExample } from './McpToolSchema.js';
+import { ToolErrorData } from './ToolError.js';
+/**
+ * The single result shape every `defineTool` tool returns.
+ *
+ * Extends the framework's McpToolHandlerResult, so these tools drop into the
+ * existing registries and socket paths unchanged, and adds the explicit
+ * `isError` flag those shapes were missing.
+ */
+export interface ToolResultEnvelope<TData = unknown> extends McpToolHandlerResult {
+    /** Result payload. `data` holds the tool's own output, or a ToolErrorData on failure. */
+    content: McpToolResultContent & {
+        data: TData | ToolErrorData;
+    };
+    /** True when the tool failed. Callers branch on this — never on payload shape. */
+    isError: boolean;
+    /** Execution metadata (tool name, timing, and the error code when isError). */
+    metadata: {
+        toolName: string;
+        executedAt: number;
+        durationMs: number;
+        /** Present only when isError is true */
+        errorCode?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Context handed to a tool's `run` function.
+ *
+ * agentId, channelId and requestId are always present — `defineTool` rejects the
+ * call before `run` is reached if any is missing, so `run` never has to check.
+ */
+export interface ToolRunContext {
+    /** Agent that invoked the tool. Always present. */
+    agentId: string;
+    /** Channel the invocation belongs to. Always present. */
+    channelId: string;
+    /** Correlation id for events and logs. Always present. */
+    requestId: string;
+    /** Any extra context the caller attached. */
+    data?: Record<string, unknown>;
+}
+/**
+ * Options accepted by {@link defineTool}.
+ */
+export interface DefineToolOptions<TInput, TOutput> {
+    /** Tool name exposed to the model. Must be unique across the whole tool set. */
+    name: string;
+    /**
+     * What the tool does, written for the model that decides whether to call it.
+     * This is prompt text: state the behavior plainly, and describe only what the
+     * implementation actually does.
+     */
+    description: string;
+    /** Category used for grouping and filtering. */
+    category: string;
+    /** JSON Schema for the tool's input. Enforced on every entry path. */
+    inputSchema: Record<string, any>;
+    /**
+     * The tool's behavior. Return the payload to send back; throw a ToolError to
+     * fail. Do not catch-and-wrap — the factory owns error handling.
+     */
+    run: (input: TInput, context: ToolRunContext) => Promise<TOutput> | TOutput;
+    /** Optional worked examples surfaced in tool documentation. */
+    examples?: McpToolExample[];
+    /** Where the tool may execute. Defaults to 'server'. */
+    executionSide?: 'server' | 'client' | 'either';
+    /** Whether the tool is enabled. Defaults to true. */
+    enabled?: boolean;
+    /** Extra metadata merged into the registered tool definition. */
+    metadata?: Record<string, any>;
+}
+/**
+ * A tool produced by {@link defineTool}.
+ *
+ * Structurally a McpToolDefinition, so it registers exactly like a hand-written
+ * tool, plus the `category` it was declared with.
+ */
+export interface DefinedMcpTool extends McpToolDefinition {
+    category: string;
+}
+/**
+ * Declare an MCP tool.
+ *
+ * @example
+ * export const gitStatusTool = defineTool({
+ *     name: 'git_status',
+ *     category: TOOL_CATEGORIES.VERSION_CONTROL,
+ *     description: 'Report staged, modified and untracked files by running `git status`.',
+ *     inputSchema: {
+ *         type: 'object',
+ *         properties: { workingDirectory: { type: 'string' } }
+ *     },
+ *     run: async (input, context) => {
+ *         const result = await runGit(['status'], input.workingDirectory);
+ *         if (result.exitCode !== 0) {
+ *             throw ToolError.executionFailed(`git status failed: ${result.stderr}`);
+ *         }
+ *         return { files: parse(result.stdout) };
+ *     }
+ * });
+ */
+export declare function defineTool<TInput = Record<string, any>, TOutput = unknown>(options: DefineToolOptions<TInput, TOutput>): DefinedMcpTool;
+/**
+ * Type guard: did this tool call fail?
+ *
+ * Use this instead of inspecting the payload. Results produced by `defineTool`
+ * always carry an explicit `isError`.
+ */
+export declare function isToolError(result: unknown): result is ToolResultEnvelope & {
+    isError: true;
+};
+//# sourceMappingURL=defineTool.d.ts.map

package/dist/protocols/mcp/defineTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineTool.d.ts","sourceRoot":"","sources":["../../../src/protocols/mcp/defineTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA+BH,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAa,aAAa,EAAe,MAAM,gBAAgB,CAAC;AAoCvE;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,oBAAoB;IAC7E,yFAAyF;IACzF,OAAO,EAAE,oBAAoB,GAAG;QAAE,IAAI,EAAE,KAAK,GAAG,aAAa,CAAA;KAAE,CAAC;IAChE,kFAAkF;IAClF,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,QAAQ,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,wCAAwC;QACxC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KAC1B,CAAC;CACL;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC3B,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,MAAM,EAAE,OAAO;IAC9C,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC;;;OAGG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC5E,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B,wDAAwD;IACxD,aAAa,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC/C,qDAAqD;IACrD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACrD,QAAQ,EAAE,MAAM,CAAC;CACpB;AAqBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,EACtE,OAAO,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5C,cAAc,CAyJhB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,kBAAkB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAO7F"}

package/dist/protocols/mcp/defineTool.js

@@ -0,0 +1,236 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * defineTool.ts
+ *
+ * The one way to declare an MCP tool.
+ *
+ * Tools used to hand-roll their own scaffolding: each file repeated its own
+ * try/catch, its own `error instanceof Error ? error.message : String(error)`,
+ * its own logger call, and its own result wrapper. Four different result shapes
+ * emerged across the tool set, so there was no reliable way to tell that a tool
+ * had failed.
+ *
+ * `defineTool` owns that scaffolding. A tool supplies a schema and a `run`
+ * function that returns a value or throws a {@link ToolError}; the factory:
+ *
+ *   1. validates the execution context (agentId / channelId / requestId),
+ *   2. validates the input against `inputSchema` with AJV on every entry path —
+ *      not just the socket path, so a direct handler call is checked too,
+ *   3. runs `run` inside a single try/catch,
+ *   4. returns one envelope: `{ content: { type, data }, isError, metadata }`.
+ *
+ * `isError` is explicit (MCP-spec style). Callers test that flag; they never
+ * shape-sniff the payload.
+ */
+import { Ajv } from 'ajv';
+import * as ajvFormatsModule from 'ajv-formats';
+import { Logger } from '../../utils/Logger.js';
+import { ToolError, toToolError } from './ToolError.js';
+const ajvFormatsAny = ajvFormatsModule;
+const addFormats = (typeof ajvFormatsAny.default === 'function' ? ajvFormatsAny.default : ajvFormatsModule);
+const logger = new Logger('info', 'defineTool', 'server');
+/**
+ * Shared AJV instance for input validation.
+ *
+ * `strict: false` because tool schemas carry annotation keywords AJV does not
+ * know (for example `default` inside nested properties, and MXF's own metadata).
+ * `coerceTypes` is deliberately OFF: an LLM sending `"5"` where the schema says
+ * `number` is a real mistake worth surfacing, not one to paper over.
+ */
+const ajv = new Ajv({
+    allErrors: true,
+    strict: false,
+    validateFormats: true,
+    coerceTypes: false,
+    useDefaults: true
+});
+addFormats(ajv);
+/**
+ * Content type used for structured tool results.
+ */
+const JSON_CONTENT_TYPE = 'application/json';
+/**
+ * Format AJV errors into one line a model can act on.
+ */
+function formatSchemaErrors(validate) {
+    const errors = validate.errors ?? [];
+    if (errors.length === 0) {
+        return 'input did not match the tool schema';
+    }
+    return errors
+        .map(err => {
+        // instancePath is '' for a root-level failure (e.g. a missing required
+        // property); name that root explicitly rather than printing an empty path.
+        const where = err.instancePath ? err.instancePath.replace(/^\//, '') : 'input';
+        return `${where} ${err.message}`;
+    })
+        .join('; ');
+}
+/**
+ * Declare an MCP tool.
+ *
+ * @example
+ * export const gitStatusTool = defineTool({
+ *     name: 'git_status',
+ *     category: TOOL_CATEGORIES.VERSION_CONTROL,
+ *     description: 'Report staged, modified and untracked files by running `git status`.',
+ *     inputSchema: {
+ *         type: 'object',
+ *         properties: { workingDirectory: { type: 'string' } }
+ *     },
+ *     run: async (input, context) => {
+ *         const result = await runGit(['status'], input.workingDirectory);
+ *         if (result.exitCode !== 0) {
+ *             throw ToolError.executionFailed(`git status failed: ${result.stderr}`);
+ *         }
+ *         return { files: parse(result.stdout) };
+ *     }
+ * });
+ */
+export function defineTool(options) {
+    const { name, description, category, inputSchema, run, examples, executionSide = 'server', enabled = true, metadata = {} } = options;
+    // Fail at module load, not at call time, if a tool is declared wrong. A tool
+    // with no name or no schema cannot be registered or described to a model.
+    if (!name || typeof name !== 'string') {
+        throw new Error('defineTool: name must be a non-empty string');
+    }
+    if (!description || typeof description !== 'string') {
+        throw new Error(`defineTool(${name}): description must be a non-empty string`);
+    }
+    if (!category || typeof category !== 'string') {
+        throw new Error(`defineTool(${name}): category must be a non-empty string`);
+    }
+    if (!inputSchema || typeof inputSchema !== 'object') {
+        throw new Error(`defineTool(${name}): inputSchema must be an object`);
+    }
+    if (typeof run !== 'function') {
+        throw new Error(`defineTool(${name}): run must be a function`);
+    }
+    // Compile the schema once, at declaration. A schema AJV cannot compile is a
+    // bug in the tool, and it surfaces here rather than on first invocation.
+    let validateInput;
+    try {
+        validateInput = ajv.compile(inputSchema);
+    }
+    catch (error) {
+        throw new Error(`defineTool(${name}): inputSchema failed to compile: ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+    }
+    const handler = async (rawInput, rawContext) => {
+        const startedAt = Date.now();
+        const fail = (toolError) => {
+            toolError.toolName = name;
+            logger.error(`Tool ${name} failed [${toolError.code}]: ${toolError.message}`);
+            return {
+                content: {
+                    type: JSON_CONTENT_TYPE,
+                    data: toolError.toData()
+                },
+                isError: true,
+                metadata: {
+                    toolName: name,
+                    executedAt: Date.now(),
+                    durationMs: Date.now() - startedAt,
+                    errorCode: toolError.code
+                }
+            };
+        };
+        // ── 1. Validate the execution context ──────────────────────────────
+        // agentId and channelId gate every downstream security and memory
+        // decision. A missing one is a wiring bug — never default it.
+        const context = rawContext;
+        if (!context || typeof context !== 'object') {
+            return fail(ToolError.invalidInput(`Tool ${name} was called without an execution context. ` +
+                `agentId, channelId and requestId are required.`));
+        }
+        if (typeof context.agentId !== 'string' || context.agentId.length === 0) {
+            return fail(ToolError.invalidInput(`Tool ${name} was called without a valid agentId. ` +
+                `agentId is required for all MCP tool execution.`));
+        }
+        if (typeof context.channelId !== 'string' || context.channelId.length === 0) {
+            return fail(ToolError.invalidInput(`Tool ${name} was called without a valid channelId. ` +
+                `channelId is required for all MCP tool execution.`));
+        }
+        if (typeof context.requestId !== 'string' || context.requestId.length === 0) {
+            return fail(ToolError.invalidInput(`Tool ${name} was called without a valid requestId. ` +
+                `requestId is required to correlate tool events.`));
+        }
+        const runContext = {
+            agentId: context.agentId,
+            channelId: context.channelId,
+            requestId: context.requestId,
+            data: context.data
+        };
+        // ── 2. Validate the input against the schema ───────────────────────
+        // AJV runs here so a direct handler call is checked exactly like a call
+        // arriving over the socket. `useDefaults` fills declared defaults in place.
+        const input = (rawInput ?? {});
+        if (!validateInput(input)) {
+            return fail(ToolError.invalidInput(`Invalid arguments for ${name}: ${formatSchemaErrors(validateInput)}`, { schemaErrors: validateInput.errors ?? [] }));
+        }
+        // ── 3. Run the tool ────────────────────────────────────────────────
+        try {
+            const output = await run(input, runContext);
+            return {
+                content: {
+                    type: JSON_CONTENT_TYPE,
+                    data: output
+                },
+                isError: false,
+                metadata: {
+                    toolName: name,
+                    executedAt: Date.now(),
+                    durationMs: Date.now() - startedAt
+                }
+            };
+        }
+        catch (error) {
+            return fail(toToolError(error));
+        }
+    };
+    return {
+        name,
+        description,
+        category,
+        inputSchema,
+        enabled,
+        executionSide,
+        examples,
+        metadata: {
+            ...metadata,
+            category
+        },
+        handler: handler
+    };
+}
+/**
+ * Type guard: did this tool call fail?
+ *
+ * Use this instead of inspecting the payload. Results produced by `defineTool`
+ * always carry an explicit `isError`.
+ */
+export function isToolError(result) {
+    return (typeof result === 'object' &&
+        result !== null &&
+        'isError' in result &&
+        result.isError === true);
+}
+//# sourceMappingURL=defineTool.js.map

package/dist/protocols/mcp/defineTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineTool.js","sourceRoot":"","sources":["../../../src/protocols/mcp/defineTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,GAAG,EAAyB,MAAM,KAAK,CAAC;AACjD,OAAO,KAAK,gBAAgB,MAAM,aAAa,CAAC;AAGhD,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAG/C,OAAO,EAAE,SAAS,EAAiB,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAOvE,MAAM,aAAa,GAAG,gBAAyC,CAAC;AAChE,MAAM,UAAU,GAAqB,CACjC,OAAO,aAAa,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,CACrE,CAAC;AAEtB,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC;IAChB,SAAS,EAAE,IAAI;IACf,MAAM,EAAE,KAAK;IACb,eAAe,EAAE,IAAI;IACrB,WAAW,EAAE,KAAK;IAClB,WAAW,EAAE,IAAI;CACpB,CAAC,CAAC;AACH,UAAU,CAAC,GAAG,CAAC,CAAC;AAEhB;;GAEG;AACH,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAmF7C;;GAEG;AACH,SAAS,kBAAkB,CAAC,QAA0B;IAClD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC;IACrC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,qCAAqC,CAAC;IACjD,CAAC;IAED,OAAO,MAAM;SACR,GAAG,CAAC,GAAG,CAAC,EAAE;QACP,uEAAuE;QACvE,2EAA2E;QAC3E,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAC/E,OAAO,GAAG,KAAK,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;IACrC,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU,CACtB,OAA2C;IAE3C,MAAM,EACF,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,WAAW,EACX,GAAG,EACH,QAAQ,EACR,aAAa,GAAG,QAAQ,EACxB,OAAO,GAAG,IAAI,EACd,QAAQ,GAAG,EAAE,EAChB,GAAG,OAAO,CAAC;IAEZ,6EAA6E;IAC7E,0EAA0E;IAC1E,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,WAAW,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,2CAA2C,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,wCAAwC,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,CAAC,WAAW,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,kCAAkC,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,UAAU,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,2BAA2B,CAAC,CAAC;IACnE,CAAC;IAED,4EAA4E;IAC5E,yEAAyE;IACzE,IAAI,aAA+B,CAAC;IACpC,IAAI,CAAC;QACD,aAAa,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACX,cAAc,IAAI,oCAAoC;YACtD,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC9D,CAAC;IACN,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,EACjB,QAAiB,EACjB,UAAmB,EACiB,EAAE;QACtC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,MAAM,IAAI,GAAG,CAAC,SAAoB,EAA+B,EAAE;YAC/D,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC;YAE1B,MAAM,CAAC,KAAK,CAAC,QAAQ,IAAI,YAAY,SAAS,CAAC,IAAI,MAAM,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;YAE9E,OAAO;gBACH,OAAO,EAAE;oBACL,IAAI,EAAE,iBAAiB;oBACvB,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE;iBAC3B;gBACD,OAAO,EAAE,IAAI;gBACb,QAAQ,EAAE;oBACN,QAAQ,EAAE,IAAI;oBACd,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;oBACtB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;oBAClC,SAAS,EAAE,SAAS,CAAC,IAAI;iBAC5B;aACJ,CAAC;QACN,CAAC,CAAC;QAEF,sEAAsE;QACtE,kEAAkE;QAClE,8DAA8D;QAC9D,MAAM,OAAO,GAAG,UAAiD,CAAC;QAElE,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAC9B,QAAQ,IAAI,4CAA4C;gBACxD,gDAAgD,CACnD,CAAC,CAAC;QACP,CAAC;QACD,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtE,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAC9B,QAAQ,IAAI,uCAAuC;gBACnD,iDAAiD,CACpD,CAAC,CAAC;QACP,CAAC;QACD,IAAI,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1E,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAC9B,QAAQ,IAAI,yCAAyC;gBACrD,mDAAmD,CACtD,CAAC,CAAC;QACP,CAAC;QACD,IAAI,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1E,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAC9B,QAAQ,IAAI,yCAAyC;gBACrD,iDAAiD,CACpD,CAAC,CAAC;QACP,CAAC;QAED,MAAM,UAAU,GAAmB;YAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,IAAI,EAAE,OAAO,CAAC,IAAI;SACrB,CAAC;QAEF,sEAAsE;QACtE,wEAAwE;QACxE,4EAA4E;QAC5E,MAAM,KAAK,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAW,CAAC;QAEzC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAC9B,yBAAyB,IAAI,KAAK,kBAAkB,CAAC,aAAa,CAAC,EAAE,EACrE,EAAE,YAAY,EAAE,aAAa,CAAC,MAAM,IAAI,EAAE,EAAE,CAC/C,CAAC,CAAC;QACP,CAAC;QAED,sEAAsE;QACtE,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;YAE5C,OAAO;gBACH,OAAO,EAAE;oBACL,IAAI,EAAE,iBAAiB;oBACvB,IAAI,EAAE,MAAM;iBACf;gBACD,OAAO,EAAE,KAAK;gBACd,QAAQ,EAAE;oBACN,QAAQ,EAAE,IAAI;oBACd,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;oBACtB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;iBACrC;aACJ,CAAC;QACN,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;QACpC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO;QACH,IAAI;QACJ,WAAW;QACX,QAAQ;QACR,WAAW;QACX,OAAO;QACP,aAAa;QACb,QAAQ;QACR,QAAQ,EAAE;YACN,GAAG,QAAQ;YACX,QAAQ;SACX;QACD,OAAO,EAAE,OAAuC;KACnD,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,MAAe;IACvC,OAAO,CACH,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,SAAS,IAAI,MAAM;QAClB,MAA+B,CAAC,OAAO,KAAK,IAAI,CACpD,CAAC;AACN,CAAC"}

package/dist/protocols/mcp/security/HttpTargetGuard.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * Result of checking a URL.
+ */
+export interface HttpTargetCheck {
+    /** Whether the fetch may proceed */
+    allowed: boolean;
+    /** Why it was refused — written for the model, so it can correct course */
+    reason?: string;
+    /** The addresses the hostname resolved to */
+    resolvedAddresses?: string[];
+}
+/**
+ * Check whether an agent-supplied URL may be fetched.
+ *
+ * @param rawUrl - The URL the tool was asked to fetch
+ * @returns Whether the fetch may proceed, and why not when it may not
+ */
+export declare function checkHttpTarget(rawUrl: string): Promise<HttpTargetCheck>;
+//# sourceMappingURL=HttpTargetGuard.d.ts.map

package/dist/protocols/mcp/security/HttpTargetGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpTargetGuard.d.ts","sourceRoot":"","sources":["../../../../src/protocols/mcp/security/HttpTargetGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAyBH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAkHD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA6F9E"}

package/dist/protocols/mcp/security/HttpTargetGuard.js

@@ -0,0 +1,227 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * HttpTargetGuard.ts
+ *
+ * Decides whether an agent-supplied URL may be fetched from the server.
+ *
+ * The server sits inside the trust boundary: it can reach the MXF API on
+ * localhost:3001, Meilisearch, MongoDB, and — on a cloud host — the instance
+ * metadata endpoint at 169.254.169.254 that hands out IAM credentials. A tool
+ * that fetches an arbitrary URL on the model's behalf turns the server into a
+ * proxy across that boundary (server-side request forgery).
+ *
+ * This guard resolves the hostname and checks every address it resolves to, so a
+ * public name that points at 127.0.0.1 is caught as well as a literal IP.
+ *
+ * The guard fails closed: a target that cannot be resolved or cannot be parsed
+ * is refused, with an error saying why. It never silently skips the check.
+ */
+import { promises as dns } from 'dns';
+import { isIP } from 'net';
+import { allowPrivateHttpHosts } from './McpToolPolicy.js';
+/**
+ * IPv4 ranges the server must not be steered into.
+ * Each entry is [first octet-based CIDR, human name].
+ */
+const BLOCKED_IPV4_RANGES = [
+    { cidr: '0.0.0.0/8', name: '"this network"' },
+    { cidr: '10.0.0.0/8', name: 'RFC1918 private network' },
+    { cidr: '100.64.0.0/10', name: 'carrier-grade NAT' },
+    { cidr: '127.0.0.0/8', name: 'loopback' },
+    { cidr: '169.254.0.0/16', name: 'link-local / cloud instance metadata' },
+    { cidr: '172.16.0.0/12', name: 'RFC1918 private network' },
+    { cidr: '192.0.0.0/24', name: 'IETF protocol assignments' },
+    { cidr: '192.168.0.0/16', name: 'RFC1918 private network' },
+    { cidr: '198.18.0.0/15', name: 'benchmark network' },
+    { cidr: '224.0.0.0/4', name: 'multicast' },
+    { cidr: '240.0.0.0/4', name: 'reserved' }
+];
+/** Convert a dotted-quad IPv4 string to a 32-bit unsigned integer. */
+function ipv4ToInt(address) {
+    const octets = address.split('.');
+    if (octets.length !== 4) {
+        return null;
+    }
+    let value = 0;
+    for (const octet of octets) {
+        // Reject empty, non-numeric, or out-of-range octets rather than coercing.
+        if (!/^\d{1,3}$/.test(octet)) {
+            return null;
+        }
+        const num = Number(octet);
+        if (num > 255) {
+            return null;
+        }
+        value = (value << 8) | num;
+    }
+    // `>>> 0` forces the result back to unsigned — the shifts above produce a
+    // signed 32-bit int for addresses above 127.255.255.255.
+    return value >>> 0;
+}
+/** Is an IPv4 address inside the given CIDR block? */
+function ipv4InCidr(address, cidr) {
+    const [network, prefixText] = cidr.split('/');
+    const prefix = Number(prefixText);
+    const addressInt = ipv4ToInt(address);
+    const networkInt = ipv4ToInt(network);
+    if (addressInt === null || networkInt === null) {
+        return false;
+    }
+    // A /0 mask would shift by 32, which is a no-op in JS — handle it explicitly.
+    if (prefix === 0) {
+        return true;
+    }
+    const mask = (0xffffffff << (32 - prefix)) >>> 0;
+    return (addressInt & mask) === (networkInt & mask);
+}
+/**
+ * Is this address one the server must not be steered into?
+ *
+ * @returns the name of the matched range, or null when the address is fine
+ */
+function matchBlockedRange(address) {
+    const version = isIP(address);
+    if (version === 4) {
+        for (const range of BLOCKED_IPV4_RANGES) {
+            if (ipv4InCidr(address, range.cidr)) {
+                return range.name;
+            }
+        }
+        return null;
+    }
+    if (version === 6) {
+        const normalized = address.toLowerCase();
+        // IPv6 loopback
+        if (normalized === '::1' || normalized === '0:0:0:0:0:0:0:1') {
+            return 'IPv6 loopback';
+        }
+        // Unspecified address
+        if (normalized === '::' || normalized === '0:0:0:0:0:0:0:0') {
+            return 'IPv6 unspecified address';
+        }
+        // Unique local addresses, fc00::/7
+        if (/^f[cd][0-9a-f]{2}:/.test(normalized)) {
+            return 'IPv6 unique local address';
+        }
+        // Link-local, fe80::/10
+        if (/^fe[89ab][0-9a-f]:/.test(normalized)) {
+            return 'IPv6 link-local address';
+        }
+        // IPv4-mapped (::ffff:127.0.0.1) — re-check the embedded IPv4 address,
+        // otherwise ::ffff:169.254.169.254 would walk straight past this guard.
+        const mapped = normalized.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+        if (mapped) {
+            return matchBlockedRange(mapped[1]);
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * Check whether an agent-supplied URL may be fetched.
+ *
+ * @param rawUrl - The URL the tool was asked to fetch
+ * @returns Whether the fetch may proceed, and why not when it may not
+ */
+export async function checkHttpTarget(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return {
+            allowed: false,
+            reason: `"${rawUrl}" is not a valid URL.`
+        };
+    }
+    // Only HTTP(S). file:, gopher:, ftp: and friends reach places an HTTP client
+    // has no business reaching.
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return {
+            allowed: false,
+            reason: `Protocol "${url.protocol}" is not allowed. Use http: or https:.`
+        };
+    }
+    // The operator can open this up for local development. Off by default.
+    if (allowPrivateHttpHosts()) {
+        return { allowed: true };
+    }
+    const hostname = url.hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+    // A literal IP needs no DNS round trip.
+    if (isIP(hostname) !== 0) {
+        const blocked = matchBlockedRange(hostname);
+        if (blocked) {
+            return {
+                allowed: false,
+                reason: `Refusing to fetch ${hostname}: it is a ${blocked} address. ` +
+                    `This tool may only reach public internet hosts. ` +
+                    `Set MXF_HTTP_ALLOW_PRIVATE_HOSTS=true to permit private addresses.`,
+                resolvedAddresses: [hostname]
+            };
+        }
+        return { allowed: true, resolvedAddresses: [hostname] };
+    }
+    // "localhost" and anything under .localhost resolve to loopback by definition.
+    const lowerHost = hostname.toLowerCase();
+    if (lowerHost === 'localhost' || lowerHost.endsWith('.localhost')) {
+        return {
+            allowed: false,
+            reason: `Refusing to fetch ${hostname}: it is a loopback address. ` +
+                `This tool may only reach public internet hosts. ` +
+                `Set MXF_HTTP_ALLOW_PRIVATE_HOSTS=true to permit private addresses.`
+        };
+    }
+    // Resolve the name and check every address behind it. A public hostname can
+    // legitimately resolve to 127.0.0.1, and a malicious one will.
+    let addresses;
+    try {
+        const records = await dns.lookup(hostname, { all: true, verbatim: true });
+        addresses = records.map(record => record.address);
+    }
+    catch (error) {
+        // Fail closed. An unresolvable host is not a host we quietly try anyway.
+        return {
+            allowed: false,
+            reason: `Could not resolve "${hostname}": ` +
+                `${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+    if (addresses.length === 0) {
+        return {
+            allowed: false,
+            reason: `"${hostname}" did not resolve to any address.`
+        };
+    }
+    for (const address of addresses) {
+        const blocked = matchBlockedRange(address);
+        if (blocked) {
+            return {
+                allowed: false,
+                reason: `Refusing to fetch ${hostname}: it resolves to ${address}, ` +
+                    `a ${blocked} address. This tool may only reach public internet hosts. ` +
+                    `Set MXF_HTTP_ALLOW_PRIVATE_HOSTS=true to permit private addresses.`,
+                resolvedAddresses: addresses
+            };
+        }
+    }
+    return { allowed: true, resolvedAddresses: addresses };
+}
+//# sourceMappingURL=HttpTargetGuard.js.map

package/dist/protocols/mcp/security/HttpTargetGuard.js.map

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