kusto-mcp: Instructions file for Claude Code

kusto-mcp

Telemetry (product code)

• Telemetry is always on. Never add an opt-out, enable flag, or env kill-switch — not even "for local dev". Only salted hashes and bounded enums may ship — except execute-query's optional purpose, sent as written when off-list; README's "What is NEVER collected" is the contract.
• Never export error messages or stacks — they echo query text and identifiers. Error class name only, plus an errno code where present (see recordSpanError).
• Crash-path telemetry must never throw. A second failure inside a crash handler is what turned #180/#196 into a 100% CPU spin.
• Never delete autoDetectResources: false (src/common/telemetry.ts:117). NodeSDK's default detectors add host.id, host.name and process.owner as resource attributes — under every span, and invisible to a span-attribute review.
• Every local run ships real spans to the production Honeycomb dataset. src/index.ts starts telemetry unconditionally and npm run test:e2e spawns the built server and mocks nothing. machine.id persists to disk, so the machine joins the fleet permanently. Export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:9999 before running the server or e2e locally.
• azure-kusto-data 7.2 rethrows DNS/refused failures from its cloud-metadata lookup as a plain Error with no code, so kustomcp.connection.failure_category is unknown for them. The user-facing hint re-probes the host (probeReachability); telemetry does not.
• Before analysing the Honeycomb kusto-mcp environment, read docs/telemetry-semantics.md if you have it — it holds the counting conventions and query gotchas. It is maintainer-local and deliberately untracked, so it is absent from a fresh clone and from CI; without it, derive conventions from the code rather than assuming span volume means anything.

Tests and CI

• CI runs the unit project only; tests/e2e never runs there (it needs az login and a live cluster). Any regression guard that must hold goes in tests/unit.
• CI order is lint → typecheck → test → build, so dist/ does not exist while unit tests run.
• npm run typecheck (tsc -p tsconfig.test.json) typechecks src/ and all of tests/, e2e included, and CI runs it before the unit tests. It is the only type gate on tests: ts-jest does not fail a run on type errors. Nothing lints tests/ — every lint script is eslint src.
• npm run format is scoped to src/**/*.ts. Never prettier --write README.md or docs/*.md — it reflows unrelated lines into the diff.
• CI is ubuntu-latest only, but Windows is ~75% of the fleet. A platform-specific fix gets no Closes # until a windows-latest A/B (baseline vs patched) has actually run.
• Check CI with gh pr view --json statusCheckRollup, not by parsing gh pr checks — it renders cancelled jobs as fail.