mcp.class.php

Go to the documentation of this file.

<?php
/* Copyright (C) 2026   Laurent Destailleur     <eldy@users.sourceforge.net>
 * Copyright (C) 2026 Nick Fragoulis
 * Copyright (C) 2026 MDW           <mdeweerd@users.noreply.github.com>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY, without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
 * or see https://www.gnu.org/
 */
 
require_once DOL_DOCUMENT_ROOT . "/ai/class/mcptool.class.php";
 
class McpHandler
{
  const CTX_ASSISTANT = 'assistant';
 
  const CTX_MCP_SERVER = 'mcp_server';
 
  private $db;
 
  private $user;
 
  private $conf;
 
  public $loadedTools = [];
 
  public $toolsByName = [];
 
 
  private $toolcontext;
 
  public function __construct($db, $user, $conf_obj = null, $toolcontext = '')
  {
    $this->db = $db;
    $this->user = $user;
 
    if ($conf_obj === null) {
      global $conf;
      $conf_obj = $conf;
    }
    $this->conf = $conf_obj;
 
    $this->toolcontext = (!empty($toolcontext)) ? $toolcontext : self::CTX_ASSISTANT;
  }
 
  private function isSystemTool($toolInstance)
  {
    return (method_exists($toolInstance, 'isSystem') && $toolInstance->isSystem());
  }
 
  private function getAllowedToolsList()
  {
    if ($this->toolcontext === self::CTX_MCP_SERVER) {
      $constName = 'AI_MCP_SERVER_ALLOWED_TOOLS';
    } else {
      $constName = 'AI_ASSISTANT_ALLOWED_TOOLS';
    }
 
    $raw = getDolGlobalString($constName);    // Return the list (separated by coma) of all enabled tools
 
    if ($raw === '') {
      // Constant not yet configured — allow everything
      return array();
    }
 
    if ($raw === 'NONE') {
      // Admin explicitly disabled all tools via the preset button
      return array('__blocked__');
    }
 
    return array_values(array_filter(array_map('trim', explode(',', $raw))));
  }
 
  public static function resolveAllowList($raw, $allDiscoveredTools)
  {
    if ($raw === '') {
      // Not yet configured → implicitly all tools are allowed
      return $allDiscoveredTools;
    }
    if ($raw === 'NONE') {
      // Admin explicitly disabled everything
      return array();
    }
    // Explicit list stored by a previous save
    return array_values(array_filter(array_map('trim', explode(',', $raw))));
  }
 
 
  public function loadTools()
  {
    $this->loadNativeTools();   // Tools found into directory ai/tools/
    $this->loadExternalTools();   // Tools provided by external module and hook addMcpTools
  }
 
