@4onstudios/iris-agent 0.1.0

package/dist/api/core/agent/tools/mcpTools.js

@@ -0,0 +1,442 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import Ajv from "ajv";
+import os from "os";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport, } from "@modelcontextprotocol/sdk/client/stdio.js";
+const MCP_TIMEOUT_MS = 20000;
+const ajv = new Ajv({ allErrors: true });
+const safeToolToken = (value) => value.replace(/[^a-zA-Z0-9_]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 80);
+export const toMcpToolKey = (serverName, toolName) => `mcp_${safeToolToken(serverName)}_${safeToolToken(toolName)}`;
+const formatAjvErrorPath = (instancePath, missingProperty) => {
+    const path = instancePath || "/";
+    return missingProperty ? `${path}${path.endsWith("/") ? "" : "/"}${missingProperty}` : path;
+};
+const summarizeMcpContent = (content) => {
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = content
+        .map((item) => {
+        if (!item || typeof item !== "object")
+            return null;
+        const entry = item;
+        if (typeof entry.text === "string" && entry.text.trim()) {
+            return entry.text.trim();
+        }
+        if (typeof entry.message === "string" && entry.message.trim()) {
+            return entry.message.trim();
+        }
+        return null;
+    })
+        .filter((value) => Boolean(value));
+    if (parts.length === 0)
+        return undefined;
+    return parts.join("\n");
+};
+const summarizeStructuredError = (structuredContent) => {
+    if (!structuredContent || typeof structuredContent !== "object" || Array.isArray(structuredContent)) {
+        return undefined;
+    }
+    const record = structuredContent;
+    const directMessage = [record.error, record.message, record.detail]
+        .find((value) => typeof value === "string" && value.trim().length > 0);
+    if (typeof directMessage === "string") {
+        return directMessage.trim();
+    }
+    return undefined;
+};
+const toMcpToolParams = (params) => {
+    if (params === null || params === undefined)
+        return {};
+    if (typeof params === "object" && !Array.isArray(params)) {
+        return params;
+    }
+    return null;
+};
+export const validateMcpToolInput = (toolName, inputSchema, params) => {
+    if (!inputSchema || Object.keys(inputSchema).length === 0) {
+        return null;
+    }
+    const validate = ajv.compile(inputSchema);
+    const valid = validate(params);
+    if (valid) {
+        return null;
+    }
+    const details = (validate.errors || [])
+        .map((error) => {
+        const missingProperty = error.keyword === "required" &&
+            typeof error.params?.missingProperty === "string"
+            ? (error.params.missingProperty || undefined)
+            : undefined;
+        const path = formatAjvErrorPath(error.dataPath || "", missingProperty);
+        return `${path}: ${error.message || "invalid value"}`;
+    })
+        .join("; ");
+    return `Invalid arguments for MCP tool '${toolName}'. ${details}`;
+};
+export const summarizeMcpToolError = (result) => {
+    if (!result.isError)
+        return undefined;
+    return summarizeStructuredError(result.structuredContent) || summarizeMcpContent(result.content);
+};
+const buildAugmentedPath = () => {
+    const home = process.env.HOME || os.homedir() || "";
+    const currentPath = process.env.PATH || "";
+    const pathParts = [
+        currentPath,
+        "/opt/homebrew/bin",
+        "/usr/local/bin",
+        "/usr/bin",
+        "/bin",
+        home ? `${home}/.local/bin` : "",
+        home ? `${home}/.cargo/bin` : "",
+    ].filter(Boolean);
+    return Array.from(new Set(pathParts.join(":").split(":"))).join(":");
+};
+const shellEscape = (value) => `'${value.replace(/'/g, `'"'"'`)}'`;
+const toShellCommand = (command, args) => [command, ...args].map((part) => shellEscape(part)).join(" ");
+const getCommandCandidates = (command) => {
+    const base = command.trim();
+    if (!base)
+        return [];
+    const candidates = [{ command: base }];
+    if (base === "npx") {
+        candidates.push({ command: "/opt/homebrew/bin/npx" }, { command: "/usr/local/bin/npx" }, { command: "/usr/bin/npx" });
+    }
+    if (base === "uvx") {
+        const home = process.env.HOME || os.homedir() || "";
+        candidates.push({ command: "/opt/homebrew/bin/uvx" }, { command: "/usr/local/bin/uvx" }, { command: "/usr/bin/uvx" }, ...(home ? [{ command: `${home}/.cargo/bin/uvx` }] : []), ...(home ? [{ command: `${home}/.local/bin/uvx` }] : []), { command: "uv", prependArgs: ["x"] }, { command: "/opt/homebrew/bin/uv", prependArgs: ["x"] }, { command: "/usr/local/bin/uv", prependArgs: ["x"] }, ...(home ? [{ command: `${home}/.cargo/bin/uv`, prependArgs: ["x"] }] : []), ...(home ? [{ command: `${home}/.local/bin/uv`, prependArgs: ["x"] }] : []));
+    }
+    const seen = new Set();
+    return candidates.filter((candidate) => {
+        const key = `${candidate.command}::${(candidate.prependArgs || []).join(" ")}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+};
+const createTransportParams = (server, workspacePath) => {
+    const env = {
+        ...process.env,
+        ...server.env,
+    };
+    env.PATH = buildAugmentedPath();
+    return {
+        command: server.command.trim(),
+        args: [...server.args],
+        env,
+        cwd: workspacePath,
+        stderr: "pipe",
+    };
+};
+const connectClient = async (server, workspacePath) => {
+    const command = server.command.trim();
+    const args = [...server.args];
+    const commandCandidates = getCommandCandidates(command);
+    const attempted = [];
+    let lastError = null;
+    for (const candidate of commandCandidates) {
+        const client = new Client({ name: "iris-mcp", version: "1.0.0" });
+        const transport = new StdioClientTransport({
+            ...createTransportParams(server, workspacePath),
+            command: candidate.command,
+            args: [
+                ...(candidate.prependArgs || []),
+                ...args,
+            ],
+        });
+        attempted.push(`${candidate.command}${(candidate.prependArgs || []).length > 0
+            ? ` ${(candidate.prependArgs || []).join(" ")}`
+            : ""}`);
+        try {
+            await client.connect(transport, { timeout: MCP_TIMEOUT_MS });
+            return { client, transport };
+        }
+        catch (error) {
+            await closeTransport(transport);
+            lastError = error;
+            const message = lastError.message || "";
+            const isEnoent = /ENOENT/i.test(message);
+            if (!isEnoent) {
+                throw lastError;
+            }
+        }
+    }
+    // Some desktop launch contexts have constrained PATH/environment.
+    // If direct spawn failed with ENOENT, retry through a login shell.
+    if (lastError && /ENOENT/i.test(lastError.message || "")) {
+        const shellCommand = toShellCommand(command, args);
+        const shellCandidates = ["/bin/zsh", "/bin/bash"];
+        for (const shellPath of shellCandidates) {
+            const client = new Client({ name: "iris-mcp", version: "1.0.0" });
+            const transport = new StdioClientTransport({
+                ...createTransportParams(server, workspacePath),
+                command: shellPath,
+                args: ["-lc", shellCommand],
+            });
+            attempted.push(`${shellPath} -lc ${shellCommand}`);
+            try {
+                await client.connect(transport, { timeout: MCP_TIMEOUT_MS });
+                return { client, transport };
+            }
+            catch (error) {
+                await closeTransport(transport);
+                lastError = error;
+            }
+        }
+    }
+    if (lastError) {
+        const detail = attempted.length > 0 ? ` Tried: ${attempted.join(", ")}.` : "";
+        throw new Error(`${lastError.message}${detail}`);
+    }
+    throw new Error("Failed to start MCP client transport");
+};
+const closeTransport = async (transport) => {
+    if (!transport)
+        return;
+    try {
+        await transport.close();
+    }
+    catch {
+        // No-op; transport teardown should not fail request handling.
+    }
+};
+export const listMcpServerTools = async (server, workspacePath) => {
+    let transport;
+    try {
+        const { client, transport: activeTransport } = await connectClient(server, workspacePath);
+        transport = activeTransport;
+        const listed = await client.listTools(undefined, { timeout: MCP_TIMEOUT_MS });
+        return (listed.tools || []).map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: (tool.inputSchema || {}),
+        }));
+    }
+    finally {
+        await closeTransport(transport);
+    }
+};
+const callServerTool = async (server, workspacePath, toolName, input) => {
+    let transport;
+    try {
+        const { client, transport: activeTransport } = await connectClient(server, workspacePath);
+        transport = activeTransport;
+        const result = await client.callTool({
+            name: toolName,
+            arguments: input,
+        }, undefined, { timeout: MCP_TIMEOUT_MS });
+        return {
+            success: !result.isError,
+            server: server.name,
+            tool: toolName,
+            isError: !!result.isError,
+            content: result.content,
+            structuredContent: result.structuredContent,
+            error: summarizeMcpToolError({
+                isError: !!result.isError,
+                content: result.content,
+                structuredContent: result.structuredContent,
+            }),
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            success: false,
+            server: server.name,
+            tool: toolName,
+            isError: true,
+            error: err.message,
+        };
+    }
+    finally {
+        await closeTransport(transport);
+    }
+};
+export const executeMcpToolByKey = async (servers, workspacePath, toolKey, input) => {
+    console.log("🔍 executeMcpToolByKey called with:", {
+        toolKey,
+        inputKeys: Object.keys(input),
+        serversCount: servers.length,
+    });
+    for (const server of servers) {
+        if (!server.enabled) {
+            console.log(`⏭️ Skipping disabled server: ${server.name}`);
+            continue;
+        }
+        console.log(`🔍 Checking server: ${server.name}`);
+        let tools = [];
+        try {
+            console.log(`📋 Listing tools from ${server.name}...`);
+            tools = await listMcpServerTools(server, workspacePath);
+            console.log(`✅ ${server.name} reports ${tools.length} tools available`);
+        }
+        catch (error) {
+            console.error(`❌ Failed to list tools from ${server.name}:`, error.message);
+            continue;
+        }
+        for (const tool of tools) {
+            const computedKey = toMcpToolKey(server.name, tool.name);
+            console.log(`🔑 Checking tool: ${tool.name} (key: ${computedKey})`);
+            if (computedKey !== toolKey) {
+                continue;
+            }
+            console.log(`🎯 Match found! Validating input for ${tool.name}...`);
+            const validationError = validateMcpToolInput(tool.name, tool.inputSchema, input);
+            if (validationError) {
+                console.error("❌ Input validation failed:", validationError);
+                return {
+                    success: false,
+                    server: server.name,
+                    tool: tool.name,
+                    isError: true,
+                    error: validationError,
+                };
+            }
+            console.log("🚀 Calling MCP tool with input:", input);
+            const result = await callServerTool(server, workspacePath, tool.name, input);
+            console.log("✅ MCP tool call completed");
+            console.log("📤 Result:", result);
+            return result;
+        }
+    }
+    console.warn("⚠️ Tool key not found on any server:", toolKey);
+    return {
+        success: false,
+        isError: true,
+        error: `MCP tool '${toolKey}' is not available on the configured servers`,
+    };
+};
+/**
+ * Generate MCP tools documentation for persistence in knowledge base.
+ * Only includes servers that are connected and available.
+ * Returns tool metadata that can be stored in the workspace for semantic search.
+ * Returns null if no connected servers with tools are available.
+ */
+export const generateMcpToolsDocs = async (servers, workspacePath) => {
+    const sections = [
+        "# MCP Tools Documentation",
+        "",
+        "This document contains all available MCP (Model Context Protocol) tools registered in this workspace.",
+        "Only connected and available servers are documented here.",
+        "",
+    ];
+    let hasAnyTools = false;
+    for (const server of servers) {
+        if (!server.enabled)
+            continue;
+        let tools = [];
+        try {
+            tools = await listMcpServerTools(server, workspacePath);
+        }
+        catch (error) {
+            const err = error;
+            console.warn(`[mcp-docs] Skipping unavailable server ${server.name}: ${err.message}`);
+            // Skip unavailable servers - don't document them
+            continue;
+        }
+        // Skip servers with no tools
+        if (tools.length === 0) {
+            console.warn(`[mcp-docs] Skipping server ${server.name}: no tools exposed`);
+            continue;
+        }
+        hasAnyTools = true;
+        sections.push(`## ${server.name}`);
+        sections.push(`- **Command**: \`${server.command}\``);
+        sections.push(`- **Tools**: ${tools.length}`);
+        sections.push(`- **Status**: ✅ Connected`);
+        sections.push("");
+        for (const tool of tools) {
+            const toolKey = toMcpToolKey(server.name, tool.name);
+            sections.push(`### \`${toolKey}\``);
+            sections.push("");
+            sections.push(`**Description**: ${tool.description || "No description available"}`);
+            sections.push("");
+            if (tool.inputSchema) {
+                sections.push("**Input Schema**:");
+                sections.push("```json");
+                sections.push(JSON.stringify(tool.inputSchema, null, 2));
+                sections.push("```");
+                sections.push("");
+            }
+            sections.push(`**Usage Example**:`);
+            sections.push("```javascript");
+            sections.push(`${toolKey}({ /* args matching schema */ })`);
+            sections.push("```");
+            sections.push("");
+        }
+    }
+    // Return null if no servers have tools available
+    return hasAnyTools ? sections.join("\n") : null;
+};
+export const buildMcpTools = async (servers, workspacePath) => {
+    const registered = {};
+    for (const server of servers) {
+        if (!server.enabled)
+            continue;
+        let tools = [];
+        try {
+            tools = await listMcpServerTools(server, workspacePath);
+        }
+        catch (error) {
+            const err = error;
+            console.warn(`[mcp] Failed to list tools for ${server.name} (${server.command}): ${err.message}`);
+            continue;
+        }
+        for (const tool of tools) {
+            const key = toMcpToolKey(server.name, tool.name);
+            if (!key || registered[key])
+                continue;
+            const schemaPreview = tool.inputSchema
+                ? JSON.stringify(tool.inputSchema).slice(0, 800)
+                : "{}";
+            // Expose the MCP server's declared JSON Schema directly to the model's
+            // function-calling API instead of an unconstrained passthrough object.
+            // Previously every MCP tool used `z.object({}).passthrough()`, so the
+            // model had no structured schema to call against and had to *guess*
+            // the parameter shape from a text blob in the description. That caused
+            // repeated invalid tool calls (caught by Ajv validation below) until
+            // the tool-call budget's repeated-call guard kicked in and forced an
+            // abrupt synthesis/response. Passing the real JSON Schema lets
+            // providers that support structured tool calling constrain arguments
+            // correctly on the first attempt.
+            const toolInputSchema = tool.inputSchema && Object.keys(tool.inputSchema).length > 0
+                ? tool.inputSchema
+                : z.object({}).passthrough();
+            registered[key] = createTool({
+                id: key,
+                description: `MCP tool from server '${server.name}' (${server.command}) named '${tool.name}'. ` +
+                    `Pass the tool arguments directly as fields in the input object and match the declared schema exactly.` +
+                    `\n\nDeclared input schema:\n${schemaPreview}`,
+                inputSchema: toolInputSchema,
+                execute: async (params) => {
+                    const input = toMcpToolParams(params);
+                    if (!input) {
+                        return {
+                            success: false,
+                            server: server.name,
+                            tool: tool.name,
+                            isError: true,
+                            error: `Invalid arguments for MCP tool '${tool.name}'. Expected an object.`,
+                        };
+                    }
+                    const validationError = validateMcpToolInput(tool.name, tool.inputSchema, input);
+                    if (validationError) {
+                        return {
+                            success: false,
+                            server: server.name,
+                            tool: tool.name,
+                            isError: true,
+                            error: validationError,
+                        };
+                    }
+                    return callServerTool(server, workspacePath, tool.name, input);
+                },
+            });
+        }
+    }
+    return registered;
+};

package/dist/api/core/agent/tools/queryKnowledgeGraph.d.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+type QueryType = "summary" | "relationships" | "components" | "related-files" | "stats" | "question";
+type QueryKnowledgeGraphParams = {
+    filePath?: string;
+    queryType?: QueryType;
+    question?: string;
+    maxDepth?: number;
+    maxTokens?: number;
+};
+type ComponentSummary = {
+    type: string;
+    name: string;
+    line: number | undefined;
+    tokenCount: number;
+};
+type RelationshipInfo = {
+    nodeId: string;
+    type: string;
+    name: string;
+    metadata?: Record<string, unknown>;
+};
+type FileSummary = {
+    fileName: unknown;
+    language: unknown;
+    tokenCount: number;
+    accessCount: number;
+    lastAccessed: string;
+    componentCount: number;
+    components: ComponentSummary[];
+    relationshipCount: number;
+};
+type RelationshipSummary = {
+    imports: RelationshipInfo[];
+    exports: RelationshipInfo[];
+    calls: RelationshipInfo[];
+    usedBy: Array<{
+        nodeId: string;
+        type: string;
+        name: string;
+    }>;
+    contains: RelationshipInfo[];
+};
+type ComponentGroups = {
+    functions: Array<Record<string, unknown>>;
+    classes: Array<Record<string, unknown>>;
+    imports: Array<Record<string, unknown>>;
+    methods: Array<Record<string, unknown>>;
+    other: Array<Record<string, unknown>>;
+};
+type RelatedFilesSummary = {
+    imports: string[];
+    importedBy: string[];
+    allDependencies: string[];
+};
+type GraphStatistics = {
+    nodeCount: number;
+    cacheSize: number;
+    cacheHits: number;
+    cacheMisses: number;
+    hitRate: string;
+    totalTokensSaved: number;
+    estimatedCostSaved: string;
+};
+type QuestionSummary = {
+    question: string;
+    matchedTerms: string[];
+    anchorNodes: Array<{
+        id: string;
+        type: string;
+        name: unknown;
+    }>;
+    nodeCount: number;
+    tokenCount: number;
+    contextPreview: string;
+};
+type QueryKnowledgeGraphData = FileSummary | RelationshipSummary | ComponentGroups | RelatedFilesSummary | GraphStatistics | QuestionSummary;
+type QueryKnowledgeGraphResult = {
+    success: true;
+    filePath: string;
+    queryType: QueryType;
+    data: QueryKnowledgeGraphData;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Query the knowledge graph for code insights
+ * @param {Object} params
+ * @param {string} params.filePath - The file path to query
+ * @param {string} [params.queryType] - Type of query: 'summary', 'relationships', 'components', 'related-files'
+ * @returns {Promise<Object>} Query results from knowledge graph
+ */
+export declare function queryKnowledgeGraph({ filePath, queryType, question, maxDepth, maxTokens, }: QueryKnowledgeGraphParams): Promise<QueryKnowledgeGraphResult>;
+/**
+ * Tool metadata for agent system
+ */
+export declare const queryKnowledgeGraphTool: {
+    description: string;
+    parameters: z.ZodObject<{
+        filePath: z.ZodOptional<z.ZodString>;
+        queryType: z.ZodDefault<z.ZodEnum<["summary", "relationships", "components", "related-files", "stats", "question"]>>;
+        question: z.ZodOptional<z.ZodString>;
+        maxDepth: z.ZodDefault<z.ZodNumber>;
+        maxTokens: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxDepth?: number;
+        maxTokens?: number;
+        filePath?: string;
+        question?: string;
+        queryType?: "question" | "components" | "relationships" | "summary" | "related-files" | "stats";
+    }, {
+        maxDepth?: number;
+        maxTokens?: number;
+        filePath?: string;
+        question?: string;
+        queryType?: "question" | "components" | "relationships" | "summary" | "related-files" | "stats";
+    }>;
+    execute: typeof queryKnowledgeGraph;
+};
+export default queryKnowledgeGraphTool;