Skip to content

Commit d134212

Browse files
feat(mcp): add hyperdx_describe_source tool and slim list_sources to catalog (#2309)
## Problem The #1 MCP error class (39% of clickstack failures, 9 of 23 errors) is **unknown column or identifier** — the LLM invents column names like `TimestampTime`, `service.name`, `count`, `Timestamp`, `rows_read`, `memory_usage` that don't exist in the ClickHouse schema. Root causes: 1. `hyperdx_list_sources` returned full column schemas for ALL sources in one response (50KB+), which overwhelms LLM context 2. No way to discover actual column **values** — the LLM guesses `SeverityText:error` when the real data uses `ERROR` or `Error` 3. Prompt guidance says "don't assume values" but provides no tool to discover them ## Solution ### New tool: `hyperdx_describe_source` Per-source schema discovery that returns: - **Column schema** (name, ClickHouse type, JS type) from `DESCRIBE TABLE` - **Map attribute keys** (e.g. SpanAttributes, ResourceAttributes) — max 50 per map column - **Low-cardinality value samples** for `LowCardinality(String)` columns like SeverityText, StatusCode, ServiceName — uses existing `getAllKeyValues()` rollup tables for performance - **Map attribute value samples** for top-10 keys per map column — also via rollup tables - **10-second hard timeout** with structured AbortError handling - Team-scoped access via `getSource(teamId, sourceId)` ### Slimmed `hyperdx_list_sources` Now a lightweight MongoDB-only catalog: - Returns: id, name, kind, connectionId, timestampColumn, keyColumns - No ClickHouse queries — instant response - Includes `nextStep` hint pointing to `describe_source` ### Two-step workflow ``` hyperdx_list_sources → pick sourceId(s) hyperdx_describe_source → get columns, attribute keys, sample values hyperdx_timeseries / table / search / ... → query with real column names ``` ## Changes | File | Change | |------|--------| | `tools/sources/describeSource.ts` | **NEW** — `hyperdx_describe_source` tool | | `tools/sources/index.ts` | **NEW** — registers both source tools | | `tools/sources/listSources.ts` | **MOVED** from dashboards/, slimmed to catalog | | `tools/dashboards/listSources.ts` | **DELETED** — moved to sources/ | | `tools/dashboards/index.ts` | Removed source tool registrations | | `mcpServer.ts` | Registers new `sourcesTools` module | | `tools/query/{search,table,timeseries,sql,eventPatterns}.ts` | Tool descriptions reference `describe_source` | | `prompts/dashboards/content.ts` | Workflow, SeverityText guidance, common mistakes updated | | `__tests__/sources.test.ts` | **NEW** — 11 tests (catalog, schema, LC values, metrics, cross-team) | | `__tests__/dashboards.test.ts` | Removed source tests (moved to sources.test.ts) | | `MCP.md` | Documents two-step workflow and new tool | **No changes to `common-utils`** — reuses existing `getAllKeyValues()` and `getMapValues()` methods. ## Changeset Patch release — this is a new tool addition and behavioral change to `list_sources`, but the MCP server is still in beta (`version: ${CODE_VERSION}-beta`), so a patch bump is appropriate. ## Testing Ensure agents call the new tool locally, and it queries the correct SeverityText (not hallucinate) <img width="1344" height="473" alt="Screenshot 2026-05-19 at 1 28 39 PM" src="https://github.com/user-attachments/assets/cb95f8d3-6f3e-4b8c-9675-12a396432655" /> - `make ci-lint` — passes (0 errors) - `make ci-unit` — 957 tests pass across 19 suites
1 parent 19cd7c9 commit d134212

16 files changed

Lines changed: 910 additions & 267 deletions

File tree

‎.changeset/describe-source-tool.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
'@hyperdx/api': patch
3+
---
4+
5+
feat(mcp): add hyperdx_describe_source tool and slim list_sources to catalog
6+
7+
Add `hyperdx_describe_source` — returns full column schema, map attribute
8+
keys, and sampled low-cardinality values (SeverityText, StatusCode,
9+
ServiceName, etc.) for a single source. Uses existing rollup tables for
10+
performant value sampling.
11+
12+
Slim `hyperdx_list_sources` to a lightweight MongoDB-only catalog (no
13+
ClickHouse queries). Source tools moved to a dedicated `tools/sources/`
14+
module.
15+
16+
All query tool descriptions and prompts updated to reference the two-step
17+
`list_sources → describe_source` discovery workflow.

‎MCP.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,8 @@ with:
108108

109109
| Tool | Description |
110110
| ----------------------------- | -------------------------------------------------------------------------------------------- |
111-
| `hyperdx_list_sources` | List all data sources and database connections, including column schemas and attribute keys |
111+
| `hyperdx_list_sources` | List all data sources and connections as a lightweight catalog (IDs, names, kinds) |
112+
| `hyperdx_describe_source` | Full column schema, attribute keys, and sampled low-cardinality values for a single source |
112113
| `hyperdx_timeseries` | Plot metrics over time as a line or stacked bar chart |
113114
| `hyperdx_table` | Compute aggregated metrics as a table, single number, or pie chart |
114115
| `hyperdx_search` | Browse individual log, event, or trace rows |

‎packages/api/src/mcp/__tests__/dashboards.test.ts‎

Lines changed: 0 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -76,65 +76,6 @@ describe('MCP Dashboard Tools', () => {
7676
await server.stop();
7777
});
7878

79-
describe('hyperdx_list_sources', () => {
80-
it('should list available sources and connections', async () => {
81-
const result = await callTool(client, 'hyperdx_list_sources');
82-
83-
expect(result.isError).toBeFalsy();
84-
expect(result.content).toHaveLength(1);
85-
86-
const output = JSON.parse(getFirstText(result));
87-
expect(output.sources).toHaveLength(1);
88-
expect(output.sources[0]).toMatchObject({
89-
id: traceSource._id.toString(),
90-
name: 'Traces',
91-
kind: SourceKind.Trace,
92-
});
93-
94-
expect(output.connections).toHaveLength(1);
95-
expect(output.connections[0]).toMatchObject({
96-
id: connection._id.toString(),
97-
name: 'Default',
98-
});
99-
100-
expect(output.usage).toBeDefined();
101-
});
102-
103-
it('should include column schema for sources', async () => {
104-
const result = await callTool(client, 'hyperdx_list_sources');
105-
const output = JSON.parse(getFirstText(result));
106-
const source = output.sources[0];
107-
108-
expect(source.columns).toBeDefined();
109-
expect(Array.isArray(source.columns)).toBe(true);
110-
expect(source.columns.length).toBeGreaterThan(0);
111-
// Each column should have name, type, and jsType
112-
expect(source.columns[0]).toHaveProperty('name');
113-
expect(source.columns[0]).toHaveProperty('type');
114-
expect(source.columns[0]).toHaveProperty('jsType');
115-
});
116-
117-
it('should return empty sources for a team with no sources', async () => {
118-
// Clear everything and re-register with new team
119-
await client.close();
120-
await server.clearDBs();
121-
const result2 = await getLoggedInAgent(server);
122-
const context2: McpContext = {
123-
teamId: result2.team._id.toString(),
124-
userId: result2.user._id.toString(),
125-
};
126-
const client2 = await createTestClient(context2);
127-
128-
const result = await callTool(client2, 'hyperdx_list_sources');
129-
const output = JSON.parse(getFirstText(result));
130-
131-
expect(output.sources).toHaveLength(0);
132-
expect(output.connections).toHaveLength(0);
133-
134-
await client2.close();
135-
});
136-
});
137-
13879
describe('hyperdx_get_dashboard', () => {
13980
it('should list all dashboards when no id provided', async () => {
14081
await new Dashboard({

0 commit comments

Comments
 (0)