gasp-standard-mcp 1.3.1 → 1.5.0

package/README.md

@@ -33,19 +33,26 @@ Restart your MCP client after adding the config.
 
 | Tool | Description |
 |------|-------------|
-| `lookup_metric` | Full metric details: definition, formula, benchmarks, common mistakes, sources |
-| `list_metrics` | List all metrics, optionally filtered by department |
+| `lookup_metric` | Full metric details: definition, formula, benchmarks, entity, common mistakes, sources |
+| `list_metrics` | List all metrics, optionally filtered by department and/or signal type |
 | `get_formula` | Get formula(s) for a metric |
-| `get_relationships` | Upstream and downstream metric relationships |
+| `get_relationships` | Upstream/downstream relationships for metrics, entities, or concepts — includes business model edges (OWNS, GRANTS, CONVERTS_TO, etc.) |
 | `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 |
+| `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 |
 
 ## Data
 
 - 300 metrics across 13 departments
 - 80 glossary definitions
-- 22 relationship nodes, 34 edges
+- 76 relationship nodes (60 metrics + 11 entities + 5 concepts), 157 edges
+- 15 entity-to-entity business model edges (OWNS, GRANTS, CONVERTS_TO, GENERATES, etc.)
 - 78 data requirements with field types, grain, and example SQL
+- 11 business entities, 5 business concepts, 22 source categories, 198 canonical fields
+- 60 structured formulas with decomposed inputs (metric refs + field refs)
+- 60 temporal mappings (grain, frequency, period for every metric node)
+- CEL `change_nature` field for revenue quality analysis (Adjusted NRR/GRR)
 - Sources: the canonical [GASP Standard](https://gaspwiki.com) files
 
 ## Examples
@@ -55,6 +62,7 @@ Once installed, ask your AI assistant:
 - "What is NRR?"
 - "How do I calculate CAC Payback?"
 - "What drives ARR?"
+- "How does Customer relate to Subscription?"
 - "List all marketing metrics"
 - "What data do I need to implement ARR tracking?"
 - "Search for churn"

package/build/index.js

@@ -94,6 +94,25 @@ 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(", ")}`);
     }
+    // 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;
+            }
+        }
+    }
     // Dual-lens content
     if (metric.dualLens) {
         const dl = metric.dualLens;
@@ -129,6 +148,16 @@ server.tool("lookup_metric", "Look up a GASP Standard metric by name or abbrevia
     if (metric.dualLensNote) {
         parts.push(`\n## Dual-Lens Note\n\n${metric.dualLensNote}`);
     }
+    // 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 (sf && typeof sf === 'object' && 'adjustedVariant' in sf) {
+            parts.push(`\n## Adjusted Variant\n\n${sf.adjustedVariant}`);
+        }
+    }
     // Swap EOM → GASP branding
     const text = parts.join("\n").replace(/\bEOM Standard\b/g, "GASP Standard");
     return { content: [{ type: "text", text }] };
@@ -221,11 +250,40 @@ server.tool("get_formula", "Get the formula(s) for a GASP Standard metric. Retur
         }
         parts.push("```\n" + metric.formulas[i] + "\n```\n");
     }
+    // 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;
+            }
+        }
+    }
+    if (structured) {
+        if (structured.inputs && structured.inputs.length > 0) {
+            parts.push("## Inputs (metric dependencies)");
+            for (const input of structured.inputs) {
+                const inputNode = data.nodes.find(n => n.id === input.ref);
+                const label = inputNode?.label || input.ref;
+                parts.push(`- **${label}** (${input.role})`);
+            }
+            parts.push("");
+        }
+        if (structured.fields && structured.fields.length > 0) {
+            parts.push("## Required fields");
+            parts.push(structured.fields.map(f => `\`${f}\``).join(", "));
+            parts.push("");
+        }
+    }
     const text = parts.join("\n").replace(/\bEOM Standard\b/g, "GASP Standard");
     return { content: [{ type: "text", text }] };
 });
 // --- Tool 4: get_relationships ---
