@juspay/neurolink 9.32.0 → 9.33.0

package/dist/client/mcp/toolAnnotations.js

@@ -1,239 +0,0 @@
-/**
- * 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

@@ -1,258 +0,0 @@
-/**
- * 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,
-    },
-};