@luanpdd/kit-mcp 1.17.0 → 1.18.0

package/kit/file-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.17.0",
-  "timestamp": "2026-05-09T15:58:57.716Z",
+  "version": "1.18.0",
+  "timestamp": "2026-05-09T17:01:35.745Z",
   "files": {
     "COMANDOS.md": "d24ec61a6ec35db314cc5f2ae287bfb927b794789c8f1d558c55862f5e6534b2",
     "COMPATIBILITY.md": "794e336a87045cdf0161785b9a7a0975a49abbd80bdd816b8852251fcc8126ca",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Generic infrastructure to ship YOUR personal kit of agents/commands/skills as an MCP server, with cross-IDE sync (Claude Code, Cursor, Codex, Gemini, Windsurf, Antigravity, Copilot, Trae).",
   "type": "module",
   "bin": {

package/src/core/metrics.js

@@ -0,0 +1,143 @@
+// OBS-18-01 / OBS-18-02 — in-memory golden signals for kit-mcp server.
+//
+// Phase 94: Eat Your Own Dog Food. The skill `four-golden-signals` says any
+// user-facing service worth its salt instruments Latency + Traffic + Errors
+// + Saturation. The MCP server qualifies — every tool call is a request from
+// an LLM client and tail latency / error rate are exactly the signals an
+// operator wants when something feels off.
+//
+// Scope decisions (see .planning/phases/94-golden-signals-mcp-server/94-CONTEXT.md):
+//   - Zero dependencies. Map + array stdlib only — preserves the 6-deps budget
+//     that Phase 92.01 fought to maintain and that Phase 93.01 enforces in CI.
+//   - In-memory only. No file persistence, no socket export, no OTel SDK.
+//     kit-mcp is a developer tool launched on demand by an IDE; cross-process
+//     telemetry pipelines are explicit non-goals (see <deferred> block in
+//     94-CONTEXT.md). A future phase can layer OTel on top of this API.
+//   - Bounded memory. Histograms cap at HISTOGRAM_CAP=1000 samples per tool
+//     with FIFO drop. At cap, p50/p95/p99 over the latest 1000 samples is
+//     more useful than an unbounded array that could grow for the lifetime
+//     of a long-lived MCP session.
+//   - Snapshot is read-only. Returns a fresh plain-object copy so callers
+//     can JSON.stringify it without exposing internal Map references.
+//
+// API surface (4 exports):
+//   incrementInvocation(tool, status)  — counter++ keyed `${tool}:${status}`
+//   recordLatency(tool, ms)            — push to histogram, FIFO at cap
+//   snapshot()                         — { counters, latency } plain object
+//   reset()                            — clear both maps; called on boot if
+//                                         KIT_MCP_METRICS_RESET=1
+//
+// Boot-time reset honors the env var by calling reset() at module load when
+// the flag is set. This keeps the signal "fresh" for a probe in tests or for
+// an operator who spawned the server with the flag for a clean comparison.
+
+const HISTOGRAM_CAP = 1000;
+
+const counters = new Map();   // key: `${tool}:${status}` → count (number)
+const histograms = new Map(); // key: tool → number[] (length ≤ HISTOGRAM_CAP)
+
+/**
+ * Increment the invocation counter for a tool/status pair.
+ *
+ * @param {string} tool   Tool name as it appears in the MCP request payload.
+ * @param {'ok'|'error'} [status='ok']  Outcome of the dispatch.
+ * @returns {void}
+ */
+export function incrementInvocation(tool, status = 'ok') {
+  if (typeof tool !== 'string' || tool.length === 0) return;
+  const key = `${tool}:${status}`;
+  counters.set(key, (counters.get(key) ?? 0) + 1);
+}
+
+/**
+ * Record an observed latency for a tool. Drops the oldest sample (FIFO) once
+ * the per-tool histogram reaches HISTOGRAM_CAP, keeping memory bounded across
+ * long-lived MCP sessions.
+ *
+ * @param {string} tool   Tool name.
+ * @param {number} ms     Elapsed wall-clock time in milliseconds.
+ * @returns {void}
+ */
+export function recordLatency(tool, ms) {
+  if (typeof tool !== 'string' || tool.length === 0) return;
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) return;
+  let arr = histograms.get(tool);
+  if (!arr) {
+    arr = [];
+    histograms.set(tool, arr);
+  }
+  arr.push(ms);
+  if (arr.length > HISTOGRAM_CAP) arr.shift(); // FIFO drop oldest sample
+}
+
+/**
+ * Compute a percentile over a sorted ascending array. Linear-interpolation
+ * variant matches the typical Prometheus / Datadog reading. For N≤1000
+ * (HISTOGRAM_CAP) the sort cost on snapshot is acceptable — snapshots are
+ * read on-demand by the metrics-snapshot tool, not on every dispatch.
+ *
+ * @param {number[]} sorted  Ascending-sorted samples.
+ * @param {number} p         Percentile in [0, 1].
+ * @returns {number}
+ */
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0];
+  const rank = p * (sorted.length - 1);
+  const lo = Math.floor(rank);
+  const hi = Math.ceil(rank);
+  if (lo === hi) return sorted[lo];
+  const frac = rank - lo;
+  return sorted[lo] + (sorted[hi] - sorted[lo]) * frac;
+}
+
+/**
+ * Build a read-only snapshot of all metrics. Counters are returned as a plain
+ * object keyed `${tool}:${status}` → count. Latency is keyed by tool to a
+ * `{ p50, p95, p99, count }` triple so a single tool never appears split
+ * across status outcomes (latency observation point is a single line in the
+ * dispatcher, success and failure both record).
+ *
+ * @returns {{
+ *   counters: Record<string, number>,
+ *   latency:  Record<string, { p50: number, p95: number, p99: number, count: number }>
+ * }}
+ */
+export function snapshot() {
+  const out = { counters: {}, latency: {} };
+  for (const [key, val] of counters) out.counters[key] = val;
+  for (const [tool, samples] of histograms) {
+    if (samples.length === 0) continue;
+    const sorted = [...samples].sort((a, b) => a - b);
+    out.latency[tool] = {
+      p50: percentile(sorted, 0.50),
+      p95: percentile(sorted, 0.95),
+      p99: percentile(sorted, 0.99),
+      count: samples.length,
+    };
+  }
+  return out;
+}
+
+/**
+ * Clear both counters and histograms. Used by tests and by the boot-time
+ * KIT_MCP_METRICS_RESET=1 path so an operator can probe a fresh window.
+ *
+ * @returns {void}
+ */
+export function reset() {
+  counters.clear();
+  histograms.clear();
+}
+
+// Boot-time reset honors KIT_MCP_METRICS_RESET=1. We call reset() instead of
+// merely skipping init because the maps are already empty at module load —
+// the call is a no-op today but documents the contract for any future module
+// that imports metrics.js after another module has already populated state.
+if (process.env.KIT_MCP_METRICS_RESET === '1') {
+  reset();
+}
+
+// Exported for tests only — keeps the API surface explicit while letting unit
+// tests assert on the FIFO behavior at the boundary.
+export const __TEST_HISTOGRAM_CAP = HISTOGRAM_CAP;

