@cyanheads/secedgar-mcp-server 0.13.0 → 0.13.1

package/dist/services/edgar/concept-series.d.ts

@@ -32,6 +32,21 @@ export type PeriodType = 'annual' | 'quarterly' | 'all';
  * concept is not reported at all".
  */
 export declare function resolveFrameSeries(units: readonly TagPrioritizedUnit[]): Map<string, FramedUnit>;
+/**
+ * Caveat for a concept that resolved to a tag SEC has retired from the taxonomy.
+ *
+ * A friendly name is a priority-ordered list of tags, and the lookup walks it
+ * until one returns data. When every current tag comes back empty for a filer,
+ * a deprecated tag at the end of the list can still match and produce a series
+ * that looks complete but stops around the tag's retirement — the failure is
+ * otherwise silent, since nothing in the values themselves says the tag is dead.
+ * The signal is the taxonomy label SEC already ships with the payload, so this
+ * generalizes to any concept whose fallback chain reaches a retired tag rather
+ * than to one hard-coded pair.
+ *
+ * Returns an empty array for a current tag, which is the common case.
+ */
+export declare function deprecatedTagCaveats(tag: string, label: string): string[];
 /**
  * Whether a frame belongs to the requested period type. `fp` reflects the source
  * filing rather than the data point, so the frame label is the only reliable

package/dist/services/edgar/concept-series.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"concept-series.d.ts","sourceRoot":"","sources":["../../../src/services/edgar/concept-series.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE3E,gFAAgF;AAChF,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAW,SAAQ,kBAAkB;IACpD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kDAAkD;AAClD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,KAAK,CAAC;AAQxD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAoBhG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAIhF;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,EAC3B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,aAAa,GAAG,SAAS,CA0B3B"}
+{"version":3,"file":"concept-series.d.ts","sourceRoot":"","sources":["../../../src/services/edgar/concept-series.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE3E,gFAAgF;AAChF,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAW,SAAQ,kBAAkB;IACpD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kDAAkD;AAClD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,KAAK,CAAC;AAgBxD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAoBhG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAMzE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAIhF;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,EAC3B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,aAAa,GAAG,SAAS,CA0B3B"}

package/dist/services/edgar/concept-series.js

@@ -8,6 +8,13 @@
  * than re-implementing the rules.
  * @module services/edgar/concept-series
  */
+/**
+ * SEC stamps a retired element's retirement date into the taxonomy label it
+ * serves with every companyconcept and companyfacts payload — e.g.
+ * `"Sales Revenue, Goods, Net (Deprecated 2018-01-31)"`. Matching it is the whole
+ * staleness signal; no extra upstream call is involved.
+ */
+const DEPRECATED_LABEL = /\(Deprecated\s+(\d{4}-\d{2}-\d{2})\)/i;
 /** Annual duration frame — `CY2023`. */
 const ANNUAL_FRAME = /^CY\d{4}$/;
 /** Quarterly frame — `CY2023Q3` (duration) or `CY2023Q3I` (instant). */
@@ -42,6 +49,28 @@ export function resolveFrameSeries(units) {
     }
     return resolved;
 }
+/**
+ * Caveat for a concept that resolved to a tag SEC has retired from the taxonomy.
+ *
+ * A friendly name is a priority-ordered list of tags, and the lookup walks it
+ * until one returns data. When every current tag comes back empty for a filer,
+ * a deprecated tag at the end of the list can still match and produce a series
+ * that looks complete but stops around the tag's retirement — the failure is
+ * otherwise silent, since nothing in the values themselves says the tag is dead.
+ * The signal is the taxonomy label SEC already ships with the payload, so this
+ * generalizes to any concept whose fallback chain reaches a retired tag rather
+ * than to one hard-coded pair.
+ *
+ * Returns an empty array for a current tag, which is the common case.
+ */
+export function deprecatedTagCaveats(tag, label) {
+    const match = DEPRECATED_LABEL.exec(label);
+    if (!match?.[1])
+        return [];
+    return [
+        `XBRL tag ${tag} was retired from the taxonomy on ${match[1]} — SEC labels it "${label}". It matched only because every current tag ahead of it in this concept's priority list reports nothing for this filer, so the series can end years before the filer's latest report. Check secedgar_search_concepts for the concept's full tag list, or pass the tag this filer reports today.`,
+    ];
+}
 /**
  * Whether a frame belongs to the requested period type. `fp` reflects the source
  * filing rather than the data point, so the frame label is the only reliable

package/dist/services/edgar/concept-series.js.map

@@ -1 +1 @@
-{"version":3,"file":"concept-series.js","sourceRoot":"","sources":["../../../src/services/edgar/concept-series.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"concept-series.js","sourceRoot":"","sources":["../../../src/services/edgar/concept-series.ts"],"names":[],"mappings":"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"}

package/dist/services/edgar/fiscal-periods.d.ts

@@ -19,7 +19,7 @@
  */
 export declare function fiscalQ4Caveats(period: string): string[];
 /**
- * Caveat for one filer's frame-tagged quarterly series: name the calendar
+ * Caveat for one filer's frame-tagged quarterly series: name every calendar
  * quarter that never appears, so a caller can tell "the company did not report"
  * apart from "the frame tagging does not expose it".
  *
@@ -28,10 +28,15 @@ export declare function fiscalQ4Caveats(period: string): string[];
  * inside it a year counts only when it reports at least
  * {@link MIN_QUARTERS_PER_YEAR} of the four calendar quarters (partial first/last
  * years carry no signal), and a caveat is emitted only when at least
- * {@link MIN_YEARS} of the counting years all omit the same single quarter. A
- * year inside the window that reports all four quarters, two that disagree about
- * which quarter is missing, or a window too sparse to reach the quorum all
- * suppress the caveat.
+ * {@link MIN_YEARS} of the counting years agree on a non-empty set of absent
+ * quarters. A year inside the window that reports all four quarters, years that
+ * disagree so no quarter is absent from all of them, or a window too sparse to
+ * reach the quorum all suppress the caveat.
+ *
+ * One or two quarters can be absent — the per-year quorum bounds it there. A
+ * single absent quarter is the fiscal-Q4 residual; a second one means the
+ * filer's fiscal quarters do not line up with calendar quarters at all, so
+ * further durations match no `CY####Q#` frame.
  */
 export declare function missingQuarterCaveats(frames: Iterable<string>): string[];
 //# sourceMappingURL=fiscal-periods.d.ts.map

