Skip to content

D120 — Tool-prefix discovery for client-owned multi-KB operations

Decision. GET /health now advertises each mounted KB's effective tool-name prefix (mcpserver.KBInfo.ToolPrefix, populated at mount time), and every client-owned direct tool call is qualified from that snapshot rather than from a locally recomputed prefix (resolveKBTargets/qualifyTool/callTool in cmd/cartographer/multikb.go, used by sync, reindex and the TUI). The discovered value is used live and never persisted. The TUI's MCP-config badge becomes three-state — in-sync, partial, missing — computed against all expected multi-KB entries instead of collapsing an incomplete configuration to missing. Remote failures carry a typed taxonomy that separates a server that never answered from a server that answered with a protocol or tool error, so the latter is no longer displayed as unreachable. This is a corrective extension of D102: the prefix remains opt-in and default-off.

Rationale. D102 let an operator choose an arbitrary tool_prefix, but the client kept deriving the namespace from the KB name. On any installation whose prefix was not exactly the sanitised KB name, every client-owned call named a tool that did not exist. The symptom reached the operator as two false diagnostics — mcp-config missing and artifacts: server unreachable — that pointed at the network and the provider config while the server was healthy and correctly configured. Discovery is the only sound fix: the prefix is server state, so the server must report it. Not persisting it keeps client and server from drifting when a prefix changes. The badge and the error taxonomy are part of the same defect: a diagnostic that misattributes a failure costs more than the failure.

Consequences. /health grows a field; the key is omitted when empty, so an older client parsing the response is unaffected and an unprefixed deployment sees a byte-identical body. Every direct tool call now depends on a successful /health first — a client that cannot reach health cannot qualify a call, which is why an unreachable server is reported as exactly that and not as a tool failure. The three-state badge means an operator who previously read missing on a partially provisioned multi-KB setup now reads partial: same underlying state, but it no longer suggests nothing was written. server_url in the client config is still expected to include the /mcp path segment; /health is derived from it by stripping that segment, unchanged from before.