package/src/mcp-server/index.js

@@ -1,10 +1,11 @@
-// kit-mcp server — exposes 5 tools, each with action-based dispatch.
+// kit-mcp server — exposes 7 tools, each with action-based dispatch (or none).
 //
-//   kit       action: list-agents | list-commands | list-skills | get | search
-//   sync      action: targets | status | install | remove
-//   gates     action: list | get | for-stage
-//   forensics action: collect | summarize | write-learnings | list-replays | record-replay | load-replay
-//   install   action: targets | install | dry-run                    (registers this MCP into an IDE)
+//   kit              action: list-agents | list-commands | list-skills | get | search
+//   sync             action: targets | status | install | remove
+//   gates            action: list | get | for-stage
+//   forensics        action: collect | summarize | write-learnings | list-replays | record-replay | load-replay
+//   install          action: targets | install | dry-run                    (registers this MCP into an IDE)
+//   metrics-snapshot (parameterless)                                          (OBS-18 four-golden-signals readout)
 //
 // Transport: stdio (MCP standard).
 
@@ -30,6 +31,7 @@ import { recordReplay, listReplays, loadReplay, annotateReplay } from '../core/r
 import { installMcp, listInstallTargets } from './install.js';
 import { ensureSidecar } from '../ui/auto-spawn.js';
 import { wrapProgressForUi } from '../ui/wrapper.js';
+import { incrementInvocation, recordLatency, snapshot as metricsSnapshot } from '../core/metrics.js';
 
 const TOOLS = [
   {
@@ -130,6 +132,17 @@ const TOOLS = [
       required: ['action'],
     },
   },
+  {
+    // OBS-18 (Phase 94.01): expose four-golden-signals data for the MCP server itself.
+    // Read-only (no auth needed beyond the underlying transport): returns counters
+    // keyed `${tool}:${status}` and per-tool latency p50/p95/p99/count.
+    name: 'metrics-snapshot',
+    description: 'Read in-memory golden-signals metrics for this MCP server (counters + latency p50/p95/p99 per tool).',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
 ];
 
 // DRIFT-13-03: read version from package.json at module load (NOT inside
@@ -292,13 +305,21 @@ async function handleInstall(args) {
   }
 }
 
+// OBS-18 (Phase 94.01): metrics-snapshot is parameterless and read-only.
+// Returns the live snapshot synchronously — no auth, no projectRoot guard
+// (no disk reads, no shell). Wraps in an async fn for handler-API uniformity.
+async function handleMetricsSnapshot() {
+  return metricsSnapshot();
+}
+
 const HANDLERS = {
-  kit:           handleKit,
-  sync:          handleSync,
-  'reverse-sync':handleReverseSync,
-  gates:         handleGates,
-  forensics:     handleForensics,
-  install:       handleInstall,
+  kit:               handleKit,
+  sync:              handleSync,
+  'reverse-sync':    handleReverseSync,
+  gates:             handleGates,
+  forensics:         handleForensics,
+  install:           handleInstall,
+  'metrics-snapshot': handleMetricsSnapshot,
 };
 
 function slim(x) {
@@ -330,12 +351,30 @@ export async function createServer() {
     const { name, arguments: args } = req.params;
     const handler = HANDLERS[name];
     if (!handler) {
+      // OBS-18 (Phase 94.01): unknown-tool path counts as an error against
+      // the unknown name itself — useful signal if a client is mis-spelling
+      // a tool name in production. No latency observation (handler never ran).
+      incrementInvocation(name || 'unknown', 'error');
       return { content: [{ type: 'text', text: JSON.stringify({ error: `Unknown tool: ${name}` }) }], isError: true };
     }
+    // OBS-18 (Phase 94.01): timestamp the dispatch boundary. The four-golden-signals
+    // skill cares about the *user-facing* latency, which for the MCP server is the
+    // time from request receipt (we are inside the SDK callback) to the JSON envelope
+    // being ready. Date.now() is sub-millisecond-cheap and aligns with the bucket
+    // granularity we report (50/100/250/500ms thresholds in CONTEXT.md).
+    const start = Date.now();
     try {
       const result = await handler(args ?? {});
+      recordLatency(name, Date.now() - start);
+      incrementInvocation(name, 'ok');
       return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     } catch (e) {
+      // OBS-18: still record latency on the error path — half the value of a
+      // latency histogram is catching tail-latency-then-fail patterns. Status
+      // 'error' covers any thrown exception, including Phase 79.01 gates guard
+      // and the validateProjectRoot rejection (Phase 83.01).
+      recordLatency(name, Date.now() - start);
+      incrementInvocation(name, 'error');
       // SEC-14-06: full stack stays in stderr for operator debug; client envelope is sanitized.
       // sanitizeMcpError redacts secrets/paths from e.message, preserves e.code (Phase 83
       // EMANIFESTMISMATCH invariant), and emits NO stack field.