@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/mcp/browser-capability.js

@@ -0,0 +1,191 @@
+/**
+ * Browser Capability -- Abstraction layer for browser MCP (#10, #24, #30)
+ *
+ * Provides a unified API for browser interactions. All methods check
+ * MCP availability and degrade gracefully when no browser server is
+ * configured.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/mcp/browser-capability
+ * @version 3.0.0
+ */
+
+"use strict";
+
+class BrowserCapability {
+  /**
+   * @param {Object} [config]
+   * @param {Object} [config.capabilityMapper] - CapabilityMapper instance
+   * @param {Object} [config.mcpClient] - MCP client for invoking tools
+   */
+  constructor(config = {}) {
+    this._mapper = config.capabilityMapper || null;
+    this._client = config.mcpClient || null;
+    this._available = null; // cached availability
+  }
+
+  /**
+   * Check if browser MCP is available.
+   * @returns {boolean}
+   */
+  isAvailable() {
+    if (this._available !== null) return this._available;
+
+    if (!this._mapper || !this._client) {
+      this._available = false;
+      return false;
+    }
+
+    const resolved = this._mapper.resolve("browser:screenshot");
+    this._available = resolved !== null;
+    return this._available;
+  }
+
+  /**
+   * Capture a screenshot of a URL.
+   *
+   * @param {string} url - URL to screenshot
+   * @param {Object} [opts]
+   * @param {boolean} [opts.fullPage=false] - Capture full page
+   * @param {number} [opts.width=1280] - Viewport width
+   * @param {number} [opts.height=720] - Viewport height
+   * @returns {Promise<Object>} Screenshot result or graceful fallback
+   */
+  async screenshot(url, opts = {}) {
+    if (!this.isAvailable()) {
+      return {
+        success: false,
+        error: "Browser MCP not available",
+        fallback: true,
+      };
+    }
+
+    return this._invoke("browser:screenshot", {
+      url,
+      fullPage: opts.fullPage || false,
+      width: opts.width || 1280,
+      height: opts.height || 720,
+    });
+  }
+
+  /**
+   * Get DOM content from a URL using a CSS selector.
+   *
+   * @param {string} url - URL to query
+   * @param {string} selector - CSS selector
+   * @returns {Promise<Object>} DOM content or fallback
+   */
+  async getDOM(url, selector) {
+    if (!this.isAvailable()) {
+      return {
+        success: false,
+        error: "Browser MCP not available",
+        fallback: true,
+      };
+    }
+
+    return this._invoke("browser:dom", { url, selector });
+  }
+
+  /**
+   * Get browser console logs for a URL.
+   *
+   * @param {string} url - URL to inspect
+   * @returns {Promise<Object>} Console logs or fallback
+   */
+  async getConsoleLogs(url) {
+    if (!this.isAvailable()) {
+      return {
+        success: false,
+        error: "Browser MCP not available",
+        fallback: true,
+      };
+    }
+
+    return this._invoke("browser:console", { url });
+  }
+
+  /**
+   * Get network requests for a URL (#30).
+   *
+   * @param {string} url - URL to monitor
+   * @param {Object} [filter] - Optional request filter
+   * @param {string} [filter.method] - HTTP method filter (GET, POST, etc.)
+   * @param {string} [filter.urlPattern] - URL pattern to match
+   * @param {number} [filter.statusCode] - Status code filter
+   * @returns {Promise<Object>} Network requests or fallback
+   */
+  async getNetworkRequests(url, filter = {}) {
+    if (!this.isAvailable()) {
+      return {
+        success: false,
+        error: "Browser MCP not available",
+        fallback: true,
+      };
+    }
+
+    return this._invoke("browser:network", { url, filter });
+  }
+
+  /**
+   * Execute JavaScript in a page context.
+   *
+   * @param {string} url - URL to run script in
+   * @param {string} script - JavaScript to execute
+   * @returns {Promise<Object>} Execution result or fallback
+   */
+  async executeJS(url, script) {
+    if (!this.isAvailable()) {
+      return {
+        success: false,
+        error: "Browser MCP not available",
+        fallback: true,
+      };
+    }
+
+    return this._invoke("browser:execute-js", { url, script });
+  }
+
+  /**
+   * Reset cached availability (e.g., after MCP config change).
+   */
+  resetCache() {
+    this._available = null;
+  }
+
+  // -------------------------------------------------------------------------
+  //  Private
+  // -------------------------------------------------------------------------
+
+  /**
+   * Invoke a browser capability via MCP.
+   * @param {string} capability - Capability key
+   * @param {Object} params - Tool parameters
+   * @returns {Promise<Object>}
+   * @private
+   */
+  async _invoke(capability, params) {
+    try {
+      const resolved = this._mapper.resolve(capability);
+      if (!resolved) {
+        return {
+          success: false,
+          error: `Capability ${capability} not registered`,
+        };
+      }
+
+      const result = await this._client.callTool(
+        resolved.server,
+        resolved.tool,
+        params,
+      );
+
+      return { success: true, data: result };
+    } catch (error) {
+      return { success: false, error: error.message };
+    }
+  }
+}
+
+module.exports = { BrowserCapability };

