bc-telemetry-buddy-mcp 3.5.2 → 3.7.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.7.0] - 2026-07-18
+
+_Highest blast-radius rating across all plans landed in this release: `low-risk`._
+
+### Added
+- **MCP Embedded Resources for `query_telemetry`**: New `resultFormat` (`text` | `resource`) and `fileFormat` (`json` | `csv`) parameters. When `resultFormat: "resource"`, query results are returned as an MCP embedded resource file (CSV or JSON) with a brief text summary in model context — enabling agents with code interpreters to process large datasets. Aligned with Microsoft BC MCP 2026 Wave 1 pattern. Spec: [docs/specs/131-query-telemetry-embedded-resources.md](../../docs/specs/131-query-telemetry-embedded-resources.md).
+- **Resource template** `bctb://exports/{filename}`: Clients can list and read exported files via `resources/list` and `resources/read`. Embedded and listed resources always use the `bctb://` scheme (never `file://` absolute paths).
+- **`resources` capability** added to server capabilities.
+- **`ExportService`** in shared package: CSV/JSON file exports to `.vscode/.bctb/exports/` (git-ignored) with 24h auto-cleanup keyed on `mtime`.
+- **Telemetry**: `TB-MCP-117` (`RESOURCE_EXPORTED`) event ID for tracking resource exports with format and row/column counts.
+
+### Fixed
+- **`query_telemetry` responses now contain real column names.** The App Insights v1 API returns columns as `{name, type}`, but parsing mapped the Kusto-native `columnName` field — so the `columns` array was `[null, …]` for every query. Both shapes are now accepted. (Found by the PR #108 embedded-resources smoke test: CSV exports had an empty header row.)
+
+## [3.6.0] - 2026-07-18
+
+_Highest blast-radius rating across all plans landed in this release: `low-risk`._
+
+### Added
+- **Per-workspace connections are now discoverable and selectable under Claude Code (and other roots-advertising hosts).** A workspace's own flat `.bctb-config.json` connection is discovered from `CLAUDE_PROJECT_DIR` (synchronous, checked at the opened folder and one level below — so the `…/<Customer>/TelemetryAnalysis/.bctb-config.json` layout is found) and from the MCP `roots` capability. Discovered connections appear in `list_profiles` tagged `source:"workspace"` and are selectable with `switch_profile <name>` — no global-config edit, no restart. A single globally-registered server can now query any customer workspace you open. See [docs/plans/mcp-workspace-connection-discovery.md](../../docs/plans/mcp-workspace-connection-discovery.md).
+- **Opt-in auto-activation of the local connection.** Set `BCTB_AUTO_WORKSPACE_CONNECTION=true` in the server `env` and, when exactly one workspace connection is discovered, it becomes the active connection at startup (with a loud `[MCP] AUTO-ACTIVATED …` stderr line). Default is OFF; discovery never silently retargets which App Insights resource is queried (cross-tenant safety). More than one discovered connection → no auto-pick.
+- **New telemetry** `TB-MCP-006` (`WorkspaceProfileSwitch`, emitted when a workspace connection is activated) and a `connectionsFound` count added to `TB-MCP-004` (`RootsDiscovery`) — both path-free.
+
+### Fixed
+- **Switching to a workspace connection no longer strands you.** `list_profiles`/`switch_profile` are now anchored to the pinned/global config file (`baseConfigFilePath`), so after selecting a workspace connection the global profiles remain listed and switchable. Profile-switch service re-initialization is now atomic — a mid-switch failure leaves the previous connection fully intact.
+
 ## [3.5.2] - 2026-06-25
 
 _Highest blast-radius rating across all plans landed in this release: `low-risk`._

package/README.md

@@ -267,6 +267,25 @@ Outside VS Code there is no extension to inject `BCTB_WORKSPACE_PATH`, so the se
 
 If knowledge can't be located, `get_knowledge` returns a diagnostic naming the exact path it looked under and why (e.g. `reason: no-workspace-config`) — so a missing Knowledge Base is debuggable rather than silent. The server also logs a `[KB]` line to stderr at startup.
 
+#### Per-workspace connections (`list_profiles` / `switch_profile`)
+
+The workspace folder(s) you open are also scanned for their own `.bctb-config.json` **connections**, so a single globally-registered server can query any customer without editing the global config. Discovered connections show up in `list_profiles` tagged `source:"workspace"` and are selectable with `switch_profile <name>` — no restart, no global-file edit. Two discovery signals feed this:
+
+- **`CLAUDE_PROJECT_DIR`** — Claude Code sets this to the opened project root. The server checks it and one level below it (so `…/<Customer>/TelemetryAnalysis/.bctb-config.json` is found even though the config is a subfolder of the opened root). This is synchronous, so the connection is available on the very first `list_profiles` call.
+- **MCP `roots`** — every advertised root is scanned the same way.
+
+Discovered connections are keyed by the opened folder's name (e.g. `Coeck`), because most customer configs share the same `connectionName`. When two discovered connections share a name, `switch_profile` by that name returns an "ambiguous" error listing the exact keys to use instead.
+
+**Safety — discovery never silently retargets your queries.** By default a workspace connection is only made *selectable*; the active App Insights resource changes only when *you* call `switch_profile`. To make the local connection win automatically on open, opt in with:
+
+```json
+"env": { "BCTB_AUTO_WORKSPACE_CONNECTION": "true" }
+```
+
+When set, and when **exactly one** workspace connection is discovered, the server activates it at startup and prints a loud `[MCP] AUTO-ACTIVATED …` line to stderr. Setting this flag means: *I accept that opening a workspace retargets which App Insights resource is queried.* With more than one connection discovered, it does nothing (ambiguous) and you pick with `switch_profile`.
+
+> **Auth note (`azure_cli`):** switching connection changes the App Insights *resource*, not your identity — `azure_cli` uses your current `az login` session and ignores the config's `tenantId`. If a query returns 403 after switching, run `az login --tenant <tenantId>`.
+
 ### With Copilot Studio
 
 Register as Custom Action:
@@ -427,8 +446,9 @@ The server exposes **11 tools** to language models (GitHub Copilot, Claude Deskt
 
 ### Query Execution (Step 4 of workflow)
 - **`query_telemetry`**: Execute KQL queries against Application Insights
-  - Parameters: `kql` (required KQL query string), `useContext` (boolean, default: true), `includeExternal` (boolean, default: true)
+  - Parameters: `kql` (required KQL query string), `useContext` (boolean, default: true), `includeExternal` (boolean, default: true), `resultFormat` (enum: `text` | `resource`, default: `text`), `fileFormat` (enum: `json` | `csv`, default: `csv`)
   - Returns: Query results with summary, recommendations, and chart suggestions
+  - **Embedded Resources**: Set `resultFormat: "resource"` to receive results as an MCP embedded resource file instead of inline text. The response contains a brief text summary (for lightweight model context) plus an embedded resource with the full data as CSV or JSON. This enables agents with code interpreters (e.g., Python/pandas) to process large datasets, create visualizations, and perform structured analysis. CSV is the default file format as it works natively with `pd.read_csv()`.
   - **When to use**: After discovery and understanding phases - execute the actual query with precise KQL
 
 ### Query Library (Step 3 of workflow)
@@ -696,7 +716,7 @@ The MCP server uses `@bctb/shared` for core functionality (auth, kusto, cache, q
 **`mcpSdkServer.ts`** - MCP SDK server for stdio mode (primary)
 - Uses official `@modelcontextprotocol/sdk` (protocol 2025-06-18)
 - `StdioServerTransport` for JSON-RPC 2.0 over stdin/stdout
-- Capabilities: `tools` (with `listChanged`), `logging`
+- Capabilities: `tools` (with `listChanged`), `resources`, `prompts`, `logging`
 - Automatic Zod schema conversion from JSON Schema tool definitions
 
 **`tools/toolDefinitions.ts`** - Single source of truth for all tool metadata
@@ -727,6 +747,7 @@ The MCP server uses `@bctb/shared` for core functionality (auth, kusto, cache, q
 - **`sanitize.ts`** - PII removal and data sanitization
 - **`eventLookup.ts`** - Telemetry event catalog and schema discovery
 - **`references.ts`** - External KQL example fetching
+- **`exports.ts`** - File export service for embedded MCP resources (CSV/JSON)
 
 ### Data Flow
 
@@ -743,6 +764,22 @@ The MCP server uses `@bctb/shared` for core functionality (auth, kusto, cache, q
 3. **Execution**: Same business logic methods on MCPServer class
 4. **Response**: JSON-RPC response over HTTP
 
+### Embedded Resources (MCP Resource Support)
+
+The MCP server supports **embedded resources** for `query_telemetry`, enabling agents to receive large result sets as file references instead of inline text. This is aligned with Microsoft's BC MCP 2026 Wave 1 pattern.
+
+**How it works:**
+1. Agent calls `query_telemetry` with `resultFormat: "resource"` (and optionally `fileFormat: "csv"` or `"json"`)
+2. Server executes the query, writes results to a file in `{workspace}/.vscode/.bctb/exports/`
+3. Response contains a brief text summary + an MCP embedded resource (`{type: "resource", resource: {uri, mimeType, text}}`)
+4. Agent passes the file reference to a code interpreter for analysis, charts, etc.
+
+**Resource template:** `bctb://exports/{filename}` — clients can list and read exported files via `resources/list` and `resources/read`.
+
+**File cleanup:** Export files older than 24 hours are automatically cleaned up on server startup and after each new export.
+
+**Backward compatible:** Without `resultFormat` (or with `resultFormat: "text"`), behavior is unchanged — results are returned as inline JSON text.
+
 ## Publishing
 
 ### Publish to NPM