-server.tool("get_relationships", "Get the upstream (what drives it) and downstream (what it drives) relationships for a metric from the GASP relationship graph.", { metric: z.string().describe("Metric name or ID (e.g. 'arr', 'NRR', 'pipeline', 'churn_rate')") }, async ({ metric: name }) => {
+server.tool("get_relationships", "Get the upstream (what drives it) and downstream (what it drives) relationships for a metric, entity, or concept from the GASP relationship graph. Entity nodes show business model connections (OWNS, GRANTS, CONVERTS_TO, etc.).", { metric: z.string().describe("Metric name or ID (e.g. 'arr', 'NRR'), entity (e.g. 'customer', 'subscription'), or concept (e.g. 'revenue', 'bookings')") }, async ({ metric: name }) => {
     const { node, upstream, downstream } = getRelationships(data, name);
     if (!node) {
         const available = data.nodes.map((n) => `${n.label} (${n.id})`).join(", ");
@@ -355,6 +413,241 @@ server.tool("search", "Search across all GASP Standard metrics and definitions.
     }
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
+// --- Tool 7: generate_query ---
+server.tool("generate_query", "Generate a SQL query for a GASP metric using your adapter mapping. Takes a metric name and adapter JSON, fills in parameterized SQL templates with your warehouse column names.", {
+    metric: z
+        .string()
+        .describe("Metric name to generate SQL for (e.g. 'NRR', 'CAC', 'Pipeline Value', 'ARR')"),
+    adapter: z
+        .string()
+        .describe("Your GASP adapter JSON string with field mappings"),
+}, async ({ metric: metricName, adapter: adapterJson }) => {
+    if (!data.queryTemplates) {
+        return {
+            content: [{ type: "text", text: "Query templates not available. Update the GASP Standard data." }],
+        };
+    }
+    // Parse adapter
+    let adapter;
+    try {
+        adapter = JSON.parse(adapterJson);
+    }
+    catch {
+        return {
+            content: [{ type: "text", text: "Invalid adapter JSON." }],
+        };
+    }
+    if (!adapter.mappings || !Array.isArray(adapter.mappings)) {
+        return {
+            content: [{ type: "text", text: 'Adapter must have a "mappings" array.' }],
+        };
+    }
+    // Find matching template (fuzzy match on metric name)
+    const q = metricName.toLowerCase();
+    let templateKey;
+    let template;
+    // Exact match first
+    for (const [key, tmpl] of Object.entries(data.queryTemplates)) {
+        if (key.toLowerCase() === q) {
+            templateKey = key;
+            template = tmpl;
+            break;
+        }
+    }
+    // Partial match
+    if (!template) {
+        for (const [key, tmpl] of Object.entries(data.queryTemplates)) {
+            if (key.toLowerCase().includes(q) || q.includes(key.toLowerCase())) {
+                templateKey = key;
+                template = tmpl;
+                break;
+            }
+        }
+    }
+    if (!template || !templateKey) {
+        const available = Object.keys(data.queryTemplates).slice(0, 20).join(", ");
+        return {
+            content: [{
+                    type: "text",
+                    text: `No query template found for "${metricName}".\n\nAvailable templates: ${available}...`,
+                }],
+        };
+    }
+    // Build field → warehouseRef map from adapter
+    const fieldMap = new Map();
+    for (const m of adapter.mappings) {
+        if (m.gaspField && m.warehouseRef && m.warehouseRef.trim() !== "") {
+            fieldMap.set(m.gaspField, { ref: m.warehouseRef, transform: m.transform });
+        }
+    }
+    // Check which template fields are mapped
+    const mapped = [];
+    const missing = [];
+    for (const field of template.fields) {
+        if (fieldMap.has(field))
+            mapped.push(field);
+        else
+            missing.push(field);
+    }
+    // Fill in the template
+    let sql = template.parameterizedQuery;
+    // Replace {{field}} placeholders with warehouse refs
+    for (const [field, mapping] of fieldMap) {
+        const placeholder = `{{${field}}}`;
+        if (sql.includes(placeholder)) {
+            // Extract just the column name (last part of schema.table.column)
+            const parts = mapping.ref.split(".");
+            const column = parts[parts.length - 1];
+            const replacement = mapping.transform
+                ? mapping.transform.replace(/\{\{value\}\}/g, column)
+                : column;
+            sql = sql.split(placeholder).join(replacement);
+        }
+    }
+    // Replace {{_table}} with the most common table from mapped fields
+    if (sql.includes("{{_table}}")) {
+        const tableCounts = new Map();
+        for (const field of template.fields) {
+            const m = fieldMap.get(field);
+            if (m) {
+                const parts = m.ref.split(".");
+                // Table is everything except the last segment (column)
+                const table = parts.slice(0, -1).join(".");
+                if (table)
+                    tableCounts.set(table, (tableCounts.get(table) || 0) + 1);
+            }
+        }
+        // Pick the most-referenced table
+        let bestTable = "your_table";
+        let bestCount = 0;
+        for (const [table, count] of tableCounts) {
+            if (count > bestCount) {
+                bestTable = table;
+                bestCount = count;
+            }
+        }
+        sql = sql.split("{{_table}}").join(bestTable);
+    }
+    // Mark any remaining unfilled placeholders
+    const unfilled = sql.match(/\{\{[^}]+\}\}/g);
+    if (unfilled) {
+        sql = sql + "\n\n-- NOTE: Unmapped fields (fill in your adapter): " + [...new Set(unfilled)].join(", ");
+    }
+    // Build response
+    const parts = [
+        `# ${templateKey} — Generated SQL\n`,
+        `**Warehouse:** ${adapter.warehouse || "not specified"}`,
+        `**Source:** ${template.source}`,
+        `**Grain:** ${template.grain}`,
+        `**Fields mapped:** ${mapped.length} / ${template.fields.length}\n`,
+    ];
+    if (missing.length > 0) {
+        parts.push(`**Missing fields:** \`${missing.join("`, `")}\`\n`);
+    }
+    parts.push("```sql\n" + sql + "\n```");
+    if (mapped.length > 0) {
+        parts.push("\n**Field mapping used:**");
+        for (const field of mapped) {
+            const m = fieldMap.get(field);
+            const line = `- \`${field}\` → \`${m.ref}\`${m.transform ? ` (transform: ${m.transform})` : ""}`;
+            parts.push(line);
+        }
+    }
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+});
+// --- Tool 8: validate_adapter ---
+server.tool("validate_adapter", "Validate a GASP adapter mapping file. Takes a JSON string of your adapter and reports which GASP metrics are fully covered, partially covered, or missing based on your mapped fields.", {
+    adapter: z
+        .string()
+        .describe("The adapter JSON as a string. Must follow the GASP adapter schema with version, organization, warehouse, and mappings array."),
+}, async ({ adapter: adapterJson }) => {
+    // Parse the adapter
+    let adapter;
+    try {
+        adapter = JSON.parse(adapterJson);
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: "Invalid JSON. The adapter must be a valid JSON object." }],
+        };
+    }
+    if (!adapter.mappings || !Array.isArray(adapter.mappings)) {
+        return {
+            content: [{ type: "text", text: 'Adapter must have a "mappings" array. Download the template from https://gaspwiki.com/downloads/gasp-adapter-template.json' }],
+        };
+    }
+    // Build set of mapped fields (only those with a non-empty warehouseRef)
+    const mappedFields = new Set();
+    for (const m of adapter.mappings) {
+        if (m.gaspField && m.warehouseRef && m.warehouseRef.trim() !== "") {
+            mappedFields.add(m.gaspField);
+        }
+    }
+    // Check each data requirement
+    const drs = data.dataRequirements || [];
+    const fullyCovered = [];
+    const partiallyCovered = [];
+    const notCovered = [];
+    for (const dr of drs) {
+        const mapped = dr.fields.filter((f) => mappedFields.has(f));
+        const missing = dr.fields.filter((f) => !mappedFields.has(f));
+        if (missing.length === 0) {
+            fullyCovered.push(dr.metric);
+        }
+        else if (mapped.length > 0) {
+            partiallyCovered.push({ metric: dr.metric, mapped, missing });
+        }
+        else {
+            notCovered.push(dr.metric);
+        }
+    }
+    // Find unmapped GASP fields
+    const allGaspFields = new Set();
+    for (const dr of drs) {
+        for (const f of dr.fields)
+            allGaspFields.add(f);
+    }
+    const unmappedFields = [...allGaspFields].filter((f) => !mappedFields.has(f)).sort();
+    // Build report
+    const org = adapter.organization || "Unknown";
+    const wh = adapter.warehouse || "not specified";
+    const parts = [
+        `# GASP Adapter Validation — ${org}\n`,
+        `**Warehouse:** ${wh}`,
+        `**Mapped fields:** ${mappedFields.size} / ${allGaspFields.size} (${Math.round((mappedFields.size / allGaspFields.size) * 100)}%)\n`,
+    ];
+    if (fullyCovered.length > 0) {
+        parts.push(`## Fully Covered Metrics (${fullyCovered.length})`);
+        parts.push("These metrics have all required fields mapped and can be computed:\n");
+        for (const m of fullyCovered)
+            parts.push(`- ${m}`);
+        parts.push("");
+    }
+    if (partiallyCovered.length > 0) {
+        parts.push(`## Partially Covered Metrics (${partiallyCovered.length})`);
+        parts.push("These metrics are missing some fields:\n");
+        for (const p of partiallyCovered) {
+            parts.push(`- **${p.metric}** — missing: \`${p.missing.join("`, `")}\``);
+        }
+        parts.push("");
+    }
+    if (notCovered.length > 0) {
+        parts.push(`## Not Covered (${notCovered.length})`);
+        parts.push("No fields mapped for these metrics:\n");
+        for (const m of notCovered)
+            parts.push(`- ${m}`);
+        parts.push("");
+    }
+    if (unmappedFields.length > 0 && unmappedFields.length <= 30) {
+        parts.push(`## Unmapped Fields (${unmappedFields.length})`);
+        parts.push(`\`${unmappedFields.join("`, `")}\``);
+    }
+    else if (unmappedFields.length > 30) {
+        parts.push(`## Unmapped Fields (${unmappedFields.length})`);
+        parts.push(`First 30: \`${unmappedFields.slice(0, 30).join("`, `")}\` ...`);
+    }
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+});
 // Start the server
 async function main() {
     const transport = new StdioServerTransport();

package/build/loader.js

@@ -97,7 +97,76 @@ export function loadStandard() {
             }
         }
     }
