Class to handle MCP (Model Context Protocol). More...

Collaboration diagram for McpHandler:

Public Member Functions
	__construct ($db, $user, $conf=null, $toolcontext='')
	Constructor.

	getToolsSchemaUnfiltered ()
	Returns the full schema of every loaded tool with no allow-list filtering.

	getToolsSchema ()
	Returns the schema of all tools permitted in the current context.

	getToolsSchemaForLLM ()
	Returns the schema of tools permitted in the current context, with system tools completely excluded.

	executeTool (string $toolName, array $args)
	Execute a specific tool by its name.

Static Public Member Functions
static	resolveAllowList ($raw, $allDiscoveredTools)
	Resolves a raw allow-list constant value into an explicit PHP array of tool names.

Private Member Functions
	isSystemTool ($toolInstance)
	Returns true if the given tool instance declares itself as a system tool.

	getAllowedToolsList ()
	Returns the configured allow-list for the current context as an array of tool names.

	loadTools ()
	Load all available MCP tools.

	loadNativeTools ()
	Load native tools from the specific tools directory.

	loadExternalTools ()
	Loads external tools registered via the 'addMcpTools' hook.

	registerTool (string $key, McpTool $toolInstance)
	Helper method to register a tool instance and populate lookup arrays.

Detailed Description

Class to handle MCP (Model Context Protocol).

This class is responsible for discovering, loading, and executing tools that implement the Model Context Protocol. It supports both native tools from the ai/tools directory and external tools registered via hooks.

Context-aware: pass McpHandler\CTX_ASSISTANT (default) or McpHandler\CTX_MCP_SERVER to the constructor so that the correct allow-list constant is applied.

Definition at line 38 of file mcp.class.php.

Constructor & Destructor Documentation

◆ __construct()

McpHandler::__construct	(	$db,
		$user,
		$conf = null,
		$toolcontext = '' )

Constructor.

Parameters

DoliDB	$db	Database handler object
User	$user	User object
Conf \| null	$conf	Configuration object. Falls back to global $conf when null.
string	$toolcontext	Pass McpHandler\CTX_ASSISTANT or McpHandler\CTX_MCP_SERVER. Defaults to CTX_ASSISTANT when empty.

Definition at line 80 of file mcp.class.php.

References conf(), loadTools(), and user.

Member Function Documentation

◆ executeTool()

McpHandler::executeTool	(	string	$toolName,
		array	$args )

Execute a specific tool by its name.

Enforces the tool context allow-list as a second gate so that even a crafted direct request cannot run a tool that was disabled in the admin UI.

Parameters

string	$toolName	The name of the tool to execute.
	array<string,mixed>	$args The arguments to pass to the tool.

Returns: array<string, mixed> The result of the tool execution or an error array.

Definition at line 453 of file mcp.class.php.

References dol_syslog(), getAllowedToolsList(), and isSystemTool().

◆ getAllowedToolsList()

McpHandler::getAllowedToolsList ( )

private

Returns the configured allow-list for the current context as an array of tool names.

Logic: constant not set / empty string → no restriction → returns array() constant = 'NONE' → all blocked → returns array('blocked') otherwise → returns the list of allowed names

The sentinel 'blocked' will never match any real tool name so in_array() checks against it always return false.

Returns: string[]

Definition at line 124 of file mcp.class.php.

References getDolGlobalString().

Referenced by executeTool(), getToolsSchema(), and getToolsSchemaForLLM().

◆ getToolsSchema()

McpHandler::getToolsSchema ( )

Returns the schema of all tools permitted in the current context.

System tools (isSystem() = true) are always included and tagged with is_system = true so callers can identify and exclude them from the schema sent to the LLM (system tools are parse_intent.php infrastructure — they must never be called directly by the model).

All other tools are filtered against the tool context allow-list.

Returns: array<int, array<string, mixed>> Array of tool schemas

Definition at line 346 of file mcp.class.php.

References getAllowedToolsList(), and isSystemTool().

◆ getToolsSchemaForLLM()

McpHandler::getToolsSchemaForLLM ( )

Returns the schema of tools permitted in the current context, with system tools completely excluded.

This is the exact list sent to the LLM.

