McpTool Class Reference

Abstract base class for all MCP (Model Context Protocol) tools. More...

Inheritance diagram for McpTool:

Collaboration diagram for McpTool:

Public Member Functions
	__construct ($db, $user, $conf)
	Constructor.
	getDefinitions ()
	Return the list of tools provided by this class.
	execute (string $toolName, array $args)
	Execute a specific tool.
	getCategories ()
	Return categories this tool belongs to.
	isSystem ()
	Return true if this is a system/infrastructure tool that must always remain visible and executable regardless of the admin allow-list.
	getRequiredRights (string $toolName)
	Rights the caller must hold to run a tool of this class.
	writeConfirmationPreview (string $toolName, array $args)
	Preview of what a call would write, or NO_WRITE for a read tool.

Public Attributes
const	RIGHTS_UNDECLARED = 'undeclared'
	Default of getRequiredRights(): the class never declared anything, deny.
const	NO_WRITE = ''
	Returned by writeConfirmationPreview() when the tool writes nothing.

Detailed Description

Abstract base class for all MCP (Model Context Protocol) tools.

All AI tools must extend this class. It provides a standard interface for defining tool capabilities and executing them, along with common utility methods for interacting with Dolibarr.

Definition at line 32 of file mcptool.class.php.

Constructor & Destructor Documentation

__construct()

McpTool::__construct	(		$db,
			$user,
			$conf )

Constructor.

Parameters

DoliDB	$db	Database handler object
User	$user	User object
Conf	$conf	Configuration object

Reimplemented in ToolApiBridge.

Definition at line 62 of file mcptool.class.php.

References conf(), and user.

Member Function Documentation

execute()

McpTool::execute ( string $toolName, array $args )

abstract

Execute a specific tool.

This method must be implemented by child classes to contain the logic for executing the tools defined in getDefinitions.

Parameters

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

Returns

mixed The result of the tool execution.

Reimplemented in ToolApiBridge, ToolCategories, ToolCoffeeMaker, ToolConversation, ToolCrudObjects, ToolEmailCleaner, ToolInvoices, ToolNavigation, ToolProducts, ToolReports, and ToolThirdParty.

getCategories()

McpTool::getCategories

(

)

Return categories this tool belongs to.

Used by the intent parser to filter available tools.

Returns

array<string> List of categories (e.g., ['billing', 'commercial'])

Reimplemented in ToolApiBridge, ToolCategories, ToolCoffeeMaker, ToolConversation, ToolCrudObjects, ToolEmailCleaner, ToolInvoices, ToolNavigation, ToolProducts, ToolReports, and ToolThirdParty.

Definition at line 98 of file mcptool.class.php.

getDefinitions()

McpTool::getDefinitions ( )

abstract

Return the list of tools provided by this class.

This method must be implemented by child classes to define their capabilities. It should return an array of tool definitions, typically in a JSON schema format.

Returns

list<array<string, mixed>> Array of tool definitions.

Reimplemented in ToolApiBridge, ToolCategories, ToolCoffeeMaker, ToolConversation, ToolCrudObjects, ToolEmailCleaner, ToolInvoices, ToolNavigation, ToolProducts, ToolReports, and ToolThirdParty.

Referenced by McpHandler\registerTool().

getRequiredRights()

McpTool::getRequiredRights

(

string

$toolName

)

Rights the caller must hold to run a tool of this class.

Returns a list of [module, permission, sub-permission] triples; all of them must hold. Three answers are meaningful:

• array() the tool reads no business data
• array(array('facture', 'lire')) checked before the tool runs
• self\RIGHTS_ENFORCED_DOWNSTREAM the callee checks (REST API classes)

Tools that do not override this are denied: a caller authenticates as a real user since #40425, so a missing declaration must fail closed.

Parameters

string

$toolName

Tool being executed, for classes exposing several.

Returns

array<int,array<int,string>>|string Triples, or RIGHTS_ENFORCED_DOWNSTREAM.

Reimplemented in ToolApiBridge, ToolCategories, ToolCoffeeMaker, ToolConversation, ToolCrudObjects, ToolInvoices, ToolNavigation, ToolProducts, ToolReports, and ToolThirdParty.

Definition at line 137 of file mcptool.class.php.

References RIGHTS_UNDECLARED.

isSystem()

McpTool::isSystem

(

)

Return true if this is a system/infrastructure tool that must always remain visible and executable regardless of the admin allow-list.

The default is false. Override and return true in any tool class that provides core assistant communication functions (clarification, confirmation, responses, etc.).

McpHandler calls this method at runtime — no tool names are hardcoded anywhere. Adding a new system tool class in the future requires only overriding this method in that class; no changes to McpHandler are needed.

Returns

bool

Reimplemented in ToolConversation.

Definition at line 117 of file mcptool.class.php.

writeConfirmationPreview()

McpTool::writeConfirmationPreview	(	string	$toolName,
		array	$args )

Preview of what a call would write, or NO_WRITE for a read tool.

A tool returning a preview does not execute on the first call: the handler answers with that text and a confirmation state, and runs the tool only when the caller comes back with it. The text is what a human is asked to approve, so it names the records and amounts involved rather than dumping arguments.

Parameters

string	$toolName	Tool that would run.
	array<string,mixed>	$args Arguments it would run with.

Returns

string Preview text, or self\NO_WRITE when nothing is written.

Reimplemented in ToolCategories, ToolCrudObjects, ToolInvoices, ToolProducts, and ToolThirdParty.

Definition at line 153 of file mcptool.class.php.

References NO_WRITE.

---

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

• dolibarr_dev/htdocs/ai/class/mcptool.class.php