>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3613896. --> Reported by: [michaellander](https://www.drupal.org/user/636494) Related to !7 >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The Tool API module (1.0.x) now provides an invoker-aware event system for input/output value transforms and definition normalization, along with a shared entity handle service for token-based entity passing between tool calls. The <code>mcp_server_tool_bridge</code> module should use these upstream capabilities rather than implementing its own schema generation and entity management.</p> <p>Currently the bridge module:<br> - Duplicates JSON Schema generation with a custom type map and constraint conversion in McpToolConfigDeriver<br> - Manually handles entity serialization via tempstore in ToolApi::execute()<br> - Has its own prepareArgument() method for type coercion (list wrapping, boolean conversion, map recursion)<br> - Lacks entity handle support (entities can't be passed between consecutive tool calls in an MCP session)</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <p>1. Enable mcp_server_tool_bridge with a tool that accepts/returns entity inputs/outputs<br> 2. Call the tool via MCP &mdash; entities cannot be passed between calls, schema generation doesn't reflect handle descriptions, and type coercion logic is duplicated from what the Tool API now provides generically</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>1. Opt into entity handles through the Tool API invoker</p> <p>Tool API 1.0.0-beta8 lets a connector pass an <code>Invoker</code> with capabilities to <code>ToolManager::createInstance()</code> instead of a bare ID string. The bridge builds an <code>Invoker</code> with the <code>EntitiesAsHandles</code> capability and Tool API's own subscriber resolves handle strings to entities on input, transforms entities to handle strings with hints on output, and rewrites entity definitions in the schema. The bridge registers no subscriber and no services.</p> <p>2. Add McpServerToolBridgeInvoker</p> <p>A small factory class holds the invoker ID (<code>mcp_server</code>) and the capability list. Both <code>ToolApi</code> and <code>McpToolConfigDeriver</code> call its <code>create()</code> method, so the bridge declares what it needs from Tool API in one place.</p> <p>3. Replace McpToolConfigDeriver schema generation</p> <p>Remove all custom schema methods (convertToMcpSchema, convertInputDefinitionToSchema, type maps, constraint mappers). Replace with ToolDefinitionSerializer::normalizeInputSchema($tool) using a tool instance created with the MCP invoker &mdash; this dispatches definition normalize events automatically.</p> <p>4. Simplify ToolApi::execute()</p> <p>Remove prepareArgument() (handled by upstream InputTypeCoercionSubscriber) and PrivateTempStoreFactory dependency (handled by handle store via events). The execute method becomes: create instance &rarr; set inputs &rarr; validate &rarr; check access &rarr; execute &rarr; get formatted result &rarr; append hints &rarr; return.</p> <p>5. Classify failures with Tool API's FailureCategory</p> <p><code>ToolApi::execute()</code> classifies each failure as Input, Access, or Runtime and echoes the input schema only for Input failures, the ones a client can fix by resending different arguments. Validation violations, <code>InputException</code>, and handle exceptions are Input. Access denials are Access. Anything else, including a failure result the wrapped tool marks as Runtime, is Runtime.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <p>- Add McpServerToolBridgeInvoker<br> - Rewrite McpToolConfigDeriver to use ToolDefinitionSerializer<br> - Simplify ToolApi::execute() &mdash; remove prepareArgument() and tempstore<br> - Adopt FailureCategory in ToolApi::execute()<br> - Remove unused imports and dependencies<br> - Add kernel tests for handle round-trip through MCP execution</p> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>- McpServerToolBridgeInvoker::ID constant and McpServerToolBridgeInvoker::create() factory added<br> - ToolApi::prepareArgument() removed (no longer needed)<br> - PrivateTempStoreFactory removed from ToolApi constructor<br> - ToolDefinitionSerializer added to McpToolConfigDeriver constructor<br> - MCP tool schemas now include handle descriptions for entity inputs/outputs<br> - Tool execution results now include entity handle hints in the message<br> - Access denials and runtime failures no longer include input_schema in the result. Only failures a client can fix by resending different arguments carry it. This is a wire-visible change for MCP clients that inspected the schema on every failure.<br> - Bridged tools that throw during execution are reported with the exception class only. The full message goes to the log. This comes from Tool API beta8, not the bridge, but clients of the bridge will see it.<br> - drupal:serialization is a new hard dependency. tool.definition_serializer is wired with @?serializer and throws a LogicException without it; tool.info.yml does not declare it, so this module must.<br> - ToolApi::execute() now forwards the MCP ClientGateway to backing tools implementing ClientGatewayAwareInterface, so bridged tools can use sampling.<br> - Requires tool &gt;= 1.0.0-beta8 (composer and info.yml).</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>- Entity handles are stored in the Tool API's handle store (private tempstore) rather than a custom tempstore implementation<br> - MCP tool input schemas now use the Tool API's JSON Schema normalizer format instead of a custom type map</p>