System tools (ask_for_confirmation, respond_to_user, etc.) must NEVER be visible to the model. If the LLM sees ask_for_confirmation in its schema it will call it directly with wrong arguments instead of the real action tool, causing an infinite confirmation loop on the client side.

parse_intent.php uses this method to build $toolsForLLM, and keeps getToolsSchema() separately only for the post-LLM validation step (where system tools must still be accepted as valid responses).

Returns: array<int, array<string, mixed>>

Definition at line 403 of file mcp.class.php.

References getAllowedToolsList(), and isSystemTool().

◆ getToolsSchemaUnfiltered()

McpHandler::getToolsSchemaUnfiltered ( )

Returns the full schema of every loaded tool with no allow-list filtering.

Adds is_system and class_name metadata needed by admin/configure_tools.php.

Must not be called from any user-facing entry point — admin use only.

Returns: array<int, array<string, mixed>>

Definition at line 315 of file mcp.class.php.

References isSystemTool().

◆ isSystemTool()

McpHandler::isSystemTool ( $toolInstance )

private

Returns true if the given tool instance declares itself as a system tool.

Detection is entirely delegated to the tool class via isSystem() — no tool names are hardcoded here. Any tool class that overrides isSystem() returning true is treated as a system tool automatically.

Parameters

McpTool $toolInstance The tool instance to evaluate.

Returns: bool

Definition at line 105 of file mcp.class.php.

Referenced by executeTool(), getToolsSchema(), getToolsSchemaForLLM(), and getToolsSchemaUnfiltered().

◆ loadExternalTools()

McpHandler::loadExternalTools ( )

private

Loads external tools registered via the 'addMcpTools' hook.

Initializes the HookManager for the 'aimcp' context and executes the 'addMcpTools' hook. It expects modules to populate the result array with arrays containing valid McpTool instances.

Returns: void

Definition at line 242 of file mcp.class.php.

References dol_syslog(), and registerTool().

Referenced by loadTools().

◆ loadNativeTools()

McpHandler::loadNativeTools ( )

private

Load native tools from the specific tools directory.

Scans the ai/tools/ directory for PHP files. It validates the file paths for security, attempts to load the corresponding class (following the convention "Tool" + PascalCase filename), and registers the tool if it is a valid instance of McpTool.

Returns: void

Definition at line 193 of file mcp.class.php.

References conf(), dol_syslog(), registerTool(), and user.

Referenced by loadTools().

◆ loadTools()

McpHandler::loadTools ( )

private

Load all available MCP tools.

This method scans the ai/tools directory for native tools and executes the 'addMcpTools' hook to allow external modules to register their own tools.

Returns: void

Definition at line 177 of file mcp.class.php.

References loadExternalTools(), and loadNativeTools().

Referenced by __construct().

◆ registerTool()

McpHandler::registerTool	(	string	$key,
		McpTool	$toolInstance )

private

Helper method to register a tool instance and populate lookup arrays.

Parameters

string	$key	A unique key for the tool (e.g., filename or class name).
McpTool	$toolInstance	The instantiated tool object.

Returns: void

Definition at line 287 of file mcp.class.php.

References dol_syslog(), and McpTool\getDefinitions().

Referenced by loadExternalTools(), and loadNativeTools().

◆ resolveAllowList()

static McpHandler::resolveAllowList	(		$raw,
			$allDiscoveredTools )

static

Resolves a raw allow-list constant value into an explicit PHP array of tool names.

Parameters

string	$raw	Raw value of the constant from getDolGlobalString().
string[]	$allDiscoveredTools	Full list of all non-system tool names discovered.

Returns: string[] Explicit list of currently allowed tool names.

Definition at line 154 of file mcp.class.php.

The documentation for this class was generated from the following file:

dolibarr_dev/htdocs/ai/class/mcp.class.php

Public Member Functions

Static Public Member Functions

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ executeTool()

◆ getAllowedToolsList()

◆ getToolsSchema()

◆ getToolsSchemaForLLM()

◆ getToolsSchemaUnfiltered()

◆ isSystemTool()

◆ loadExternalTools()

◆ loadNativeTools()

◆ loadTools()

◆ registerTool()

◆ resolveAllowList()