gasp-standard-mcp 1.8.0 → 1.10.0

package/README.md

@@ -33,14 +33,20 @@ Restart your MCP client after adding the config.
 
 | Tool | Description |
 |------|-------------|
-| `lookup_metric` | Full metric details: definition, formula, benchmarks, entity, common mistakes, sources |
+| `lookup_metric` | Full metric details: definition, formula, benchmarks, entity, common mistakes, sources and page URL. Falls back to glossary terms when no metric matches |
+| `lookup_definition` | Glossary term lookup (e.g. Signal Type, Sensitivity Tier, Access Scope, Metric Owner, CEL): full definition, section, canonical or reference link and page URL |
 | `list_metrics` | List all metrics, optionally filtered by department and/or signal type |
 | `get_formula` | Get formula(s) for a metric |
 | `get_relationships` | Upstream/downstream relationships for metrics, entities, or concepts — 21 relationship types across signal, lifecycle, ownership, interaction, and financial flow categories |
 | `get_data_requirements` | Data requirements for implementing a metric: fields, types, grain, source, and example SQL |
-| `search` | Full-text search across metrics, definitions, and data requirements |
+| `search` | Full-text search across metrics, definitions, and data requirements. Metric and definition hits include their gaspwiki.com URL |
 | `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
 
@@ -57,12 +63,15 @@ Restart your MCP client after adding the config.
 - 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
+- Every metric and definition result carries its gaspwiki.com page URL; definitions keep their full body and reference links
+- Access classifications, structured formulas and entity mappings resolve for every graph metric, including cross-reference records (e.g. NRR under Customer Success, CAC under Marketing)
 - 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?"
@@ -75,6 +84,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

@@ -2,7 +2,9 @@
 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 { loadStandard, loadBundled, loadRemote, findMetric, findDefinition, metricNodeId, getRelationships, search, } from "./loader.js";
+import { buildContext, inferDrivers, findPaths, coverageGap, } from "./traversal.js";
+import { SITE, metricUrl, definitionUrl, resolveDocLink } from "./urls.js";
 // Load data: local repo files → bundled JSON → remote fetch from gaspwiki.com
 let data;
 try {
@@ -43,17 +45,75 @@ 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(", ");
+}
+/** Markdown for a glossary definition, with absolute links so agents never guess URLs */
+function formatDefinition(def) {
+    const absolutise = (md) => md.replace(/\]\((\/[^)]*)\)/g, `](${SITE}$1)`);
+    const parts = [`# ${def.term}`, `**Type:** Definition (${def.section})`, `**URL:** ${definitionUrl(def)}`];
+    parts.push(`\n**Definition:** ${absolutise(def.definition)}`);
+    if (def.body)
+        parts.push(absolutise(def.body));
+    const canonical = def.canonicalLink ? resolveDocLink(def.canonicalLink) : null;
+    if (canonical)
+        parts.push(`\n**Canonical definition:** ${canonical}`);
+    const reference = def.referenceLink ? resolveDocLink(def.referenceLink) : null;
+    if (reference)
+        parts.push(`\n**Reference:** ${reference}`);
+    if (def.usedIn.length > 0)
+        parts.push(`**Used in:** ${def.usedIn.join(", ")}`);
+    return parts.join("\n").replace(/\bEOM Standard\b/g, "GASP Standard");
+}
 // --- 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 }) => {