  private function loadNativeTools()
  {
    $toolsDir = DOL_DOCUMENT_ROOT . '/ai/tools/';
    if (!is_dir($toolsDir)) {
      dol_syslog('[McpHandler] MCP tools directory not found: ' . $toolsDir, LOG_INFO);
      return;
    }
 
    $files = glob($toolsDir . '*.php');
    foreach ($files as $file) {
      try {
        // Validate the file path before inclusion
        $realFilePath = realpath($file);
        if ($realFilePath === false || strpos($realFilePath, realpath($toolsDir)) !== 0) {
          dol_syslog('[McpHandler] Attempted to load tool outside of allowed directory: ' . $file, LOG_WARNING);
          continue;
        }
 
        require_once $realFilePath;
 
        $basename = basename($file, '.class.php');
        $className = 'Tool' . str_replace(' ', '', ucwords(str_replace('_', ' ', $basename)));
 
        if (!class_exists($className)) {
          dol_syslog("[McpHandler] Tool class '{$className}' not found in file '{$file}'.", LOG_WARNING);
          continue;
        }
 
        $toolInstance = new $className($this->db, $this->user, $this->conf);
 
        if ($toolInstance instanceof McpTool) {
          $this->registerTool($basename, $toolInstance);
        } else {
          dol_syslog("[McpHandler] Tool class '{$className}' does not extend McpTool.", LOG_ERR);
        }
      } catch (\Throwable $e) {
        dol_syslog("[McpHandler] Failed to load tool from file '{$file}': " . $e->getMessage(), LOG_ERR);
      }
    }
  }
  private function loadExternalTools()
  {
    global $hookmanager;
    if (!is_object($hookmanager)) {
      require_once DOL_DOCUMENT_ROOT . '/core/class/hookmanager.class.php';
      $hookmanager = new HookManager($this->db);
    }
 
    $hookmanager->initHooks(['aimcp']);
 
    $parameters = ['db' => $this->db, 'user' => $this->user, 'conf' => $this->conf];
    $action = '';
 
    try {
      $hookmanager->executeHooks('addMcpTools', $parameters, $this, $action);
 
      if (!is_array($hookmanager->resArray)) {
        return;
      }
 
      foreach ($hookmanager->resArray as $moduleTools) {
        if ($moduleTools instanceof McpTool) {
          // Tolerance: a module that set results = array($tool)
          // instead of array(array($tool)) still works - the
          // HookManager flattens results into resArray, so bare
          // instances are the natural mistake to make.
          $this->registerTool(get_class($moduleTools), $moduleTools);
          continue;
        }
        if (!is_array($moduleTools)) {
          continue;
        }
        foreach ($moduleTools as $toolInstance) {
          if ($toolInstance instanceof McpTool) {
            $this->registerTool(get_class($toolInstance), $toolInstance);
          } else {
            dol_syslog('[McpHandler] A module provided a tool that is not an instance of McpTool.', LOG_WARNING);
          }
        }
      }
    } catch (\Throwable $e) {
      dol_syslog('[McpHandler] Error during \'addMcpTools\' hook execution: ' . $e->getMessage(), LOG_ERR);
    }
  }
 
  private function registerTool(string $key, McpTool $toolInstance)
  {
    $this->loadedTools[$key] = $toolInstance;
 
    // Populate the lookup map
    foreach ($toolInstance->getDefinitions() as $def) {
      if (isset($def['name'])) {
        if (isset($this->toolsByName[$def['name']])) {
          dol_syslog(
            "[McpHandler] Tool name conflict: '{$def['name']}' is already registered by '" . get_class($this->toolsByName[$def['name']]) . "'. Skipping registration from '" . get_class($toolInstance) . "'.",
            LOG_WARNING
          );
        } else {
          $this->toolsByName[$def['name']] = $toolInstance;
        }
      }
    }
    dol_syslog('[McpHandler] Successfully registered MCP tool: ' . get_class($toolInstance), LOG_INFO);
  }
 
  public function getToolsSchemaUnfiltered()
  {
    $schema = array();
 
    foreach ($this->loadedTools as $tool) {
      $isSystem  = $this->isSystemTool($tool);
      $className = get_class($tool);
 
      foreach ($tool->getDefinitions() as $def) {
        $def['is_system']  = $isSystem;
        $def['class_name'] = $className;
        if (empty($def['categories'])) {
          $def['categories'] = $tool->getCategories();  // class-level fallback; a tool may set finer per-definition categories
        }
        $schema[] = $def;
      }
    }
 
    return $schema;
  }
 
