DA-2125: Add cluster metrics tool and node discovery tool

[VirajAgarwal-couchbase]

Related Issue

Resolves: DA-2125

What does this change do?

Adds two new read-only MCP tools:

• get_cluster_metrics — retrieves one or more cluster statistics over a historic time window
  in a single call, via the Management REST API's POST /pools/default/stats/range
  (stats-range) endpoint.
• get_nodes_in_cluster — lists the cluster's nodes as host:port targets, via the Management
  REST API's GET /prometheus_sd_config (Prometheus service-discovery) endpoint.

Both tools are registered as read-only (readOnlyHint=True, always available regardless of
READ_ONLY_MODE) and are self-managed-Couchbase-Server-only: if the configured connection
string points at a Capella cluster, the tool detects this up front and returns a clean
{"status": "error", ...} response instead of attempting the REST call.

Evidence of Testing

Automated tests — commands run and results summary:

env-cmd -f .env -- uv run pytest tests/
726 passed, 13 skipped in 923.19s (0:15:23)

uv run pre-commit run --files <all files touched by this PR>
ruff-lint ... Passed
ruff-format ... Passed
(all other configured hooks) ... Passed

Environments tested:

• Couchbase Capella (version: ____) —The new tools do not support Capella
• Self-managed Couchbase Server (version: Enterprise Edition 8.0.1) — full test
  suite (unit + integration + accuracy) run above.

Manual verification — MCP client used (Claude Desktop, Cursor, MCP Inspector, ...) and what was exercised. Screenshots or tool-call transcripts are very helpful:

Compatibility Considerations

• Capella vs. self-managed: both new tools are self-managed-only. They call raw Management
  REST endpoints (/pools/default/stats/range, /prometheus_sd_config) that Capella does not
  expose the same way; rather than let the request fail with an opaque network/auth error, the
  tools detect a Capella connection string up front and return a clear, structured error instead.

Checklist

• Linked to an issue (required for new tools). The issue can be on JIRA (preferred for internal contributors) or GitHub.
• Uses the Couchbase SDK (REST fallback justified in the description, if any) — REST, not SDK: the Python SDK does not expose the stats-range or Prometheus service-discovery Management REST endpoints, so both tools call them directly via httpx, following the same precedent as list_indexes's existing /getIndexStatus REST fallback in index_utils.py.
• Works on both Capella and self-managed Couchbase Server — self-managed only, by design (see Compatibility Considerations); Capella is rejected cleanly rather than silently failing.
• No changes to cb_mcp.core contracts / managed MCP interfaces (or discussed first)
• Unit tests added/updated
• Integration tests added/updated (for cluster-touching changes)
• Read-only mode and tool annotations handled (for new/changed tools)
• Evidence of testing included above
• Docs updated (README, DOCKER.md) for user-facing changes
• Lint and pre-commit pass

[Copilot]

🟡 Changes recommended

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds two new read-only Couchbase Server MCP tools that call Management REST endpoints directly: one for fetching historical cluster metrics (stats-range) and one for discovering cluster nodes (Prometheus SD). The change also introduces small connection-string parsing utilities, registers the new tools in the tool registry/read-only mode, and expands unit/integration/accuracy coverage plus documentation.

Changes:

• Add get_cluster_metrics (POST /pools/default/stats/range) and get_nodes_in_cluster (GET /prometheus_sd_config) with Capella upfront rejection and multi-host failover.
• Register both tools as always-available read-only tools and update read-only tool counts.
• Add/extend unit, integration, and accuracy tests; update README/DOCKER docs.

File summaries

File	Description
tests/unit/test_server_tools_unit.py	Adds unit tests for Capella rejection, REST success/error envelopes, and multi-host failover for the new tools.
tests/unit/test_read_only_mode.py	Updates read-only tool name set and expected tool counts to include the two new tools.
tests/unit/test_connection_string.py	Adds unit tests for connection-string host extraction and Capella detection helpers.
tests/integration/test_server_tools.py	Adds integration coverage for calling the two new tools via MCP session.
tests/integration/conftest.py	Allows the new tools in integration tool allowlists.
tests/accuracy/tool_calling/test_server.py	Adds accuracy cases expecting the model to select the new tools.
tests/accuracy/result_validation/test_server.py	Adds faithfulness validation cases for the new tools’ outputs.
src/cb_mcp/utils/connection_string.py	Introduces helpers to extract hosts from connection strings and detect Capella connections.
src/cb_mcp/tools/server.py	Implements the two new REST-backed tools and uses connection-string helpers + settings validation.
src/cb_mcp/tools/init.py	Registers the new tools in READ_ONLY_TOOLS, annotations, and __all__.
README.md	Documents the two new tools and Capella/self-managed constraints.
DOCKER.md	Mirrors README tool documentation updates for Docker usage.

Review details

Suppressed comments (1)

src/cb_mcp/tools/server.py:414

• Same as get_cluster_metrics: if host extraction returns an empty list, the function currently falls through and raises RuntimeError with last_error=None (and may attempt invalid URLs). Add a fast-fail check for an empty host list to return a clearer error envelope.

        # Capella is already excluded above, so no Capella-CA handling is needed here —
        # just the CA path for a self-signed self-managed cert, or the system CA bundle.
        verify_ssl = (settings.get("ca_cert_path") or True) if is_tls else False
        hosts = extract_hosts_from_connection_string(connection_string)

        last_error: Exception | None = None
        with httpx.Client(verify=verify_ssl, timeout=timeout) as client:
            for host in hosts:

• Files reviewed: 12/12 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.