package/.merlin-core/core/mcp/capability-mapper.js

@@ -0,0 +1,92 @@
+/**
+ * MCP Capability Mapper
+ *
+ * Maps MCP server tools to agent capabilities.
+ * When an agent needs a capability (e.g., "send email"),
+ * the mapper finds the appropriate MCP server and tool.
+ *
+ * @module core/mcp/capability-mapper
+ * @version 3.0.0
+ */
+
+/**
+ * Well-known capability constants for MCP integrations.
+ * @constant
+ */
+const BROWSER_CAPABILITIES = [
+  "browser:screenshot",
+  "browser:dom",
+  "browser:console",
+  "browser:network",
+  "browser:execute-js",
+];
+
+/**
+ * LSP capability constants.
+ * @constant
+ */
+const LSP_CAPABILITIES = [
+  "lsp:go-to-definition",
+  "lsp:find-references",
+  "lsp:hover",
+  "lsp:diagnostics",
+];
+
+class CapabilityMapper {
+  constructor(registry) {
+    this.registry = registry;
+    this._mappings = new Map();
+  }
+
+  /**
+   * Register a capability-to-tool mapping.
+   *
+   * @param {string} capability - Capability name (e.g., 'send-email')
+   * @param {string} server - MCP server name
+   * @param {string} tool - Tool name on the server
+   */
+  register(capability, server, tool) {
+    this._mappings.set(capability, { server, tool });
+  }
+
+  /**
+   * Find the MCP tool for a given capability.
+   *
+   * @param {string} capability - Capability name
+   * @returns {{server: string, tool: string}|null}
+   */
+  resolve(capability) {
+    return this._mappings.get(capability) || null;
+  }
+
+  /**
+   * List all registered capabilities.
+   */
+  listCapabilities() {
+    return Array.from(this._mappings.entries()).map(([cap, mapping]) => ({
+      capability: cap,
+      ...mapping,
+    }));
+  }
+
+  /**
+   * Auto-discover capabilities from registered MCP servers.
+   * Parses tool lists from server metadata.
+   */
+  autoDiscover() {
+    const servers = this.registry.list();
+    for (const server of servers) {
+      if (server.tools && Array.isArray(server.tools)) {
+        for (const tool of server.tools) {
+          const capability = `${server.name}:${tool.name || tool}`;
+          this._mappings.set(capability, {
+            server: server.name,
+            tool: tool.name || tool,
+          });
+        }
+      }
+    }
+  }
+}
+
+module.exports = { CapabilityMapper, BROWSER_CAPABILITIES, LSP_CAPABILITIES };

package/.merlin-core/core/mcp/mcp-connector.js