  public function getToolsSchema(): array
  {
    $allowed = $this->getAllowedToolsList();  // Return list of "allowed" tools for the current context $this->toolcontext (Chat or MCP)
    $schema  = [];
 
    foreach ($this->loadedTools as $tool) {
      $isSystem = $this->isSystemTool($tool);
 
      foreach ($tool->getDefinitions() as $def) {
        $name = isset($def['name']) ? $def['name'] : '';
 
        if ($isSystem) {
          // Always include system tools but tag them so parse_intent.php
          // can strip them from $toolsForLLM while keeping them available
          // for the validation check (executeTool must still be able to
          // run respond_to_user, ask_for_clarification, etc.).
          $def['is_system']  = true;
          if (empty($def['categories'])) {
            $def['categories'] = $tool->getCategories();  // class-level fallback; a tool may set finer per-definition categories
          }
          $schema[] = $def;
          continue;
        }
 
        $def['is_system'] = false;
 
        // Same rule as getToolsSchemaForLLM(): this is what tools/list on the
        // MCP server returns, so a caller must not be offered what it cannot run.
        if ($this->checkToolRights($tool, $name) !== '') {
          continue;
        }
 
        if (empty($allowed)) {
          // No restriction configured — include everything
          if (empty($def['categories'])) {
            $def['categories'] = $tool->getCategories();  // class-level fallback; a tool may set finer per-definition categories
          }
          $schema[] = $def;
          continue;
        }
 
        if (in_array($name, $allowed, true)) {
          if (empty($def['categories'])) {
            $def['categories'] = $tool->getCategories();  // class-level fallback; a tool may set finer per-definition categories
          }
          $schema[] = $def;
        }
        // Not in $allowed — silently omitted; LLM never sees this tool
      }
    }
 
    return $schema;
  }
 
  public function getToolsSchemaForLLM()
  {
    $allowed = $this->getAllowedToolsList();
    $schema  = array();
 
    foreach ($this->loadedTools as $tool) {
      // Check isSystem() class method first (requires conversation.class.php
      // to implement it). This is the preferred path for future extensibility.
      if ($this->isSystemTool($tool)) {
        continue;
      }
 
      foreach ($tool->getDefinitions() as $def) {
        $name = isset($def['name']) ? $def['name'] : '';
 
        // Check is_system flag in the definition array itself.
        // This is set directly in conversation.class.php getDefinitions()
        // and works even if the isSystem() class method is not yet deployed.
        if (!empty($def['is_system'])) {
          continue;
        }
 
        // Do not advertise what this user cannot run.
        if ($this->checkToolRights($tool, $name) !== '') {
          continue;
        }
 
        if (empty($allowed)) {
          // No restriction configured — include everything
          if (empty($def['categories'])) {
            $def['categories'] = $tool->getCategories();  // class-level fallback; a tool may set finer per-definition categories
          }
          $schema[] = $def;
          continue;
        }
 
        if (in_array($name, $allowed, true)) {
          if (empty($def['categories'])) {
            $def['categories'] = $tool->getCategories();  // class-level fallback; a tool may set finer per-definition categories
          }
          $schema[] = $def;
        }
      }
    }
 
    return $schema;
  }
 
  private function checkToolRights($tool, $toolName)
  {
    if ($this->isSystemTool($tool)) {
      return '';
    }
 
    $declared = method_exists($tool, 'getRequiredRights') ? $tool->getRequiredRights($toolName) : McpTool::RIGHTS_UNDECLARED;
 
    if ($declared === McpTool::RIGHTS_ENFORCED_DOWNSTREAM) {
      return '';  // REST API classes check DolibarrApiAccess::$user themselves
    }
    if ($declared === McpTool::RIGHTS_UNDECLARED) {
      dol_syslog("[McpHandler] Tool '".$toolName."' declares no rights: denied.", LOG_WARNING);
 
      return 'undeclared';
    }
    foreach ((array) $declared as $right) {
      $right = (array) $right;
      $module = isset($right[0]) ? $right[0] : '';
      $perm = isset($right[1]) ? $right[1] : '';
      $subperm = isset($right[2]) ? $right[2] : '';
      if ($module === '' || !$this->user->hasRight($module, $perm, $subperm)) {
        return $module.'/'.$perm.($subperm !== '' ? '/'.$subperm : '');
      }
    }
 
    return '';
  }
  private function checkWriteConfirmation($tool, $toolName, array $args)
  {
    if (!method_exists($tool, 'writeConfirmationPreview')) {
      return null;
    }
    $preview = (string) $tool->writeConfirmationPreview($toolName, $args);
    if ($preview === McpTool::NO_WRITE) {
      return null;  // read tool
    }
 
    require_once DOL_DOCUMENT_ROOT.'/ai/class/writeconfirmation.class.php';
    $gate = new AiWriteConfirmation($this->db);
 
    $state = isset($args['requestState']) ? (string) $args['requestState'] : '';
    if ($state !== '') {
      if ($gate->consume($this->user, $toolName, $args, $state)) {
        return null;  // confirmed: the write runs
      }
 
      return array('error' => $gate->error);
    }
 
    $issued = $gate->issue($this->user, $toolName, $args, $preview);
    if ($issued === '') {
      return array('error' => $gate->error);
    }
 
    return array(
      'resultType' => 'input_required',
      'inputRequests' => array(
        array(
          'type' => 'confirmation',
          'prompt' => $preview
        )
      ),
      'requestState' => $issued
    );
  }
 
