@muggleai/telemetry

Shared client-side telemetry for Muggle Test. Used by:

• MCP (muggle-ai-works/packages/mcps)
• Electron app (muggle-ai-teaching-service/packages/electron-app)
• Skills (muggle-ai-works skill bundle) — calls into MCP, which calls this package

Sends customEvents to Azure Application Insights with consistent identity (installId, userId, release, buildId, commitSha) and a source: 'client' tag so dashboards can separate client-emitted events from server-auto-collected request spans.

Usage

import { initTelemetry, track } from "@muggleai/telemetry";

initTelemetry({ serviceName: "muggle-mcp", surface: "mcp-local" });

track({
  name: "mcp.tool.invoked",
  props: {
    toolName: "muggle-local-execute-replay",
    toolSurface: "local",
    correlationId: "abc-123",
  },
});

Connection string

Read in this order:

1. Explicit initTelemetry({ connectionString }) argument
2. APPLICATIONINSIGHTS_CONNECTION_STRING env var
3. VITE_APPLICATIONINSIGHTS_CONNECTION_STRING env var (Electron-style)

When none is set, initTelemetry() becomes a no-op — track() calls are silently dropped. This keeps the package safe to import in dev environments.

Opt-out

import { isTelemetryEnabled, setTelemetryEnabled } from "@muggleai/telemetry";

if (!isTelemetryEnabled()) { /* nothing will be sent */ }
setTelemetryEnabled(false); // persists to ~/.muggle-ai/preferences.json

Or set the env var MUGGLE_TELEMETRY_DISABLED=1.

Disclosure

import { getDisclosureCopy, hasShownDisclosure, markDisclosureShown } from "@muggleai/telemetry";

if (!hasShownDisclosure()) {
  console.log(getDisclosureCopy());
  markDisclosureShown();
}

Privacy

See PRIVACY.md for the complete list of fields collected.

Design

See muggle-ai-brain/architecture/2026-05-05-mcp-skill-telemetry-design.md (private repo).

Development

npm install
npm test          # vitest
npm run typecheck
npm run build     # tsc → dist/

Releasing

CI/CD only — never npm publish from a local machine. The npm registry is configured to trust only this repo's publish.yml GitHub Actions workflow (OIDC trusted publishing). A local publish bypasses the build verification, has no provenance, and may need to be manually unpublished.

To cut a release:

1. Bump version in package.json (e.g. 0.3.1 → 0.3.2).
2. Commit on main.
3. Tag and push:

   git tag v0.3.2
   git push origin main v0.3.2

4. The tag push triggers .github/workflows/publish.yml. It:
   • runs npm ci, npm run typecheck, npm test, npm run build
   • publishes to https://registry.npmjs.org via OIDC (no NPM_TOKEN secret)

Why no --provenance?

npm rejects provenance from private source repos (422 Unprocessable Entity ... Unsupported GitHub Actions source repository visibility: "private"). This repo stays private, so publish.yml deliberately omits the flag. End consumers can't cryptographically verify the build chain — they install with the same trust they'd give any private-source npm package.

If publish fails

• ENEEDAUTH: the Trusted Publisher config on npmjs.com no longer matches the workflow filename, name, or environment. Reconcile and re-tag.
• E422 provenance error: someone re-added --provenance to the publish step. Drop it.
• E403 over-existing-version: you tried to republish an already-published version. Bump the patch and re-tag.