@@ -0,0 +1,278 @@
+/**
+ * MCP Connector -- Server Connection Management
+ *
+ * Manages live connections to MCP (Model Context Protocol) servers.
+ * Handles connection lifecycle, tool invocation, and health monitoring.
+ *
+ * Works with MCPRegistry for server discovery and CapabilityMapper
+ * for capability resolution.
+ *
+ * @module core/mcp/mcp-connector
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const { EventEmitter } = require("events");
+
+/**
+ * Connection state enum
+ * @enum {string}
+ */
+const ConnectionState = {
+  DISCONNECTED: "DISCONNECTED",
+  CONNECTING: "CONNECTING",
+  CONNECTED: "CONNECTED",
+  ERROR: "ERROR",
+};
+
+class MCPConnector extends EventEmitter {
+  /**
+   * @param {import('./mcp-registry').MCPRegistry} registry - MCP server registry
+   */
+  constructor(registry) {
+    super();
+    this.registry = registry;
+
+    /** @type {Map<string, {state: string, connection: object|null, config: object, connectedAt: number|null, lastPing: number|null, healthInterval: NodeJS.Timeout|null}>} */
+    this._connections = new Map();
+  }
+
+  /**
+   * Establish a connection to an MCP server.
+   *
+   * @param {string} serverName - Name of the registered server
+   * @returns {Promise<{success: boolean, serverName: string, state: string}>}
+   */
+  async connect(serverName) {
+    const serverConfig = this.registry.get(serverName);
+    if (!serverConfig) {
+      throw new Error(
+        `MCP server "${serverName}" is not registered in the registry`,
+      );
+    }
+
+    const existing = this._connections.get(serverName);
+    if (existing && existing.state === ConnectionState.CONNECTED) {
+      return { success: true, serverName, state: ConnectionState.CONNECTED };
+    }
+
+    this._connections.set(serverName, {
+      state: ConnectionState.CONNECTING,
+      connection: null,
+      config: serverConfig,
+      connectedAt: null,
+      lastPing: null,
+      healthInterval: null,
+    });
+
+    this.emit("connecting", { serverName });
+
+    try {
+      // Simulate connection establishment.
+      // In production this would spawn a child process or open a transport
+      // based on serverConfig.command / serverConfig.url.
+      const connection = await this._establishConnection(serverConfig);
+
+      const entry = this._connections.get(serverName);
+      entry.state = ConnectionState.CONNECTED;
+      entry.connection = connection;
+      entry.connectedAt = Date.now();
+      entry.lastPing = Date.now();
+
+      this.emit("connected", { serverName, connectedAt: entry.connectedAt });
+
+      // Start periodic health check
+      this._startHealthCheck(serverName, 30000);
+
+      return { success: true, serverName, state: ConnectionState.CONNECTED };
+    } catch (err) {
+      const entry = this._connections.get(serverName);
+      if (entry) {
+        entry.state = ConnectionState.ERROR;
+      }
+      this.emit("error", { serverName, error: err.message });
+      return { success: false, serverName, state: ConnectionState.ERROR };
+    }
+  }
+
+  /**
+   * Disconnect from an MCP server.
+   *
+   * @param {string} serverName - Name of the server to disconnect
+   */
+  async disconnect(serverName) {
+    const entry = this._connections.get(serverName);
+    if (!entry) return;
+
+    if (entry.healthInterval) {
+      clearInterval(entry.healthInterval);
+      entry.healthInterval = null;
+    }
+
+    entry.state = ConnectionState.DISCONNECTED;
+    entry.connection = null;
+    entry.connectedAt = null;
+
+    this.emit("disconnected", { serverName });
+  }
+
+  /**
+   * Invoke a tool on a connected MCP server.
+   *
+   * @param {string} serverName - Name of the server
+   * @param {string} toolName - Name of the tool to invoke
+   * @param {object} [params={}] - Parameters to pass to the tool
+   * @returns {Promise<object>} Tool execution result
+   */
+  async callTool(serverName, toolName, params = {}) {
+    const entry = this._connections.get(serverName);
+    if (!entry || entry.state !== ConnectionState.CONNECTED) {
+      throw new Error(
+        `Cannot call tool "${toolName}" -- server "${serverName}" is not connected (state: ${entry?.state || "UNKNOWN"})`,
+      );
+    }
+
+    this.emit("tool:call", { serverName, toolName, params });
+
+    try {
+      // In production this would send a JSON-RPC request over the transport.
+      // For now, delegate to the connection object if it has a callTool method.
+      let result;
+      if (entry.connection && typeof entry.connection.callTool === "function") {
+        result = await entry.connection.callTool(toolName, params);
+      } else {
+        result = {
+          status: "ok",
+          tool: toolName,
+          params,
+          message: "Stub response -- no live transport",
+        };
+      }
+
+      this.emit("tool:result", { serverName, toolName, result });
+      return result;
+    } catch (err) {
+      this.emit("tool:error", { serverName, toolName, error: err.message });
+      throw err;
+    }
+  }
+
+  /**
+   * Get the connection status for a server.
+   *
+   * @param {string} serverName - Name of the server
+   * @returns {{state: string, connectedAt: number|null, lastPing: number|null}|null}
+   */
+  getStatus(serverName) {
+    const entry = this._connections.get(serverName);
+    if (!entry) return null;
+
+    return {
+      state: entry.state,
+      connectedAt: entry.connectedAt,
+      lastPing: entry.lastPing,
+    };
+  }
+
+  /**
+   * List all currently connected servers.
+   *
+   * @returns {Array<{serverName: string, state: string, connectedAt: number|null}>}
+   */
+  listConnected() {
+    const connected = [];
+    for (const [serverName, entry] of this._connections) {
+      if (entry.state === ConnectionState.CONNECTED) {
+        connected.push({
+          serverName,
+          state: entry.state,
+          connectedAt: entry.connectedAt,
+        });
+      }
+    }
+    return connected;
+  }
+
+  /**
+   * Start periodic health checks for a connected server.
+   *
+   * @param {string} serverName - Name of the server
+   * @param {number} intervalMs - Check interval in milliseconds
+   * @private
+   */
+  _startHealthCheck(serverName, intervalMs) {
+    const entry = this._connections.get(serverName);
+    if (!entry) return;
+
+    if (entry.healthInterval) {
+      clearInterval(entry.healthInterval);
+    }
+
+    entry.healthInterval = setInterval(async () => {
+      try {
+        if (entry.connection && typeof entry.connection.ping === "function") {
+          await entry.connection.ping();
+        }
+        entry.lastPing = Date.now();
+        this.emit("health:ok", { serverName, lastPing: entry.lastPing });
+      } catch {
+        entry.state = ConnectionState.ERROR;
+        this.emit("health:fail", { serverName });
+        clearInterval(entry.healthInterval);
+        entry.healthInterval = null;
+      }
+    }, intervalMs);
+
+    // Do not keep the process alive just for health checks
+    if (entry.healthInterval.unref) {
+      entry.healthInterval.unref();
+    }
+  }
+
+  /**
+   * Establish a connection to an MCP server based on its configuration.
+   *
+   * @param {object} config - Server configuration from the registry
+   * @returns {Promise<object>} Connection handle
+   * @private
+   */
+  async _establishConnection(config) {
+    // Connection establishment is transport-dependent.
+    // stdio: spawn child process with config.command + config.args
+    // sse:   open HTTP SSE connection to config.url
+
+    // M6 fix: Validate MCP server command against whitelist
+    if (config.command) {
+      const SAFE_COMMANDS = [
+        "node",
+        "npx",
+        "python",
+        "python3",
+        "deno",
+        "bun",
+        "ruby",
+      ];
+      const cmdBase = config.command
+        .split(/[\\/]/)
+        .pop()
+        .split(/\s+/)[0]
+        .replace(/\.(exe|cmd)$/i, "");
+      if (!SAFE_COMMANDS.includes(cmdBase)) {
+        throw new Error(
+          `MCP command "${cmdBase}" not in whitelist: ${SAFE_COMMANDS.join(", ")}`,
+        );
+      }
+    }
+
+    // For now, return a stub connection object.
+    return {
+      transport: config.command ? "stdio" : "sse",
+      config,
+      callTool: null,
+      ping: null,
+    };
+  }
+}
+
+module.exports = { MCPConnector, ConnectionState };

