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 +28 -31
- package/build/compile.d.ts +80 -2
- package/build/compile.js +282 -17
- package/build/derive.d.ts +1 -3
- package/build/derive.js +27 -22
- package/build/dialect.d.ts +62 -0
- package/build/dialect.js +66 -0
- package/build/export-data.d.ts +3 -1
- package/build/export-data.js +5 -14
- package/build/filters.d.ts +16 -0
- package/build/filters.js +92 -0
- package/build/formula.d.ts +27 -1
- package/build/formula.js +89 -10
- package/build/fuzzy.d.ts +34 -0
- package/build/fuzzy.js +95 -0
- package/build/index.js +161 -88
- package/build/loader.d.ts +88 -8
- package/build/loader.js +278 -137
- package/build/ossie/index.js +1 -1
- package/build/ossie/metrics.d.ts +14 -2
- package/build/ossie/metrics.js +44 -4
- package/build/ossie/model.d.ts +13 -3
- package/build/ossie/model.js +66 -19
- package/build/parser.js +14 -1
- package/build/standard-data.json +1 -1
- package/build/standard-version.json +1 -1
- package/build/tools.d.ts +108 -21
- package/build/tools.js +269 -88
- package/build/traversal.d.ts +9 -9
- package/build/traversal.js +37 -2
- package/build/types.d.ts +79 -1
- package/package.json +5 -5
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
|
|
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,
|
|
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
|
|
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:
|
|
42
|
-
| `search` |
|
|
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 (
|
|
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:
|
|
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
|
|
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.
|
|
53
|
+
Version 1.14.0.
|
|
54
54
|
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
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
|
-
-
|
|
60
|
-
-
|
|
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` (
|
|
63
|
-
-
|
|
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
|
-
-
|
|
66
|
-
-
|
|
67
|
-
- Canonical formulas for every metric in the GASP formula grammar (`standard/formulas.json`): 289 entries covering all
|
|
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 (
|
|
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
|
-
-
|
|
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**
|
|
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
|
-
|
|
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).
|
package/build/compile.d.ts
CHANGED
|
@@ -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
|
|
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}}". */
|