@pbhamri/quartermaster-mcp 0.8.0 → 0.9.0

package/README.md

@@ -211,9 +211,22 @@ resources/
 | `QM_REPO_ROOT` | `process.cwd()` | Override repo root for read-only access |
 | `QM_CONNECT_DB` | `~/.quartermaster/connect-db.json` | Connect tracker path for `qm_personalize` |
 | `QM_METRICS_FILE` | `~/.copilot/metrics/paved-path-events.jsonl` | Telemetry output path |
-| `QM_METRICS_OPT_OUT` | (unset) | Set to `1` to disable telemetry |
+| `QM_METRICS_OPT_OUT` | (unset) | Set to `1` to disable **all** telemetry (local file + beacon) |
+| `QM_BEACON_URL` | (from package) | Override the usage-beacon endpoint |
+| `QM_BEACON_OPT_OUT` | (unset) | Set to `1` to disable only the usage beacon |
 | `QM_SELF_AGENT_DIR` | `~/.copilot/self-agent` | Self-agent skeleton directory |
 
+### Telemetry & privacy
+
+This package emits **one anonymized usage ping per machine per UTC day** so the
+maintainer can count distinct PMs using it. The ping contains only a SHA-256
+**machine hash** (`platform:arch:cpus:ram`) plus version, OS, and date —
+**never** usernames, hostnames, IPs, file paths, repo names, or content.
+
+Opt out any time with `QM_BEACON_OPT_OUT=1` (beacon only) or
+`QM_METRICS_OPT_OUT=1` (everything). The beacon server is open-source in
+[`beacon/`](beacon/README.md).
+
 ---
 
 ## Why MCP, not a script

package/bin/server.js

@@ -62,6 +62,60 @@ async function timed(type, baseData, fn) {
   }
 }
 
+// ---- First-run-of-day usage beacon (privacy-preserving, opt-out) ----
+// Sends ONE anonymized ping per machine per UTC day so the maintainer can
+// count DISTINCT PMs who ran `npx @pbhamri/quartermaster-mcp`. Payload is
+// machine hash (already non-PII: SHA-256 of platform:arch:cpus:ram) + version
+// + OS + date. NO usernames, hostnames, paths, repo names, or content.
+// Disable entirely with QM_BEACON_OPT_OUT=1 or QM_METRICS_OPT_OUT=1.
+const BEACON_URL = process.env.QM_BEACON_URL || PKG.beaconUrl || "";
+const BEACON_STATE_FILE = process.env.QM_BEACON_STATE
+  || path.join(os.homedir(), ".quartermaster", "beacon-state.json");
+
+function beaconOptedOut() {
+  return process.env.QM_BEACON_OPT_OUT === "1" || process.env.QM_METRICS_OPT_OUT === "1";
+}
+
+function alreadyBeaconedToday(today) {
+  try {
+    const s = JSON.parse(fs.readFileSync(BEACON_STATE_FILE, "utf8"));
+    return s.last_beacon_date === today;
+  } catch { return false; }
+}
+
+function markBeaconed(today) {
+  try {
+    fs.mkdirSync(path.dirname(BEACON_STATE_FILE), { recursive: true });
+    fs.writeFileSync(BEACON_STATE_FILE, JSON.stringify({ last_beacon_date: today, version: PKG.version }), "utf8");
+  } catch { /* non-fatal */ }
+}
+
+// Fire-and-forget. Never throws, never blocks server startup.
+function sendBeacon() {
+  try {
+    if (beaconOptedOut() || !BEACON_URL) return;
+    if (typeof fetch !== "function") return; // Node < 18: skip silently
+    const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD (UTC)
+    if (alreadyBeaconedToday(today)) return;
+    markBeaconed(today); // mark first so a slow/failed POST never double-sends
+    const payload = {
+      machine: machineId(),
+      version: PKG.version,
+      os: os.platform(),
+      arch: os.arch(),
+      date: today,
+    };
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 1500);
+    fetch(BEACON_URL, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: ctrl.signal,
+    }).catch(() => {}).finally(() => clearTimeout(timer));
+  } catch { /* beacon must never break the server */ }
+}
+
 const readJson = (p) => JSON.parse(fs.readFileSync(p, "utf8"));
 const writeText = (p, t) => { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, t, "utf8"); };
 const exists = (p) => fs.existsSync(p);
@@ -1089,4 +1143,5 @@ server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
 
 await server.connect(new StdioServerTransport());
 process.stderr.write(`quartermaster-mcp v${PKG.version} ready (stdio)\n`);
+sendBeacon(); // once/day anonymized usage ping; opt out via QM_BEACON_OPT_OUT=1
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@pbhamri/quartermaster-mcp",
-  "version": "0.8.0",
+  "version": "0.9.0",
+  "beaconUrl": "",
   "description": "MCP server that seeds any repo with a customizable PM kit. Any PM, any product — connect YOUR GitHub, ADO, Kusto, IcM. 19 tools: scaffolding, repo-read, onboarding, custom profile creation, self-agent auto-reply. Never ships personal data — profiles are templates you fill in.",
   "type": "module",
   "bin": {