package/.merlin-core/core/mcp/mcp-registry.js

@@ -0,0 +1,101 @@
+/**
+ * MCP Registry -- Server Discovery and Registration
+ *
+ * Manages the registry of available MCP (Model Context Protocol) servers.
+ * Implements Constitution Article VI: MCP First.
+ *
+ * Sources:
+ * - .mcp.json (project-level)
+ * - .claude/mcp.json (Claude Code integration)
+ * - Runtime registration via API
+ *
+ * @module core/mcp/mcp-registry
+ * @version 3.0.0
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+class MCPRegistry {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this._servers = new Map();
+    this._loaded = false;
+  }
+
+  /**
+   * Load MCP server configurations from project files.
+   */
+  load() {
+    if (this._loaded) return;
+
+    // Load from .mcp.json (project-level)
+    const projectMcp = path.join(this.projectRoot, ".mcp.json");
+    this._loadFromFile(projectMcp, "project");
+
+    // Load from .claude/mcp.json (Claude Code)
+    const claudeMcp = path.join(this.projectRoot, ".claude", "mcp.json");
+    this._loadFromFile(claudeMcp, "claude");
+
+    this._loaded = true;
+  }
+
+  _loadFromFile(filePath, source) {
+    try {
+      if (!fs.existsSync(filePath)) return;
+      const content = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      const servers = content.mcpServers || content.servers || {};
+
+      for (const [name, config] of Object.entries(servers)) {
+        this._servers.set(name, {
+          name,
+          ...config,
+          source,
+          status: "registered",
+          registeredAt: Date.now(),
+        });
+      }
+    } catch {
+      /* graceful */
+    }
+  }
+
+  /**
+   * Register a server at runtime.
+   */
+  register(name, config) {
+    this._servers.set(name, {
+      name,
+      ...config,
+      source: "runtime",
+      status: "registered",
+      registeredAt: Date.now(),
+    });
+  }
+
+  /**
+   * Get a registered server by name.
+   */
+  get(name) {
+    this.load();
+    return this._servers.get(name) || null;
+  }
+
+  /**
+   * List all registered servers.
+   */
+  list() {
+    this.load();
+    return Array.from(this._servers.values());
+  }
+
+  /**
+   * Check if a server is registered.
+   */
+  has(name) {
+    this.load();
+    return this._servers.has(name);
+  }
+}
+
+module.exports = { MCPRegistry };

package/.merlin-core/core/orchestration/README.md

@@ -0,0 +1,17 @@
+# Multi-Agent Orchestration
+
+The orchestration module coordinates complex workflows across multiple agents and systems. It includes the master orchestrator that manages agent lifecycle, decision trees for intelligent routing, workflow execution engines, and quality gate evaluation to ensure reliability and compliance.
+
+## Contents
+
+- **master-orchestrator/** - Central coordinator managing agent lifecycle and communication
+- **decision-tree/** - Intelligent routing logic for task delegation and execution flow
+- **workflow-executor/** - Executes multi-step workflows with state management
+- **gate-evaluator/** - Evaluates quality gates and compliance requirements
+- **orchestrator.js** - Main orchestration controller
+
+## Related
+
+- [Alkimia](../alkimia/README.md)
+- [Execution](../execution/README.md)
+- [Approval](../approval/README.md)