gasp-standard-mcp 1.12.0 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  MCP server for the [GASP Standard](https://gaspwiki.com), the Generally Accepted SaaS Principles standard for metric definitions, formulas, benchmarks and relationships.
4
4
 
5
- Works with Claude Code, Claude Desktop, or any [MCP](https://modelcontextprotocol.io/)-compatible client.
5
+ Works with Claude Code, Claude Desktop or any [MCP](https://modelcontextprotocol.io/)-compatible client. The package bundles a copy of the standard, so it runs offline. I maintain the standard and this server together. Each release carries the standard as it stood on the day I published it.
6
6
 
7
7
  ## Install
8
8
 
@@ -33,44 +33,43 @@ Restart your MCP client after adding the config.
33
33
 
34
34
  | Tool | Description |
35
35
  |------|-------------|
36
- | `lookup_metric` | Full metric details: definition, formula, benchmarks, entity, common mistakes, sources and page URL. Matches exactly (name with or without its abbreviation, abbreviation, alias, slug or graph label) and suggests close names instead of guessing. Falls back to glossary terms when no metric matches |
36
+ | `lookup_metric` | Full metric details: department, signal type, definition, formula, benchmarks, entities, common mistakes, sources and page URL. Matches exactly (formula id, name with or without its abbreviation, abbreviation, graph label, alias or slug), prefers the full record over a cross-reference stub and suggests close names (misspellings included) when nothing matches. A name two departments define (Escalation Rate) lists each candidate with department, formula id and URL; qualify by department ("Support Escalation Rate") or pass the formula id. Falls back to glossary terms when no metric matches |
37
37
  | `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. Matches exactly and suggests close terms instead of guessing |
38
- | `list_metrics` | List all metrics, optionally filtered by department and/or signal type |
39
- | `get_formula` | Canonical formula in the GASP formula grammar, with unit, O/M forms, variants, inputs with polarity, raw fields and the datasets they live in. Metrics that cannot be computed carry the reason |
40
- | `get_relationships` | Upstream/downstream relationships for metrics, entities or concepts. 21 relationship types across signal, lifecycle, ownership, interaction and financial flow categories |
41
- | `get_data_requirements` | Data requirements for implementing a metric: fields, types, grain, source and example SQL |
42
- | `search` | Full-text search across metrics, definitions and data requirements. Metric and definition hits include their gaspwiki.com URL |
43
- | `generate_query` | Compile warehouse-specific SQL from the metric's canonical formula and an adapter mapping. One scalar subquery per aggregate, each reading the table mapped for its dataset, with `:period_start` and `:period_end` parameters. Unmapped fields stay as `{{field@dataset}}` placeholders. Matches the metric exactly and suggests close names instead of guessing |
44
- | `validate_adapter` | Validate a GASP adapter mapping file (schema 1.1). Reports schema-level problems, unknown fields and datasets, dataset table conflicts, enum fields mapped without a transform and covered metrics without an owner. Computes coverage per metric against the exact field and dataset pairs its compiled SQL reads (full, partial or none) and ranks the highest-value next pairs to map |
38
+ | `list_metrics` | List all metrics, optionally filtered by exact department name (case-insensitive; an unknown name returns the department list) and/or signal type. The Core tier is the Core department |
39
+ | `get_formula` | Canonical formula in the GASP formula grammar, with unit, O/M forms, variants, inputs with polarity, raw fields with the datasets they live in and the enum filters each form applies (CAC-O reads `cost_function in (gtm, implementation, onboarding)`, CAC-M `cost_function = gtm`). Metrics that cannot be computed carry the reason |
40
+ | `get_relationships` | Upstream/downstream relationships for metrics, entities or concepts. 21 relationship types across signal, lifecycle, ownership, interaction and financial flow categories. Metric names resolve as in `lookup_metric`, ambiguity included. An entity also lists every metric whose formula reads its datasets (from `entityMappings`), with department and URL |
41
+ | `get_data_requirements` | Data requirements for implementing a metric or a department: each field with its type and the dataset it is read from, the staged flag, grain, source, page URL and example SQL. The metric resolves exactly as in `lookup_metric`; `department` (exact name) lists a department or picks between metrics sharing a name. Optional `breakdown` names a breakdown the metric declares (`by_plan` on MRR) and returns that breakdown's requirement: the dimension among the fields and example SQL with one row per value; an unknown name lists the declared ones. Optional `dialect` (`postgres`, `snowflake`, `bigquery`, `databricks`) writes the example SQL for that warehouse |
42
+ | `search` | Whole-word search across metrics (names, aliases, definitions, formulas, fields) and glossary definitions. Up to 10 results, one per metric or term, ranked name and alias above definition above formula and field, each with what matched and its gaspwiki.com URL. A query that matches nothing returns the closest names as "Did you mean" |
43
+ | `generate_query` | Compile warehouse-specific SQL from the metric's canonical formula and an adapter mapping. One scalar subquery per aggregate, each reading the table mapped for its dataset, with `:period_start` and `:period_end` parameters. Unmapped fields stay as `{{field@dataset}}` placeholders. Optional `breakdown` names a breakdown the metric declares (`by_plan` on MRR) and returns one row per value of its field; an unknown name lists the declared ones. Optional `dialect` (`postgres`, `snowflake`, `bigquery`, `databricks`; `postgres` also covers Redshift) picks the SQL syntax for date arithmetic, casts and percentiles; without it the adapter's `warehouse` decides when it names one of them, else postgres. The output says which dialect it used. Matches the metric exactly and suggests close names instead of guessing |
44
+ | `validate_adapter` | Validate a GASP adapter mapping file. Applies the bundled adapter JSON Schema (draft 2020-12, version 1.1) first and lists each violation with its JSON path, then reports unknown fields and datasets, fields mapped to a dataset that does not carry them, dataset table conflicts, enum fields mapped without a transform and covered metrics without an owner. Computes coverage per metric against the exact field and dataset pairs its compiled SQL reads (full, partial or none) and ranks the highest-value next pairs to map |
45
45
  | `infer_drivers` | Diagnose what could explain an observed metric movement: ranked upstream candidates with paths and per-step edge classifications |
46
- | `explain_path` | Enumerate edge chains between two metrics, with classification (metric_signal / structural / lifecycle / behavioral / assignment / generative) per step |
47
- | `coverage_gap` | Audit a metric set: identify one-hop upstream/downstream metrics not in the set, plus any disconnected metrics |
46
+ | `explain_path` | Enumerate up to 5 edge chains between two metrics, with classification (metric_signal / structural / lifecycle / behavioral / assignment / generative) per step |
47
+ | `coverage_gap` | Audit a metric set: one-hop upstream and downstream metrics missing from it, plus graph metrics with no path to or from it. Entities and concepts are ignored |
48
48
 
49
- 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).
49
+ The traversal tools (`infer_drivers`, `explain_path`, `coverage_gap`) return paths, edge classifications and attenuation scores. A score says how strongly the graph connects two metrics, never how far one will move. The tools chain: `infer_drivers` picks candidates, `explain_path` shows the chain behind one and `coverage_gap` checks whether you measure it. For "what if" simulation, use the [TWIN Modifier](https://gaspwiki.com/v1/twin-modifier).
50
50
 
51
51
  ## Data
52
52
 
53
- Version 1.12.0.
53
+ Version 1.14.0.
54
54
 
55
- - 300 metrics across 13 departments
56
- - 92 glossary definitions (80 SaaS domain + 12 GASP framework)
57
- - 82 relationship nodes (60 metrics + 15 entities + 7 concepts), 172 edges
55
+ - 301 metrics across 13 departments
56
+ - 93 glossary definitions (80 SaaS domain + 13 GASP framework)
57
+ - 95 relationship nodes (60 metrics + 28 entities + 7 concepts), 183 edges
58
58
  - 21 relationship types: metric signal (drives, reduces, predicts, component, measures), entity lifecycle (converts_to, parent_of, belongs_to), entity ownership (owns, grants, priced_by), entity interactions (manages, serves, engages_via, submits, represented_by, sources), entity financial flows (generates, produces, contributes_to, incurs)
59
- - 270 data requirements, one per metric with a formula, compiled from the formula at load time: fields with types, datasets, grain and a compiled example query
60
- - 270 query templates, one per metric with a formula, compiled from the formulas by the same step (no hand-written SQL). Every field placeholder names the dataset it is read from (`{{customer_status@customer}}`), so `generate_query` resolves per-dataset adapter mappings by tag, including inside cohort subqueries. The grammar's `window(expr, n unit)` gives DAU, WAU and MAU their 1, 7 and 30 day windows and `all_time(expr)` lets retention numerators read past the period end; intervals are emitted in units Postgres accepts
59
+ - 274 data requirements, one per metric with a formula, compiled from the formula at load time: fields with types, datasets, grain and a compiled example query
60
+ - 274 query templates, one per metric with a formula, compiled by the same step. None of the SQL is hand-written. Every field placeholder names the dataset it is read from (`{{customer_status@customer}}`), so `generate_query` resolves per-dataset adapter mappings by tag, inside cohort subqueries too. The grammar's `window(expr, n unit)` gives Daily, Weekly and Monthly Active Users (DAU, WAU, MAU) their 1, 7 and 30 day windows. `all_time(expr)` lets retention numerators read past the period end. A multi-argument `count_distinct` counts distinct tuples (Breadth of Adoption counts account and feature pairs). A formula with a `breakdown` field compiles to one row per value of that field, with `total(expr)` reading the whole population for shares of total (Ticket Distribution by Type, CAC by Channel)
61
61
  - The test suite executes every compiled template against a seeded fixture in an in-process Postgres (PGlite) and checks ten metrics against independently computed values
62
- - Apache Ossie (incubating) export, written by `npm run derive` to https://gaspwiki.com/downloads/ossie/: `gasp.ontology.yaml` (every dataset and GASP concept as an entity type, every field as a value type or relationship, enum values as constraints), `gasp.semantic_model.yaml` (the 47 datasets with `OSSIE_SQL_2026` field expressions, 40 foreign-key relationships and every canonical formula as a metric: 164 direct expressions, 138 staged through per-period datasets that carry the compiled SQL, O/M forms and variants as separate metrics with the form in `custom_extensions`), `gasp.mapping.yaml` (the ontology mapped onto the model) and `coverage.json` (how each formula was exported and why). All three documents pass the upstream validator, vendored at `ossie-validator/`, plus GASP's own cross-reference checks (`src/ossie/check.ts`), which catch what the upstream validator does not
63
- - 15 business entities (Customer, Subscription, License, Lead, Opportunity, User, Ticket, Employee, Invoice, Partner, Project, Plan, Product, Campaign and Contact)
62
+ - Apache Ossie (incubating) export, written by `npm run derive` to `standard/exports/ossie/` and served at https://gaspwiki.com/downloads/ossie/: `gasp.ontology.yaml` (every dataset and GASP concept as an entity type, every field as a value type or relationship, enum values as constraints), `gasp.semantic_model.yaml` (every dataset with `OSSIE_SQL_2026` field expressions, the foreign-key relationships between them and every canonical formula as a metric, either a direct expression or staged through a per-period dataset that carries the compiled SQL; O/M forms and variants are separate metrics with the form in `custom_extensions`), `gasp.mapping.yaml` (the ontology mapped onto the model) and `coverage.json` (how each formula was exported and why). All three documents pass the upstream validator (vendored at `ossie-validator/`) and GASP's own cross-reference checks in `src/ossie/check.ts`, which cover references the upstream validator leaves alone
63
+ - 28 business entities (Customer, Subscription, License, Lead, Opportunity, User, Ticket, Employee, Invoice, Partner, Project, Plan, Product, Campaign, Contact, Incident, Deployment, Release, Issue, Vulnerability, Feature, Requisition, Project Milestone, Deliverable, Quote, Order, Knowledge Article and Deal Registration). Every dataset with its own identity maps to an entity; ledger and period-level facts (cost events, financials, forecasts, web traffic) stay entity-free
64
64
  - 7 business concepts (Revenue, Bookings, COGS, Cohort, Pipeline, Segment and TCV)
65
- - 251 canonical fields across 47 datasets (event, snapshot and fact tables with date and key fields, entities, CEL class and activation rules). Enum fields declare their allowed values
66
- - 59 structured formulas with decomposed inputs (metric refs + field refs)
67
- - Canonical formulas for every metric in the GASP formula grammar (`standard/formulas.json`): 289 entries covering all 300 metrics (270 with formulas, 19 marked not computable with a reason, 2 department-qualified ids for shared headings), with units, O/M forms for ARR, NRR, CAC, LTV and Gross Margin (a form can reference another metric's form, `metric.gross_margin.O`) and variants such as Adjusted NRR (served by `get_formula` and compiled by `generate_query` and `get_data_requirements`)
65
+ - 264 canonical fields across 51 datasets (event, snapshot and fact tables with date and key fields, entities, CEL class and activation rules). Enum fields declare their allowed values
66
+ - 60 structured formulas with decomposed inputs (metric refs + field refs, with baseline inputs marked)
67
+ - Canonical formulas for every metric in the GASP formula grammar (`standard/formulas.json`): 289 entries covering all 301 metrics (274 with formulas, 15 marked not computable with a reason, 2 department-qualified ids for shared headings), with units, O/M forms for ARR, NRR, CAC, LTV, LTV:CAC, CAC Payback and Gross Margin (a form can reference another metric's form, `metric.gross_margin.O`) and variants such as Adjusted NRR (served by `get_formula` and compiled by `generate_query` and `get_data_requirements`)
68
68
  - Access control classifications for every graph metric (sensitivity tier + access scope)
69
- - CEL `change_nature` field for revenue quality analysis (Adjusted NRR/GRR)
70
- - Per-department cross-references (e.g. NRR under Customer Success, Gross Margin under Finance) now resolve to the full canonical content via slug lookup
69
+ - CEL `change_nature` field for revenue quality analysis (Adjusted NRR/GRR) and `segment` on revenue, contract and amendment events, so MRR, retention and churn metrics break down by customer segment
70
+ - Per-department cross-references (NRR under Customer Success, CAC under Marketing) resolve to the full canonical record, with its access classification, structured formula and entity mappings
71
71
  - Every metric and definition result carries its gaspwiki.com page URL; definitions keep their full body and reference links
72
- - 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)
73
- - Adapter schema 1.1 (`standard/gasp-adapter-schema.json`): a `datasets` map, per-dataset mappings (a mapping names its `dataset`), informational fields and `$schema`. A ready template ships at `gasp-wiki-frontend/public/downloads/gasp-adapter-template.json` and is tested against the public copy of the schema at https://gaspwiki.com/schemas/gasp-adapter-v1.json, which `npm run derive` writes from the canonical file
72
+ - Adapter schema 1.1 (`standard/gasp-adapter-schema.json`, JSON Schema draft 2020-12, served at https://gaspwiki.com/schemas/gasp-adapter-v1.json): a `datasets` map, per-dataset mappings (a mapping names its `dataset`), informational fields and `$schema`. The schema travels in the bundled data as `adapterSchema` and `validate_adapter` applies it with Ajv, so validation works offline. `npm run derive` writes a ready template to `standard/exports/gasp-adapter-template.json` (served at https://gaspwiki.com/downloads/gasp-adapter-template.json) and the tests validate it against the schema
74
73
  - Sources: the canonical [GASP Standard](https://gaspwiki.com) files
75
74
 
76
75
  ## Examples
@@ -90,7 +89,7 @@ Once installed, ask your AI assistant:
90
89
  - "What data do I need to implement ARR tracking?"
91
90
  - "Search for churn"
92
91
 
93
- **Diagnosis, exploration and coverage** (new in 1.9.0)
92
+ **Diagnosis, exploration and coverage**
94
93
  - "ARR is down this month. What could explain it?" (`infer_drivers`)
95
94
  - "How does Health Score eventually affect NRR?" (`explain_path`)
96
95
  - "We track ARR, NRR, GRR, CAC and CAC Payback. What important metrics are we missing?" (`coverage_gap`)
@@ -98,6 +97,4 @@ Once installed, ask your AI assistant:
98
97
 
99
98
  ## License
100
99
 
101
- <!-- TODO: add a "Source" link and package.json "repository" field to https://github.com/GASP-Standard/gasp once the repository is public. -->
102
-
103
- Apache-2.0
100
+ Apache-2.0. Source: https://github.com/GASP-Standard/standard (the standard itself is CC BY 4.0, see `standard/LICENSE` there).
@@ -19,13 +19,44 @@
19
19
  * at the period end. `all_time` drops it. `lag` shifts both bounds. `over cohort`
20
20
  * restricts every aggregate to keys present in the key's dataset at the point.
21
21
  * Intervals are emitted in units Postgres accepts (a quarter is 3 months).
22
+ * `ctx.dialect` picks another spelling for the warehouse-specific constructs
23
+ * (date shifts and differences, the double cast, percentiles): src/dialect.ts.
24
+ *
25
+ * A multi-argument count_distinct counts distinct tuples through a derived
26
+ * table: (SELECT COUNT(*) FROM (SELECT DISTINCT a, b FROM t WHERE ...) _pairs).
27
+ *
28
+ * A formula entry with `breakdown` compiles to one row per value of the field
29
+ * (and so does a named breakdown in `breakdowns`, compiled as a variant):
30
+ * SELECT _d.<field> AS <field>, <expr> AS <id>
31
+ * FROM (<domain>) _d
32
+ * Every aggregate not under total() gains `AND {{<field>@<ds>}} = _d.<field>`.
33
+ * The domain is the field's declared enum values as a UNION ALL of literals
34
+ * (no VALUES clause, which BigQuery lacks), else the distinct non-null values
35
+ * on the dataset keyed by the field, else on the first dataset the formula
36
+ * reads that carries it.
37
+ *
38
+ * A breakdown field may live only on a dataset D keyed by K (plan_name on plan,
39
+ * keyed by plan_id): an aggregate whose dataset carries K but not the field
40
+ * correlates on `{{K@ds}} = _d.<K>`, the domain is D's (K, field) rows (at
41
+ * period end when D is a snapshot) and the result carries both columns:
42
+ * SELECT _d.<K> AS <K>, _d.<field> AS <field>, <expr> AS <id> FROM (<domain>) _d
43
+ *
44
+ * A bucketed breakdown ({ expression, buckets }) groups by a per-row expression
45
+ * instead of a field: the domain is the bucket labels, the column is the
46
+ * breakdown name (or `bucket`), and each grouped aggregate gains
47
+ * AND CASE WHEN <expr> BETWEEN lo AND hi THEN '<label>' ... END = _d.<column>
48
+ * (an open top bucket is `>= lo`). The expression's fields must all live on
49
+ * the dataset of every grouped aggregate.
22
50
  */
23
- import { type LagUnit } from "./formula.js";
24
- import type { MetricFormula, OntologyDataset, OntologyField } from "./types.js";
51
+ import { type Node, type LagUnit } from "./formula.js";
52
+ import { type DialectName } from "./dialect.js";
53
+ import type { BreakdownSpec, MetricFormula, OntologyDataset, OntologyField } from "./types.js";
25
54
  export interface CompileContext {
26
55
  fields: Record<string, OntologyField>;
27
56
  datasets: Record<string, OntologyDataset>;
28
57
  formulas: Record<string, MetricFormula>;
58
+ /** SQL dialect of the output (src/dialect.ts); postgres when omitted */
59
+ dialect?: DialectName;
29
60
  }
30
61
  export interface Compiled {
31
62
  /** Scalar SELECT with placeholders */
@@ -38,12 +69,59 @@ export interface Compiled {
38
69
  metricRefs: string[];
39
70
  /** Uses cohort or lag, so it cannot run as one Ossie aggregate */
40
71
  staged: boolean;
72
+ /**
73
+ * Set when the entry declares a breakdown: the SQL returns one row per value of
74
+ * `field`, the output column. For a bucketed breakdown `field` is the column
75
+ * name (the breakdown name, or `bucket`) and `buckets` lists the labels.
76
+ */
77
+ breakdown?: {
78
+ field: string;
79
+ total?: boolean;
80
+ expression?: string;
81
+ buckets?: Record<string, [number, number | null]>;
82
+ via?: {
83
+ dataset: string;
84
+ key: string;
85
+ };
86
+ };
87
+ }
88
+ /** A checked breakdown: a field, or a bucketed per-row expression, and the total mode. */
89
+ export interface ResolvedBreakdown {
90
+ /** The output column: the field id, or the bucket column name */
91
+ column: string;
92
+ field?: string;
93
+ expression?: {
94
+ src: string;
95
+ node: Node;
96
+ fields: string[];
97
+ };
98
+ buckets?: Array<{
99
+ label: string;
100
+ lo: number;
101
+ hi: number | null;
102
+ }>;
103
+ total: boolean;
41
104
  }
42
105
  export declare class CompileError extends Error {
43
106
  }
44
107
  /** An interval literal in units Postgres, Redshift and Snowflake accept. */
45
108
  export declare function interval(n: number, unit: LagUnit): string;
46
109
  export declare function compileMetric(id: string, ctx: CompileContext, variant?: string): Compiled;
110
+ /**
111
+ * A breakdown spec checked against the ontology: "field.<id>", { field, total },
112
+ * or { expression, buckets, total }. `name` is the named breakdown's name, which
113
+ * becomes a bucketed breakdown's column (else `bucket`).
114
+ */
115
+ export declare function resolveBreakdown(ref: BreakdownSpec, ctx: Pick<CompileContext, "fields" | "datasets">, id?: string, name?: string): ResolvedBreakdown;
116
+ /** A breakdown spec (string or { field, total }) as a checked field id and total mode. */
117
+ export declare function breakdownSpec(ref: Exclude<BreakdownSpec, {
118
+ expression: string;
119
+ }>, ctx: Pick<CompileContext, "fields">, id?: string): {
120
+ field: string;
121
+ total: boolean;
122
+ };
123
+ /** The field id of an entry's `breakdown` ("field.<id>"), checked against the ontology. */
124
+ export declare function breakdownField(ref: string, ctx: Pick<CompileContext, "fields">, id?: string): string;
47
125
  /** Replace placeholders with plain names, for documentation examples. */
48
126
  export declare function exampleSql(sql: string): string;
49
127
  /** Strip the dataset tag from a field placeholder: "{{mrr@subscription}}" -> "{{mrr}}". */