@cyanheads/secedgar-mcp-server 0.15.4 → 0.15.6

package/changelog/0.5.x/0.5.0.md

@@ -0,0 +1,35 @@
+---
+summary: "In-conversation SQL analytics over SEC EDGAR. `secedgar_search_filings`, `secedgar_get_financials`, and the new `secedgar_fetch_frames` (renamed from `secedgar_compare_metric`) now materialize their full upstream response as a DuckDB-backed `df_<id>` dataframe, queryable via three new `secedgar_dataframe_*` tools."
+breaking: true
+---
+
+# 0.5.0 — 2026-05-17
+
+In-conversation SQL analytics. Three data-returning tools now spill their full upstream response onto a shared DuckDB canvas, addressable by `df_<id>` and queryable via standard DuckDB SQL across the new `secedgar_dataframe_*` tools. Closes [#17](https://github.com/cyanheads/secedgar-mcp-server/issues/17).
+
+## Added
+
+- **`secedgar_fetch_frames`** — replaces `secedgar_compare_metric`. Same friendly-concept × calendar-period × unit input, but the inline response now carries `value_distribution` (median, p95, max, max_to_p95_ratio), `period_end_range` (min/max across the frame, surfaces fiscal-year mixing), and `unqueried_tags` (other XBRL tags in the same friendly-name mapping the call did NOT query, so the LLM can fan out and UNION/COALESCE).
+- **`secedgar_dataframe_describe`** — list canvas dataframes with `source_tool`, `query_params`, `created_at`, `expires_at`, `row_count`, `column_schema`, and `truncated`.
+- **`secedgar_dataframe_query`** — single-statement SELECT against the shared canvas. Framework's three-layer SQL gate (single-statement → SELECT only → plan-walk allowlist) plus a bridge-layer deny on `information_schema`, `pg_catalog`, `sqlite_master`, and `duckdb_*` system catalogs so callers can't enumerate `df_<id>` handles they don't already hold. Optional `register_as` chains the result as a new dataframe with a fresh per-table TTL.
+- **`secedgar_dataframe_drop`** — idempotent drop. Opt-in via `EDGAR_DATAFRAME_DROP_ENABLED=true`; off by default since TTL already handles cleanup. The only destructive tool on this server.
+- **`dataset` field on `secedgar_search_filings`, `secedgar_get_financials`, `secedgar_fetch_frames`** — each call returns a `df_XXXXX_XXXXX` handle, row count, and ISO 8601 `expires_at`. `secedgar_search_filings` also reports `truncated: true` when EFTS has more text matches than the response window. Absent when no canvas is wired (e.g. Workers, `CANVAS_PROVIDER_TYPE=none`), when materialization failed, or when the inline response already fits.
+- **`ticker` field on `secedgar_search_filings` results** — primary ticker parsed from the EFTS `display_names[0]` parenthetical, with hyphen-aware regex for multi-class issuers (BRK-A / BRK-B). Absent for private filers, foreign filers without a US listing, and filings whose display name omits a ticker parenthetical.
+- **`CanvasBridge`** — `src/services/canvas-bridge/canvas-bridge.ts`. One shared canvas per tenant via `ctx.state['canvas-id']`. Tools call `bridge.registerDataframe({ rows, sourceTool, queryParams })` to mint `df_XXXXX_XXXXX` (~3.7×10^15 keyspace) and persist provenance + per-table TTL (`EDGAR_DATASET_TTL_SECONDS`, default 86400) under `df-meta/<table>`. Lazy TTL sweep on every public op. All-nullable column schemas via `deriveAllNullableSchema` — sparse SEC columns (`loc`, `ticker`, `start`) must not trip DuckDB's NOT NULL appender rollback.
+- **`sql-gate-extras`** — `src/services/canvas-bridge/sql-gate-extras.ts`. `assertNoSystemCatalogAccess` strips string literals first, then rejects `information_schema`, `pg_catalog`, `sqlite_master`, `duckdb_*` references. Layered on top of the framework's plan-walk gate.
+- **`EDGAR_DATASET_TTL_SECONDS`** (default `86400`) — per-table TTL for canvas-registered dataframes. Bridge-side bookkeeping in `ctx.state`; backstop for [cyanheads/mcp-ts-core#140](https://github.com/cyanheads/mcp-ts-core/issues/140) until the framework exposes `RegisterTableOptions.ttlMs`.
+- **`EDGAR_DATAFRAME_DROP_ENABLED`** (default `false`) — gates registration of `secedgar_dataframe_drop`.
+- **`CANVAS_PROVIDER_TYPE`** (default `duckdb`) — `src/index.ts` opts the canvas on by default (DuckDB ships as a direct dep). Set to `none` on Cloudflare Workers, where DuckDB has no V8-isolate build.
+- **`@duckdb/node-api ^1.5.2-r.1`** direct dependency — DuckDB is now in the install tree, not an optional peer.
+
+## Changed
+
+- **`EdgarApiService.getTickerCache` is now singleflight.** Concurrent first-time callers (e.g. `secedgar_fetch_frames` enriching ~5k reporters in parallel) share one in-flight `loadTickerCache()` instead of each queuing their own SEC fetch through the 10 req/s throttle. Cache key timestamp now uses post-fetch `Date.now()` so the TTL window measures cached lifetime, not wall-clock from before the request.
+- **`secedgar_search_filings` `cleanCompanyName` regex** allows hyphens in the trailing parenthetical to keep multi-class ticker symbols (BRK-A, BRK-B) intact during stripping. Format string now renders `(TICKER, CIK …)` when a ticker is parsed, falling back to `(CIK …)` otherwise.
+- **`FrameEntry.start`** field added to the EDGAR types — present on duration frames, absent on instant frames. Surfaced in the canvas row as `period_start`.
+- **`createApp({ setup })`** signature in `src/index.ts` now takes the framework `core` argument and passes `core.canvas` to `initCanvasBridge`.
+- **`instructions` orientation string** updated for the new tool surface: `secedgar_compare_metric` reference replaced with `secedgar_fetch_frames`, plus a sentence on the `df_<id>` materialization flow and `secedgar_dataframe_query` / `secedgar_dataframe_describe`.
+
+## Removed
+
+- **`secedgar_compare_metric`** — renamed to `secedgar_fetch_frames`. Wire signature changed: `data[]` rows still carry `rank`, `company_name`, `cik`, `ticker`, `value`, `period_end`, `accession_number`, but `location` is now optional (absent when SEC has no location for the filer), and the inline response adds `value_distribution`, `period_end_range`, `unqueried_tags`, and the optional `dataset` handle. Callers should migrate the tool name and add handling for the new fields.

package/changelog/0.5.x/0.5.1.md

@@ -0,0 +1,13 @@
+---
+summary: "`secedgar_fetch_frames` flags fiscal-Q4 silent dropout on `CY####Q[1-4]` periods via a new `caveats` field. Ticker enrichment now resolves multi-class CIKs to common stock (JPM, BAC, C) instead of preferred-share variants (JPM-PA, BAC-PS, C-PR)."
+---
+
+# 0.5.1 — 2026-05-17
+
+## Added
+
+- **`caveats: string[]` on `secedgar_fetch_frames`** — populated when the queried period matches `^CY\d{4}Q[1-4]$`. SEC XBRL reports fiscal Q4 as the 10-K residual rather than a discrete quarterly fact, so any filer whose fiscal year ends inside the queried calendar quarter is silently absent from a `CY####Q[1-4]` frame. The caveat names the affected fiscal-year-end bucket with examples (e.g. `AAPL Sep-end, ACN Aug-end, CSCO Jul-end, COST early Sep` for Q3) and points callers at `secedgar_get_financials` with `period_type='annual'` for those filers. Empty array for annual (`CY####`) and instant (`CY####Q#I`) periods, where the underlying facts exist. Surfaced in `format()` as `Caveat: …` lines. Closes [#10](https://github.com/cyanheads/secedgar-mcp-server/issues/10).
+
+## Fixed
+
+- **`EdgarApiService` `byCik` index** picks common stock over preferred-share, debt-security, and multi-class variants when SEC's `company_tickers.json` lists multiple ticker entries against one CIK. New `pickPreferredTicker(a, b)` export resolves ties by: (1) hyphen-free wins over hyphenated (`JPM` beats `JPM-PA`), (2) otherwise the incumbent wins (SEC lists common stock first, so `PRU` stays seated against later `PFH`/`PRH`/`PRS`). Replaces the prior last-write-wins behavior that surfaced `JPM-PM`, `BAC-PS`, `C-PR` in `secedgar_fetch_frames` and `secedgar_search_filings` output. Closes [#8](https://github.com/cyanheads/secedgar-mcp-server/issues/8).

package/changelog/0.5.x/0.5.2.md

@@ -0,0 +1,13 @@
+---
+summary: "`@cyanheads/mcp-ts-core ^0.9.1 → ^0.9.6`. `RequestContextLike` canvas cast removed. `zod` added as explicit dependency. `manifest.json` + `.mcpbignore` scaffolded for MCPB bundle support. Install badges added to README."
+---
+
+# 0.5.2 — 2026-05-23
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core` `^0.9.1 → ^0.9.6`** — picks up all upstream fixes across the series: OTel attribute type corrections, context-state key-lookup improvements, `spillover()` reliability fixes, and linter rule additions (`server-json-*`, `schema-format-portability`).
+- **`RequestContextLike` canvas cast removed** — `CanvasBridge` now receives a concrete `Context` directly; the intermediate cast was unnecessary after the framework stabilized `RequestContextLike`'s exported shape.
+- **`zod` added as explicit dependency** — was previously only a transitive dep from the framework; now declared in `dependencies` for `z` re-exports used in tool schemas.
+- **`manifest.json` + `.mcpbignore` scaffolded** — enables `bun run bundle` to produce a `.mcpb` extension bundle for one-click Claude Desktop install via `@anthropic-ai/mcpb`.
+- **Install badges added to README** — Visual Studio Code and Claude Desktop one-click install buttons.

package/changelog/0.6.x/0.6.0.md

@@ -0,0 +1,24 @@
+---
+summary: "Concept catalog 16 → 33; get_financials companyfacts probe on no_concept_data; FY bracket label dropped; get_filing primary_document preserved on exhibit fetches; search_filings form_distribution fixed for forms filter; fiscal_year_end formatted MM-DD."
+breaking: false
+security: false
+---
+
+# 0.6.0 — 2026-05-25
+
+## Added
+
+- **`concept-map.ts` expanded from 16 → 33 entries** — 17 new friendly names across income statement (`cogs`, `rd_expense`, `sga_expense`, `interest_expense`, `tax_expense`, `stock_based_compensation`), balance sheet (`current_assets`, `current_liabilities`, `inventory`, `accounts_receivable`, `accounts_payable`, `goodwill`, `intangible_assets`), and cash flow (`dividends_paid`, `share_repurchases`, `investing_cash_flow`, `financing_cash_flow`). ([#12](https://github.com/cyanheads/secedgar-mcp-server/issues/12))
+- **`get_financials` probes `companyfacts` on `no_concept_data`** — when no XBRL data is found, surfaces actual namespaces and matching tags from the filer's `companyfacts` payload so callers have concrete fallback options. `available_namespaces` added to error data. Adds `EdgarApiService.tryGetCompanyFacts`. ([#13](https://github.com/cyanheads/secedgar-mcp-server/issues/13))
+- **`get_filing` adds `requested_document` field** — present only when the document param targets an exhibit that differs from `primary_document`. ([#4](https://github.com/cyanheads/secedgar-mcp-server/issues/4))
+
+## Changed
+
+- **`get_financials` fiscal context format** — changed from the bracket notation `[FY2023 FY]` to a parenthetical inline with the form: `10-K (FY2023 FY)`. ([#11](https://github.com/cyanheads/secedgar-mcp-server/issues/11))
+- **`company_search` `fiscal_year_end`** — formatted as `MM-DD` (e.g. `09-26`) instead of the raw `MMDD` string from the SEC API. ([#14](https://github.com/cyanheads/secedgar-mcp-server/issues/14))
+- **`search_filings` `forms` param description** — notes that amendment types (e.g. `10-K/A`) are included when filtering by base form. ([#14](https://github.com/cyanheads/secedgar-mcp-server/issues/14))
+
+## Fixed
+
+- **`get_filing` `primary_document`** — now always reflects the filing's actual primary document regardless of the `document` param. Previously, fetching an exhibit overwrote `primary_document` with the exhibit filename. ([#4](https://github.com/cyanheads/secedgar-mcp-server/issues/4))
+- **`search_filings` `form_distribution`** — was recomputed from post-filter hits only when entity targeting was active. Now also recomputed when a `forms` filter is applied, keeping counts consistent with `total`. ([#6](https://github.com/cyanheads/secedgar-mcp-server/issues/6))

package/changelog/0.6.x/0.6.1.md

@@ -0,0 +1,21 @@
+---
+summary: "mcp-ts-core ^0.9.6 → ^0.9.9: git-wrapup skill, ctx.elicit/ctx.fail/ctx.notifyPromptListChanged/ctx.notifyToolListChanged docs, release artifact verification, structured tag annotation format; @duckdb/node-api ^1.5.3-r.1 → ^1.5.3-r.2; stdio/streamable-http npm keywords added."
+breaking: false
+security: false
+---
+
+# 0.6.1 — 2026-05-25
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core` ^0.9.6 → ^0.9.9** — picks up three framework releases:
+  - 0.9.7: structured tag annotation format; release artifact verification step added to release-and-publish skill; changelog template tag annotation example added
+  - 0.9.8: git-wrapup skill added; `ctx.elicit`, `ctx.fail`, `ctx.notifyPromptListChanged`, `ctx.notifyToolListChanged` documented in api-context skill; `@hono/node-server` ^2.0.3 → ^2.0.4
+  - 0.9.9: "Close the loop on issues" rule added to CLAUDE.md/AGENTS.md; `fast-check` moved to optional peer dep; `split-changelog.ts` removed
+- **`@duckdb/node-api` ^1.5.3-r.1 → ^1.5.3-r.2**
+- **npm keywords** — `stdio` and `streamable-http` added to `package.json`
+- **`skills/git-wrapup`** — new skill synced from framework 0.9.8
+- **`skills/release-and-publish`** — artifact verification step (v2.5 → v2.6) synced from framework 0.9.7
+- **`CLAUDE.md` / `AGENTS.md`** — "Close the loop on issues" rule and git-wrapup skill reference added
+- **`changelog/template.md`** — tag annotation format example added
+- **`scripts/check-framework-antipatterns.ts`** — header comment clarified

package/changelog/0.6.x/0.6.2.md

@@ -0,0 +1,34 @@
+---
+summary: "mcp-ts-core ^0.9.9 → ^0.9.13: HTTP body cap (413), session-init gate, quieter 401/403/400/404 logs, GET /mcp keywords; @biomejs/biome ^2.4.15 → ^2.4.16; plugin metadata files; code-simplifier skill."
+breaking: false
+security: true
+---
+
+# 0.6.2 — 2026-05-28
+
+## Added
+
+- **`.claude-plugin/`** and **`.codex-plugin/`** — plugin metadata files for Claude Code and Codex plugin discovery.
+- **`skills/code-simplifier/`** — post-session code review and cleanup skill synced from framework 0.9.11.
+- **`MCP_HTTP_MAX_BODY_BYTES`** — inbound request-body cap on the HTTP MCP endpoint (default 1 MiB). Oversized requests are rejected with `413` before the request body is parsed. Set to `0` to disable. Documented in `.env.example`. (via mcp-ts-core 0.9.13, [#157](https://github.com/cyanheads/mcp-ts-core/issues/157))
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core` ^0.9.9 → ^0.9.13** — four framework releases:
+  - 0.9.10: HTTP session-init gate — stateful HTTP mode rejects non-`initialize` requests without `Mcp-Session-Id` with HTTP 400 ([#154](https://github.com/cyanheads/mcp-ts-core/issues/154)); expected client errors (401, 403, 400, 404) now log at `warning` level without stack traces ([#158](https://github.com/cyanheads/mcp-ts-core/issues/158))
+  - 0.9.11: `code-simplifier` skill added; `mcp-ts-core init --help` flag added
+  - 0.9.12: `GET /mcp` status JSON now includes `package.json` `keywords` ([#165](https://github.com/cyanheads/mcp-ts-core/issues/165))
+  - 0.9.13: `MCP_HTTP_MAX_BODY_BYTES` 413 body cap; `landing.requireAuth` defaults to `true` when auth mode is `jwt` or `oauth` ([#157](https://github.com/cyanheads/mcp-ts-core/issues/157), [#156](https://github.com/cyanheads/mcp-ts-core/issues/156))
+- **`@biomejs/biome` ^2.4.15 → ^2.4.16**
+- **`manifest.json`** — `repository`, `homepage`, and `license` fields added.
+- **`skills/`** — `api-canvas`, `api-config`, `design-mcp-server`, `git-wrapup`, `polish-docs-meta`, `release-and-publish`, `report-issue-framework` updated from framework sync.
+- **`CLAUDE.md` / `AGENTS.md`** — plugin file checklist items and skill table entries added.
+- **`changelog/template.md`** — `agent-notes` frontmatter field documented.
+
+## Security
+
+- **HTTP request-body cap** — `MCP_HTTP_MAX_BODY_BYTES` (default 1 MiB) rejects oversized bodies with `413` before parsing, guarding against request-body amplification on the HTTP transport.
+
+## Removed
+
+- **`skills/migrate-mcp-ts-template/SKILL.md`** — migration-era skill removed (framework 0.9.12).

package/changelog/0.6.x/0.6.3.md

@@ -0,0 +1,23 @@
+---
+summary: "enrichment adoption — search/concept tools surface query echoes and empty-result guidance via typed enrichment block"
+breaking: false
+security: false
+---
+
+# 0.6.3 — 2026-05-30
+
+## Added
+
+- **`enrichment` block** on `secedgar_search_filings`, `secedgar_search_concepts`, `secedgar_company_search`, and `secedgar_dataframe_query` — populates via `ctx.enrich` so agent-facing context reaches both `structuredContent` JSON and the `content[]` markdown trailer automatically.
+  - `secedgar_search_filings`: echoes `effectiveQuery` (the query as EDGAR executed it) and surfaces a `notice` with empty-result guidance including entity targeting syntax hints.
+  - `secedgar_search_concepts`: surfaces a `notice` with empty-result guidance including applied filters and a full-catalog fallback suggestion.
+  - `secedgar_company_search`: surfaces a `notice` when `include_filings=true` but no filings matched the `form_types` filter.
+  - `secedgar_dataframe_query`: surfaces a `notice` for 0-row results (prompts `secedgar_dataframe_describe` verification) and row-cap hits (suggests `register_as` or raising `row_limit`).
+- `dataframe-query.tool.test.ts` and `search-concepts.tool.test.ts` — enrichment and edge-case coverage for the two newly-enriched tools.
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core`** `^0.9.13 → ^0.9.16` — picks up `ctx.enrich` API, enrichment lint rules, and stale-skill detection in the skills-sync check.
+- **`secedgar_search_concepts` `format()`** — empty-result path now returns `Found 0 concepts.` (plain count); the actionable guidance moves to the `enrichment.notice` channel instead of the markdown body.
+- **Skills** updated to `^0.9.16` framework: `add-tool`, `add-app-tool`, `add-service`, `api-context` (ctx.enrich API), `api-linter` (enrichment rules), `design-mcp-server`, `git-wrapup`, `maintenance`, `polish-docs-meta`, `setup`; `devcheck` skill removed (merged into framework devcheck).
+- **`format` / `format:unsafe`** split into two scripts in `package.json` — `format` runs safe Biome fixes; `format:unsafe` runs unsafe rewrites.

package/changelog/0.7.x/0.7.0.md

@@ -0,0 +1,25 @@
+---
+summary: "Insider transactions (Form 3/4/5), institutional holdings (13F), IFRS friendly-name resolution, ambiguous-company guard, and system_catalog_access error contract"
+breaking: false
+security: false
+---
+
+# 0.7.0 — 2026-05-30
+
+## Added
+
+- **`secedgar_get_insider_transactions`** — Form 3/4/5 insider activity for a company, parsed from ownership XML: reporting person, relationship, transaction date, type, shares, price, and post-transaction ownership. Supports `transaction_type` filter (`purchase`, `sale`, `all`). ([#18](https://github.com/cyanheads/secedgar-mcp-server/issues/18))
+- **`secedgar_get_institutional_holdings`** — 13F-HR quarterly institutional holdings parsed from the information table: issuer name, CUSIP, market value, shares, put/call, investment discretion, and filing manager name. Supports `quarter` filter (e.g. `"2025-Q4"`). ([#18](https://github.com/cyanheads/secedgar-mcp-server/issues/18))
+- **IFRS friendly-name resolution** in `secedgar_get_financials` and `secedgar_search_concepts` — `revenue`, `net_income`, and `assets` now resolve to their `ifrs-full` tag equivalents when `taxonomy: "ifrs-full"` is passed; `search_concepts` surfaces these entries instead of returning an empty set. ([#19](https://github.com/cyanheads/secedgar-mcp-server/issues/19))
+- **`ambiguous_company` error** in `secedgar_get_financials` — thrown when `resolveCik` returns multiple matches, with a `matches` list (CIK, name, ticker) so agents can select the correct entity and retry. ([#23](https://github.com/cyanheads/secedgar-mcp-server/issues/23))
+- **`system_catalog_access` error contract** declared in `secedgar_dataframe_query`'s `errors[]` array — the bridge-layer deny on DuckDB system catalogs (`information_schema`, `pg_catalog`, `sqlite_master`, `duckdb_*`) now surfaces as a typed, documented reason. ([#22](https://github.com/cyanheads/secedgar-mcp-server/issues/22))
+
+## Fixed
+
+- **Stale `secedgar_compare_metric` references** in `search-concepts.tool.ts`, `concepts.resource.ts`, and `company-analysis.prompt.ts` updated to `secedgar_fetch_frames`. ([#20](https://github.com/cyanheads/secedgar-mcp-server/issues/20))
+
+## Dependencies
+
+- `+ domhandler ^6.0.1` (Form 4/13F XML parsing)
+- `+ domutils ^4.0.2`
+- `+ htmlparser2 ^12.0.0`

package/changelog/0.7.x/0.7.1.md

@@ -0,0 +1,12 @@
+---
+summary: "Empty strings now rejected for required string fields — company/concept on secedgar_get_financials and concept/period on secedgar_fetch_frames return a clean ValidationError instead of reaching the handler."
+breaking: false
+security: false
+---
+
+# 0.7.1 — 2026-05-30
+
+## Fixed
+
+- **`secedgar_get_financials`** — `company` and `concept` now carry `.min(1)`; empty strings return `MCP error -32602 ValidationError` before the handler runs. ([#24](https://github.com/cyanheads/secedgar-mcp-server/issues/24))
+- **`secedgar_fetch_frames`** — `concept` and `period` now carry `.min(1)`; same validation gate. ([#24](https://github.com/cyanheads/secedgar-mcp-server/issues/24))

package/changelog/0.7.x/0.7.2.md

@@ -0,0 +1,23 @@
+---
+summary: "Opt-in local SQLite mirror of company_tickers and XBRL company-facts via MirrorService; routed lookups hit SQLite with live-API fallback. Adds EDGAR_MIRROR_* env vars, mirror:init/refresh/verify scripts, and Node/Bun-only Workers guard."
+breaking: false
+security: false
+---
+
+# 0.7.2 — 2026-05-31
+
+## Added
+
+- **Local mirror (opt-in)** — set `EDGAR_MIRROR_ENABLED=true` to route `resolveCik`, `tryGetCompanyConcept`, and `tryGetFrames` to a local SQLite mirror of `company_tickers.json` + the `companyfacts.zip` bulk archive. Live-API fallback on miss controlled by `EDGAR_MIRROR_FALLBACK_LIVE` (default `true`). ([#21](https://github.com/cyanheads/secedgar-mcp-server/issues/21))
+- **`EDGAR_MIRROR_PATH`** — directory for the mirror SQLite databases (default `./data/edgar-mirror`).
+- **`EDGAR_MIRROR_REFRESH_CRON`** — in-process nightly refresh schedule for HTTP transport (e.g. `0 9 * * *`); omit to refresh out-of-band.
+- **`EDGAR_MIRROR_FALLBACK_LIVE`** — set `false` for strict mirror-only reads.
+- **`bun run mirror:init`** — one-time bootstrap: downloads `company_tickers.json` + streams `companyfacts.zip` into SQLite. Resumable.
+- **`bun run mirror:refresh`** — incremental refresh from SEC bulk files.
+- **`bun run mirror:verify`** — prints sync status and runs sample reads.
+- **`better-sqlite3 ^12.10.0`** and **`fflate ^0.8.2`** — new production deps for the mirror store and zip streaming.
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core`** `^0.9.16 → ^0.9.19` — devcheck enhancements, skill-version checks, `release-github` script, and `api-mirror` skill bundled into this release.
+- **`@duckdb/node-api`** `^1.5.3-r.2 → ^1.5.3-r.3`.

package/changelog/0.7.x/0.7.3.md

@@ -0,0 +1,12 @@
+---
+summary: "Declare node-cron dependency so EDGAR_MIRROR_REFRESH_CRON works in the published package and Docker image; wrap scheduler init in try/catch so a scheduling fault degrades gracefully instead of crashing startup."
+breaking: false
+security: false
+---
+
+# 0.7.3 — 2026-06-01
+
+## Fixed
+
+- **`EDGAR_MIRROR_REFRESH_CRON` crash on startup** — `node-cron ^4.2.1` is now declared in `dependencies` so it ships in the published npm package and Docker image. Previously the framework's `schedulerService` lazily imported `node-cron` (an optional peer of `@cyanheads/mcp-ts-core` not installed transitively), causing an uncaught module-resolution error that crash-looped the server whenever the cron was configured. ([#26](https://github.com/cyanheads/secedgar-mcp-server/issues/26))
+- **Graceful scheduling fault** — `schedulerService.schedule()` / `start()` in `setup()` is now wrapped in try/catch. If scheduling fails for any reason, the server logs a warning and continues serving; the mirror still answers reads with live-API fallback and can be refreshed out-of-band via `bun run mirror:refresh`. ([#26](https://github.com/cyanheads/secedgar-mcp-server/issues/26))

package/changelog/0.7.x/0.7.4.md

@@ -0,0 +1,16 @@
+---
+summary: "Gate cross-company frames on a full-coverage completion marker (falling back to live while the store is partial or re-syncing); fix the companyfacts ingester to checkpoint only after the full archive drains so an interrupted ingest re-streams on the next refresh."
+breaking: false
+security: false
+---
+
+# 0.7.4 — 2026-06-01
+
+## Fixed
+
+- **`fetch_frames` partial-mirror coverage** — `tryGetFrames` / `mirrorOrLive` now gates on `companyFactsComplete()` (`status === 'complete'`) instead of the point-lookup readiness flag. A partial or mid-(re)sync company-facts store falls back to the live frames API, preventing a tiny CIK slice from being returned as a complete cross-company frame. ([#29](https://github.com/cyanheads/secedgar-mcp-server/issues/29))
+- **`companyfacts-sync` interrupted-ingest checkpoint** — the ingester now emits `checkpoint` only on the terminal page after the full archive stream drains; intermediate pages carry `checkpoint: undefined`. An interrupted ingest leaves no completion checkpoint, so the next `refresh` re-streams the full archive instead of HEAD-skipping a partial store as already-synced. ([#33](https://github.com/cyanheads/secedgar-mcp-server/issues/33))
+
+## Changed
+
+- `vitest` `^4.1.7` → `^4.1.8`

package/changelog/0.8.x/0.8.0.md

@@ -0,0 +1,20 @@
+---
+summary: "get_institutional_holdings: whole-USD market values, distinct-position consolidation, working quarter targeting"
+breaking: true
+security: false
+---
+
+# 0.8.0 — 2026-06-01
+
+Three corrections to `get_institutional_holdings` that change output shape and behavior.
+
+## Added
+
+- **`consolidate` input** (default `true`) — when true, sub-lines for the same security (`cusip` + `title_of_class` + `put_call`) are collapsed into one position (shares and value summed), sorted by `market_value_usd` descending. Set `false` for raw filing rows in filing order. ([#30](https://github.com/cyanheads/secedgar-mcp-server/issues/30))
+- **`total_positions`** output field — count of distinct consolidated positions (or raw rows when `consolidate: false`). ([#30](https://github.com/cyanheads/secedgar-mcp-server/issues/30))
+
+## Changed
+
+- **`value_in_thousands` → `market_value_usd`** — field renamed and units corrected. SEC Form 13F Information Table Column 4 reports whole dollars effective 2023-01-03 (Release No. 34-95148); earlier filings reported thousands and are now normalized up to whole USD by filing date. `format()` renders the value with a scaled B/M/K suffix plus the exact figure. ([#27](https://github.com/cyanheads/secedgar-mcp-server/issues/27)) ⚠️ Breaking
+- **`quarter` parameter now targets the actual filing** — matches the requested quarter against the SEC submissions `reportDate` (period-end). No match → `no_filings_found` error naming the quarter (no silent substitution of the latest filing). Malformed quarter → `ValidationError`. The EFTS full-text search path is no longer used for quarter resolution. ([#31](https://github.com/cyanheads/secedgar-mcp-server/issues/31)) ⚠️ Breaking
+- **`limit`** now applies after consolidation, so it returns the N largest distinct positions (by `market_value_usd` descending) rather than N raw sub-lines. ([#30](https://github.com/cyanheads/secedgar-mcp-server/issues/30))

package/changelog/0.8.x/0.8.1.md

@@ -0,0 +1,17 @@
+---
+summary: "search_filings cik:/ticker: now scopes server-side via EFTS ciks param; date/period validators; dataframe_query register_as preserves real DuckDB types; get_financials limit param"
+breaking: false
+security: false
+---
+
+# 0.8.1 — 2026-06-01
+
+## Added
+
+- **`limit` input for `get_financials`** — caps inline `data[]` to the most-recent N periods (newest-first). Full series always registers to the canvas dataframe for SQL access. Format output notes the truncation when active. ([#32](https://github.com/cyanheads/secedgar-mcp-server/issues/32))
+- **`.regex()` validators for date and period format fields** — `start_date`/`end_date` on `search_filings` and `period` on `fetch_frames` now emit a `pattern` in JSON Schema so format violations (e.g. `2023/01/01`, `2023Q4`) are caught at the MCP layer, not silently forwarded to EFTS. ([#25](https://github.com/cyanheads/secedgar-mcp-server/issues/25))
+
+## Fixed
+
+- **`search_filings` entity targeting** — `cik:`/`ticker:` tokens now scope the EFTS query server-side via the `ciks` param instead of injecting the entity's current name as a required phrase. Filings made under a former company name on the same CIK (e.g. Facebook-era 10-Ks under Meta's CIK 1326801) are now returned. `total`/`total_is_exact` reflect the exact entity match count from EFTS. ([#35](https://github.com/cyanheads/secedgar-mcp-server/issues/35))
+- **`dataframe_query` `register_as` schema** — recorded column schema now reflects the result's real DuckDB column types (BIGINT, DOUBLE, etc.) instead of hardcoding VARCHAR. `dataframe_describe` output is accurate for downstream arithmetic and join decisions. ([#28](https://github.com/cyanheads/secedgar-mcp-server/issues/28))

package/changelog/0.8.x/0.8.2.md

@@ -0,0 +1,14 @@
+---
+summary: "mirror:init/verify/refresh commands ship in the production Docker image; docker exec now a supported lever for mirror bootstrap and re-ingest"
+breaking: false
+security: false
+---
+
+# 0.8.2 — 2026-06-02
+
+The production Docker image shipped `dist/` only — `docker exec <container> bun run mirror:init` (and `mirror:refresh` / `mirror:verify`) failed because the raw `.ts` scripts and the `@/` path alias they depend on were absent. The runtime stage now copies the four mirror scripts and emits a minimal `tsconfig.json` that maps `@/*` → `./dist/*`, so Bun can resolve the alias against the compiled output. The scripts are also added to `files[]` so the npm tarball and `.mcpb` bundle carry the CLI. Closes [#34](https://github.com/cyanheads/secedgar-mcp-server/issues/34).
+
+## Added
+
+- **Mirror CLI in the production image** — the runtime Docker stage copies `scripts/edgar-mirror-init.ts`, `edgar-mirror-refresh.ts`, `edgar-mirror-verify.ts`, and `_mirror-context.ts` from the build stage; emits a minimal `tsconfig.json` mapping `@/*` → `./dist/*` so Bun resolves the path alias against `./dist/`. Operators can now run `docker exec <container> bun run mirror:<init|refresh|verify>` without an external rebuild or volume copy.
+- **Mirror scripts in `files[]`** — the four mirror scripts are included in the npm tarball and `.mcpb` bundle.

package/changelog/0.8.x/0.8.3.md

@@ -0,0 +1,20 @@
+---
+summary: "Adopt @cyanheads/mcp-ts-core ^0.9.21 — per-request log context fix, secret-stripped error messages, and fail-fast retry behavior"
+breaking: false
+security: false
+---
+
+# 0.8.3 — 2026-06-02
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core` ^0.9.19 → ^0.9.21** — three framework fixes:
+  - Per-request logs and traces now carry fresh request + trace/span IDs instead of the frozen boot context (HTTP transport log context fix).
+  - `fetchWithTimeout` strips query-string secrets (e.g. `?api_key=`) from error messages and logs.
+  - `withRetry` fails fast on non-retryable errors; `ctx.fail` auto-populates the `retryable` flag.
+- **Skills re-synced** — `add-tool`, `api-canvas`, `api-context`, `api-linter`, `api-utils`, `design-mcp-server` updated to framework 0.9.21; new `orchestrations` skill added.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.9.19 → ^0.9.21
+- `fflate` ^0.8.2 → ^0.8.3

package/changelog/0.8.x/0.8.4.md

@@ -0,0 +1,12 @@
+---
+summary: "get_filing error data now returns categorized documents instead of a flat list; search_filings notes Form 3/4/5 index limitations"
+breaking: false
+security: false
+---
+
+# 0.8.4 — 2026-06-04
+
+## Fixed
+
+- **`secedgar_get_filing` `document_not_found` / `no_documents` error data** — error payload now returns `documents.primary`, `documents.exhibits`, and `documents.auxiliary` (matching success-path categorization) instead of a flat `available_documents` array that included every XBRL viewer fragment (`R1.htm`…`Rn.htm`, `_cal/_def/_lab/_pre.xml`, `Show.js`, `report.css`). Recovery hint now names the primary document filename directly. ([#37](https://github.com/cyanheads/secedgar-mcp-server/issues/37))
+- **`secedgar_search_filings` `forms` field description** — added note that ownership forms (3, 4, 5) are indexed by reporting person (e.g. `"LEVINSON ARTHUR D"`) and carry no issuer name, transaction code, share count, or price; routes insider-transaction workflows to `secedgar_get_insider_transactions`. ([#38](https://github.com/cyanheads/secedgar-mcp-server/issues/38))

package/changelog/0.9.x/0.9.0.md

@@ -0,0 +1,20 @@
+---
+summary: "Ownership tools now register full parsed results to the canvas; fetch_frames surfaces alternate-definition XBRL tags that cover a meaningful share of filers for the base concept."
+breaking: false
+security: false
+---
+
+# 0.9.0 — 2026-06-08
+
+## Added
+
+- **`secedgar_get_insider_transactions` canvas output** — when a canvas is present, the tool now materializes the full parsed Form 4 result set as a `df_<id>` dataframe (new `dataset` output field); the inline response remains a preview capped at `limit`. The scan covers up to `INSIDER_CANVAS_FILING_SCAN` (default 40) recent filings and flags `dataset.truncated` when the form index has more. Canvas behavior is transparent when unavailable — no extra fetches occur. ([#39](https://github.com/cyanheads/secedgar-mcp-server/issues/39))
+- **`secedgar_get_institutional_holdings` canvas output** — same pattern: full info-table result (consolidated or raw per `consolidate`) registered as `df_<id>`; inline response is a preview capped at `limit`. ([#39](https://github.com/cyanheads/secedgar-mcp-server/issues/39))
+- **`secedgar_dataframe_describe` now includes ownership tools** — `get_insider_transactions` and `get_institutional_holdings` appear in the tool source list alongside the three existing canvas tools.
+- **`secedgar_fetch_frames` `related_tags` field** — returns alternate-definition XBRL tags that a meaningful share of filers report as their primary line for the base concept (e.g. `us-gaap/CashAndCashEquivalentsAtCarryingValue` → includes `us-gaap/CashCashEquivalentsAndShortTermInvestments`; `us-gaap/StockholdersEquity` → includes noncontrolling-interest-inclusive totals; operating-only vs. combined cash-flow variants). A whole-universe screen on the base tag alone is no longer silently under-inclusive. ([#36](https://github.com/cyanheads/secedgar-mcp-server/issues/36))
+- **Alternate-definition tags in `secedgar_search_concepts` and `secedgar://concepts` resource** — each concept entry now surfaces `alternateTags` listing related definitions, and alternate tags are reverse-searchable (a lookup on an alternate tag returns its canonical concept). ([#36](https://github.com/cyanheads/secedgar-mcp-server/issues/36))
+- **Alternate tags excluded from `get_financials` fallback chain** — kept out intentionally to avoid conflating semantically distinct totals; the `related_tags` in `fetch_frames` provides the explicit signal for cross-tag aggregation.
+
+## Changed
+
+- **`@types/node`** `^25.9.1` → `^25.9.2` (dev-dep patch).

package/changelog/template.md

@@ -0,0 +1,151 @@
+---
+# FORMAT REFERENCE — do not edit. Copy this file to
+# `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.8.x/0.8.6.md`)
+# to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
+# with a concrete date.
+
+# Required. One-line GitHub Release-style headline. 350 character cap — a
+# ceiling, not a target. Default short and scannable. Don't pad, don't stitch
+# unrelated changes with commas/semicolons into an inventory — pick the
+# headline, like a tag's theme line. Quotes required: unquoted YAML treats
+# `: ` inside the value as a key separator and fails GitHub's strict parser.
+summary: ""
+
+# Set `true` when consumers must change code to upgrade: API removals,
+# signature changes, config renames, behavior changes that break existing
+# usage. Flagged as `Breaking` in the rollup.
+breaking: false
+
+# Set `true` ONLY for a security fix in THIS project's own source code — a
+# vulnerability or hardening in code you ship. A dependency or transitive CVE
+# bump is routine maintenance, NOT a security release: record it under
+# `## Dependencies` (with the advisory ID) and leave this `false`. When true,
+# pairs with the `## Security` section below and flags `Security` in the rollup.
+security: false
+
+# Optional free-form notes for maintenance agents processing this release.
+# Not rendered in CHANGELOG — consumed by agents running `maintenance` on
+# downstream servers. ADOPTION STEPS ONLY — new files to create, fields to
+# populate, one-time migration steps. Never a second rendering of the body:
+# if a body bullet already says it, name the bullet's symbol instead of
+# re-explaining. Omit the field entirely when there's nothing to say.
+# agent-notes: |
+#   <instructions for downstream maintenance agents>
+---
+
+# <version> — YYYY-MM-DD
+
+<!--
+  AUTHORING GUIDE — applies to the new per-version file you create from this
+  template.
+
+  Audience: someone scanning release notes to decide what affects them. Lead
+  each bullet with the symbol or concept name in **bold** so they can skip
+  what's irrelevant and zoom in on what's not.
+
+  Tone: terse, fact-dense, not verbose. Bullet shape: **symbol** + what
+  changed + at most one consumer-facing caveat. One sentence by default, two
+  when the second carries weight — a bullet past ~40 words or three sentences
+  is wrong. The depth lives one hop away: the linked issue carries the why,
+  the commit diff carries the how. The changelog names what changed and what
+  a consumer does about it; a reader who wants mechanism opens the link.
+
+  Model length on THIS guide, never on the previous entry — entries modeled
+  on entries compound.
+
+  Cut (each has shipped as a wall of text; these are the cruft):
+  - History/justification narration — how the bug worked, why the old
+    behavior was wrong. One short clause at most; the issue carries the story.
+  - Design-rationale defense — "chosen over Y because…", "guarding the
+    getter is not enough…". That is the author arguing with a reviewer;
+    reviewers read the PR, not the changelog.
+  - Defensive unchanged-clauses — "X is unchanged", "byte-identical to
+    <prev>". Keep one only where its absence would cause a real misread,
+    as a short parenthetical.
+  - Edge-case inventories — marker lists, not-flagged lists, escape tables.
+    Tests and the issue carry those.
+  - Mechanism walkthroughs (JSDoc, CLAUDE.md/AGENTS.md, or the relevant
+    skill own those), ceremonial framings ("This release introduces…"),
+    backwards-compat paragraphs, file-by-file test enumerations. Prefer
+    code/symbol names over English re-explanations.
+
+  Verified ≠ included: the every-claim-verified-from-the-diff rule bounds
+  the TRUTH of what you write, never the AMOUNT.
+
+  Example — same fact, right size:
+
+    TOO LONG: **`fetchWithTimeout`'s `timeoutMs` bounds the whole exchange**
+    (#341). `fetch` resolves once headers arrive and the deadline was
+    cleared as the helper returned, so a peer that answered promptly and
+    then stalled the stream held the request open indefinitely. A 2xx
+    carrying a body now comes back as a passthrough wrapper that disarms
+    the deadline when the body closes, errors, or is cancelled; …
+    [+90 more words of mechanism and edge cases]
+
+    RIGHT: **`fetchWithTimeout`'s `timeoutMs` now bounds the whole
+    exchange, not just the headers** (#341). A stalled body aborts with
+    the same `Timeout` error; the returned `Response` is a wrapper, so
+    identity assertions (`toBe(response)`) no longer hold.
+
+  Narrative intro: skip by default. Add one short sentence only when the
+  release theme genuinely needs framing the bullets can't carry. When many
+  bullets share one upgrade consequence, state it ONCE — intro line or
+  agent-notes — never per bullet.
+
+  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
+  Fixed, Security. Include only sections with entries; delete the rest
+  (including the commented-out scaffolding below). Don't ship empty headers.
+
+  Include: every distinct fact a reader needs to adopt or audit the release —
+  new exports, signatures, lint rule IDs, env vars, breaking changes, version
+  bumps on shipped skills. Nothing more.
+
+  Links: link issues, PRs, docs, or skills where they help a reader jump to
+  context. Once per item per entry — don't re-link the same issue in summary,
+  narrative, and bullet. Skip links for inline symbol names; code spans speak
+  for themselves.
+
+  Issue/PR URLs: use full URLs. GitHub's bare `#NN` auto-link only resolves
+  inside its own UI, not in npm reads or local editors.
+
+      [#38](https://github.com/cyanheads/mcp-ts-core/issues/38)   ← issue
+      [#42](https://github.com/cyanheads/mcp-ts-core/pull/42)     ← PR
+
+  Verify numbers exist before linking (`gh issue view NN`, `gh pr view NN`).
+  Never speculate on a future number — `#42` for an upcoming PR silently
+  resolves to whatever real item already owns 42, and timeline previews pull
+  in that unrelated item's metadata.
+
+  TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
+  via `gh release create --notes-from-tag`. It is a condensed digest of this
+  entry, never a copy, and its format is owned by the `release-and-publish`
+  skill (step 4, "Create the annotated tag"): the entry's `summary:` as the
+  theme line without the version, flat headline bullets — no Keep-a-Changelog
+  section headers, no gates line — at most one deps line, issue backlinks,
+  and the changelog link last. In release-PR mode the `git-wrapup` skill
+  authors that digest as the PR body's `## Changes` and the tag copies it.
+-->
+
+## Added
+
+-
+
+## Changed
+
+-
+
+<!-- ## Deprecated
+
+- -->
+
+<!-- ## Removed
+
+- -->
+
+## Fixed
+
+-
+
+<!-- ## Security
+
+- -->