[Bug]: Single-server MCP config advertising a built-in tool name (e.g. 'terminal') crashes conversation initialization

Aperta
#6,992 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@zsicheng0214 ci sta già lavorando.

Dal 19/11/2026.

  • #6988 di @zsicheng0214 — aperta

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
35/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Ferma
Stack tecnologico
python
Ambito
ai, backend

Direzione di ricerca

Read LocalConversation._runtime_mcp_tools() in openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py and the existing single-server naming test in tests/sdk/conversation/test_local_conversation_mcp.py. Check how MCP tools are registered and how with_server_prefix() preserves the advertised name, then run the MCP conversation tests. Done means colliding tools are namespaced while built-ins and non-colliding siblings remain callable; the linked pull request #6988 indicates work is already underway.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

priority:low ready-for-dev
Is there an existing issue for the same bug?
  • I have searched existing issues and this is not a duplicate.
Bug Description

In LocalConversation._runtime_mcp_tools(), prefixed = len(mcp_config) > 1 prefixes MCP tools as {server}_{tool} only when multiple MCP servers are configured. When a single MCP server (len(mcp_config) == 1) advertises a tool whose bare name matches a built-in agent tool (such as terminal) or duplicates an earlier tool from the same server, self.agent.add_runtime_tools() raises ValueError: Duplicate tool names found, crashing initialization and taking down both the native built-in executor and all valid sibling MCP tools.

Expected Behavior

Built-in agent tools must remain intact, and colliding MCP tools on a single-server config should fall back to tool.with_server_prefix(server_name) ({server}_{tool}) while non-colliding sibling tools remain callable.

Actual Behavior

Reproducible via uv run pytest: configuring Agent(tools=[Tool(name="terminal")], mcp_config={"ext": ...}) where ext advertises terminal and sibling_check causes conv._ensure_agent_ready() to fail with ValueError: Duplicate tool names found: {'terminal'}.

Discovered via TraceTrial-Bench (arXiv:2610.32285, mechanism nodes T2 & T3, where stock OpenHands scored 0% across all 3 reserved-name tasks). Companion fix ready in #6988.

Acceptance Criteria
  • Single-server MCP tools colliding with non-MCP built-in tools are namespaced via with_server_prefix(name) instead of crashing add_runtime_tools
  • Native built-in tools and non-colliding sibling MCP tools remain intact
  • Unit tests pass via uv run pytest tests/sdk/conversation/test_mcp_reserved_tool_collision.py

OpenHands AI triage

The following comments and acceptance criteria were added by the OpenHands AI agent.

Triage

Verified against main (1414239): LocalConversation._runtime_mcp_tools() sets prefixed = len(mcp_config) > 1 (openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py:1728), so single-server MCP tools are never namespaced. AgentBase.add_runtime_tools() raises ValueError: Duplicate tool names found in the conflict check (openhands-sdk/openhands/sdk/agent/base.py:901), which aborts _ensure_agent_ready() after _initialize() already registered built-ins - taking down the native executor and every sibling tool on that server. MCPToolDefinition.with_server_prefix() (openhands-sdk/openhands/sdk/mcp/tool.py:424) is the existing, authoritative renaming mechanism and keeps executor.server_tool_name pointing at the original tool name, so the call still reaches the MCP server under its advertised name. The existing test test_single_enabled_mcp_server_keeps_unprefixed_tool_names (tests/sdk/conversation/test_local_conversation_mcp.py:730) pins that non-colliding single-server tools stay unprefixed, so the fix must leave them unchanged.

The issue includes reproduction, root cause, expected behavior, and an open companion implementation (#6988). Repository guidance defines issue readiness as scope and expected behavior clear enough to start; PR or fix evidence is explicitly not required.

Bounded scope: only the single-server naming path in LocalConversation._runtime_mcp_tools() (startup, tools-changed, and reconciled callbacks). Non-goals: no change to multi-server {server}_{tool} naming; no changes to AgentBase.add_runtime_tools() conflict semantics or error messages; no user-facing docs or deprecation cycle - the fix restores intended behavior; no TypeScript client or Agent Canvas changes (MCP tool naming is server-internal); no framework/user tool sharing via hidden remapping beyond the existing prefix mechanism.

Acceptance Criteria
  • With a single MCP server whose advertised tool list includes a name matching a built-in or other non-MCP agent tool (e.g. terminal), _ensure_agent_ready() completes without raising, and agent.tools_map contains the native built-in tool under its original name plus the MCP tool namespaced as {server}_{tool} whose executor still invokes the server's advertised tool name
  • With a single MCP server advertising a non-colliding tool name (e.g. fetch), the tool remains registered unprefixed, matching test_single_enabled_mcp_server_keeps_unprefixed_tool_names
  • With a single MCP server advertising duplicate tool names, exactly one registered tool per distinct advertised name remains, no duplicate-name error is raised, and no duplicate-name entry appears in the agent tool map
  • Two MCP servers where one advertises terminal and the other advertises fetch register s1_terminal and s2_fetch; multi-server naming behavior is unchanged
  • A server that misses the startup budget and registers late via the tools-changed path receives the same collision handling as startup-time tools, and a colliding late tool is never registered under a name that overwrites a non-MCP tool
  • uv run pytest tests/sdk/conversation/test_local_conversation_mcp.py and the tests covering this behavior pass
Lingua principale
Python
Stelle
1.4k
Fork
797
Merge medio
1g 17h
PR unite (30g)
354

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di OpenHands/software-agent-sdk

Tutte le issue di OpenHands/software-agent-sdk

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.