CLI broken: similarity commands fail after API schema change to require mcp_servers

[therealnb]

CLI broken: similarity commands fail after API schema change to require mcp_servers

Problem

CLI similarity commands (similarity matrix, similarity analyze, similarity overlap-matrix, similarity recommend) are failing with HTTP 422 validation errors.

Error Message

✗ HTTP error from mcp-tef server
  Status: 422 - {"detail":[{"type":"missing","loc":["body","mcp_servers"],"msg":"Field required","input":{"mcp_server_urls":[...],"similarity_threshold":0.85}}]}

Affected Commands

All similarity-related CLI commands fail:

• mtef similarity matrix --server-urls ...
• mtef similarity analyze --server-urls ...
• mtef similarity overlap-matrix --server-urls ...
• mtef similarity recommend --server-urls ...

Root Cause

The API schema was changed in commit 99c763d (Dec 12, 2025) to require mcp_servers (array of MCPServerConfig objects) instead of accepting mcp_server_urls (array of strings). The CLI client was never updated to match this change.

Breaking Change Details

Commit: 99c763d - "Add transport protocol support to MCP server configurations (#18)"

• Changed SimilarityAnalysisRequest to require mcp_servers: list[MCPServerConfig]
• MCPServerConfig requires both url (string) and transport (string, defaults to "streamable-http")
• Removed backward compatibility for mcp_server_urls format

What CLI sends (WRONG):

{
  "mcp_server_urls": ["http://host.docker.internal:8080/fetch/mcp", ...],
  "similarity_threshold": 0.85
}

What API expects (CORRECT):

{
  "mcp_servers": [
    {"url": "http://host.docker.internal:8080/fetch/mcp", "transport": "streamable-http"},
    ...
  ],
  "similarity_threshold": 0.85
}

Evidence

• Issue bad output for a bigger grid #12 shows the command worked before Dec 12, 2025
• Commit aa2aa8e updated tests to use mcp_servers format, confirming the breaking change
• CLI client code (cli/src/mcp_tef_cli/client.py) still sends mcp_server_urls format

Affected Files

• cli/src/mcp_tef_cli/client.py:
  • get_similarity_matrix() (line 477)
  • analyze_similarity() (line 442)
  • get_overlap_matrix() (line 503)
  • get_recommendations() (line 556)

Solution

Update the CLI client to:

1. Convert URL strings to MCPServerConfig objects
2. Use field name mcp_servers instead of mcp_server_urls
3. Support optional transport specification (e.g., url:transport format)

Reproduction Steps

1. Run any similarity CLI command:

   mtef similarity matrix \
     --server-urls http://host.docker.internal:8080/fetch/mcp,http://host.docker.internal:8080/toolhive-doc-mcp/mcp \
     --threshold 0.85 \
     --insecure

2. Observe HTTP 422 error with "Field required" for mcp_servers

Related

• Issue bad output for a bigger grid #12 - Shows the command worked before the breaking change
• Commit 99c763d - Introduced the breaking change
• Commit aa2aa8e - Updated tests to match new format