Fix MCP tool naming for LLM provider compatibility (#3)

This PR updates tool naming in nexus-mcp from service/operation to
service_operation to comply with LLM provider requirements
(^[a-zA-Z0-9_-]{1,64}$ for Claude Desktop and ^[a-zA-Z0-9_-]{1,128}$ for
others). It adds validation, clearer errors, and logging, ensuring that
generated tool names are always valid. Parsing logic has been updated to
support underscore-separated names while maintaining compatibility with
existing Nexus usage.

This guarantees full compatibility with OpenAI, Claude/Anthropic, and
Groq function calling.

---------

Co-authored-by: Roey Berman <[email protected]>

Author: steveandroulakis

nexusmcp/inbound_gateway.py

@@ -78,24 +78,27 @@ async def _handle_call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
         Handle MCP tool call request by calling the corresponding Nexus Operation in the given endpoint.
 
         Args:
-            name: Tool name in the format "service/operation"
+            name: Tool name in the format "service_operation" (LLM-compatible format)
             arguments: Dictionary of arguments to pass to the tool
 
         Returns:
             Result of the tool call (type depends on the specific tool)
 
         Raises:
-            ValueError: If the tool name format is invalid (missing '/')
+            ValueError: If the tool name format is invalid (missing '_' separator)
 
         Example:
             result = await gateway._handle_call_tool(
-                "calculator/add",
+                "calculator_add",
                 {"a": 5, "b": 3}
             )
         """
-        service, _, operation = name.partition("/")
+        # Parse tool name in LLM-compatible format: "service_operation"
+        service, _, operation = name.partition("_")
+
         if not service or not operation:
-            raise ValueError(f"Invalid tool name: {name}, must be in the format 'service/operation'")
+            raise ValueError(f"Invalid tool name: {name}, must be in the format 'service_operation'")
+
         return await self._client.execute_workflow(
             ToolCallWorkflow.run,
             arg=ToolCallInput(

nexusmcp/service_handler.py

@@ -12,13 +12,22 @@
 from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Any
+import re
+import logging
 
 import mcp.types
 import nexusrpc
 import pydantic
 
 from .service import MCPService
 
+# Set up logging
+logger = logging.getLogger(__name__)
+
+# Compile regex patterns ahead of time for better performance
+_TOOL_NAME_PATTERN = re.compile(r"^[a-zA-Z0-9_-]{1,64}$")
+_SERVICE_NAME_PATTERN = re.compile(r"^[a-zA-Z0-9-]{1,64}$")
+
 
 @dataclass
 class _Tool:
@@ -50,8 +59,18 @@ def to_mcp_tool(self, service: nexusrpc.ServiceDefinition) -> mcp.types.Tool:
         Returns:
             An MCP Tool object ready for use by MCP clients
         """
+        # Generate LLM-compatible tool name using underscores instead of forward slashes
+        tool_name = f"{service.name}_{self.defn.name}"
+
+        # Validate tool name meets LLM provider requirements
+        if not _is_valid_tool_name(tool_name):
+            raise ValueError(
+                f"Generated tool name '{tool_name}' does not meet LLM provider requirements. "
+                f"Tool names must match pattern ^[a-zA-Z0-9_-]{{1,64}}$ for Claude Desktop or ^[a-zA-Z0-9_-]{{1,128}}$ for other clients."
+            )
+
         return mcp.types.Tool(
-            name=f"{service.name}/{self.defn.name}",
+            name=tool_name,
             description=(self.func.__doc__.strip() if self.func.__doc__ is not None else None),
             inputSchema=(
                 self.defn.input_type.model_json_schema()
@@ -119,9 +138,14 @@ def register(self, cls: type) -> type:
         service_defn = nexusrpc.get_service_definition(cls)
         if service_defn is None:
             raise ValueError(f"Class {cls.__name__} is not a Nexus Service")
-        if "/" in service_defn.name:
+        # Validate service name contains only characters that will create valid tool names
+        if not _is_valid_service_name(service_defn.name):
+            invalid_chars = set(service_defn.name) - set(
+                "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-"
+            )
             raise ValueError(
-                f"Service name {service_defn.name} cannot contain '/' as it is used to separate service and operation names in MCP tools"
+                f"Service name '{service_defn.name}' contains invalid characters {invalid_chars}. "
+                f"Only alphanumeric characters and hyphens are allowed for LLM provider compatibility."
             )
 
         tools: list[_Tool] = []
@@ -153,7 +177,10 @@ async def list_tools(self, _ctx: nexusrpc.handler.StartOperationContext, _input:
         Returns:
             List of MCP Tool objects representing all available Operations
         """
-        return [tool.to_mcp_tool(service.defn) for service in self._tool_services for tool in service.tools]
+        tools = [tool.to_mcp_tool(service.defn) for service in self._tool_services for tool in service.tools]
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"MCP.list_tools found {len(tools)} tools: {[tool.name for tool in tools]}")
+        return tools
 
 
 ExcludedCallable = Callable[..., Any]
@@ -191,3 +218,35 @@ def internal_operation(self, _ctx: nexusrpc.handler.StartOperationContext, _inpu
     """
     setattr(fn, "__nexus_mcp_tool__", False)
     return fn
+
+
+def _is_valid_tool_name(name: str) -> bool:
+    """Validate tool name against LLM provider requirements.
+
+    Tool names must match the pattern ^[a-zA-Z0-9_-]{1,64}$ for Claude Desktop
+    or ^[a-zA-Z0-9_-]{1,128}$ for other clients (Goose, OpenAI, etc.).
+    Validates against the most restrictive (64 chars) for maximum compatibility.
+
+    Args:
+        name: The tool name to validate
+
+    Returns:
+        True if the name is valid, False otherwise
+    """
+    return bool(_TOOL_NAME_PATTERN.match(name))
+
+
+def _is_valid_service_name(name: str) -> bool:
+    """Validate service name for tool naming compatibility.
+
+    Service names cannot contain underscores as they are used to
+    split service names from operation names when creating tool names.
+
+    Args:
+        name: The service name to validate
+
+    Returns:
+        True if the service name is valid, False otherwise
+    """
+    # Service names cannot contain underscores (used as delimiter)
+    return bool(_SERVICE_NAME_PATTERN.match(name))