@mimik/agent-kit 1.0.0

package/src/agent.js

@@ -0,0 +1,456 @@
+/* eslint-disable no-await-in-loop, no-plusplus, no-continue, class-methods-use-this */
+
+const { createChatCompletionStream } = require('./oai');
+const { MCPServer, convertMCPToolsToOpenAI } = require('./mcp-server');
+
+// MCP Agent Class
+class Agent {
+  constructor(config) {
+    this.name = config.name || 'MCP Assistant';
+    this.instructions = config.instructions || 'You are a helpful assistant with access to MCP tools.';
+    this.maxIterations = config.maxIterations || 5;
+
+    // LLM configuration grouped together
+    const llmConfig = config.llm || {};
+    this.llm = {
+      model: llmConfig.model || 'lmstudio-community/Qwen3-4B-GGUF',
+      temperature: llmConfig.temperature || 0.1,
+      max_tokens: llmConfig.max_tokens || 2048,
+      endpoint: llmConfig.endpoint || 'http://127.0.0.1:8083/api/milm/v1/chat/completions',
+      apiKey: llmConfig.apiKey || 'bearer 1234',
+      no_think: llmConfig.no_think || false
+    };
+
+    // MCP configuration - support multiple endpoints
+    this.mcpEndpoints = config.mcpEndpoints || [config.mcpEndpoint];
+    this.httpClient = config.httpClient;
+    this.mcpServers = new Map(); // Map of endpoint -> MCPServer instance
+    this.tools = [];
+    this.toolToServerMap = new Map(); // Map of tool name -> server endpoint
+  }
+
+  async initialize() {
+    try {
+      let totalTools = 0;
+
+      // Initialize all MCP servers
+      for (const endpointObj of this.mcpEndpoints) {
+        try {
+          let endpoint;
+          let apiKey;
+          let options;
+          if (typeof endpointObj === 'object') {
+            endpoint = endpointObj.url;
+            apiKey = endpointObj.apiKey;
+            options = endpointObj.options;
+          } else {
+            endpoint = endpointObj;
+          }
+
+          if (!endpoint) {
+            continue;
+          }
+          // console.log(`[${this.name}] Initializing MCP server: ${endpoint}`);
+
+          const mcpServer = new MCPServer(this.httpClient, endpoint, apiKey, options);
+          await mcpServer.initialize();
+
+          // Load tools from this server
+          const toolsResult = await mcpServer.listTools();
+          const serverTools = convertMCPToolsToOpenAI(toolsResult.tools);
+
+          // Store server and tools
+          this.mcpServers.set(endpoint, mcpServer);
+
+          // Add tools to global list and map them to their server
+          for (const tool of serverTools) {
+            this.tools.push({
+              ...tool,
+              _mcpEndpoint: endpoint, // Add metadata for routing
+            });
+            this.toolToServerMap.set(tool.function.name, endpoint);
+          }
+
+          totalTools += serverTools.length;
+          // console.log(`[${this.name}] Server ${endpoint}: ${serverTools.length} tools loaded`);
+        } catch (error) {
+          // console.error(`[${this.name}] Failed to initialize ${endpoint}:`, error);
+          // Continue with other servers even if one fails
+        }
+      }
+
+      // console.log(`[${this.name}] Initialized with ${totalTools} tools from ${this.mcpServers.size} servers`);
+      return this;
+    } catch (error) {
+      // console.error(`[${this.name}] Initialization error:`, error);
+      this.tools = [];
+      return this;
+    }
+  }
+
+  async run(userMessage, options = {}) {
+    const { toolApproval = null } = options;
+
+    const stream = true;
+
+    if (this.mcpServers.size === 0) {
+      await this.initialize();
+    }
+
+    let userPrompt = userMessage;
+
+    if (this.llm.no_think) {
+      userPrompt = `${userMessage} /no_think`;
+    }
+
+    const messages = [
+      { role: 'system', content: this.instructions },
+      { role: 'user', content: userPrompt },
+    ];
+
+    if (stream) {
+      return this.runStreaming(messages, { toolApproval });
+    }
+    return this.runSync(messages, { toolApproval });
+  }
+
+  async* runStreaming(initialMessages, options = {}) {
+    const { toolApproval = null } = options;
+    const conversationMessages = [...initialMessages];
+    let iteration = 0;
+    let finalOutput = '';
+
+    while (iteration < this.maxIterations) {
+      iteration++;
+
+      yield {
+        type: 'iteration_start',
+        data: { iteration, messages: conversationMessages },
+      };
+
+      const stream = await this.createLLMStream(conversationMessages);
+
+      const assistantMessage = {
+        role: 'assistant',
+        content: '',
+        tool_calls: [],
+      };
+
+      const currentToolCalls = {};
+      let hasToolCalls = false;
+      let finishReason = null;
+
+      // Process stream
+      for await (const chunk of stream) {
+        if (chunk.data && chunk.type === 'data') {
+          const chunkData = chunk.data;
+
+          yield {
+            type: 'raw_model_stream_event',
+            data: { type: 'model', event: chunkData },
+          };
+
+          if (chunkData.choices?.[0]?.delta) {
+            const { delta } = chunkData.choices[0];
+
+            // Handle content
+            if (delta.content) {
+              if (delta.content.indexOf('<|processing_prompt|>') >= 0) {
+              }
+              else if (delta.content.indexOf('<|loading_model|>') >= 0) {
+              }
+              else {
+                assistantMessage.content += delta.content;
+                finalOutput += delta.content;
+              }
+
+              yield {
+                type: 'content_delta',
+                data: { content: delta.content },
+              };
+            }
+
+            // Handle tool calls
+            if (delta.tool_calls) {
+              hasToolCalls = true;
+
+              for (const toolCallDelta of delta.tool_calls) {
+                const { index } = toolCallDelta;
+
+                if (!currentToolCalls[index]) {
+                  currentToolCalls[index] = {
+                    id: '',
+                    type: 'function',
+                    function: { name: '', arguments: '' },
+                  };
+                }
+
+                if (toolCallDelta.id) currentToolCalls[index].id = toolCallDelta.id;
+                if (toolCallDelta.function?.name) currentToolCalls[index].function.name += toolCallDelta.function.name;
+                if (toolCallDelta.function?.arguments) currentToolCalls[index].function.arguments += toolCallDelta.function.arguments;
+              }
+
+              yield {
+                type: 'tool_call_delta',
+                data: { tool_calls: delta.tool_calls },
+              };
+            }
+
+            if (chunkData.choices[0].finish_reason) {
+              finishReason = chunkData.choices[0].finish_reason;
+            }
+          }
+        } else if (chunk.type === 'done') {
+          break;
+        }
+      }
+
+      // Process tool calls if detected
+      if (finishReason === 'tool_calls' && hasToolCalls) {
+        assistantMessage.tool_calls = Object.values(currentToolCalls).filter((tc) => tc.id && tc.function.name);
+        conversationMessages.push(assistantMessage);
+
+        yield {
+          type: 'tool_calls_detected',
+          data: { toolCalls: assistantMessage.tool_calls },
+        };
+
+        // Handle tool approval if callback provided
+        let approvalResult = {
+          stopAfterExecution: false,
+          approvals: assistantMessage.tool_calls.map(() => true), // Default: approve all
+        };
+
+        if (toolApproval) {
+          try {
+            const userApprovalResult = await toolApproval(assistantMessage.tool_calls);
+            approvalResult = this.normalizeApprovalResult(userApprovalResult, assistantMessage.tool_calls.length);
+          } catch (error) {
+            // console.error(`[${this.name}] Tool approval callback error:`, error);
+            // On error, deny all tools
+            approvalResult = {
+              stopAfterExecution: false,
+              approvals: assistantMessage.tool_calls.map(() => ({
+                approve: false,
+                reason: 'Approval callback failed',
+              })),
+            };
+          }
+        }
+
+        yield {
+          type: 'tool_approval_result',
+          data: { approvalResult },
+        };
+
+        // Process approved and denied tools
+        const { approvedTools, denialMessages } = this.processToolApprovals(
+          assistantMessage.tool_calls,
+          approvalResult.approvals,
+        );
+
+        // Add denial messages to conversation
+        conversationMessages.push(...denialMessages);
+
+        // Execute approved tools
+        if (approvedTools.length > 0) {
+          const toolResults = await this.executeTools(approvedTools);
+          conversationMessages.push(...toolResults);
+
+          yield {
+            type: 'tool_results',
+            data: { results: toolResults },
+          };
+        }
+
+        // Check if we should stop after execution
+        if (approvalResult.stopAfterExecution) {
+          yield {
+            type: 'conversation_complete',
+            data: {
+              finalOutput: finalOutput || 'Tool execution completed.',
+              messages: conversationMessages,
+              iterations: iteration,
+              stoppedAfterToolExecution: true,
+            },
+          };
+
+          return {
+            finalOutput: finalOutput || 'Tool execution completed.',
+            messages: conversationMessages,
+            stoppedAfterToolExecution: true,
+          };
+        }
+
+        // Continue conversation with tool results
+        continue;
+      } else {
+        // Conversation finished
+        if (assistantMessage.content || assistantMessage.tool_calls.length > 0) {
+          conversationMessages.push(assistantMessage);
+        }
+
+        yield {
+          type: 'conversation_complete',
+          data: {
+            finalOutput,
+            messages: conversationMessages,
+            iterations: iteration,
+          },
+        };
+
+        return { finalOutput, messages: conversationMessages };
+      }
+    }
+
+    yield {
+      type: 'max_iterations_reached',
+      data: { maxIterations: this.maxIterations, finalOutput },
+    };
+
+    return { finalOutput, messages: conversationMessages };
+  }
+
+  async runSync(initialMessages, options = {}) {
+    const { toolApproval = null } = options;
+    const events = [];
+    for await (const event of this.runStreaming(initialMessages, { toolApproval })) {
+      events.push(event);
+    }
+
+    const finalEvent = events[events.length - 1];
+    return finalEvent.data;
+  }
+
+  async createLLMStream(messages) {
+    const body = {
+      model: this.llm.model,
+      messages,
+      tools: this.tools,
+      tool_choice: 'auto',
+      temperature: this.llm.temperature,
+      max_tokens: this.llm.max_tokens,
+      stream: true,
+    };
+
+    return createChatCompletionStream(
+      { http: this.httpClient },
+      JSON.stringify(body),
+      this.llm.endpoint,
+      this.llm.apiKey,
+    );
+  }
+
+  // Helper method to normalize approval result from user callback
+  normalizeApprovalResult(userResult, toolCount) {
+    // Handle simple boolean array format
+    if (Array.isArray(userResult)) {
+      return {
+        stopAfterExecution: false, // Default
+        approvals: userResult,
+      };
+    }
+
+    // Handle object format
+    if (typeof userResult === 'object' && userResult !== null) {
+      return {
+        stopAfterExecution: userResult.stopAfterExecution || false,
+        approvals: userResult.approvals || Array(toolCount).fill(true),
+      };
+    }
+
+    // Fallback - approve all
+    return {
+      stopAfterExecution: false,
+      approvals: Array(toolCount).fill(true),
+    };
+  }
+
+  // Helper method to process tool approvals and generate denial messages
+  processToolApprovals(toolCalls, approvals) {
+    const approvedTools = [];
+    const denialMessages = [];
+
+    for (let i = 0; i < toolCalls.length; i++) {
+      const toolCall = toolCalls[i];
+      const approval = approvals[i];
+
+      // Normalize approval to object format
+      let normalizedApproval;
+      if (typeof approval === 'boolean') {
+        normalizedApproval = { approve: approval, reason: null };
+      } else if (typeof approval === 'object' && approval !== null) {
+        normalizedApproval = {
+          approve: approval.approve !== false, // Default to true if not explicitly false
+          reason: approval.reason || null,
+        };
+      } else {
+        normalizedApproval = { approve: true, reason: null }; // Default approve
+      }
+
+      if (normalizedApproval.approve) {
+        approvedTools.push(toolCall);
+      } else {
+        // Create denial message with standard format
+        const reason = normalizedApproval.reason
+          ? ` because: ${normalizedApproval.reason}`
+          : '.';
+
+        denialMessages.push({
+          role: 'user',
+          content: `I denied the ${toolCall.function.name} tool${reason}`,
+        });
+      }
+    }
+
+    return { approvedTools, denialMessages };
+  }
+
+  async executeTools(toolCalls) {
+    const toolResults = [];
+
+    for (const toolCall of toolCalls) {
+      try {
+        // Find which server handles this tool
+        const serverEndpoint = this.toolToServerMap.get(toolCall.function.name);
+        const mcpServer = this.mcpServers.get(serverEndpoint);
+
+        if (!mcpServer) {
+          throw new Error(`No MCP server found for tool: ${toolCall.function.name}`);
+        }
+
+        let args = toolCall.function.arguments;
+        if (typeof args === 'string') {
+          args = JSON.parse(args);
+        }
+
+        // console.log(`[${this.name}] Calling tool ${toolCall.function.name} on server ${serverEndpoint}`);
+
+        const result = await mcpServer.callTool({
+          name: toolCall.function.name,
+          arguments: args,
+        });
+
+        toolResults.push({
+          role: 'tool',
+          tool_call_id: toolCall.id,
+          name: toolCall.function.name,
+          content: JSON.stringify(result),
+        });
+      } catch (error) {
+        // console.error(`[${this.name}] Error calling tool ${toolCall.function.name}:`, error);
+
+        toolResults.push({
+          role: 'tool',
+          tool_call_id: toolCall.id,
+          name: toolCall.function.name,
+          content: JSON.stringify({ error: error.message }),
+        });
+      }
+    }
+
+    return toolResults;
+  }
+}
+
+module.exports = { Agent };

