Add: basic FastMCP server for analytics tools with similar input-outp…

[VirajAgarwal-couchbase]

Add prototype Enterprise Analytics MCP server (analytics-mcp)

Related Issue

Resolves: https://jira.issues.couchbase.com/browse/IDEA-1036
Related: https://jira.issues.couchbase.com/browse/DA-2027

What does this change do?

Adds a small, standalone FastMCP server under analytics-mcp/ exposing 5 P0 tools for
Couchbase Enterprise Analytics (EA), built on the couchbase-analytics Python SDK:
get_databases_in_cluster, get_scopes_in_database, get_collections_in_scope,
get_schema_for_collection, and run_query_sync.

Why is this change needed?

There's customer interest in MCP tooling for Enterprise Analytics, a separate service from
operational Couchbase Server that requires a different SDK. This is a prototype to validate
the tool set and input/output conventions against a live EA cluster before deciding on final
architecture (separate server vs. merged into the main MCP server). It's intentionally minimal
— no OAuth, no scope enforcement, no read-only-mode toggle — so the tool bodies and tests can
be copy-pasted wholesale once that architecture decision is made.

Evidence of Testing

Automated tests — commands run and results summary:

uv run pytest tests/unit/ -v → 10 passed
uv run pytest tests/integration/ -v → 5 passed

Environments tested:

• Couchbase Capella — N/A, Enterprise Analytics is self-managed-only for now
• Self-managed Couchbase Server (version: couchbase/enterprise-analytics:2.2.0, via Docker — single node, per the quick-install guide)

Manual verification — ran uv run ea-mcp-server over stdio against the local Docker EA
cluster (http://localhost:8095, Administrator/password), confirmed all 5 tools register
and each was exercised directly (create scope/collection, insert, list, infer schema,
run_query_sync happy path + error envelope) with resultstring.

Compatibility Considerations

New, independent package (analytics-mcp/) with its owanges to
cb_mcp.core, the existing mcp-server-couchbase tool set, CLI flags, or dependencies of the
parent server. Enterprise Analytics is self-managed-onld.

Checklist

• Linked to an issue (required for new tools). The erred for internal contributors) or GitHub.
• Uses the Couchbase SDK (couchbase-analytics, the EA-specific SDK)
• Works on both Capella and self-managed Couchbase anaged-only
• 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 ad-only mode in this prototype by design;ToolAnnotations set per tool
• Evidence of testing included above
• Docs updated (README, DOCKER.md) for user-facing changes — new analytics-mcp/README.md; parent README/DOCKER.md untouched (separate package)
• Lint and pre-commit pass

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a minimal Enterprise Analytics (EA) FastMCP prototype server plus query/metadata tools, along with unit/integration tests and packaging scaffolding to run against a live EA cluster.

Changes:

• Introduces EA MCP server entrypoint, cluster connection handling, and standard tool response envelopes.
• Adds query + metadata tool implementations and registers them with FastMCP.
• Adds unit tests (mocked cluster) and integration tests (live cluster via subprocess), plus pyproject/README for running.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
analytics-mcp/src/ea_mcp_server.py	Adds the stdio FastMCP server entrypoint and tool registration.
analytics-mcp/src/ea_mcp/connection.py	Implements minimal “connect once” cluster lifecycle and context access.
analytics-mcp/src/ea_mcp/tools/query.py	Adds a write-style query tool returning success/error envelopes.
analytics-mcp/src/ea_mcp/tools/metadata.py	Adds read-only metadata introspection tools querying System.Metadata.
analytics-mcp/src/ea_mcp/tools/init.py	Exposes the tool list + annotations for registration.
analytics-mcp/src/ea_mcp/responses.py	Adds shared success/error envelope helpers.
analytics-mcp/tests/unit/test_query_tools_unit.py	Unit-tests query tool envelope behavior with mocked SDK errors.
analytics-mcp/tests/unit/test_metadata_tools_unit.py	Unit-tests metadata tools query execution and raise-on-error behavior.
analytics-mcp/tests/integration/conftest.py	Adds subprocess-based MCP session fixture + response payload extraction.
analytics-mcp/tests/integration/test_query_tools.py	Adds live-cluster integration tests for the query tool.
analytics-mcp/tests/integration/test_metadata_tools.py	Adds live-cluster integration tests for metadata tools with setup/teardown DDL.
analytics-mcp/pyproject.toml	Adds project metadata, deps, lint/test config, and dev dependency pins.
analytics-mcp/README.md	Documents how to run the server and execute unit/integration tests.

---

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