@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/mcp/toolAnnotations.js

@@ -0,0 +1,239 @@
+/**
+ * MCP Tool Annotations System
+ *
+ * Enhanced tool annotations for MCP tools providing hints to AI models
+ * about tool behavior, safety, and execution characteristics.
+ *
+ * Implements MCP 2024-11-05 specification tool annotations including:
+ * - readOnlyHint: Tool only reads data
+ * - destructiveHint: Tool performs destructive operations
+ * - idempotentHint: Tool can be safely retried
+ * - requiresConfirmation: Tool needs user confirmation
+ *
+ * @module mcp/toolAnnotations
+ * @since 8.39.0
+ */
+/**
+ * Infer annotations from tool definition
+ * Uses heuristics based on tool description and name
+ */
+export function inferAnnotations(tool) {
+    const name = tool.name;
+    const description = tool.description.toLowerCase();
+    const annotations = {};
+    // Helper: match keyword with word boundaries to avoid false positives
+    // (e.g., "get" should not match "forget", "together", "target")
+    // Also handles underscore/hyphen/camelCase-separated names (e.g., "delete_record", "readFile")
+    const matchesKeyword = (text, keyword) => {
+        // Standard word boundary match (works for space-separated text like descriptions)
+        if (new RegExp(`\\b${keyword}\\b`, "i").test(text)) {
+            return true;
+        }
+        // Also check underscore/hyphen/camelCase segments (common in tool names)
+        const normalized = text
+            .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+            .toLowerCase();
+        return normalized
+            .split(/[_-]/)
+            .some((segment) => segment === keyword.toLowerCase());
+    };
+    // Infer read-only from description keywords
+    const readOnlyKeywords = [
+        "get",
+        "list",
+        "read",
+        "fetch",
+        "query",
+        "search",
+        "find",
+        "show",
+        "display",
+        "view",
+        "retrieve",
+        "check",
+        "inspect",
+        "look",
+    ];
+    if (readOnlyKeywords.some((keyword) => matchesKeyword(description, keyword) || matchesKeyword(name, keyword))) {
+        annotations.readOnlyHint = true;
+    }
+    // Infer destructive from description keywords
+    const destructiveKeywords = [
+        "delete",
+        "remove",
+        "drop",
+        "destroy",
+        "clear",
+        "purge",
+        "erase",
+        "wipe",
+        "truncate",
+        "reset",
+    ];
+    if (destructiveKeywords.some((keyword) => matchesKeyword(description, keyword) || matchesKeyword(name, keyword))) {
+        annotations.destructiveHint = true;
+        annotations.requiresConfirmation = true;
+    }
+    // Infer idempotent from description keywords
+    const idempotentKeywords = ["set", "update", "put", "upsert", "replace"];
+    if (idempotentKeywords.some((keyword) => matchesKeyword(description, keyword) || matchesKeyword(name, keyword)) &&
+        !annotations.destructiveHint) {
+        annotations.idempotentHint = true;
+    }
+    // Infer complexity from description length and keywords
+    const complexKeywords = [
+        "complex",
+        "analyze",
+        "process",
+        "generate",
+        "transform",
+        "compute",
+        "calculate",
+    ];
+    if (complexKeywords.some((keyword) => matchesKeyword(description, keyword) || matchesKeyword(name, keyword))) {
+        annotations.complexity = "complex";
+    }
+    else if (description.length > 100) {
+        annotations.complexity = "medium";
+    }
+    else {
+        annotations.complexity = "simple";
+    }
+    return annotations;
+}
+/**
+ * Merge multiple annotation objects with precedence
+ * Later annotations override earlier ones
+ */
+export function mergeAnnotations(...annotationSets) {
+    const result = {};
+    for (const annotations of annotationSets) {
+        if (annotations) {
+            const existingTags = result.tags ? [...result.tags] : [];
+            Object.assign(result, annotations);
+            // Special handling for arrays (merge instead of replace)
+            if (existingTags.length > 0 || annotations.tags) {
+                const newTags = annotations.tags ?? [];
+                result.tags = [...new Set([...existingTags, ...newTags])];
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Validate tool annotations
+ * Returns list of validation errors (empty if valid)
+ */
+export function validateAnnotations(annotations) {
+    const errors = [];
+    // Check for conflicting annotations
+    if (annotations.readOnlyHint && annotations.destructiveHint) {
+        errors.push("Tool cannot be both readOnly and destructive - these are conflicting hints");
+    }
+    // Validate rate limit hint
+    if (annotations.rateLimitHint !== undefined &&
+        (annotations.rateLimitHint < 0 ||
+            !Number.isFinite(annotations.rateLimitHint))) {
+        errors.push("rateLimitHint must be a non-negative number");
+    }
+    // Validate estimated duration
+    if (annotations.estimatedDuration !== undefined &&
+        (annotations.estimatedDuration < 0 ||
+            !Number.isFinite(annotations.estimatedDuration))) {
+        errors.push("estimatedDuration must be a non-negative number");
+    }
+    // Validate cost hint
+    if (annotations.costHint !== undefined &&
+        (annotations.costHint < 0 || !Number.isFinite(annotations.costHint))) {
+        errors.push("costHint must be a non-negative number");
+    }
+    // Validate tags are strings
+    if (annotations.tags) {
+        for (const tag of annotations.tags) {
+            if (typeof tag !== "string" || tag.length === 0) {
+                errors.push("All tags must be non-empty strings");
+                break;
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Create a tool with default annotations inferred
+ */
+export function createAnnotatedTool(tool) {
+    const inferredAnnotations = inferAnnotations(tool);
+    const mergedAnnotations = mergeAnnotations(inferredAnnotations, tool.annotations);
+    return {
+        ...tool,
+        annotations: mergedAnnotations,
+    };
+}
+/**
+ * Check if a tool requires confirmation based on annotations
+ */
+export function requiresConfirmation(tool) {
+    return !!(tool.annotations?.requiresConfirmation || tool.annotations?.destructiveHint);
+}
+/**
+ * Check if a tool is safe for automatic retry
+ */
+export function isSafeToRetry(tool) {
+    return !!(tool.annotations?.idempotentHint || tool.annotations?.readOnlyHint);
+}
+/**
+ * Get tool safety level based on annotations
+ */
+export function getToolSafetyLevel(tool) {
+    if (tool.annotations?.destructiveHint) {
+        return "dangerous";
+    }
+    if (tool.annotations?.readOnlyHint) {
+        return "safe";
+    }
+    if (tool.annotations?.idempotentHint) {
+        return "moderate";
+    }
+    // Default to moderate for unknown tools
+    return "moderate";
+}
+/**
+ * Filter tools by annotation predicates
+ */
+export function filterToolsByAnnotations(tools, predicate) {
+    return tools.filter((tool) => {
+        const annotations = tool.annotations ?? {};
+        return predicate(annotations);
+    });
+}
+/**
+ * Get human-readable summary of tool annotations
+ */
+export function getAnnotationSummary(annotations) {
+    const parts = [];
+    if (annotations.title) {
+        parts.push(annotations.title);
+    }
+    if (annotations.readOnlyHint) {
+        parts.push("read-only");
+    }
+    if (annotations.destructiveHint) {
+        parts.push("DESTRUCTIVE");
+    }
+    if (annotations.idempotentHint) {
+        parts.push("idempotent");
+    }
+    if (annotations.requiresConfirmation) {
+        parts.push("requires confirmation");
+    }
+    if (annotations.complexity) {
+        parts.push(`${annotations.complexity} complexity`);
+    }
+    if (annotations.estimatedDuration !== undefined) {
+        parts.push(`~${annotations.estimatedDuration}ms`);
+    }
+    if (annotations.tags?.length) {
+        parts.push(`tags: ${annotations.tags.join(", ")}`);
+    }
+    return parts.length > 0 ? `[${parts.join(" | ")}]` : "[no annotations]";
+}

package/dist/client/mcp/toolConverter.js

@@ -0,0 +1,258 @@
+/**
+ * Tool Converter Utilities
+ *
+ * Converts between NeuroLink tool format and MCP tool format.
+ * Enables seamless interoperability between NeuroLink's internal
+ * tool representation and the MCP protocol specification.
+ *
+ * @module mcp/toolConverter
+ * @since 8.39.0
+ */
+import { inferAnnotations } from "./toolAnnotations.js";
+import { withTimeout } from "../utils/async/withTimeout.js";
+/**
+ * Convert NeuroLink tool to MCP server tool format
+ */
+export function neuroLinkToolToMCP(tool, options = {}) {
+    const { inferAnnotations: shouldInfer = true, defaultAnnotations = {}, preserveMetadata = true, namespacePrefix, } = options;
+    // Apply namespace prefix if provided
+    const toolName = namespacePrefix
+        ? `${namespacePrefix}_${tool.name}`
+        : tool.name;
+    // Infer annotations from tool definition
+    const inferredAnnotations = shouldInfer
+        ? inferAnnotations({ name: tool.name, description: tool.description })
+        : {};
+    // Build annotations
+    const annotations = {
+        ...defaultAnnotations,
+        ...inferredAnnotations,
+    };
+    // Add tags if present
+    if (tool.tags?.length) {
+        annotations.tags = [
+            ...new Set([...(annotations.tags ?? []), ...tool.tags]),
+        ];
+    }
+    // Build input schema
+    const inputSchema = tool.parameters ?? {
+        type: "object",
+        properties: {},
+    };
+    // Build metadata
+    const metadata = preserveMetadata
+        ? { ...tool.metadata }
+        : {};
+    if (tool.category) {
+        metadata.category = tool.category;
+    }
+    if (tool.isAsync !== undefined) {
+        metadata.isAsync = tool.isAsync;
+    }
+    return {
+        name: toolName,
+        description: tool.description,
+        inputSchema,
+        annotations,
+        execute: tool.execute,
+        metadata,
+    };
+}
+/**
+ * Convert MCP server tool to NeuroLink tool format
+ */
+export function mcpToolToNeuroLink(tool, options = {}) {
+    const { removeNamespacePrefix } = options;
+    // Remove namespace prefix if provided
+    let toolName = tool.name;
+    if (removeNamespacePrefix &&
+        tool.name.startsWith(`${removeNamespacePrefix}_`)) {
+        toolName = tool.name.slice(removeNamespacePrefix.length + 1);
+    }
+    return {
+        name: toolName,
+        description: tool.description,
+        parameters: tool.inputSchema,
+        execute: tool.execute,
+        category: tool.metadata?.category,
+        tags: tool.annotations?.tags,
+        metadata: tool.metadata,
+    };
+}
+/**
+ * Convert MCP protocol tool to MCPServerTool
+ * (For tools received from external MCP servers)
+ */
+export function mcpProtocolToolToServerTool(protocolTool, executor, options = {}) {
+    const { inferAnnotations: shouldInfer = true, defaultAnnotations = {} } = options;
+    // Convert protocol annotations to our format
+    const protocolAnnotations = protocolTool.annotations ?? {};
+    // Infer additional annotations
+    const inferredAnnotations = shouldInfer
+        ? inferAnnotations({
+            name: protocolTool.name,
+            description: protocolTool.description ?? "",
+        })
+        : {};
+    // Merge annotations with precedence: protocol > inferred > defaults
+    const annotations = {
+        ...defaultAnnotations,
+        ...inferredAnnotations,
+        title: protocolAnnotations.title ??
+            inferredAnnotations.title ??
+            defaultAnnotations.title,
+        readOnlyHint: protocolAnnotations.readOnlyHint ??
+            inferredAnnotations.readOnlyHint ??
+            defaultAnnotations.readOnlyHint,
+        destructiveHint: protocolAnnotations.destructiveHint ??
+            inferredAnnotations.destructiveHint ??
+            defaultAnnotations.destructiveHint,
+        idempotentHint: protocolAnnotations.idempotentHint ??
+            inferredAnnotations.idempotentHint ??
+            defaultAnnotations.idempotentHint,
+        openWorldHint: protocolAnnotations.openWorldHint ??
+            inferredAnnotations.openWorldHint ??
+            defaultAnnotations.openWorldHint,
+    };
+    return {
+        name: protocolTool.name,
+        description: protocolTool.description ?? "No description provided",
+        inputSchema: protocolTool.inputSchema,
+        annotations,
+        execute: executor,
+    };
+}
+/**
+ * Convert MCPServerTool to MCP protocol tool format
+ * (For exposing tools to external MCP clients)
+ */
+export function serverToolToMCPProtocol(tool) {
+    // Build protocol annotations
+    const annotations = {};
+    if (tool.annotations?.title) {
+        annotations.title = tool.annotations.title;
+    }
+    if (tool.annotations?.readOnlyHint !== undefined) {
+        annotations.readOnlyHint = tool.annotations.readOnlyHint;
+    }
+    if (tool.annotations?.destructiveHint !== undefined) {
+        annotations.destructiveHint = tool.annotations.destructiveHint;
+    }
+    if (tool.annotations?.idempotentHint !== undefined) {
+        annotations.idempotentHint = tool.annotations.idempotentHint;
+    }
+    if (tool.annotations?.openWorldHint !== undefined) {
+        annotations.openWorldHint = tool.annotations.openWorldHint;
+    }
+    // Build input schema
+    const inputSchema = tool.inputSchema ?? {
+        type: "object",
+        properties: {},
+    };
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: {
+            type: "object",
+            properties: (inputSchema.properties ?? {}),
+            required: ("required" in inputSchema
+                ? inputSchema.required
+                : undefined),
+        },
+        annotations: Object.keys(annotations).length > 0 ? annotations : undefined,
+    };
+}
+/**
+ * Batch convert NeuroLink tools to MCP format
+ */
+export function batchConvertToMCP(tools, options = {}) {
+    return tools.map((tool) => neuroLinkToolToMCP(tool, options));
+}
+/**
+ * Batch convert MCP tools to NeuroLink format
+ */
+export function batchConvertToNeuroLink(tools, options = {}) {
+    return tools.map((tool) => mcpToolToNeuroLink(tool, options));
+}
+/**
+ * Create a tool from a function with automatic schema inference
+ */
+export function createToolFromFunction(name, description, fn, options) {
+    const inferredAnnotations = inferAnnotations({ name, description });
+    return {
+        name,
+        description,
+        inputSchema: options?.parameters ?? { type: "object", properties: {} },
+        annotations: {
+            ...inferredAnnotations,
+            ...options?.annotations,
+        },
+        execute: async (params, context) => {
+            const toolTimeoutMs = 30_000;
+            const result = await withTimeout(fn(params, context), toolTimeoutMs, `Tool '${name}' execution timed out after ${toolTimeoutMs}ms`);
+            return result;
+        },
+        metadata: options?.metadata,
+    };
+}
+/**
+ * Validate tool name according to MCP specification
+ */
+export function validateToolName(name) {
+    const errors = [];
+    if (!name || typeof name !== "string") {
+        errors.push("Tool name is required and must be a string");
+    }
+    else {
+        if (name.length > 64) {
+            errors.push("Tool name must be 64 characters or less");
+        }
+        if (!/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(name)) {
+            errors.push("Tool name must start with a letter or underscore and contain only alphanumeric characters, underscores, and hyphens");
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Sanitize tool name for MCP compatibility
+ */
+export function sanitizeToolName(name) {
+    // Replace invalid characters with underscores
+    let sanitized = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+    // Ensure starts with letter or underscore
+    if (!/^[a-zA-Z_]/.test(sanitized)) {
+        sanitized = `_${sanitized}`;
+    }
+    // Truncate to 64 characters
+    if (sanitized.length > 64) {
+        sanitized = sanitized.slice(0, 64);
+    }
+    return sanitized;
+}
+/**
+ * Tool compatibility matrix
+ */
+export const TOOL_COMPATIBILITY = {
+    /**
+     * Features supported by MCP 2024-11-05 specification
+     */
+    MCP_2024_11_05: {
+        annotations: true,
+        inputSchema: true,
+        outputSchema: false,
+        streamingResults: false,
+        batchExecution: false,
+    },
+    /**
+     * Features supported by NeuroLink
+     */
+    NEUROLINK: {
+        annotations: true,
+        inputSchema: true,
+        outputSchema: true,
+        streamingResults: true,
+        batchExecution: true,
+        categories: true,
+        tags: true,
+    },
+};