package/src/index.js

@@ -0,0 +1,10 @@
+const { createChatCompletionStream, parseSSEChunk } = require('./oai');
+const { Agent } = require('./agent');
+const { McpResponseParser } = require('./mcp-response-parser');
+
+module.exports = {
+  createChatCompletionStream,
+  parseSSEChunk,
+  Agent,
+  McpResponseParser,
+};

package/src/mcp-response-parser.js

@@ -0,0 +1,177 @@
+/**
+ * Simplified parser for MCP (Model Context Protocol) tool responses
+ * Handles the actual MCP format without over-engineering
+ * 
+ * Expected MCP Tool Response Format:
+ * [
+ *   {
+ *     "role": "tool",
+ *     "tool_call_id": "tool_0",
+ *     "name": "read_text_file", 
+ *     "content": "{\"content\":[{\"type\":\"text\",\"text\":\"actual file content here...\"}]}"
+ *   }
+ * ]
+ * 
+ * The "content" field is a JSON string that when parsed contains:
+ * {
+ *   "content": [
+ *     {
+ *       "type": "text|image|resource|etc",
+ *       "text": "content for text type",
+ *       "data": "content for image/binary types"
+ *     }
+ *   ]
+ * }
+ */
+class McpResponseParser {
+  constructor(toolResults) {
+    this.results = toolResults || [];
+    this.contentByType = {};
+    
+    this._parseResults();
+  }
+
+  /**
+   * Parse the tool results and organize content
+   * @private
+   */
+  _parseResults() {
+    for (const result of this.results) {
+      if (result.content) {
+        try {
+          // Parse the JSON content string
+          const parsed = JSON.parse(result.content);
+          const contents = parsed.content || [];
+          
+          // Organize content by type
+          for (const item of contents) {
+            const type = item.type || 'unknown';
+            
+            if (!this.contentByType[type]) {
+              this.contentByType[type] = [];
+            }
+            
+            this.contentByType[type].push({
+              ...item,
+              toolId: result.tool_call_id,
+              toolName: result.name,
+            });
+          }
+        } catch (error) {
+          console.log(`Failed to parse tool result content: ${error.message}`);
+        }
+      }
+    }
+  }
+
+  // === Tool Information ===
+
+  /**
+   * Get all tool IDs
+   */
+  getToolIds() {
+    return this.results.map(result => result.tool_call_id).filter(Boolean);
+  }
+
+  /**
+   * Get all tool names
+   */
+  getToolNames() {
+    return this.results.map(result => result.name).filter(Boolean);
+  }
+
+  /**
+   * Get result by tool ID
+   */
+  getResultByToolId(toolId) {
+    return this.results.find(result => result.tool_call_id === toolId) || null;
+  }
+
+  /**
+   * Get result by tool name
+   */
+  getResultByToolName(toolName) {
+    return this.results.find(result => result.name === toolName) || null;
+  }
+
+  // === Content Access ===
+
+  /**
+   * Get content by type
+   */
+  getContentByType(type) {
+    return this.contentByType[type] || [];
+  }
+
+  /**
+   * Get all content organized by type
+   */
+  getAllContent() {
+    return { ...this.contentByType };
+  }
+
+  /**
+   * Get text content (convenience method)
+   */
+  getTextContent() {
+    const textItems = this.getContentByType('text');
+    if (textItems.length === 0) return null;
+    if (textItems.length === 1) return textItems[0].text;
+    return textItems.map(item => item.text);
+  }
+
+  /**
+   * Get image content (convenience method)
+   */
+  getImageContent() {
+    return this.getContentByType('image');
+  }
+
+  /**
+   * Get resource content (convenience method)
+   */
+  getResourceContent() {
+    return this.getContentByType('resource');
+  }
+
+  // === Summary Info ===
+
+  /**
+   * Check if we have any results
+   */
+  hasResults() {
+    return this.results.length > 0;
+  }
+
+  /**
+   * Get available content types
+   */
+  getContentTypes() {
+    return Object.keys(this.contentByType);
+  }
+
+  /**
+   * Get summary of parsing results
+   */
+  getSummary() {
+    return {
+      toolCount: this.results.length,
+      contentTypes: this.getContentTypes(),
+      toolIds: this.getToolIds(),
+      toolNames: this.getToolNames(),
+    };
+  }
+
+  /**
+   * Convert to JSON for serialization
+   */
+  toJSON() {
+    return {
+      summary: this.getSummary(),
+      contentByType: this.contentByType,
+      results: this.results,
+    };
+  }
+}
+
+module.exports = { McpResponseParser };