package/dist/services/edgar/fiscal-periods.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fiscal-periods.d.ts","sourceRoot":"","sources":["../../../src/services/edgar/fiscal-periods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAqCH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAOxD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CA8BxE"}
+{"version":3,"file":"fiscal-periods.d.ts","sourceRoot":"","sources":["../../../src/services/edgar/fiscal-periods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8CH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAOxD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CA2CxE"}

package/dist/services/edgar/fiscal-periods.js

@@ -23,8 +23,17 @@ const FISCAL_Q4_EXAMPLES = {
 };
 /** Duration quarterly frame (`CY2024Q2`). Instant frames (`CY2024Q2I`) are excluded. */
 const DURATION_QUARTER_FRAME = /^CY(\d{4})Q([1-4])$/;
-/** A year needs at least this many reported quarters before its gaps carry signal. */
-const MIN_QUARTERS_PER_YEAR = 3;
+/**
+ * A year needs at least this many reported quarters before its gaps carry
+ * signal. Two, not three: a filer can lose more than one calendar quarter to
+ * frame tagging — Costco's fiscal Q2 and fiscal Q4 durations both fall outside
+ * the quarters SEC frames, leaving a steady two per year — and a three-of-four
+ * quorum reads that as a sparse year and suppresses the caveat entirely. Two is
+ * also the floor at which a year still carries signal: it bounds the absent set
+ * at two quarters, so a year reporting a single quarter (a stub, a first year of
+ * filings) cannot drag three quarters into the caveat.
+ */
+const MIN_QUARTERS_PER_YEAR = 2;
 /** At least this many qualifying years must agree before a gap is called systematic. */
 const MIN_YEARS = 2;
 /**
@@ -57,7 +66,7 @@ export function fiscalQ4Caveats(period) {
     ];
 }
 /**
- * Caveat for one filer's frame-tagged quarterly series: name the calendar
+ * Caveat for one filer's frame-tagged quarterly series: name every calendar
  * quarter that never appears, so a caller can tell "the company did not report"
  * apart from "the frame tagging does not expose it".
  *
@@ -66,10 +75,15 @@ export function fiscalQ4Caveats(period) {
  * inside it a year counts only when it reports at least
  * {@link MIN_QUARTERS_PER_YEAR} of the four calendar quarters (partial first/last
  * years carry no signal), and a caveat is emitted only when at least
- * {@link MIN_YEARS} of the counting years all omit the same single quarter. A
- * year inside the window that reports all four quarters, two that disagree about
- * which quarter is missing, or a window too sparse to reach the quorum all
- * suppress the caveat.
+ * {@link MIN_YEARS} of the counting years agree on a non-empty set of absent
+ * quarters. A year inside the window that reports all four quarters, years that
+ * disagree so no quarter is absent from all of them, or a window too sparse to
+ * reach the quorum all suppress the caveat.
+ *
+ * One or two quarters can be absent — the per-year quorum bounds it there. A
+ * single absent quarter is the fiscal-Q4 residual; a second one means the
+ * filer's fiscal quarters do not line up with calendar quarters at all, so
+ * further durations match no `CY####Q#` frame.
  */
 export function missingQuarterCaveats(frames) {
     const quartersByYear = new Map();
@@ -96,11 +110,20 @@ export function missingQuarterCaveats(frames) {
         for (const quarter of quarters)
             absent.delete(quarter);
     }
-    const [missing] = absent;
-    if (absent.size !== 1 || !missing)
+    if (absent.size === 0)
         return [];
+    const missing = [...absent].sort();
+    const subject = missing.length === 1
+        ? `Calendar Q${missing[0]} carries`
+        : `Calendar ${missing.map((q) => `Q${q}`).join(' and ')} carry`;
+    const cause = missing.length === 1
+        ? 'SEC XBRL reports fiscal Q4 as the 10-K residual rather than a discrete quarterly fact, so the calendar quarter that fiscal Q4 spans drops out of the quarterly series — the period was reported, the frame tagging does not expose it.'
+        : "SEC XBRL reports fiscal Q4 as the 10-K residual rather than a discrete quarterly fact, and this filer's remaining fiscal quarters span durations that no standard calendar quarter matches, so both drop out of the quarterly series — the periods were reported, the frame tagging does not expose them.";
+    const recovery = missing.length === 1
+        ? "Use period_type='annual' for the full-year figure, or derive the missing quarter as the annual total minus the three reported quarters."
+        : "Use period_type='annual' for the full-year figure; the absent quarters can only be derived together, as the annual total minus the reported quarters, never one at a time.";
     return [
-        `Calendar Q${missing} carries no frame-tagged value in any of this filer's recent fully-reported years. SEC XBRL reports fiscal Q4 as the 10-K residual rather than a discrete quarterly fact, so the calendar quarter that fiscal Q4 spans drops out of the quarterly series — the period was reported, the frame tagging does not expose it. Use period_type='annual' for the full-year figure, or derive the missing quarter as the annual total minus the three reported quarters.`,
+        `${subject} no frame-tagged value in any of this filer's recent qualifying years. ${cause} ${recovery}`,
     ];
 }
 //# sourceMappingURL=fiscal-periods.js.map

package/dist/services/edgar/fiscal-periods.js.map

@@ -1 +1 @@
-{"version":3,"file":"fiscal-periods.js","sourceRoot":"","sources":["../../../src/services/edgar/fiscal-periods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,kBAAkB,GAA2B;IACjD,GAAG,EAAE,6CAA6C;IAClD,GAAG,EAAE,yCAAyC;IAC9C,GAAG,EAAE,sCAAsC;IAC3C,GAAG,EAAE,6DAA6D;CACnE,CAAC;AAEF,wFAAwF;AACxF,MAAM,sBAAsB,GAAG,qBAAqB,CAAC;AAErD,sFAAsF;AACtF,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEhC,wFAAwF;AACxF,MAAM,SAAS,GAAG,CAAC,CAAC;AAEpB;;;;;;;;;;GAUG;AACH,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAChD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAoC,CAAC;IACtD,OAAO;QACL,0CAA0C,CAAC,mIAAmI,kBAAkB,CAAC,CAAC,CAAC,4EAA4E;KAChR,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAwB;IAC5D,MAAM,cAAc,GAAG,IAAI,GAAG,EAAuB,CAAC;IACtD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjD,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YAAE,SAAS;QACvC,IAAI,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;YACrB,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACzC,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,aAAa,GAAG,CAAC,GAAG,cAAc,CAAC,OAAO,EAAE,CAAC;SAChD,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACtC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC;SACtB,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,IAAI,qBAAqB,CAAC;SAChE,GAAG,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,aAAa,CAAC,MAAM,GAAG,SAAS;QAAE,OAAO,EAAE,CAAC;IAEhD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7C,KAAK,MAAM,QAAQ,IAAI,aAAa,EAAE,CAAC;QACrC,KAAK,MAAM,OAAO,IAAI,QAAQ;YAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACzD,CAAC;IACD,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;IACzB,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAE7C,OAAO;QACL,aAAa,OAAO,mcAAmc;KACxd,CAAC;AACJ,CAAC"}
+{"version":3,"file":"fiscal-periods.js","sourceRoot":"","sources":["../../../src/services/edgar/fiscal-periods.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/secedgar-mcp-server",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Query SEC EDGAR filings, XBRL financials, and company data through MCP. STDIO & Streamable HTTP.",
   "mcpName": "io.github.cyanheads/secedgar-mcp-server",
   "type": "module",

package/server.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/cyanheads/secedgar-mcp-server",
     "source": "github"
   },
-  "version": "0.13.0",
+  "version": "0.13.1",
   "remotes": [
     {
       "type": "streamable-http",
@@ -19,7 +19,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/secedgar-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.13.0",
+      "version": "0.13.1",
       "environmentVariables": [
         {
           "name": "EDGAR_USER_AGENT",
@@ -44,7 +44,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/secedgar-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.13.0",
+      "version": "0.13.1",
       "environmentVariables": [
         {
           "name": "EDGAR_USER_AGENT",