feat(analytics): attach opaque server-url hash to every event

[ar2rsawseen]

Why

We want to answer "how many distinct Countly servers use the MCP" (and the same question sliced per tool, per transport, per auth method, etc.), while respecting the privacy commitment the README makes. Raw URLs and domains should never leave the process.

What this PR does

Adds a short opaque server segment to every analytics event — a 16-hex-char SHA-256 prefix of the normalized Countly server URL. That gives Countly the aggregation signal without ever transmitting an identifiable URL.

Design

• Field name: server
• Hash length: 16 hex chars (64 bits) — enough entropy to distinguish billions of servers with negligible collision impact on distinct-count aggregation; keeps per-event payload small.
• Device ID: stays "mcp" (explicit choice — the hash lives in event segmentation, not device identity). This was discussed and agreed: keep the device-level anonymity and derive distinct-server counts from the server segment breakdown.
• Normalization: scheme stripped, lowercased, trailing slashes trimmed. So https://Example.com/, http://example.com, and HTTPS://EXAMPLE.com all hash identically.
• Per-request resolution: analytics.init() accepts a getServerUrl() callback invoked lazily at event-track time. In HTTP transport the callback reads the request-scoped URL from AsyncLocalStorage (same mechanism used for per-tenant auth isolation); in stdio mode it reads the static env-derived config. Multi-tenant deployments naturally emit per-tenant counts.

Code changes

• src/lib/analytics.ts:
  • New exported normalizeServerUrlForHash() and computeServerHash()
  • Analytics.init(enabled, getServerUrl?) — second arg is the new lazy resolver
  • New private withServerSegment() merges the hash onto the segmentation of every trackEvent/trackTimedEvent call
  • All specialized helpers (trackToolExecution, trackToolCategory, trackAuthMethod, trackApiEndpoint, trackHttpRequest, trackError) delegate to those two, so the segment flows through automatically
• src/index.ts:
  • Wires the resolver: () => requestContext.getStore()?.serverUrl || this.config?.serverUrl
  • Defensive against this.config being undefined at analytics.init() time (it's populated later in the constructor, resolver is called lazily)
• README.md: Analytics Tracking section updated — explicitly lists the server hash as tracked (and explains why it's coarse, so no one reads a secrecy guarantee into it), and explicitly calls out raw URLs / domains as NOT tracked
• CHANGELOG.md: new "Changed" entry under [1.3.0] (nothing published under 1.3.0 yet so no new version bump needed)

Privacy characterization (for the README)

The hash is coarse (64 bits) and server URLs are low-entropy — cloud patterns (*.count.ly) are dictionary-bruteforceable by anyone, Countly most of all. This is intended for aggregation, not secrecy. What it does buy:

• No plaintext URL/domain in transit
• No plaintext URL/domain in stored analytics data (so a breach of stats.count.ly doesn't leak every customer's on-prem URL)
• Stable per-deployment aggregation without requiring file persistence or a random install ID

For strict privacy (e.g. on-prem URLs operators don't want even Countly to see), the server remains opt-out: analytics are disabled by default, ENABLE_ANALYTICS=true is required.

Tests

+17 tests in tests/analytics.test.ts:

• normalizeServerUrlForHash: scheme / case / trailing-slash equivalence, empty input
• computeServerHash: same inputs → same hash, different inputs → different hash, 16-hex format, undefined/empty → undefined
• Segment injection: trackEvent, trackTimedEvent, all specialized helpers propagate server segment
• Resolver semantics: omitted when no resolver, omitted when resolver returns undefined, re-evaluated per event (HTTP multi-tenant)
• device_id assertion: stays "mcp", hash is on events not device identity

Total: 356 tests passing (339 existing + 17 new). Lint clean.

Test plan

• With ENABLE_ANALYTICS=true and a real Countly server URL, run a couple of tools via stdio; confirm events arrive at stats.count.ly with a server segment matching the expected SHA-256 prefix
• With HTTP transport and two clients using different X-Countly-Server-Url headers, confirm the server segments differ (per-tenant) within the same process
• Confirm the README's accuracy about what's tracked before merging

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an opaque, truncated SHA-256–based server hash segment to analytics events so telemetry can be aggregated by distinct Countly server without transmitting raw URLs/domains.

Changes:

• Introduces URL normalization + 16-hex server hash computation and injects the server segment into all analytics event tracking.
• Wires a lazy per-event server URL resolver (AsyncLocalStorage-aware for HTTP, config fallback for stdio).
• Updates docs (README, CHANGELOG) and adds test coverage for hashing + segment injection behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/lib/analytics.ts	Adds server URL normalization/hash utilities and injects the server segment into event segmentation.
src/index.ts	Passes a per-event resolver for serverUrl (request-scoped when available).
tests/analytics.test.ts	Adds unit tests for normalization, hashing, resolver semantics, and segment propagation.
README.md	Documents the new server hash telemetry and clarifies what is/isn’t tracked.
CHANGELOG.md	Notes the telemetry change under 1.3.0.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.