bc-telemetry-buddy-mcp 3.6.0 → 3.7.1

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.7.1] - 2026-10-23
+
+_Highest blast-radius rating across all plans landed in this release: `low-risk`._
+
+### Security
+- **Node.js runtime security floor** ([#134](https://github.com/waldo1001/waldo.BCTelemetryBuddy/issues/134)): the server now writes a one-line warning to stderr at startup when it runs on a Node.js version without the [October 2026 Node.js security fixes](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases) (CVE-2026-111497 Brotli RCE, TLS hostname bypasses). That covers Node.js < 22.23.4, < 24.22.1 or < 26.12.1, and end-of-life lines (≤ 20, 23, 25). It only warns: startup is never blocked, and stdout (the stdio protocol) is never touched. Spec: [docs/specs/134-node-runtime-security-floor.md](../../docs/specs/134-node-runtime-security-floor.md).
+- `engines.node` is now `^22.23.4 || ^24.22.1 || >=26.12.1`. npm shows an `EBADENGINE` warning when you install on an older Node.js.
+- **Telemetry**: `TB-MCP-007` (`RUNTIME_UNPATCHED`), fired once per start on an unpatched runtime with `nodeVersion` and `reason` (`eol` | `below-patched`).
+
+### Changed
+- CI and release workflows dropped Node.js 20 (end-of-life). Tests now run on 22.x and 24.x.
+
+## [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`._

package/README.md

@@ -42,7 +42,7 @@ bctb-mcp --version
 
 ### Prerequisites
 
-- **Node.js 18+** installed
+- **Node.js 22.23.4+, 24.22.1+ or 26.12.1+** installed (the server warns at startup on an older, unpatched Node.js)
 - **Application Insights** set up for Business Central telemetry
 - **Azure authentication** configured (see Authentication section below)
 
@@ -446,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)
@@ -637,7 +638,7 @@ bctb-mcp start
 ## Development
 
 ### Prerequisites
-- Node.js 18+
+- Node.js 22.23.4+, 24.22.1+ or 26.12.1+
 - npm 9+
 - Azure CLI (for `azure_cli` auth flow)
 
@@ -715,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
@@ -746,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
 
@@ -762,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