gasp-standard-mcp 1.9.0 → 1.10.0

package/README.md

@@ -33,12 +33,13 @@ 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 |
@@ -62,6 +63,8 @@ The traversal tools (`infer_drivers`, `explain_path`, `coverage_gap`) return *st
 - 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

package/build/index.js

@@ -2,8 +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 {
@@ -76,15 +77,43 @@ function renderClassifications(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.`,
                 },
             ],
         };
@@ -99,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}`);
@@ -125,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
@@ -181,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 }] };
@@ -296,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)");
@@ -453,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") }] };
 });
@@ -824,6 +839,18 @@ server.tool("coverage_gap", "Audit a metric set against the GASP relationship gr
     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;