Repository navigation
Commit d134212
authored
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 suites1 parent 19cd7c9 commit d134212
16 files changed
Lines changed: 910 additions & 267 deletions
File tree
- .changeset
- packages/api/src/mcp
- __tests__
- prompts/dashboards
- tools
- dashboards
- query
- sources
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
108 | 108 | | |
109 | 109 | | |
110 | 110 | | |
111 | | - | |
| 111 | + | |
| 112 | + | |
112 | 113 | | |
113 | 114 | | |
114 | 115 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
76 | 76 | | |
77 | 77 | | |
78 | 78 | | |
79 | | - | |
80 | | - | |
81 | | - | |
82 | | - | |
83 | | - | |
84 | | - | |
85 | | - | |
86 | | - | |
87 | | - | |
88 | | - | |
89 | | - | |
90 | | - | |
91 | | - | |
92 | | - | |
93 | | - | |
94 | | - | |
95 | | - | |
96 | | - | |
97 | | - | |
98 | | - | |
99 | | - | |
100 | | - | |
101 | | - | |
102 | | - | |
103 | | - | |
104 | | - | |
105 | | - | |
106 | | - | |
107 | | - | |
108 | | - | |
109 | | - | |
110 | | - | |
111 | | - | |
112 | | - | |
113 | | - | |
114 | | - | |
115 | | - | |
116 | | - | |
117 | | - | |
118 | | - | |
119 | | - | |
120 | | - | |
121 | | - | |
122 | | - | |
123 | | - | |
124 | | - | |
125 | | - | |
126 | | - | |
127 | | - | |
128 | | - | |
129 | | - | |
130 | | - | |
131 | | - | |
132 | | - | |
133 | | - | |
134 | | - | |
135 | | - | |
136 | | - | |
137 | | - | |
138 | 79 | | |
139 | 80 | | |
140 | 81 | | |
| |||
0 commit comments