modelcontextprotocol/example-remote-client
Watch
1
0
Fork
You've already forked example-remote-client
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update conversation system documentation for tool naming fix

Browse source 
- Update MCP tool naming from server.tool to server__tool format
- Add tool naming requirements section with OpenRouter API constraints
- Update troubleshooting guide with tool naming validation errors
- Add specific troubleshooting for agent loop hanging with MCP tools

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Jerome 2025-06-12 12:08:10 +01:00
commit d028846a14
No known key found for this signature in database
1 changed files with 24 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

28
docs/conversation_system_design.md
View file

@ -132,19 +132,32 @@ Built-in tools for development and testing:
#### MCP Tools #### MCP Tools
Tools from connected MCP servers are: Tools from connected MCP servers are:
- **Name-prefixed**: `${serverName}.${toolName}` to avoid conflicts - **Name-prefixed**: `${serverName}__${toolName}` to avoid conflicts and comply with API requirements
- **Dynamically routed**: Tool calls extract server name and route to correct connection - **Dynamically routed**: Tool calls extract server name and route to correct connection
- **Auto-discovered**: Available tools update when servers connect/disconnect - **Auto-discovered**: Available tools update when servers connect/disconnect
```typescript ```typescript
// Tool execution routing // Tool execution routing
if (toolCall.function.name.includes('.')) { if (toolCall.function.name.includes('__')) {
const [serverName] = toolCall.function.name.split('.'); const [serverName] = toolCall.function.name.split('__');
const connection = connections.find(conn => conn.name === serverName); const connection = connections.find(conn => conn.name === serverName);
return await callMCPTool(connection.id, toolCall.function.name, toolCall.function.arguments); return await callMCPTool(connection.id, toolCall.function.name, toolCall.function.arguments);
} }
``` ```
#### Tool Naming Requirements
**Important**: Tool names must comply with OpenRouter API requirements:
- **Pattern**: Must match `^[a-zA-Z0-9_-]{1,64}$`
- **No dots allowed**: This is why we use double underscore (`__`) as separator
- **Length limit**: Maximum 64 characters total
Example tool names:
- ✅ `test__echo` (valid)
- ✅ `weather_service__get_forecast` (valid)
- ❌ `test.echo` (invalid - contains dot)
- ❌ `server__very_long_tool_name_that_exceeds_the_sixty_four_character_limit` (invalid - too long)
## State Management ## State Management
### Conversation Persistence ### Conversation Persistence
@ -384,8 +397,9 @@ Debug conversation state in browser DevTools:
**Tool calls not working** **Tool calls not working**
- Verify MCP server connections in MCP Status panel - Verify MCP server connections in MCP Status panel
- Check tool name prefixing for MCP tools (`server.tool_name`) - Check tool name prefixing for MCP tools (`server__tool_name`)
- Ensure tool schemas match expected format - Ensure tool schemas match expected format
- Verify tool names comply with API requirements (alphanumeric, underscore, hyphen only)
**Conversations not persisting** **Conversations not persisting**
- Check localStorage quota and permissions - Check localStorage quota and permissions
@ -397,4 +411,10 @@ Debug conversation state in browser DevTools:
- Verify `refreshAuthState()` is called after auth changes - Verify `refreshAuthState()` is called after auth changes
- Check React DevTools for proper context updates - Check React DevTools for proper context updates
**Agent loop hangs with MCP tools connected**
- Check browser console for OpenRouter API errors about tool names
- Verify tool names don't contain dots or other invalid characters
- Ensure tool names are under 64 characters total length
- Look for pattern validation errors: `String should match pattern '^[a-zA-Z0-9_-]{1,64}'`
This system provides a robust foundation for conversational AI with extensible tool calling capabilities, proper state management, and a clean user experience. This system provides a robust foundation for conversational AI with extensible tool calling capabilities, proper state management, and a clean user experience.