-    return { metrics, definitions, nodes, edges, dataRequirements };
+    // Load query templates
+    const queryTemplatePath = join(standardDir, "query-templates.json");
+    let queryTemplates;
+    try {
+        const qtRaw = JSON.parse(readFileSync(queryTemplatePath, "utf-8"));
+        queryTemplates = qtRaw.templates || {};
+    }
+    catch {
+        // query-templates.json not yet created
+    }
+    // Load ontology
+    const ontologyPath = join(standardDir, "ontology.json");
+    let ontology;
+    try {
+        const ontRaw = JSON.parse(readFileSync(ontologyPath, "utf-8"));
+        ontology = {
+            entities: ontRaw.entities || [],
+            entityMappings: ontRaw.entityMappings || {},
+            concepts: ontRaw.concepts || [],
+            entityRelationships: ontRaw.entityRelationships || undefined,
+            structuredFormulas: ontRaw.structuredFormulas || undefined,
+        };
+    }
+    catch {
+        // ontology.json not yet created
+    }
+    // Enrich relationship nodes with descriptions
+    const defBySlug = new Map();
+    for (const m of metrics) {
+        if (m.slug && m.definition)
+            defBySlug.set(m.slug, m.definition);
+    }
+    for (const d of definitions) {
+        if (d.slug && d.definition && !defBySlug.has(d.slug))
+            defBySlug.set(d.slug, d.definition);
+    }
+    for (const node of nodes) {
+        if (node.nodeType === 'entity' && ontology) {
+            const entityId = node.id.replace('entity_', '');
+            const entity = ontology.entities.find(e => e.id === entityId);
+            node.nodeType = 'entity';
+            node.description = entity?.definition || '';
+            node.category = 'entity';
+        }
+        else if (node.nodeType === 'concept' && ontology?.concepts) {
+            const conceptId = node.id.replace('concept_', '');
+            const concept = ontology.concepts.find(c => c.id === conceptId);
+            node.nodeType = 'concept';
+            node.description = concept?.definition || '';
+            node.category = 'concept';
+        }
+        else {
+            // Try to find metric description by slug
+            node.department = node.department || '';
+            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;
+                    }
+                }
+            }
+        }
+    }
+    return { metrics, definitions, nodes, edges, dataRequirements, ontology, queryTemplates };
 }
 /**
  * Search metrics + definitions for a query string.