Repository navigation
refactor(api): build MCP ClickHouse clients through one helper - #3752
brandon-pereira wants to merge 1 commit into
Conversation
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🟡 Tier 3 — StandardIntroduces new logic, modifies core functionality, or touches areas with non-trivial risk. Why this tier:
Review process: Full human review — logic, architecture, edge cases. Stats
|
PR Review✅ No issues found. |
Duplicate code analysis1 new clone introduced by this PR.
If one of these duplicates a helper that already exists, import it instead jscpd compared this branch against |
Deep ReviewScope: ✅ No critical issues found. I traced every migrated call site and confirmed the refactor is faithful:
🟡 P2 — recommended
🔵 P3 nitpicks (1)
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 |
E2E Test Results✅ All tests passed • 471 passed • 1 skipped • 1248s
Tests ran across 4 shards in parallel. |
Summary
MCP tools now build their ClickHouse clients through one helper,
getMcpClickhouseClient(context, connectionId, options?)inpackages/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 aClickhouseClient. 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
McpContext, not justteamId. 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,describeMetricImplandlistMetricsImplnow takecontextas their first argument instead ofteamId.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 returnsskipped: '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.requestTimeoutis opt-in. It is passed only at the sites that usedMCP_REQUEST_TIMEOUTbefore (runConfigTile,describe_table, the trace tools, service health). Every other site gets the same options as before.getMcpClickhouseClientintrace/shared.tsis removed. The trace and service-health tools now use the new helper.Not migrated:
sources/listSources.tsstill builds its own client. It usesPreviewClickhouseClient, 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:
cd packages/api && yarn ci:unit. The newsrc/mcp/__tests__/clickhouseClient.test.tscovers the lookup arguments, the exact options passed to the client, the not-found error and that other lookup errors pass through.make dev-int-build && make dev-int FILE=src/mcpruns 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-lintpasses, 1630 unit tests pass and 636 MCP integration tests pass.No changeset: internal refactor with no change in behavior.