  public function executeTool(string $toolName, array $args): array
  {
    if (!isset($this->toolsByName[$toolName])) {
      // LLMs routinely emit near-miss tool names (create_invoice for
      // create_customer_invoice). Recover when the real name is
      // UNAMBIGUOUS: same action verb (segment before the first '_')
      // and every underscore token of the requested name appears in the
      // candidate. Exactly one match executes (logged); zero or several
      // keep the clean error - never guess between candidates.
      $reqTokens = explode('_', dol_strtolower($toolName));
      $verb = $reqTokens[0];
      $candidates = array();
      foreach (array_keys($this->toolsByName) as $realName) {
        if (strpos($realName, $verb.'_') !== 0 || $this->isSystemTool($this->toolsByName[$realName])) {
          continue;
        }
        $realTokens = explode('_', $realName);
        if (!array_diff($reqTokens, $realTokens)) {
          $candidates[] = $realName;
        }
      }
      if (count($candidates) === 1) {
        dol_syslog("[McpHandler] Tool name '".$toolName."' recovered to '".$candidates[0]."'.", LOG_INFO);
        $toolName = $candidates[0];
      } else {
        return ["error" => "Tool '{$toolName}' not found."];
      }
    }
 
    $toolInstance = $this->toolsByName[$toolName];
 
    // enforce tool context allow-list (system tools always pass through)
    if (!$this->isSystemTool($toolInstance)) {
      $allowed = $this->getAllowedToolsList();
 
      if (!empty($allowed) && !in_array($toolName, $allowed, true)) {
        dol_syslog(
          "[McpHandler] Blocked execution of tool '$toolName' in tool context '{$this->toolcontext}' (not in allow-list).",
          LOG_WARNING
        );
        return array('error' => "Tool '" . $toolName . "' is not available in this tool context.");
      }
    }
 
    // execute
    try {
      dol_syslog('[McpHandler] Executing tool \'' . $toolName . '\' with args: ' . json_encode($args), LOG_INFO);
      $missingRight = $this->checkToolRights($toolInstance, $toolName);
      if ($missingRight !== '') {
        return array('error' => ($missingRight === 'undeclared')
          ? "Tool '".$toolName."' cannot run: it declares no required rights."
          : "Permission denied: '".$toolName."' requires the right ".$missingRight.".");
      }
 
      // Writes do not execute on the first call: the caller gets a preview and
      // a confirmation state, and comes back with it. Reads are unaffected.
      $pending = $this->checkWriteConfirmation($toolInstance, $toolName, $args);
      if ($pending !== null) {
        return $pending;
      }
 
      $result = $toolInstance->execute($toolName, $args);
      dol_syslog('[McpHandler] Tool \'' . $toolName . '\' executed successfully.', LOG_INFO);
      return $result;
    } catch (\Throwable $e) {
      dol_syslog('[McpHandler] Error executing tool \'' . $toolName . '\': ' . $e->getMessage(), LOG_ERR);
      return ["error" => "An internal error occurred while executing the tool '{$toolName}'. Details have been logged."];
    }
  }
}