+server.tool("lookup_metric", "Look up a GASP Standard metric by name or abbreviation. Returns definition, formula, benchmarks, time period, department and page URL. Falls back to glossary terms (e.g. 'Signal Type', 'Metric Owner') when no metric matches; use lookup_definition to ask for a term directly.", { name: z.string().describe("Metric name or abbreviation (e.g. 'MRR', 'Net Revenue Retention', 'CAC Payback')") }, async ({ name }) => {
     const metric = findMetric(data, name);
     if (!metric) {
+        const def = findDefinition(data, name);
+        if (def) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No metric named "${name}". Matching glossary term:\n\n${formatDefinition(def)}`,
+                    },
+                ],
+            };
+        }
         return {
             content: [
                 {
                     type: "text",
-                    text: `No metric found matching "${name}". Try searching with the 'search' tool for partial matches.`,
+                    text: `No metric or definition found matching "${name}". Try the 'search' tool for partial matches.`,
                 },
             ],
         };
@@ -68,6 +128,7 @@ server.tool("lookup_metric", "Look up a GASP Standard metric by name or abbrevia
         `**Department:** ${metric.department}`,
         `**Category:** ${metric.category}`,
         signalLine,
+        `**URL:** ${metricUrl(metric)}`,
     ];
     if (metric.definition) {
         parts.push(`\n**Definition:** ${metric.definition}`);
@@ -94,23 +155,15 @@ server.tool("lookup_metric", "Look up a GASP Standard metric by name or abbrevia
     if (metric.aliases.length > 0) {
         parts.push(`\n**Aliases:** ${metric.aliases.join(", ")}`);
     }
+    // Graph node id keys every ontology lookup below
+    const nodeId = metricNodeId(data, metric);
     // Entity mapping from ontology
-    if (data.ontology?.entityMappings) {
-        // Build reverse map: graph node ID → entity
-        for (const [entityId, metricIds] of Object.entries(data.ontology.entityMappings)) {
-            // Check if any alias/abbreviation of this metric matches a graph node ID
-            const lowerAliases = metric.aliases.map(a => a.toLowerCase().replace(/\s+/g, '_'));
-            const lowerName = metric.name.toLowerCase().replace(/[^a-z0-9]+/g, '_');
-            const matched = metricIds.some(id => lowerAliases.includes(id) ||
-                lowerName.startsWith(id.replace(/_/g, '_')) ||
-                metric.slug.startsWith(id.replace(/_/g, '-')));
-            if (matched) {
-                const entity = data.ontology.entities.find(e => e.id === entityId);
-                if (entity) {
-                    parts.push(`\n**Measures:** ${entity.label} (${entity.aliases.join(", ")})`);
-                }
-                break;
-            }
+    if (nodeId && data.ontology?.entityMappings) {
+        const entityId = Object.entries(data.ontology.entityMappings)
+            .find(([, metricIds]) => metricIds.includes(nodeId))?.[0];
+        const entity = entityId && data.ontology.entities.find(e => e.id === entityId);
+        if (entity) {
+            parts.push(`\n**Measures:** ${entity.label} (${entity.aliases.join(", ")})`);
         }
     }
     // Dual-lens content
@@ -150,27 +203,28 @@ server.tool("lookup_metric", "Look up a GASP Standard metric by name or abbrevia
     }
     // Adjusted variant from structured formulas (e.g. NRR, GRR)
     const sfMap = data.ontology?.structuredFormulas;
-    if (sfMap) {
-        const nodeId = metric.slug.replace(/-/g, '_');
-        const sf = sfMap[nodeId]
-            || Object.entries(sfMap).find(([k]) => k !== 'description' && nodeId.startsWith(k + '_'))?.[1];
+    if (sfMap && nodeId) {
+        const sf = sfMap[nodeId];
         if (sf && typeof sf === 'object' && 'adjustedVariant' in sf) {
             parts.push(`\n## Adjusted Variant\n\n${sf.adjustedVariant}`);
         }
     }
     // Access control classification (if available)
     const acMap = data.ontology?.accessControl?.classifications;
-    if (acMap) {
-        const nodeId = metric.slug.replace(/-/g, '_');
-        const ac = acMap[nodeId]
-            || Object.entries(acMap).find(([k]) => nodeId.startsWith(k + '_'))?.[1];
+    if (acMap && nodeId) {
+        const ac = acMap[nodeId];
         if (ac) {
             parts.push(`\n## Recommended Access Control\n` +
-                `- **Sensitivity:** ${ac.sensitivityTier} (https://gaspwiki.com/v1/definitions/sensitivity-tier)\n` +
-                `- **Scope:** ${ac.accessScope} (https://gaspwiki.com/v1/definitions/access-scope)\n` +
-                `See https://gaspwiki.com/v1/governance for policy patterns (Cedar, OPA, warehouse RLS).`);
+                `- **Sensitivity:** ${ac.sensitivityTier} (${SITE}/v1/definitions/sensitivity-tier)\n` +
+                `- **Scope:** ${ac.accessScope} (${SITE}/v1/definitions/access-scope)\n` +
+                `See ${SITE}/v1/governance for policy patterns (Cedar, OPA, warehouse RLS).`);
         }
     }
+    // A glossary term with the exact name the caller asked for
+    const shadowed = data.definitions.find((d) => d.term.toLowerCase() === name.toLowerCase().trim());
+    if (shadowed) {
+        parts.push(`\n**See also:** glossary term "${shadowed.term}" (${definitionUrl(shadowed)}), via lookup_definition`);
+    }
     // Swap EOM → GASP branding
     const text = parts.join("\n").replace(/\bEOM Standard\b/g, "GASP Standard");
     return { content: [{ type: "text", text }] };
@@ -265,17 +319,8 @@ server.tool("get_formula", "Get the formula(s) for a GASP Standard metric. Retur
     }
     // Append structured formula references if available
     const formulas = data.ontology?.structuredFormulas;
-    const nodeId = metric.slug.replace(/-/g, '_');
-    // Match: exact node ID, or slug starts with a formula key (e.g. "arr_annual_recurring_revenue" starts with "arr")
-    let structured = formulas?.[nodeId];
-    if (!structured && formulas) {
-        for (const [key, val] of Object.entries(formulas)) {
-            if (key !== 'description' && nodeId.startsWith(key + '_')) {
-                structured = val;
-                break;
-            }
-        }
-    }
+    const nodeId = metricNodeId(data, metric);
+    const structured = nodeId ? formulas?.[nodeId] : undefined;
     if (structured) {
         if (structured.inputs && structured.inputs.length > 0) {
             parts.push("## Inputs (metric dependencies)");
@@ -422,7 +467,8 @@ server.tool("search", "Search across all GASP Standard metrics and definitions.
     for (const r of results) {
         const dept = r.department ? ` [${r.department}]` : "";
         parts.push(`### ${r.name}${dept}`);
-        parts.push(`*${r.type}*: ${r.snippet}\n`);
+        parts.push(`*${r.type}*: ${r.snippet}`);
+        parts.push(r.url ? `URL: ${r.url}\n` : "");
     }
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
@@ -661,7 +707,150 @@ 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
+// --- Tool 12: lookup_definition ---
+server.tool("lookup_definition", "Look up a GASP Standard glossary term (e.g. 'Signal Type', 'Sensitivity Tier', 'Access Scope', 'Metric Owner', 'Churn', 'CEL'). Returns the full definition, its section, related links and page URL. Use lookup_metric for metrics.", { term: z.string().describe("Term name, abbreviation or slug (e.g. 'Signal Type', 'CEL', 'metric-owner')") }, async ({ term }) => {
+    const def = findDefinition(data, term);
+    if (!def) {
+        const metric = findMetric(data, term);
+        const hint = metric
+            ? ` "${metric.name}" is a metric: use lookup_metric (${metricUrl(metric)}).`
+            : " Try the 'search' tool for partial matches.";
+        return { content: [{ type: "text", text: `No definition found matching "${term}".${hint}` }] };
+    }
+    return { content: [{ type: "text", text: formatDefinition(def) }] };
+});
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/build/loader.d.ts

@@ -1,22 +1,35 @@
-import { Metric, RelationshipNode, StandardData } from "./types.js";
+import { Metric, Definition, RelationshipNode, StandardData } from "./types.js";
 /** Load pre-parsed data bundled with the npm package (offline fallback) */
 export declare function loadBundled(): StandardData;
 /** Fetch pre-parsed standard data from gaspwiki.com (for global/npx installs) */
 export declare function loadRemote(): Promise<StandardData>;
 /** Load all standard data from local files at startup */
 export declare function loadStandard(): StandardData;
+/**
+ * Graph node id for a metric record, used to key ontology lookups.
+ * Data bundled before metricNodeIds existed falls back to an exact slug match.
+ */
+export declare function metricNodeId(data: StandardData, metric: Pick<Metric, "slug">): string | undefined;
 /**
  * Search metrics + definitions for a query string.
  * Returns top N matches ranked by relevance.
  */
-export declare function search(data: StandardData, query: string, limit?: number): Array<{
+export interface SearchResult {
     type: "metric" | "definition" | "data_requirement";
     name: string;
     snippet: string;
     department?: string;
-}>;
+    /** gaspwiki.com page for this result (absent for data requirements) */
+    url?: string;
+}
+export declare function search(data: StandardData, query: string, limit?: number): SearchResult[];
 /** Find a metric by name, abbreviation, or slug */
 export declare function findMetric(data: StandardData, name: string): Metric | undefined;
+/**
+ * Find a glossary definition by term, slug or abbreviation.
+ * "CEL" matches "CEL (Commercial Event Ledger)" via the parenthetical.
+ */
+export declare function findDefinition(data: StandardData, name: string): Definition | undefined;
 /** Get relationships for a metric: upstream (what drives it) and downstream (what it drives) */
 export declare function getRelationships(data: StandardData, metricId: string): {
     node: RelationshipNode | undefined;

package/build/loader.js

@@ -1,6 +1,7 @@
 import { readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { parseMetricsFile, parseDefinitions } from "./parser.js";
+import { metricUrl, definitionUrl } from "./urls.js";
 /** Resolve the repo root (two levels up from build/index.js) */
 function repoRoot() {
     // gasp-wiki-mcp/build/index.js -> gasp-wiki-mcp -> repo root
@@ -42,6 +43,24 @@ export function loadStandard() {
     const relData = JSON.parse(readFileSync(relPath, "utf-8"));
     const nodes = relData.nodes;
     const edges = relData.edges;
+    // Metric slug → graph node id, from the website's node → page map.
+    // Stubs that share the canonical slug resolve directly.
+    const linksPath = join(root, "gasp-wiki-frontend", "src", "data", "metric-links.ts");
+    const metricNodeIds = {};
+    const linkRe = /^\s*(\w+):\s*\{\s*href:\s*'\/v1\/metrics\/[a-z0-9-]+\/([a-z0-9-]+)'/gm;
+    for (const [, nodeId, slug] of readFileSync(linksPath, "utf-8").matchAll(linkRe)) {
+        metricNodeIds[slug] = nodeId;
+    }
+    // Node id → canonical slug, taken before stubs are added
+    const slugByNodeId = new Map(Object.entries(metricNodeIds).map(([slug, id]) => [id, slug]));
+    // Stubs with their own slug ("See [Core](core.md#cac-customer-acquisition-cost)")
+    // inherit the node of the metric they point to.
+    for (const m of metrics) {
+        const anchor = m.rawMarkdown.match(/See \[[^\]]+\]\([^)#]*#([^)]+)\)/)?.[1];
+        if (anchor && metricNodeIds[anchor] && !metricNodeIds[m.slug]) {
+            metricNodeIds[m.slug] = metricNodeIds[anchor];
+        }
+    }
     // Load data requirements from dashboard
     const dashPath = join(root, "gasp-wiki-frontend", "src", "data", "dashboard-mock.json");
     const dashData = JSON.parse(readFileSync(dashPath, "utf-8"));
@@ -206,24 +225,24 @@ export function loadStandard() {
             node.signalType = node.signalType || '';
             node.category = node.category || node.department || '';
             if (!node.description) {
-                // Build slug from the metric-links mapping pattern
-                const slug = node.id.replace(/_/g, '-');
-                // Search for a matching definition
-                for (const [key, def] of defBySlug) {
-                    if (key.includes(slug) || slug.includes(key.split('-')[0])) {
-                        node.description = def;
-                        break;
-                    }
-                }
+                const slug = slugByNodeId.get(node.id);
+                node.description = (slug && defBySlug.get(slug)) || '';
             }
         }
     }
-    return { metrics, definitions, nodes, edges, dataRequirements, ontology, queryTemplates };
+    return { metrics, definitions, nodes, edges, dataRequirements, ontology, queryTemplates, metricNodeIds };
 }
 /**
- * Search metrics + definitions for a query string.
- * Returns top N matches ranked by relevance.
+ * Graph node id for a metric record, used to key ontology lookups.
+ * Data bundled before metricNodeIds existed falls back to an exact slug match.
  */
+export function metricNodeId(data, metric) {
+    const mapped = data.metricNodeIds?.[metric.slug];
+    if (mapped)
+        return mapped;
+    const id = metric.slug.replace(/-/g, "_");
+    return data.nodes.some((n) => n.id === id) ? id : undefined;
+}
 export function search(data, query, limit = 10) {
     const q = query.toLowerCase();
     const results = [];
@@ -236,6 +255,7 @@ export function search(data, query, limit = 10) {
                 name: m.name,
                 snippet: `[${signalLabel}] ${m.definition || m.insight || ""}`,
                 department: m.department,
+                url: metricUrl(m),
                 score,
             });
         }
@@ -247,6 +267,7 @@ export function search(data, query, limit = 10) {
                 type: "definition",
                 name: d.term,
                 snippet: d.definition,
+                url: definitionUrl(d),
                 score,
             });
         }
@@ -332,6 +353,23 @@ export function findMetric(data, name) {
         data.metrics.find((m) => m.name.toLowerCase().includes(q)) ||
         data.metrics.find((m) => m.aliases.some((a) => a.toLowerCase().includes(q))));
 }
+/**
+ * Find a glossary definition by term, slug or abbreviation.
+ * "CEL" matches "CEL (Commercial Event Ledger)" via the parenthetical.
+ */
+export function findDefinition(data, name) {
+    const q = name.toLowerCase().trim();
+    if (!q)
+        return undefined;
+    const parts = (term) => {
+        const m = term.match(/^(.+?)\s*\(([^)]+)\)\s*$/);
+        return m ? [m[1].toLowerCase().trim(), m[2].toLowerCase().trim()] : [];
+    };
+    return (data.definitions.find((d) => d.term.toLowerCase() === q) ||
+        data.definitions.find((d) => d.slug === q) ||
+        data.definitions.find((d) => parts(d.term).includes(q)) ||
+        data.definitions.find((d) => d.term.toLowerCase().includes(q)));
+}
 /** Get relationships for a metric: upstream (what drives it) and downstream (what it drives) */
 export function getRelationships(data, metricId) {
     const q = metricId.toLowerCase().trim();

package/build/parser.js

@@ -346,6 +346,15 @@ export function parseDefinitions(content) {
             // Extract canonical link
             const linkMatch = raw.match(/\*\*Canonical definition:\*\*\s*\[([^\]]+)\]\(([^)]+)\)/);
             const canonicalLink = linkMatch ? linkMatch[2] : null;
+            // Extract reference link (framework terms point at a site page instead)
+            const refMatch = raw.match(/\*\*Reference:\*\*\s*\[([^\]]+)\]\(([^)]+)\)/);
+            const referenceLink = refMatch ? refMatch[2] : null;
+            // Remaining body (bullets, examples) minus the link/metadata lines
+            const bodyLines = raw.split("\n").filter((l) => l !== defLine && !l.startsWith("---"));
+            const body = bodyLines
+                .filter((l) => !/\*\*(Canonical definition|Reference|Used in):\*\*/.test(l))
+                .join("\n")
+                .trim();
             // Extract "Used in" departments
             const usedInMatch = raw.match(/\*\*Used in:\*\*\s*(.+)/);
             const usedIn = usedInMatch
@@ -357,6 +366,8 @@ export function parseDefinitions(content) {
                 definition,
                 section: currentSection,
                 canonicalLink,
+                referenceLink,
+                body: body || null,
                 usedIn,
             });
             continue;