Skip to content

refactor(api): build MCP ClickHouse clients through one helper - #3752

Open
brandon-pereira wants to merge 1 commit into
mainfrom
claude/mcp-clickhouse-client-helper
Open

brandon-pereira wants to merge 1 commit into
mainfrom
claude/mcp-clickhouse-client-helper

Conversation

@brandon-pereira

Copy link
Copy Markdown
Member

Summary

MCP tools now build their ClickHouse clients through one helper, getMcpClickhouseClient(context, connectionId, options?) in packages/api/src/mcp/utils/clickhouse.ts. Before, a dozen tools each repeated the same steps: look up the team's connection, check it exists, and build a ClickhouseClient. Any change to how MCP talks to ClickHouse (client options, timeouts, error handling, tracing) had to be copied into every tool, and new tools copied the pattern again. This PR has no behavior change: tools pass the same client options, return the same errors and produce the same output.

Design decisions

  • The helper takes the full McpContext, not just teamId. That makes it the one place that decides how a client is built for a given caller. To get the context to the tools, runConfigTile, runEventPatterns, mineWindowPatterns, denoiseSearchResults, runSqlBatch, describeMetricImpl and listMetricsImpl now take context as their first argument instead of teamId.
  • A missing connection throws McpConnectionNotFoundError, and each tool maps it to its own response. The tools did not share one response for a missing connection: they return different user-error messages, denoise returns skipped: 'connection_not_found', and the waterfall log lookup records a note. Each call site catches the typed error and returns what it returned before. Any other error (for example, a database failure) is re-thrown unchanged.
  • requestTimeout is opt-in. It is passed only at the sites that used MCP_REQUEST_TIMEOUT before (runConfigTile, describe_table, the trace tools, service health). Every other site gets the same options as before.
  • The null-returning getMcpClickhouseClient in trace/shared.ts is removed. The trace and service-health tools now use the new helper.

Not migrated: sources/listSources.ts still builds its own client. It uses PreviewClickhouseClient, a subclass of the common-utils base client (without the API logger) that caps the execution time of each query. Moving it to the helper would either add the logger or require changing the helper's return type.

How to reproduce

N/A: internal refactor with no user-visible change. CI covers it:

  1. cd packages/api && yarn ci:unit. The new src/mcp/__tests__/clickhouseClient.test.ts covers the lookup arguments, the exact options passed to the client, the not-found error and that other lookup errors pass through.
  2. make dev-int-build && make dev-int FILE=src/mcp runs all 23 MCP integration suites (query, trace, deltas, emerging signals, describe table, sources, service health, dashboards), which exercise every migrated site.

Results locally: make ci-lint passes, 1630 unit tests pass and 636 MCP integration tests pass.

No changeset: internal refactor with no change in behavior.

@brandon-pereira
brandon-pereira requested a review from a team as a code owner November 20, 2026 22:29
@changeset-bot

changeset-bot Bot commented Nov 20, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: bfb9bb9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@vercel

vercel Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
hyperdx-oss Ready Ready Preview Nov 20, 2026 10:33pm UTC
hyperdx-storybook Ready Ready Preview Nov 20, 2026 10:33pm UTC

Request Review

@github-actions github-actions Bot added the review/tier-3 Standard — full human review required label Nov 20, 2026
@github-actions

Copy link
Copy Markdown
Contributor

🟡 Tier 3 — Standard

Introduces new logic, modifies core functionality, or touches areas with non-trivial risk.

Why this tier:

  • Diff size: 537 production lines changed (Tier 2 max: < 250)

Review process: Full human review — logic, architecture, edge cases.
SLA: First-pass feedback within 1 business day.

Stats
  • Production files changed: 23
  • Production lines changed: 537 (+ 80 in test files, excluded from tier calculation)
  • Branch: claude/mcp-clickhouse-client-helper
  • Author: brandon-pereira

To override this classification, remove the review/tier-3 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

@github-actions

Copy link
Copy Markdown
Contributor

PR Review

✅ No issues found.

@github-actions

Copy link
Copy Markdown
Contributor

Duplicate code analysis

1 new clone introduced by this PR.

  • packages/api/src/mcp/tools/query/table.ts:341-358 ↔ packages/api/src/mcp/tools/query/timeseries.ts:146-163 — 18 lines

If one of these duplicates a helper that already exists, import it instead
of redefining it. If the duplication is deliberate, ignore this comment —
the check is advisory and never fails the build.


jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 107 in total (1.12%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

@github-actions

Copy link
Copy Markdown
Contributor

Deep Review

Scope: refactor(api): build MCP ClickHouse clients through one helper — PR #3752, base d945d7ea8. 25 files, all under packages/api/src/mcp. Verified as a pure, behavior-preserving refactor that routes ~12 MCP tools through getMcpClickhouseClient(context, connectionId, options?).

✅ No critical issues found.

I traced every migrated call site and confirmed the refactor is faithful:

  • The catch (e) { if (!(e instanceof McpConnectionNotFoundError)) throw e; return <prior response> } pattern reproduces each site's original not-found handling (mcpUserError, skipped: 'connection_not_found' in denoise.ts, and logsNote/null in waterfall.ts), and re-throws every other error unchanged — matching the pre-refactor propagation of getConnectionById/ClickhouseClient throws.
  • requestTimeout: MCP_REQUEST_TIMEOUT is passed at exactly the sites that set it before (runConfigTile, describeTable, trace breakdown/waterfall, serviceHealth) and omitted at the sites that never set it, preserving query-timeout behavior.
  • context.teamId is typed string and getConnectionById(team: string, …) consumes it directly, so it is identical to the old teamId.toString() call shape.
  • waterfall.ts correctly keeps logClient defaulting to the primary clickhouseClient and only maps a distinct-connection not-found to null.

🟡 P2 — recommended

  • packages/api/src/mcp/__tests__/clickhouseClient.test.ts:76 — the new unit test exercises the helper in isolation, but the behavior this PR actually changes is the per-site McpConnectionNotFoundError→response mapping, which is asserted by no unit test (only by the broader MCP integration suites).
    • Fix: add a focused test per distinct not-found response shape (mcpUserError, skipped: 'connection_not_found', waterfall logsNote) asserting the typed error is caught and other errors propagate.
🔵 P3 nitpicks (1)
  • packages/api/src/mcp/utils/clickhouse.ts:20 — the let client; try { … } catch (e) { if (!(e instanceof McpConnectionNotFoundError)) throw e; return … } shape is now hand-duplicated at ~10 call sites, so a future site that copies it can silently drop the instanceof guard and swallow unrelated errors.
    • Fix: consider a thin wrapper that accepts a not-found fallback callback while keeping each site's distinct response, or leave as-is given the responses genuinely differ.

Reviewers (4): correctness, adversarial, kieran-typescript, testing.

Testing gaps: The per-call-site not-found→response mapping is covered only by integration suites, not unit tests; the new unit test covers the helper alone.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

@github-actions

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 471 passed • 1 skipped • 1248s

Status Count
✅ Passed 471
❌ Failed 0
⚠️ Flaky 11
⏭️ Skipped 1

Tests ran across 4 shards in parallel.

View full report →

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — bfb9bb95 Deployed Nov 20, 2026 by vercel[bot]
Preview – hyperdx-storybook — bfb9bb95 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review/tier-3 Standard — full human review required

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant