feat(mcp): #1167 prefix colliding MCP tool names

[IgnazioDS]

Summary

• add an opt-in mcp_config["include_server_in_tool_names"] flag to expose MCP tools as <server_name>_<tool_name>
• preserve the existing default behavior of raising on duplicate tool names across MCP servers
• keep invocation and meta resolution keyed to the original MCP tool name while logging the prefixed display name
• add regression coverage for collision handling, server-name sanitization, canonical meta resolution, and prefixed-name failure logging

Fixes #1167.

Validation

• uv run ruff check src/agents/agent.py src/agents/mcp/util.py tests/mcp/test_mcp_util.py
• uv run pytest tests/mcp/test_mcp_util.py -q
• uv run mypy src/agents/agent.py src/agents/mcp/util.py tests/mcp/test_mcp_util.py

Notes

• This refreshes the previously proposed server-prefix approach from closed PR feat(mcp): optional server-name prefix for colliding tool names #2442 against the current main branch and keeps the surface area limited to MCP config/util behavior plus focused tests.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9179a99593

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[IgnazioDS]

Addressed the review thread in b9f25db.

Change made:

• preserve the readable normalized server prefix when it is unique
• add a stable hash-based suffix only when multiple server names normalize to the same prefix
• add a regression test covering GitHub MCP Server vs GitHub_MCP_Server

Validation:

• uv run ruff check src/agents/mcp/util.py tests/mcp/test_mcp_util.py
• PYTHONPATH=src uv run pytest tests/mcp/test_mcp_util.py -q
• uv run mypy src/agents/mcp/util.py --disable-error-code import-not-found --disable-error-code unused-ignore

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b9f25db053

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[IgnazioDS]

Addressed the follow-up naming-collision thread in d710186.

Change made:

• switched prefixed MCP tool names to an unambiguous encoded form: mcp_<prefix_len>_<server_prefix><tool_name>
• kept the readable server-specific prefix visible in the final tool name
• retained the hash-based server-prefix disambiguation for server names that normalize to the same slug
• updated regression coverage for direct prefix collisions and tuple-level collisions

Validation:

• uv run ruff check src/agents/agent.py src/agents/mcp/util.py tests/mcp/test_mcp_util.py
• PYTHONPATH=src uv run pytest tests/mcp/test_mcp_util.py -q
• uv run mypy src/agents/agent.py src/agents/mcp/util.py --disable-error-code import-not-found --disable-error-code unused-ignore

[seratch]

Thanks for working on this. I think the feature is useful, but I don't think it's merge-ready yet because the new naming scheme can still generate invalid function tool names in two ways.

First, _server_tool_name_prefix() currently preserves non-ASCII alphanumeric characters. With include_server_in_tool_names=True, a server label like 天気サーバー becomes part of the public tool name and is then forwarded unchanged to the Responses payload. OpenAI function tool names need to stay within the allowed ASCII character set, so this path can fail at runtime even though the current tests are green.

Second, the prefixed name is never bounded to the API's 64-character limit. A sufficiently long server.name plus tool.name can easily produce a function name longer than 64 characters, and that overlong name is also passed through unchanged to the Responses tool definition.

So I think we need two additional safeguards before merging:

1. Normalize the server-derived prefix to an ASCII-safe subset only.
2. Enforce the 64-character limit on the final generated tool name, probably with a deterministic shortening/hash scheme so collisions remain impossible.

Once those two cases are covered, the overall approach looks good to me.