gasp-standard-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 GASP Standard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# gasp-standard-mcp
+
+MCP server for the [GASP Standard](https://gaspwiki.com) — the Generally Accepted SaaS Performance standard for metric definitions, formulas, benchmarks, and relationships.
+
+Works with Claude Code, Claude Desktop, or any [MCP](https://modelcontextprotocol.io/)-compatible client.
+
+## Install
+
+### Claude Code (one command)
+
+```bash
+claude mcp add gasp-standard -- npx -y gasp-standard-mcp
+```
+
+### Manual config
+
+Add to your project `.mcp.json` or `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "gasp-standard": {
+      "command": "npx",
+      "args": ["-y", "gasp-standard-mcp"]
+    }
+  }
+}
+```
+
+Restart your MCP client after adding the config.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `lookup_metric` | Full metric details: definition, formula, benchmarks, common mistakes, sources |
+| `list_metrics` | List all metrics, optionally filtered by department |
+| `get_formula` | Get formula(s) for a metric |
+| `get_relationships` | Upstream and downstream metric relationships |
+| `search` | Full-text search across all metrics and definitions |
+
+## Data
+
+- 298 metrics across 13 departments
+- 79 glossary definitions
+- 21 relationship nodes, 25 edges
+- Sources: the canonical [GASP Standard](https://gaspwiki.com) files
+
+## Examples
+
+Once installed, ask your AI assistant:
+
+- "What is NRR?"
+- "How do I calculate CAC Payback?"
+- "What drives ARR?"
+- "List all marketing metrics"
+- "Search for churn"
+
+## License
+
+MIT

package/build/export-data.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Export all parsed GASP Standard data as a single JSON file.
+ * Output: website/public/api/standard.json
+ *
+ * Usage: npm run build && npm run export-data
+ */
+export {};

package/build/export-data.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * Export all parsed GASP Standard data as a single JSON file.
+ * Output: website/public/api/standard.json
+ *
+ * Usage: npm run build && npm run export-data
+ */
+import { loadStandard } from "./loader.js";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+const data = loadStandard();
+const json = JSON.stringify(data);
+const version = {
+    metricCount: data.metrics.length,
+    definitionCount: data.definitions.length,
+    nodeCount: data.nodes.length,
+    edgeCount: data.edges.length,
+    buildDate: new Date().toISOString().slice(0, 10),
+};
+const versionJson = JSON.stringify(version);
+// 1. Write to website/public/api/ → serves as https://gaspwiki.com/api/standard.json
+const webOutDir = join(new URL(".", import.meta.url).pathname, "..", "..", "website", "public", "api");
+mkdirSync(webOutDir, { recursive: true });
+writeFileSync(join(webOutDir, "standard.json"), json);
+writeFileSync(join(webOutDir, "standard-version.json"), versionJson);
+// 2. Write to mcp-server/build/ → bundled with npm package as offline fallback
+const buildDir = new URL(".", import.meta.url).pathname;
+writeFileSync(join(buildDir, "standard-data.json"), json);
+writeFileSync(join(buildDir, "standard-version.json"), versionJson);
+console.log(`Exported ${data.metrics.length} metrics, ${data.definitions.length} definitions, ${data.nodes.length} nodes, ${data.edges.length} edges (${version.buildDate})`);
+console.log(`  → website/public/api/standard.json + standard-version.json`);
+console.log(`  → mcp-server/build/standard-data.json + standard-version.json`);

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+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";
+// Load data: local repo files → bundled JSON → remote fetch from gaspwiki.com
+let data;
+try {
+    data = loadStandard();
+}
+catch {
+    try {
+        data = loadBundled();
+    }
+    catch {
+        try {
+            data = await loadRemote();
+        }
+        catch (err) {
+            console.error("Failed to load GASP Standard data:", err);
+            process.exit(1);
+        }
+    }
+}
+// Background version check — non-blocking, stderr only
+const VERSION_URL = "https://gaspwiki.com/api/standard-version.json";
+(async () => {
+    try {
+        const res = await fetch(VERSION_URL);
+        if (!res.ok)
+            return;
+        const remote = await res.json();
+        const local = { metricCount: data.metrics.length, definitionCount: data.definitions.length };
+        if (remote.metricCount !== local.metricCount || remote.definitionCount !== local.definitionCount) {
+            console.error(`[gasp-standard] Update available: your data has ${local.metricCount} metrics / ${local.definitionCount} definitions, ` +
+                `latest has ${remote.metricCount} / ${remote.definitionCount} (${remote.buildDate}). ` +
+                `Run: npx gasp-standard-mcp@latest`);
+        }
+    }
+    catch {
+        // Offline or gaspwiki.com unreachable — silently ignore
+    }
+})();
+const server = new McpServer({
+    name: "gasp-standard",
+    version: "1.0.0",
+});
+// --- 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);
+    if (!metric) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No metric found matching "${name}". Try searching with the 'search' tool for partial matches.`,
+                },
+            ],
+        };
+    }
+    // Build response with branding swap
+    const parts = [
+        `# ${metric.name}`,
+        `**Department:** ${metric.department}`,
+        `**Category:** ${metric.category}`,
+    ];
+    if (metric.definition) {
+        parts.push(`\n**Definition:** ${metric.definition}`);
+    }
+    if (metric.formulas.length > 0) {
+        parts.push("\n**Formula(s):**");
+        for (const f of metric.formulas) {
+            parts.push("```\n" + f + "\n```");
+        }
+    }
+    if (metric.benchmarks) {
+        parts.push(`\n**Benchmarks:**\n${metric.benchmarks}`);
+    }
+    if (metric.insight) {
+        parts.push(`\n**What it tells you:** ${metric.insight}`);
+    }
+    if (metric.commonMistakes && metric.commonMistakes.length > 0) {
+        parts.push("\n**Common mistakes:**\n" +
+            metric.commonMistakes.map((m) => `- ${m}`).join("\n"));
+    }
+    if (metric.sources.length > 0) {
+        parts.push("\n**Sources:**\n" + metric.sources.map((s) => `- ${s}`).join("\n"));
+    }
+    if (metric.aliases.length > 0) {
+        parts.push(`\n**Aliases:** ${metric.aliases.join(", ")}`);
+    }
+    // Swap EOM → GASP branding
+    const text = parts.join("\n").replace(/\bEOM Standard\b/g, "GASP Standard");
+    return { content: [{ type: "text", text }] };
+});
+// --- Tool 2: list_metrics ---
+server.tool("list_metrics", "List all GASP Standard metrics, optionally filtered by department. Returns metric names grouped by category.", {
+    department: z
+        .string()
+        .optional()
+        .describe("Filter by department name (e.g. 'sales', 'marketing', 'core'). Case-insensitive. Omit to list all."),
+}, async ({ department }) => {
+    let filtered = data.metrics;
+    if (department) {
+        const q = department.toLowerCase();
+        filtered = data.metrics.filter((m) => m.department.toLowerCase().includes(q));
+    }
+    if (filtered.length === 0) {
+        const departments = [
+            ...new Set(data.metrics.map((m) => m.department)),
+        ].sort();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No metrics found for department "${department}".\n\nAvailable departments: ${departments.join(", ")}`,
+                },
+            ],
+        };
+    }
+    // Group by department then category
+    const grouped = new Map();
+    for (const m of filtered) {
+        if (!grouped.has(m.department)) {
+            grouped.set(m.department, new Map());
+        }
+        const dept = grouped.get(m.department);
+        if (!dept.has(m.category)) {
+            dept.set(m.category, []);
+        }
+        dept.get(m.category).push(m.name);
+    }
+    const parts = [`# GASP Standard Metrics (${filtered.length} total)\n`];
+    for (const [dept, categories] of grouped) {
+        parts.push(`## ${dept}`);
+        for (const [cat, names] of categories) {
+            if (cat)
+                parts.push(`### ${cat}`);
+            for (const n of names) {
+                parts.push(`- ${n}`);
+            }
+        }
+        parts.push("");
+    }
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+});
+// --- Tool 3: get_formula ---
+server.tool("get_formula", "Get the formula(s) for a GASP Standard metric. Returns all formula variants if multiple exist.", { metric: z.string().describe("Metric name or abbreviation (e.g. 'NRR', 'LTV', 'CAC Payback')") }, async ({ metric: name }) => {
+    const metric = findMetric(data, name);
+    if (!metric) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No metric found matching "${name}".`,
+                },
+            ],
+        };
+    }
+    if (metric.formulas.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${metric.name} does not have a formula defined (it may be a qualitative metric or reference).`,
+                },
+            ],
+        };
+    }
+    const parts = [`# ${metric.name} — Formula\n`];
+    for (let i = 0; i < metric.formulas.length; i++) {
+        if (metric.formulas.length > 1) {
+            parts.push(`**Variant ${i + 1}:**`);
+        }
+        parts.push("```\n" + metric.formulas[i] + "\n```\n");
+    }
+    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 }) => {
+    const { node, upstream, downstream } = getRelationships(data, name);
+    if (!node) {
+        const available = data.nodes.map((n) => `${n.label} (${n.id})`).join(", ");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No relationship node found matching "${name}".\n\nAvailable nodes: ${available}`,
+                },
+            ],
+        };
+    }
+    const parts = [
+        `# ${node.label} — Relationships\n`,
+        `**Description:** ${node.description}`,
+        `**Category:** ${node.category}`,
+        `**Level:** ${node.level}\n`,
+    ];
+    if (upstream.length > 0) {
+        parts.push("## Upstream (what drives this metric)");
+        for (const r of upstream) {
+            parts.push(`- **${r.node.label}** (${r.type}) — ${r.node.description}`);
+        }
+        parts.push("");
+    }
+    else {
+        parts.push("## Upstream\nNo upstream drivers (this is a top-level metric).\n");
+    }
+    if (downstream.length > 0) {
+        parts.push("## Downstream (what this metric drives)");
+        for (const r of downstream) {
+            parts.push(`- **${r.node.label}** (${r.type}) — ${r.node.description}`);
+        }
+    }
+    else {
+        parts.push("## Downstream\nNo downstream metrics (this is a leaf metric).");
+    }
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+});
+// --- Tool 5: search ---
+server.tool("search", "Search across all GASP Standard metrics and definitions. Returns top 10 matches ranked by relevance.", { query: z.string().describe("Search query (e.g. 'churn', 'retention', 'pipeline coverage')") }, async ({ query: q }) => {
+    const results = search(data, q, 10);
+    if (results.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No results found for "${q}".`,
+                },
+            ],
+        };
+    }
+    const parts = [`# Search results for "${q}" (${results.length} matches)\n`];
+    for (const r of results) {
+        const dept = r.department ? ` [${r.department}]` : "";
+        parts.push(`### ${r.name}${dept}`);
+        parts.push(`*${r.type}*: ${r.snippet}\n`);
+    }
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/build/loader.d.ts

@@ -0,0 +1,31 @@
+import { Metric, 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;
+/**
+ * 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<{
+    type: "metric" | "definition";
+    name: string;
+    snippet: string;
+    department?: string;
+}>;
+/** Find a metric by name, abbreviation, or slug */
+export declare function findMetric(data: StandardData, name: string): Metric | 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;
+    upstream: Array<{
+        node: RelationshipNode;
+        type: string;
+    }>;
+    downstream: Array<{
+        node: RelationshipNode;
+        type: string;
+    }>;
+};

package/build/loader.js

@@ -0,0 +1,163 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { parseMetricsFile, parseDefinitions } from "./parser.js";
+/** Resolve the repo root (two levels up from build/index.js) */
+function repoRoot() {
+    // mcp-server/build/index.js -> mcp-server -> repo root
+    const thisDir = new URL(".", import.meta.url).pathname;
+    return join(thisDir, "..", "..");
+}
+const DATA_URL = "https://gaspwiki.com/api/standard.json";
+/** Load pre-parsed data bundled with the npm package (offline fallback) */
+export function loadBundled() {
+    const bundledPath = join(new URL(".", import.meta.url).pathname, "standard-data.json");
+    const raw = readFileSync(bundledPath, "utf-8");
+    return JSON.parse(raw);
+}
+/** Fetch pre-parsed standard data from gaspwiki.com (for global/npx installs) */
+export async function loadRemote() {
+    const res = await fetch(DATA_URL);
+    if (!res.ok)
+        throw new Error(`Failed to fetch ${DATA_URL}: ${res.status}`);
+    return res.json();
+}
+/** Load all standard data from local files at startup */
+export function loadStandard() {
+    const root = repoRoot();
+    const standardDir = join(root, "standard");
+    const metricsDir = join(standardDir, "metrics");
+    // Load all metric files
+    const metricFiles = readdirSync(metricsDir).filter((f) => f.endsWith(".md"));
+    const metrics = [];
+    for (const file of metricFiles) {
+        const content = readFileSync(join(metricsDir, file), "utf-8");
+        const parsed = parseMetricsFile(content, file);
+        metrics.push(...parsed);
+    }
+    // Load definitions
+    const defsContent = readFileSync(join(standardDir, "definitions.md"), "utf-8");
+    const definitions = parseDefinitions(defsContent);
+    // Load relationships
+    const relPath = join(root, "website", "src", "data", "relationships.json");
+    const relData = JSON.parse(readFileSync(relPath, "utf-8"));
+    const nodes = relData.nodes;
+    const edges = relData.edges;
+    return { metrics, definitions, nodes, edges };
+}
+/**
+ * Search metrics + definitions for a query string.
+ * Returns top N matches ranked by relevance.
+ */
+export function search(data, query, limit = 10) {
+    const q = query.toLowerCase();
+    const results = [];
+    for (const m of data.metrics) {
+        const score = scoreMetric(m, q);
+        if (score > 0) {
+            results.push({
+                type: "metric",
+                name: m.name,
+                snippet: m.definition || m.insight || "",
+                department: m.department,
+                score,
+            });
+        }
+    }
+    for (const d of data.definitions) {
+        const score = scoreDefinition(d, q);
+        if (score > 0) {
+            results.push({
+                type: "definition",
+                name: d.term,
+                snippet: d.definition,
+                score,
+            });
+        }
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, limit).map(({ score: _, ...rest }) => rest);
+}
+/** Score a metric against a query */
+function scoreMetric(m, q) {
+    let score = 0;
+    // Exact name match
+    if (m.name.toLowerCase() === q)
+        score += 100;
+    // Name contains query
+    else if (m.name.toLowerCase().includes(q))
+        score += 50;
+    // Alias match
+    for (const alias of m.aliases) {
+        if (alias.toLowerCase() === q)
+            score += 90;
+        else if (alias.toLowerCase().includes(q))
+            score += 40;
+    }
+    // Definition contains query
+    if (m.definition.toLowerCase().includes(q))
+        score += 20;
+    // Formula contains query
+    for (const f of m.formulas) {
+        if (f.toLowerCase().includes(q))
+            score += 15;
+    }
+    // Category/department match
+    if (m.department.toLowerCase().includes(q))
+        score += 10;
+    if (m.category.toLowerCase().includes(q))
+        score += 10;
+    // Raw markdown contains query (catch-all)
+    if (score === 0 && m.rawMarkdown.toLowerCase().includes(q))
+        score += 5;
+    return score;
+}
+/** Score a definition against a query */
+function scoreDefinition(d, q) {
+    let score = 0;
+    if (d.term.toLowerCase() === q)
+        score += 80;
+    else if (d.term.toLowerCase().includes(q))
+        score += 40;
+    if (d.definition.toLowerCase().includes(q))
+        score += 15;
+    if (d.section.toLowerCase().includes(q))
+        score += 5;
+    return score;
+}
+/** Find a metric by name, abbreviation, or slug */
+export function findMetric(data, name) {
+    const q = name.toLowerCase().trim();
+    return (data.metrics.find((m) => m.name.toLowerCase() === q) ||
+        data.metrics.find((m) => m.aliases.some((a) => a.toLowerCase() === q)) ||
+        data.metrics.find((m) => m.slug === q) ||
+        data.metrics.find((m) => m.name.toLowerCase().includes(q)) ||
+        data.metrics.find((m) => m.aliases.some((a) => a.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();
+    // Find the node by id or label
+    const node = 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));
+    if (!node) {
+        return { node: undefined, upstream: [], downstream: [] };
+    }
+    // Upstream = edges where this node is the target
+    const upstream = data.edges
+        .filter((e) => e.target === node.id)
+        .map((e) => ({
+        node: data.nodes.find((n) => n.id === e.source),
+        type: e.type,
+    }))
+        .filter((r) => r.node);
+    // Downstream = edges where this node is the source
+    const downstream = data.edges
+        .filter((e) => e.source === node.id)
+        .map((e) => ({
+        node: data.nodes.find((n) => n.id === e.target),
+        type: e.type,
+    }))
+        .filter((r) => r.node);
+    return { node, upstream, downstream };
+}

package/build/parser.d.ts

@@ -0,0 +1,11 @@
+import { Metric, Definition } from "./types.js";
+/**
+ * Parse a single metric markdown file into an array of Metric objects.
+ * Splits on ### headings and extracts fields.
+ */
+export declare function parseMetricsFile(content: string, filename: string): Metric[];
+/**
+ * Parse definitions.md into Definition objects.
+ * Each ### heading is a term.
+ */
+export declare function parseDefinitions(content: string): Definition[];