feat(mcp): include source section in list/describe source tools

[alex-fedotyev]

The data source section label (added in #2432, surfaced in the selector in #2476) is read wherever a user looks at sources, but the MCP source tools never returned it. This adds it to clickstack_list_sources and clickstack_describe_source so an agent sees the same grouping a user does.

HDX-4584.

Summary

• clickstack_list_sources: each source entry now includes section when the source has one.
• clickstack_describe_source: the returned source metadata now includes section when set.
• The key is omitted when a source has no section, matching the read-only GET /api/v2/sources behavior shipped in feat(sources): add an optional Section field to data sources #2432.

Why

section lives on the shared source schema, so the tools surface a field they already receive: no controller or schema change. Adding it conditionally (only when present) mirrors the existing optional fields in the same meta builder (eventAttributesColumn, resourceAttributesColumn).

Test plan

• npx nx run @hyperdx/api:ci:lint (eslint + tsc) clean
• Integration: @hyperdx/api:dev:int mcp/__tests__/sources.test green (13/13), including new cases asserting section is returned when set and omitted when unset for both tools
• No external API / OpenAPI change (read-only GET parity already shipped in feat(sources): add an optional Section field to data sources #2432); openapi.json regenerates with no diff

[ui-check: allow] MCP tool output only, no UI.
[viewport: allow] Not applicable.
[ui-states: allow] Not applicable.

[changeset-bot]

🦋 Changeset detected

Latest commit: a8ddf85

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/api	Patch
@hyperdx/app	Patch
@hyperdx/otel-collector	Patch

Not sure what this means? Click here to learn what changesets are.

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Jun 17, 2026 10:53pm
hyperdx-storybook	Ready	Preview, Comment	Jun 17, 2026 10:53pm

[github-actions]

🔵 Tier 2 — Low Risk

Small, isolated change with no API route or data model modifications.

Why this tier:

• Standard feature/fix — introduces new logic or modifies core functionality

Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns.
SLA: Resolve within 4 business hours.

Stats

• Production files changed: 2
• Production lines changed: 8 (+ 32 in test files, excluded from tier calculation)
• Branch: alex/HDX-4584-mcp-source-section
• Author: alex-fedotyev

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

[greptile-apps]

Greptile Summary

This PR exposes the section field on MCP source tool responses so that AI agents see the same source grouping labels that the UI source selector shows, without any schema or controller changes.

• clickstack_list_sources and clickstack_describe_source: Both now include section in each source's metadata when the field is set, omitting the key entirely when it is absent — consistent with the existing conditional pattern for eventAttributesColumn and resourceAttributesColumn.
• Tests: Two new integration test cases (one per tool) verify that section is returned for the log fixture (which has section: 'Billing') and is undefined for the trace fixture (which has none).

Confidence Score: 5/5

Additive read-only change with no controller or schema modification; safe to merge.

The change is a two-line addition in each tool — a conditional write to an existing Record<string, unknown> meta object — mirroring the already-tested pattern used for eventAttributesColumn and resourceAttributesColumn. Integration tests cover both the positive (section present) and negative (section absent) cases for both tools, and no existing test assertions are invalidated. There is no risk of data mutation or cross-team leakage.

No files require special attention.

Important Files Changed

Filename	Overview
packages/api/src/mcp/tools/sources/listSources.ts	Adds conditional section field to each source's meta object, matching the existing pattern for optional fields like eventAttributesColumn.
packages/api/src/mcp/tools/sources/describeSource.ts	Adds conditional section field to the meta object in describeSourceSchema, placed correctly before the other optional attribute fields.
packages/api/src/mcp/tests/sources.test.ts	Adds section: 'Billing' to the log source fixture and two new tests — one per tool — asserting section is returned when set and omitted when unset.
.changeset/mcp-source-section.md	Patch-level changeset entry accurately describing the added section field in both MCP source tools.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Agent
    participant MCP as MCP Server
    participant DB as MongoDB (Source)

    Agent->>MCP: clickstack_list_sources
    MCP->>DB: getSources(teamId)
    DB-->>MCP: "[logSource{section:"Billing"}, traceSource{}]"
    MCP-->>Agent: "[{id, name, kind, section:"Billing", ...}, {id, name, kind, ...}]"

    Agent->>MCP: "clickstack_describe_source(sourceId=logSource)"
    MCP->>DB: getSource(teamId, sourceId)
    DB-->>MCP: "logSource{section:"Billing"}"
    MCP-->>Agent: "{source:{id, name, kind, section:"Billing", columns:[...]}, ...}"

    Agent->>MCP: "clickstack_describe_source(sourceId=traceSource)"
    MCP->>DB: getSource(teamId, sourceId)
    DB-->>MCP: "traceSource{section:undefined}"
    MCP-->>Agent: "{source:{id, name, kind, columns:[...]}, ...}"

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Agent
    participant MCP as MCP Server
    participant DB as MongoDB (Source)

    Agent->>MCP: clickstack_list_sources
    MCP->>DB: getSources(teamId)
    DB-->>MCP: "[logSource{section:"Billing"}, traceSource{}]"
    MCP-->>Agent: "[{id, name, kind, section:"Billing", ...}, {id, name, kind, ...}]"

    Agent->>MCP: "clickstack_describe_source(sourceId=logSource)"
    MCP->>DB: getSource(teamId, sourceId)
    DB-->>MCP: "logSource{section:"Billing"}"
    MCP-->>Agent: "{source:{id, name, kind, section:"Billing", columns:[...]}, ...}"

    Agent->>MCP: "clickstack_describe_source(sourceId=traceSource)"
    MCP->>DB: getSource(teamId, sourceId)
    DB-->>MCP: "traceSource{section:undefined}"
    MCP-->>Agent: "{source:{id, name, kind, columns:[...]}, ...}"

Loading

_{Reviews (1): Last reviewed commit: "feat(mcp): include source section in lis..." | Re-trigger Greptile}

[github-actions]

E2E Test Results

✅ All tests passed • 200 passed • 3 skipped • 1316s

Status	Count
✅ Passed	200
❌ Failed	0
⚠️ Flaky	4
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →