gasp-standard-mcp 1.7.1 → 1.9.0

package/README.md

@@ -41,6 +41,11 @@ Restart your MCP client after adding the config.
 | `search` | Full-text search across metrics, definitions, and data requirements |
 | `generate_query` | Generate warehouse-specific SQL from a metric name + adapter mapping |
 | `validate_adapter` | Validate a GASP adapter mapping file — reports which metrics are fully/partially/not covered |
+| `infer_drivers` | Diagnose what could explain an observed metric movement — ranked upstream candidates with paths and per-step edge classifications |
+| `explain_path` | Enumerate edge chains between two metrics, with classification (metric_signal / structural / lifecycle / behavioral / assignment / generative) per step |
+| `coverage_gap` | Audit a metric set: identify one-hop upstream/downstream metrics not in the set, plus any disconnected metrics |
+
+The traversal tools (`infer_drivers`, `explain_path`, `coverage_gap`) return *structure* — paths, classifications, attenuation scores — not numeric forecasts. They serve diagnosis, exploration, and coverage-audit workflows respectively, and compose: use `infer_drivers` to pick candidates, `explain_path` to scrutinise a chain, then `coverage_gap` to check whether the candidate is being measured. For counterfactual "what if" simulation, use the [TWIN Modifier](https://gaspwiki.com/v1/twin-modifier).
 
 ## Data
 
@@ -56,12 +61,14 @@ Restart your MCP client after adding the config.
 - 60 temporal mappings (grain, frequency, period for every metric node)
 - Access control classifications for every graph metric (sensitivity tier + access scope)
 - CEL `change_nature` field for revenue quality analysis (Adjusted NRR/GRR)
+- Per-department cross-references (e.g. NRR under Customer Success, Gross Margin under Finance) now resolve to the full canonical content via slug lookup
 - Sources: the canonical [GASP Standard](https://gaspwiki.com) files
 
 ## Examples
 
 Once installed, ask your AI assistant:
 
+**Definitions and structure**
 - "What is NRR?"
 - "How do I calculate CAC Payback?"
 - "What drives ARR?"
@@ -74,6 +81,12 @@ Once installed, ask your AI assistant:
 - "What data do I need to implement ARR tracking?"
 - "Search for churn"
 
+**Diagnosis, exploration and coverage** (new in 1.9.0)
+- "ARR is down this month. What could explain it?" — `infer_drivers`
+- "How does Win Rate eventually affect Free Cash Flow?" — `explain_path`
+- "We track ARR, NRR, GRR, CAC and CAC Payback. What important metrics are we missing?" — `coverage_gap`
+- "Why might NRR be slipping? Trace the path back through Health Score." — composes `infer_drivers` → `explain_path`
+
 ## License
 
-MIT
+Apache-2.0

package/build/index.js

@@ -3,6 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { loadStandard, loadBundled, loadRemote, findMetric, getRelationships, search, } from "./loader.js";
+import { buildContext, inferDrivers, findPaths, coverageGap, } from "./traversal.js";
 // Load data: local repo files → bundled JSON → remote fetch from gaspwiki.com
 let data;
 try {
@@ -43,8 +44,38 @@ const VERSION_URL = "https://gaspwiki.com/api/standard-version.json";
 })();
 const server = new McpServer({
     name: "gasp-standard",
-    version: "1.0.0",
+    version: "1.9.0",
 });
+// Build traversal context once at startup. Used by infer_drivers, explain_path,
+// and coverage_gap. Reads canonical structuredFormulas + edgeTypeClassification
+// from ontology.json plus the edge `inverse` flag from relationships.json.
+const traversalCtx = buildContext(data.nodes, data.edges, data.ontology);
+/** Resolve a user-supplied metric name to a graph node id, mirroring getRelationships. */
+function resolveNode(name) {
+    const q = name.toLowerCase().trim();
+    return (data.nodes.find((n) => n.id === q) ||
+        data.nodes.find((n) => n.label.toLowerCase() === q) ||
+        data.nodes.find((n) => n.id.includes(q) || n.label.toLowerCase().includes(q)));
+}
+/** Render a path as a markdown one-liner: `from → [type] to → [type] to`. */
+function renderPath(path) {
+    if (path.length === 0)
+        return "(direct)";
+    const parts = [path[0].from];
+    for (const step of path) {
+        const flip = step.directionFlip ? " ↓" : "";
+        parts.push(`→ [${step.edgeType}${flip}] ${step.to}`);
+    }
+    return parts.join(" ");
+}
+function renderClassifications(path) {
+    if (path.length === 0)
+        return "";
+    const counts = new Map();
+    for (const s of path)
+        counts.set(s.classification, (counts.get(s.classification) ?? 0) + 1);
+    return [...counts.entries()].map(([k, v]) => `${k}×${v}`).join(", ");
+}
 // --- Tool 1: lookup_metric ---
 server.tool("lookup_metric", "Look up a GASP Standard metric by name or abbreviation. Returns definition, formula, benchmarks, time period, and department.", { name: z.string().describe("Metric name or abbreviation (e.g. 'MRR', 'Net Revenue Retention', 'CAC Payback')") }, async ({ name }) => {
     const metric = findMetric(data, name);
@@ -661,6 +692,137 @@ server.tool("validate_adapter", "Validate a GASP adapter mapping file. Takes a J
     }
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
+// --- Tool 9: infer_drivers ---
+server.tool("infer_drivers", "Diagnose what could explain an observed metric movement. Walks the GASP relationship graph in reverse and ranks upstream metrics whose movement (in the inferred direction) is consistent with the observation. Returns ranked candidates with full path and per-step edge classifications. Structural reasoning, not numeric forecasting — scores are attenuation products, not magnitude estimates. Compose with explain_path to scrutinise a chain or coverage_gap to check whether a candidate is being measured. For counterfactual 'what if' simulation, use the TWIN Modifier at https://gaspwiki.com/v1/twin-modifier instead.", {
+    metric: z.string().describe("Metric name, abbreviation, or graph id (e.g. 'ARR', 'NRR', 'arr')"),
+    direction: z.enum(["up", "down"]).describe("Observed direction of movement"),
+    maxDepth: z.number().int().min(1).max(8).optional().describe("Maximum traversal depth (default 6)"),
+}, async ({ metric: name, direction: dirStr, maxDepth }) => {
+    const node = resolveNode(name);
+    if (!node) {
+        return {
+            content: [{ type: "text", text: `No graph node found matching "${name}".` }],
+        };
+    }
+    if (!traversalCtx.metricNodeIds.has(node.id)) {
+        return {
+            content: [{ type: "text", text: `"${node.label}" is not a metric node — infer_drivers operates on metrics only. Try get_relationships for entity/concept nodes.` }],
+        };
+    }
+    const observedDirection = dirStr === "up" ? 1 : -1;
+    const candidates = inferDrivers(node.id, observedDirection, traversalCtx, { maxDepth });
+    if (candidates.length === 0) {
+        return {
+            content: [{ type: "text", text: `# ${node.label} ${dirStr}\n\nNo upstream candidates found within the traversal depth limit.` }],
+        };
+    }
+    const arrow = (d) => (d === 1 ? "↑" : "↓");
+    const parts = [
+        `# ${node.label} ${arrow(observedDirection)} — Candidate drivers (${candidates.length})\n`,
+        `_Structural reasoning, not numeric forecasting. Scores are attenuation products (0–1) along the chain; they rank candidates but do not estimate magnitudes._\n`,
+        `| # | Driver | Implied direction | Score | Path |`,
+        `|---|--------|------------------|-------|------|`,
+    ];
+    for (let i = 0; i < Math.min(candidates.length, 25); i++) {
+        const c = candidates[i];
+        parts.push(`| ${i + 1} | ${c.label ?? c.id} (\`${c.id}\`) | ${arrow(c.direction)} | ${c.score.toFixed(3)} | ${renderPath(c.path)} |`);
+    }
+    if (candidates.length > 25) {
+        parts.push(`\n_Showing top 25 of ${candidates.length}._`);
+    }
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+});
+// --- Tool 10: explain_path ---
+server.tool("explain_path", "Explain how one metric reaches another by enumerating edge chains in the GASP relationship graph. Each step carries the canonical edge type and a classification bucket (metric_signal / structural / lifecycle / behavioral / assignment / generative). Returns up to 5 distinct paths sorted by length then attenuation. Empty if disconnected in the forward direction. Compose with infer_drivers to scrutinise a candidate chain.", {
+    from: z.string().describe("Source metric or node (name, abbreviation, or id)"),
+    to: z.string().describe("Target metric or node"),
+    maxDepth: z.number().int().min(1).max(8).optional().describe("Maximum chain length (default 6)"),
+}, async ({ from, to, maxDepth }) => {
+    const fromNode = resolveNode(from);
+    const toNode = resolveNode(to);
+    if (!fromNode || !toNode) {
+        const missing = !fromNode ? from : to;
+        return {
+            content: [{ type: "text", text: `No graph node found matching "${missing}".` }],
+        };
+    }
+    const paths = findPaths(fromNode.id, toNode.id, traversalCtx, { maxDepth });
+    if (paths.length === 0) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `# ${fromNode.label} → ${toNode.label}\n\nNo forward path found within depth ${maxDepth ?? 6}. They may be disconnected in this direction (try the reverse, or use coverage_gap to inspect connectivity).`,
+                }],
+        };
+    }
+    const parts = [
+        `# ${fromNode.label} → ${toNode.label} — ${paths.length} path${paths.length === 1 ? "" : "s"}\n`,
+    ];
+    for (let i = 0; i < paths.length; i++) {
+        const p = paths[i];
+        parts.push(`## Path ${i + 1} — ${p.path.length} step${p.path.length === 1 ? "" : "s"}, score ${p.score.toFixed(3)}, end direction ${p.direction === 1 ? "↑" : "↓"}`);
+        parts.push(`Classifications: ${renderClassifications(p.path)}\n`);
+        for (let j = 0; j < p.path.length; j++) {
+            const s = p.path[j];
+            const flip = s.directionFlip ? " (↓ inverts direction)" : "";
+            const fromLabel = traversalCtx.nodeById.get(s.from)?.label ?? s.from;
+            const toLabel = traversalCtx.nodeById.get(s.to)?.label ?? s.to;
+            parts.push(`${j + 1}. **${fromLabel}** → **${toLabel}** — \`${s.edgeType}\` (${s.classification}, attenuation ${s.attenuation.toFixed(2)})${flip}`);
+        }
+        parts.push("");
+    }
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+});
+// --- Tool 11: coverage_gap ---
+server.tool("coverage_gap", "Audit a metric set against the GASP relationship graph. Returns three groups: upstream_missing (one-hop drivers not in the set), downstream_missing (one-hop downstream metrics not in the set), and disconnected (in-graph metrics with no path of any length to/from the set). Operates on metric nodes only — entities and concepts are ignored. Use to identify gaps before instrumenting a dashboard, then compose with infer_drivers or explain_path to investigate specific candidates.", {
+    metrics: z.array(z.string()).min(1).describe("Metric names, abbreviations, or graph ids (e.g. ['ARR', 'NRR', 'CAC'])"),
+}, async ({ metrics }) => {
+    const resolved = [];
+    const unresolved = [];
+    for (const m of metrics) {
+        const node = resolveNode(m);
+        if (node && traversalCtx.metricNodeIds.has(node.id)) {
+            resolved.push(node.id);
+        }
+        else {
+            unresolved.push(m);
+        }
+    }
+    if (resolved.length === 0) {
+        return {
+            content: [{ type: "text", text: `No metric nodes resolved from input: ${metrics.join(", ")}. Try ids like 'arr', 'nrr', 'cac' or labels like 'NRR'.` }],
+        };
+    }
+    const result = coverageGap(new Set(resolved), traversalCtx);
+    const labelOf = (id) => traversalCtx.nodeById.get(id)?.label ?? id;
+    const formatList = (ids) => ids.length === 0 ? "_(none)_" : ids.map((id) => `- ${labelOf(id)} (\`${id}\`)`).join("\n");
+    const parts = [
+        `# Coverage gap — ${resolved.length} metric${resolved.length === 1 ? "" : "s"}\n`,
+        `**Tracked:** ${resolved.map((id) => `${labelOf(id)} (\`${id}\`)`).join(", ")}`,
+    ];
+    if (unresolved.length > 0) {
+        parts.push(`**Unresolved input:** ${unresolved.join(", ")}`);
+    }
+    parts.push("");
+    parts.push(`## Upstream missing (${result.upstreamMissing.length})`);
+    parts.push(`_Direct drivers of the tracked set that aren't tracked. Add to capture root-cause signal._\n`);
+    parts.push(formatList(result.upstreamMissing));
+    parts.push("");
+    parts.push(`## Downstream missing (${result.downstreamMissing.length})`);
+    parts.push(`_Metrics directly fed by the tracked set, not tracked. Add to see what the inputs translate into._\n`);
+    parts.push(formatList(result.downstreamMissing));
+    parts.push("");
+    parts.push(`## Disconnected (${result.disconnected.length})`);
+    parts.push(`_In-graph metrics with no path (any length, either direction) to the tracked set._\n`);
+    if (result.disconnected.length > 25) {
+        parts.push(formatList(result.disconnected.slice(0, 25)));
+        parts.push(`\n_…and ${result.disconnected.length - 25} more._`);
+    }
+    else {
+        parts.push(formatList(result.disconnected));
+    }
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+});
 // Start the server
 async function main() {
     const transport = new StdioServerTransport();

package/build/loader.js

@@ -97,6 +97,57 @@ export function loadStandard() {
             }
         }
     }
+    // Enrich cross-reference stubs with canonical content fields.
+    //
+    // Some metrics intentionally appear in multiple department files — e.g. NRR
+    // is defined canonically in core.md and listed as a "See [Core](core.md#...)"
+    // stub in customer-success.md. Per-department records are needed to drive
+    // department-scoped routes (e.g. /v1/metrics/customer-success/...), but
+    // consumers of standard.json that look up by slug expect every record to
+    // carry full content. Without this pass, Map-based lookups silently get the
+    // empty stub instead of the canonical record.
+    //
+    // Strategy: keep stub identity (department, category, name, slug, rawMarkdown)
+    // but copy any content field that's empty on the stub from the canonical.
+    const canonicalBySlug = new Map();
+    for (const m of metrics) {
+        if (m.slug && m.definition && !canonicalBySlug.has(m.slug)) {
+            canonicalBySlug.set(m.slug, m);
+        }
+    }
+    for (const m of metrics) {
+        if (m.definition)
+            continue; // already canonical or non-stub
+        const seeMatch = m.rawMarkdown.match(/See \[([^\]]+)\]\(([^)]+)\)/);
+        if (!seeMatch)
+            continue;
+        const link = seeMatch[2];
+        const anchor = link.includes("#") ? link.split("#")[1] : null;
+        if (!anchor)
+            continue;
+        const canon = canonicalBySlug.get(anchor) ||
+            canonicalBySlug.get(m.slug) ||
+            [...canonicalBySlug.values()].find((c) => c.slug.includes(anchor));
+        if (!canon || canon === m)
+            continue;
+        if (!m.definition)
+            m.definition = canon.definition;
+        if (!m.formulas?.length)
+            m.formulas = [...canon.formulas];
+        if (!m.benchmarks)
+            m.benchmarks = canon.benchmarks;
+        if (!m.insight)
+            m.insight = canon.insight;
+        if (!m.commonMistakes?.length && canon.commonMistakes)
+            m.commonMistakes = [...canon.commonMistakes];
+        if (!m.sources?.length)
+            m.sources = [...canon.sources];
+        if (!m.aliases?.length)
+            m.aliases = [...canon.aliases];
+        // dualLens and dualLensNote are intentionally NOT enriched — they are a
+        // Core-only construct (asserted by data-integrity tests). Consumers that
+        // need dual-lens content should resolve via slug to the Core record.
+    }
     // Load query templates
     const queryTemplatePath = join(standardDir, "query-templates.json");
     let queryTemplates;