MCP tooling gaps that make agents unzip source jars

[matejcerny]

I was investigating why coding agents so often give up on Metals MCP and unzip source jars instead. This is an umbrella issue for my findings so far, I'm happy to address some of them if it makes sense.

Issues

• glob-search/typed-glob-search throw without fileInFocus

  • focusedDocument is only set by editors
  • Proposed fix: pass None through, nameSearch already takes an Option and globSearch only wraps the path in Some

• The description promises glob patterns that don't exist.

  • Agents send *Redacted*Api* and get nothing back - * is not a wildcard anywhere
  • Proposed fix: drop "glob pattern" from the description or implement wildcards

• The schema says "substring", but matching is Fuzzy and boundary-anchored

  • FuzzySuite asserts checkNO("nner", "a/Inner#")
  • Proposed fix: describe the actual matching in the schema

• Qualified queries always return nothing.

  • The predicate compares only the last . segment (McpSymbolSearch), so com.test.Foo never matches - and an FQCN is the first thing an agent tries
  • Proposed fix: match the FQCN when the query contains a . or say "single name segment" in the schema

• "Returns symbol locations and signatures" is false

  • output is a kind plus an FQCN (McpPrinter), so an agent believing it has signatures never calls inspect
  • Proposed fix: correct the description and point at inspect

• Results are silently truncated.

  • ClasspathSearch.maxNonExactMatches = 10, ten hits with no notice reads exactly like "Metals doesn't know this library"
    Proposed fix: say when results were truncated

• list-modules returned an empty list while the build was still importing

  • ... then 38 targets a minute later
  • Proposed fix: say when indexing is incomplete

(Analysis was made against metals-mcp 1.6.7 and main branch b5c6f8b71eb)