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
 *
 * 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;
 
  private $loadedTools = [];
 
  private $toolsByName = [];
 
 
  private $toolcontext;
 
  public function __construct($db, $user, $conf = null, $toolcontext = '')
  {
    $this->db = $db;
    $this->user = $user;
 
    if ($conf === null) {
      global $conf;
    }
    $this->conf = $conf;
 
    $this->toolcontext = (!empty($toolcontext)) ? $toolcontext : self::CTX_ASSISTANT;
 
    $this->loadTools();
  }
 
  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);
 
    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))));
  }
 
 
  private function loadTools()
  {
    $this->loadNativeTools();
    $this->loadExternalTools();
  }
 
  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 (!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;
        $def['categories'] = $tool->getCategories();
        $schema[] = $def;
      }
    }
 
    return $schema;
  }
 
  public function getToolsSchema(): array
  {
    $allowed = $this->getAllowedToolsList();
    $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;
          $def['categories'] = $tool->getCategories();
          $schema[] = $def;
          continue;
        }
 
        $def['is_system'] = false;
 
        if (empty($allowed)) {
          // No restriction configured — include everything
          $def['categories'] = $tool->getCategories();
          $schema[] = $def;
          continue;
        }
 
        if (in_array($name, $allowed, true)) {
          $def['categories'] = $tool->getCategories();
          $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;
        }
 
        if (empty($allowed)) {
          // No restriction configured — include everything
          $def['categories'] = $tool->getCategories();
          $schema[] = $def;
          continue;
        }
 
        if (in_array($name, $allowed, true)) {
          $def['categories'] = $tool->getCategories();
          $schema[] = $def;
        }
      }
    }
 
    return $schema;
  }
 
  public function executeTool(string $toolName, array $args): array
  {
    if (!isset($this->toolsByName[$toolName])) {
      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);
      $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."];
    }
  }
}