bc-telemetry-buddy-mcp 3.5.1 → 3.5.2

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.5.2] - 2026-06-25
+
+_Highest blast-radius rating across all plans landed in this release: `low-risk`._
+
+### Fixed
+- **Workspace `.bctb-config.json` and `.vscode/.bctb/knowledge` were ignored under non-VS-Code MCP hosts (Claude Code, Cursor CLI, raw stdio), so `get_knowledge` silently returned "Knowledge Base is not available".** The server depended on the VS Code extension setting `BCTB_WORKSPACE_PATH`; without it, `workspacePath` fell back to the launch cwd (often an unrelated sibling folder) and the Knowledge Base never loaded. The workspace is now resolved host-agnostically: env → explicit `workspacePath` → **the directory of the `--config` file** → cwd, and an unexpanded `${workspaceFolder}` token no longer silently resolves to cwd. See [docs/plans/done/mcp-workspace-knowledge-discovery.md](../../docs/plans/done/mcp-workspace-knowledge-discovery.md).
+
+### Added
+- **MCP `roots` fallback for workspace knowledge.** When the eager (config-dir-anchored) load finds no workspace knowledge and the MCP client advertises the `roots` capability, the server requests the host's workspace roots after connecting and loads knowledge from the first root containing both `.bctb-config.json` and `.vscode/.bctb/knowledge`. This decouples the connection (from your global `--config`) from the knowledge (from the project you opened). Roots discovery never changes the active connection/profile.
+- **Diagnosable Knowledge Base failures.** `get_knowledge` now reports the path it looked under and the reason (`no-workspace-config`, `no-workspace-path`, `load-failed`) instead of a bare "not available", and the server logs a `[KB]` startup line. New telemetry events `TB-MCP-003` (workspace resolution) and `TB-MCP-004` (roots discovery) carry only path-free counts/enums.
+
 ## [3.5.1] - 2026-06-02
 
 _Highest blast-radius rating across all plans landed in this release: `low-risk`._

package/README.md

@@ -235,6 +235,38 @@ If Claude Desktop shows connection errors:
 3. Test authentication: Run `az account show` to verify Azure CLI login
 4. Ensure paths use absolute paths with proper escaping
 
+### With Claude Code & other non-VS-Code hosts
+
+Outside VS Code there is no extension to inject `BCTB_WORKSPACE_PATH`, so the server discovers the workspace (and therefore its Knowledge Base, cache, and queries) host-agnostically. **The connection config and the workspace knowledge are independent**: the config you load supplies the connection, and the workspace knowledge is located separately. Resolution order for the workspace folder:
+
+1. **`BCTB_WORKSPACE_PATH`** environment variable, if set.
+2. **An explicit `workspacePath`** in the loaded config (absolute path, not `${workspaceFolder}`).
+3. **The directory of the `--config` file** — so pointing `--config` at a workspace's `.bctb-config.json` auto-anchors knowledge to that folder. *(`${workspaceFolder}` is only expanded by VS Code; outside VS Code it now resolves to this config directory instead of silently falling back to the launch cwd.)*
+4. **The host's workspace roots** — if the MCP client advertises the [`roots`](https://modelcontextprotocol.io/docs/concepts/roots) capability (Claude Code does), the server requests them after connecting and loads workspace knowledge from the first root containing both `.bctb-config.json` and `.vscode/.bctb/knowledge`. This works even when `--config` points at a global config, so your global connection keeps working while knowledge comes from the project you opened.
+
+**Recommended — point `--config` at the workspace config** (project-scoped `.mcp.json` at the workspace root):
+
+```json
+{
+  "mcpServers": {
+    "bc-telemetry-buddy-mcp": {
+      "command": "npx",
+      "args": ["-y", "bc-telemetry-buddy-mcp", "start",
+               "--config", "/abs/path/TelemetryAnalysis/.bctb-config.json"],
+      "env": {}
+    }
+  }
+}
+```
+
+**Or set `BCTB_WORKSPACE_PATH` explicitly** in the server's `env` to override discovery:
+
+```json
+"env": { "BCTB_WORKSPACE_PATH": "/abs/path/TelemetryAnalysis" }
+```
+
+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.
+
 ### With Copilot Studio
 
 Register as Custom Action: