@cyanheads/secedgar-mcp-server 0.15.4 → 0.15.6

package/README.md

@@ -27,9 +27,11 @@
 
 ---
 
-## Tools
+## Overview
 
-Fourteen tools for querying SEC EDGAR data, plus three for SQL analytics over the DuckDB-backed canvas dataframes those tools materialize:
+SEC EDGAR filings, XBRL financials, and company ownership data, keyless aside from a required SEC User-Agent header. Resolve companies by ticker, name, or CIK, search filings back to 1993, pull XBRL financials and cross-company comparisons by concept, and trace ownership — insider transactions, 13F institutional holdings, 13D/13G blockholders, and fund holdings — from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
+
+### Tools
 
 | Tool | Description |
 |:---|:---|
@@ -49,238 +51,241 @@ Fourteen tools for querying SEC EDGAR data, plus three for SQL analytics over th
 | `secedgar_search_concepts` | Discover supported XBRL concept names or reverse-lookup a raw tag |
 | `secedgar_dataframe_describe` | List canvas dataframes with provenance, TTL, and schema |
 | `secedgar_dataframe_query` | Run a single-statement SELECT across dataframes |
-| `secedgar_dataframe_drop` | Drop a canvas dataframe by name. Opt-in via `EDGAR_DATAFRAME_DROP_ENABLED=true` — off by default since TTL already handles cleanup |
+| `secedgar_dataframe_drop` | Drop a canvas dataframe by name. Opt-in via `EDGAR_DATAFRAME_DROP_ENABLED=true` — off by default since TTL already handles cleanup, and uncallable until the flag is set |
 
-### `secedgar_company_search`
+### Resources
 
-Entry point for most EDGAR workflows — resolve tickers, names, or CIKs to entity details.
+| Resource | Description |
+|:---|:---|
+| `secedgar://concepts` | Common XBRL financial concepts grouped by statement, mapping friendly names to XBRL tags |
+| `secedgar://filing-types` | Common SEC filing types with descriptions, cadence, and use cases, plus the full 8-K item-code decode tables for both numbering regimes |
 
-- Supports ticker symbols (`AAPL`, `VOO`), company names (`Apple`), or CIK numbers (`320193`); a multi-class share ticker resolves in either form (`BRK-B` or `BRK.B`)
-- ETFs and mutual funds resolve by ticker via `company_tickers_mf.json`; fund results include `series_id` and `class_id` for downstream scoping
-- Current and former company names both resolve (`Facebook` → Meta Platforms, `Square` → Block)
-- Corporate suffix form does not have to match the registry (`Beacon Financial Corporation` → `Beacon Financial Corp`); `Corp`, `Inc`, `Co`, and `Ltd` stay distinct from one another, since separate registrants differ only by which one they use (`TORO CO` vs `TORO CORP.`)
-- Near-match suggestions on a zero-result name or ticker search (e.g. `Microsfot` → `MICROSOFT CORP / MSFT`, `CSWI` → `CSW INDUSTRIALS, INC. / CSW`)
-- Optionally includes recent filings with form type filtering
-- Date filtering (`filed_after` / `filed_before`) and under-filled form filters page into the older submissions archive, reaching filings that predate the ~1000-entry recent window (e.g. a 2005 10-K); `history_scanned_through` discloses the scan depth, and the full filtered history materializes as a `df_<id>` dataframe when it exceeds the inline `filing_limit`
-- Returns entity metadata: SIC code, exchanges, fiscal year end, state of incorporation
+### Prompts
 
----
+| Prompt | Description |
+|:---|:---|
+| `secedgar_company_analysis` | Guides a structured analysis of a public company's SEC filings: identify recent filings, extract financial trends, surface risk factors, and note material events |
 
-### `secedgar_search_filings`
+## Capability reference
 
-Search EDGAR filings since 1993. Full-text search covers 2001-present (the EFTS index floor); pre-2001 date ranges are served from the archives — pre-2001 full-text matching requires entity scope.
+### `secedgar_company_search` <sub>tool</sub>
 
-- Exact phrases (`"material weakness"`), boolean operators (`revenue OR income`), wildcards (`account*`)
-- Entity targeting within query string (`cik:320193` or `ticker:AAPL`) — scoped server-side by CIK, so filings made under a former company name (same CIK) are included; a multi-class share ticker resolves in either form (`ticker:BRK-B` or `ticker:BRK.B`)
-- Browse mode: omit `query` to list filings by form type (`forms=["S-1"]`) and/or entity (`ticker:`/`cik:`), optionally narrowed by date — a bare date range is not a valid search and must be paired with forms or entity targeting
-- Pre-2001 date ranges (back to 1993) route to the archives: an entity-scoped range reads the filer's full submissions history; an unscoped forms/date range browses the quarterly full-index. Each row carries a `source` field (`efts` / `submissions` / `full-index`), preserved into the `df_<id>` dataframe
-- Pre-2001 free text is matched by reading documents, so it needs `ticker:`/`cik:` scope to bound the work: the form + date pre-filter picks candidates, up to 50 are read, and `scan` reports candidates / scanned / matched rather than presenting a partial read as a complete one. SEC's request rate is the cost — roughly 5s for a full 50-document scan. Each read covers the whole accession `.txt` (pre-1997 filings expose no per-document URL), so a match can sit in an attached exhibit rather than the body of the requested form
-- A range crossing 2001-01-01 is split at the boundary and merged: the full-text index serves 2001 onward, the archives serve the rest. `period_ending`, `ticker`, `file_description`, `sic`, and `location` exist only on `source: efts` rows, so a merged result carries them on some rows and not others
-- Date range filtering, form type filtering, pagination up to 10,000 results
-- Returns form distribution for narrowing follow-up searches
-- When the entity-scoped window exceeds the inline limit, the already-fetched EFTS window is materialized as a `df_<id>` dataframe — query it with `secedgar_dataframe_query`
+- Resolves ticker symbols, company names, or CIK numbers; a multi-class share ticker matches either form (`BRK-B` or `BRK.B`), and current/former names both resolve (`Facebook` → Meta Platforms, `Square` → Block)
+- ETFs and mutual funds resolve by ticker via `company_tickers_mf.json`; fund results carry `series_id` and `class_id`
+- Corporate suffix form need not match the registry (`Beacon Financial Corporation` → `Beacon Financial Corp`), but `Corp`/`Inc`/`Co`/`Ltd` stay distinct — separate registrants can differ only by which one they use
+- Near-match suggestions on a zero-result name or ticker search (e.g. `Microsfot` → `MICROSOFT CORP / MSFT`)
+- Optional recent filings inline with form-type filtering; `filed_after`/`filed_before` and under-filled form filters page into the older submissions archive, reaching filings past the ~1000-entry recent window — `history_scanned_through` reports the scan depth, and the full filtered history stages as `df_<id>` when it exceeds `filing_limit`
+- Returns entity metadata — SIC code, exchanges, fiscal year end, state of incorporation
 
 ---
 
-### `secedgar_get_filing`
+### `secedgar_search_filings` <sub>tool</sub>
 
-Fetch a specific filing's metadata and document content by accession number.
-
-- Accepts accession numbers in dash or no-dash format
-- Converts HTML filings to readable plain text
-- Configurable content limit (1K–200K characters, default 50K)
-- Can fetch specific exhibits by document name
-- Binary entries — scanned pages, PDF exhibits, packaged archives and spreadsheets — are marked `binary` in the document catalog and rejected with a `binary_document` error instead of being returned as decoded bytes
-- **Offset paging** for large documents (10-K, S-1/A can exceed 1M chars): pass `next_offset` from a truncated response as `offset` on the next call to continue reading; first-page truncated responses include a detected `outline` (headings with offsets) for targeted navigation
-- **Section targeting** via the `section` param: jumps directly to a named heading by substring match that ignores case, whitespace style, and quote style (e.g. `"risk factors"`, `"item 7"`, `"certain relationships"`), so a heading copied from the outline resolves whether it carries the filing's non-breaking spaces and curly quotes or plain ones; on a miss, the error carries the detected outline so you can pick the correct heading
-- Extracted text is cached per `accession + document` (bounded LRU, 8 entries), making subsequent paged calls cheap
+- Full-text search (2001–present, the EFTS index floor) with exact phrases, boolean operators, wildcards, and inline entity targeting (`cik:320193` / `ticker:AAPL`, either share-class form for multi-class tickers) — server-side scoped by CIK, so former-name filings on the same entity are included
+- Browse mode (omit `query`) lists by form type and/or entity, optionally narrowed by date; a bare date range must pair with forms or entity targeting
+- Pre-2001 date ranges (back to 1993) route to the archives — entity-scoped reads the filer's full submissions history, unscoped browses the quarterly full-index; pre-2001 free-text search needs `ticker:`/`cik:` entity scope, since it works by reading up to 50 candidate documents (`scan` reports candidates/scanned/matched, costing ~5s for a full scan)
+- A range crossing 2001-01-01 is split at the boundary and merged, each row tagged with its `source` (`efts`/`submissions`/`full-index`); `period_ending`, `ticker`, `file_description`, `sic`, and `location` exist only on `efts` rows
+- Date range and form-type filtering, pagination up to 10,000 results; response includes form distribution for narrowing follow-up searches
+- The full result set stages as `df_<id>` when it exceeds the inline limit
 
 ---
 
-### `secedgar_get_financials`
-
-Get historical XBRL financial data for a company with friendly concept name resolution.
+### `secedgar_get_filing` <sub>tool</sub>
 
-- Friendly names like `"revenue"`, `"net_income"`, `"eps_diluted"` auto-resolve to correct XBRL tags
-- Handles historical tag changes (e.g., ASC 606 revenue recognition)
-- Automatic deduplication to one value per standard calendar period
-- Filter by annual, quarterly, or all periods
-- Optional `limit` caps the inline series to the most-recent N periods; the full series stays queryable via the `df_<id>` dataframe
-- Quarterly results carry a `caveats` entry naming every calendar quarter absent from the frame-tagged series — SEC reports fiscal Q4 as the 10-K residual, so the calendar quarter that fiscal Q4 spans has no discrete quarterly value (calendar-year filers included), and a filer whose other fiscal quarters span non-calendar durations loses a second quarter the same way
-- A further `caveats` entry when the concept resolved to an XBRL tag SEC has retired from the taxonomy — that only happens when no current tag reports for the filer, and the series can stop years short
-- See `secedgar://concepts` resource for the full mapping
+- Accepts accession numbers in dash or no-dash format; fetches the primary document or a specific exhibit by name
+- Converts HTML filings to plain text; pre-2005 filings produce noisier output
+- Configurable `content_limit` (1K–200K characters, default 50K)
+- Binary entries (scanned pages, PDF exhibits, packaged archives/spreadsheets) are marked `binary` in the document catalog and rejected with a `binary_document` error rather than returned as decoded bytes
+- Offset paging for large documents (10-K, S-1/A can exceed 1M chars) — pass a truncated response's `next_offset` as `offset` to continue; first-page truncated responses include a detected `outline` (headings + offsets)
+- `section` jumps directly to a named heading by substring match ignoring case, whitespace style, and quote style (`"risk factors"`, `"item 7"`) — a miss returns the detected outline; extracted text is cached per `accession + document` (bounded LRU, 8 entries) so paged calls are cheap
 
 ---
 
-### `secedgar_get_snapshot`
+### `secedgar_get_financials` <sub>tool</sub>
+
+- Friendly names (`"revenue"`, `"net_income"`, `"eps_diluted"`) auto-resolve to XBRL tags, including historical tag changes (e.g. ASC 606 revenue recognition) — see `secedgar://concepts` for the full mapping
+- Automatic deduplication to one value per standard calendar period; filter by `period_type` (`annual`/`quarterly`/`all`)
+- Optional `limit` caps the inline series to the most-recent N periods; the full series stays queryable via `df_<id>`
+- `caveats` names every calendar quarter absent from the frame-tagged series — SEC reports fiscal Q4 as the 10-K residual, so the calendar quarter it spans carries no discrete quarterly value (calendar-year filers included), and a filer whose other fiscal quarters span non-calendar durations can lose a second quarter the same way
+- A separate `caveats` entry appears when the concept resolved to an XBRL tag SEC has retired from the taxonomy — that only happens when no current tag reports for the filer, and the series can then stop years short
+
+---
 
-Build a company financial profile in one call instead of a run of `secedgar_get_financials` calls.
+### `secedgar_get_snapshot` <sub>tool</sub>
 
-- Reads the filer's complete companyfacts payload once, then resolves every supported concept against it
+- Reads the filer's complete companyfacts payload once and resolves every supported concept against it — one call instead of a run of `secedgar_get_financials` calls
 - Same frame dedup and tag priority as `secedgar_get_financials`, so the two agree for any concept they both cover
 - Duration concepts (income statement, cash flow, per-share) report their latest full year and latest single quarter; balance-sheet and entity-info concepts report their latest point-in-time value
 - Concepts the filer does not report are listed under `gaps` with the XBRL tags that were tried — never zero-filled or interpolated
-- IFRS filers resolve through the mapped IFRS tag variants via `taxonomy: "ifrs-full"`, which covers the income statement, balance sheet, cash flow, and per-share concepts; each line reports the taxonomy its value came from
-- Compact single-record profile — no dataframe; reach for `secedgar_get_financials` when you need a time series
+- IFRS filers resolve through the mapped IFRS tag variants via `taxonomy: "ifrs-full"`, covering the income statement, balance sheet, cash flow, and per-share concepts; each line reports the taxonomy its value came from
+- Compact single-record profile, no dataframe — reach for `secedgar_get_financials` when a time series is needed
 
 ---
 
-### `secedgar_get_insider_transactions`
+### `secedgar_get_material_events` <sub>tool</sub>
+
+- Filter with `items` (e.g. `["2.02"]` results of operations, `["5.02"]` officer departures, `["4.02"]` non-reliance) — the only surface that scopes by what the event actually was, since `secedgar_search_filings` and `secedgar_company_search` cannot see item codes
+- Two numbering regimes are both accepted and decoded: the dotted scheme in force since 2004-08-23, and single integers before it (legacy `12` is the ancestor of `2.02`, `9` of `7.01`); decoding keys off the code's shape so a filing straddling the changeover is never mis-decoded
+- `item_distribution` counts every code across the scanned window before the filter, so a zero-hit filter still surfaces the items that are present
+- A date window pages into the older submissions archive, reaching 8-K filings older than the ~1000-filing recent window; `history_scanned_through` discloses the scan depth
+- The full decode table is in the `secedgar://filing-types` resource
+- The full filtered set materializes as `df_<id>` with item codes on every row — item frequency over time is one `secedgar_dataframe_query` away
+
+---
 
-Surface Form 4 / 4-A insider activity for a company by parsing ownership XML. Form 3 initial statements and Form 5 annual statements are not covered — reach those with `secedgar_search_filings` (`forms: ["3", "5"]`) plus `secedgar_get_filing`.
+### `secedgar_get_insider_transactions` <sub>tool</sub>
 
+- Parses Form 4 / 4-A insider transactions from ownership XML; Form 3 initial statements and Form 5 annual statements are not covered — reach those with `secedgar_search_filings` (`forms: ["3", "5"]`) plus `secedgar_get_filing`
 - Reporting person, relationship to issuer (director, officer + title, 10% owner), and transaction date
-- Transaction code mapped to a readable type (purchase, sale, gift, award, exercise, …); shares signed by acquired/disposed
-- Price per share and shares owned after each transaction; covers non-derivative (open-market) and derivative (option/RSU) lines
+- Transaction code mapped to a readable type (purchase, sale, gift, award, exercise, …); shares signed by acquired/disposed, price per share, and shares owned after each transaction; covers non-derivative (open-market) and derivative (option/RSU) lines
 - Filter by `transaction_type` (`purchase`, `sale`, `all`); scans newest filings first
-- The full set of transactions parsed from the scanned recent filings is materialized as a `df_<id>` dataframe (the inline list is a preview capped at `limit`) — query it with `secedgar_dataframe_query` to aggregate net buy/sell by insider
+- The full set parsed from the scanned recent filings materializes as `df_<id>` (the inline list is a preview capped at `limit`) — query it to aggregate net buy/sell by insider
 
 ---
 
-### `secedgar_get_institutional_holdings`
-
-Surface 13F-HR quarterly institutional holdings by parsing the information table.
+### `secedgar_get_institutional_holdings` <sub>tool</sub>
 
 - Pass the institutional filer (CIK or full legal name, e.g. `0000102909` for Vanguard) to see what it holds; for the reverse direction — which managers hold a given company — use `secedgar_find_holders`, whose `filer_cik` results feed straight back into this tool
 - Each holding: issuer name, CUSIP, market value (whole USD), shares/principal, and put/call; raw rows also carry investment discretion
-- Sub-lines for the same security (one per manager/account) are consolidated into distinct positions sorted by value by default — pass `consolidate: false` for raw filing rows
+- Sub-lines for the same security are consolidated into distinct positions sorted by value by default — pass `consolidate: false` for raw filing rows
 - Resolves the filing-manager name and reporting quarter from the cover page; target a specific quarter with `quarter` (e.g. `"2025-Q4"`)
-- `total_holdings_in_filing` counts raw info-table rows; `total_positions` counts distinct positions after consolidation (both before `limit`)
-- Page through a large information table with `offset` — the response echoes the effective `offset` and returns `next_offset` while rows remain, so every position stays reachable even when the canvas is disabled
-- The full parsed holdings set is materialized as a `df_<id>` dataframe (the inline list is one page of `limit` rows) — query it with `secedgar_dataframe_query` for full-filing aggregation or cross-quarter joins on `cusip` + `reporting_period`
+- `total_holdings_in_filing` counts raw info-table rows, `total_positions` counts distinct positions after consolidation (both before `limit`); page with `offset`, which returns `next_offset` while rows remain
+- The full parsed holdings set materializes as `df_<id>` for full-filing aggregation or cross-quarter joins on `cusip` + `reporting_period`
 
 ---
 
-### `secedgar_find_holders`
+### `secedgar_find_holders` <sub>tool</sub>
 
-Reverse 13F lookup: which institutional managers reported a position in an issuer, for one reporting quarter.
-
-- Searching by `cusip` matches the identifier the 13F information table itself carries — the precise path. Louisiana-Pacific Q1 2026 returns 451 filings by CUSIP `546347105` against 43 by the phrase `"LOUISIANA-PACIFIC CORP"`; the name path both under-matches (managers write the name differently) and over-matches (an unrelated issuer sharing a word)
+- Reverse 13F lookup — which institutional managers reported a position in an issuer, for one reporting quarter. Searching by `cusip` matches the identifier the 13F information table itself carries (the precise path); the name path both under-matches (managers write names differently) and over-matches (unrelated issuers sharing a word)
 - A CUSIP is not derivable from a ticker anywhere in EDGAR — read one off any `secedgar_get_institutional_holdings` result, or fall back to the name path
-- `quarter` targets a reporting period (`"2026-Q1"`); omit it for the newest quarter whose 45-day filing deadline has passed. The applied quarter and its filing window are echoed back
-- Filings are kept by the period they report, not the date they were filed, so amendments restating an older quarter (roughly 6% of any window) do not land in the wrong quarter's holder list
+- `quarter` targets a reporting period (`"2026-Q1"`); omit it for the newest quarter whose 45-day filing deadline has passed — the applied quarter and its filing window are echoed back
+- Filings are kept by the period they report, not the date they were filed, so amendments restating an older quarter (roughly 6% of any window) don't land in the wrong quarter's holder list
 - Up to 500 filer rows are fetched per call; `total_filings` reports the full count and `dataset.truncated` flags when more exist
-- **The list is unranked.** EDGAR search relevance carries no signal about position size — read a manager's actual position by passing its `filer_cik` to `secedgar_get_institutional_holdings`
+- **The list is unranked** — EDGAR search relevance carries no signal about position size; read a manager's actual position by passing its `filer_cik` to `secedgar_get_institutional_holdings`
 
 ---
 
-### `secedgar_get_beneficial_owners`
-
-The 5%-and-over stakes in an issuer — the blockholder layer between Form 4 insiders and 13F portfolios. Input is the issuer, the company being held.
+### `secedgar_get_beneficial_owners` <sub>tool</sub>
 
-- 13D is the activist form and carries the filer's stated purpose of the transaction; 13G is the passive form and has no purpose item at all, which is the substantive difference between a stake that intends to influence control and one that does not. Filter with `form_kind`
-- Every reporting person is listed separately. Voting power, dispositive power, and percent of class are reported per person even on a joint filing where several funds and their controlling principal report the same underlying shares — summing those percentages double-counts the position
-- Coverage starts **2024-12-18**, when SEC replaced the legacy `SC 13D` / `SC 13G` text filings with structured XML under the current `SCHEDULE 13D` / `SCHEDULE 13G` names. Earlier stakes are readable but not parseable, and `legacy_filings_before_coverage` reports how many the issuer has — reach them with `secedgar_search_filings` and read them with `secedgar_get_filing`
+- The 5%-and-over stakes in an issuer — the blockholder layer between Form 4 insiders and 13F portfolios; input is the issuer, the company being held
+- 13D is the activist form and carries the filer's stated purpose of the transaction; 13G is the passive form and has no purpose item at all — filter with `form_kind`
+- Every reporting person is listed separately — voting power, dispositive power, and percent of class are reported per person even on a joint filing where several funds and their controlling principal report the same underlying shares, so summing those percentages double-counts the position
+- Coverage starts **2024-12-18**, when SEC replaced the legacy `SC 13D` / `SC 13G` text filings with structured XML; earlier stakes are readable but not parseable, and `legacy_filings_before_coverage` reports how many the issuer has
 - Amendments carry the current position and are included by default; `include_amendments=false` leaves only the filings that opened a position
-- The full parsed set registers as a `df_<id>` dataframe at one row per reporting person, so it joins the insider and 13F dataframes on issuer CIK
+- The full parsed set registers as `df_<id>`, one row per reporting person, so it joins the insider and 13F dataframes on issuer CIK
 
 ---
 
-### `secedgar_get_fund_holdings`
+### `secedgar_get_fund_holdings` <sub>tool</sub>
 
-What an ETF or mutual fund owns, from the NPORT-P portfolio report it files each quarter — the inverse of the ownership tools, which answer who owns a company.
-
-- Input is the fund: a ticker (`VOO`), an SEC fund series ID (`S000002839`), or a CIK. Fund trusts are indexed by ticker and series rather than by name, so name the registrant by CIK unless the fund itself trades under that name (`SPDR S&P 500 ETF Trust`)
-- An NPORT-P covers exactly one fund series and a registrant trust files one report per series per period, so a trust running several funds needs the specific fund named. A registrant that resolves to more than one series comes back with the series listed, each with its ticker; one whose series carry no ticker is routed by reading the series off its newest report, because a trust's own filing history interleaves funds whose fiscal quarters end on different months
-- Every result is dated to `report_period_date`. Reports publish roughly two months after the period they cover, so the holdings are the portfolio as of that date, not as of today; `publication_lag_days` states the gap. Target an earlier period with `report_date`, chosen from the `available_report_periods` in any response
+- What an ETF or mutual fund owns, from the NPORT-P portfolio report it files each quarter — the inverse of the ownership tools, which answer who owns a company. Input is the fund: a ticker (`VOO`), a fund series ID (`S000002839`), or a CIK — name the registrant by CIK unless the fund itself trades under that name
+- An NPORT-P covers exactly one fund series and a registrant trust files one report per series per period, so a trust running several funds needs the specific fund named; a registrant resolving to more than one series returns the series list with tickers, and one whose series carry no ticker is routed by reading the series off its newest report
+- Every result is dated to `report_period_date` — reports publish roughly two months after the period they cover, so holdings are the portfolio as of that date, not as of today; `publication_lag_days` states the gap, and `report_date` targets an earlier period from `available_report_periods`
 - Positions carry the security name, CUSIP/ISIN/LEI where the filer reports them, share balance, USD value, and percent of net assets, alongside fund-level net assets, total assets, and total liabilities
-- Positions come back largest first by percent of net assets, one page of `limit` rows from `offset`. A broad index fund reports thousands — Vanguard Total Stock Market's most recent report carries 3,524 — so the full report registers as a `df_<id>` dataframe for aggregation and for joining the 13F and insider dataframes on CUSIP
-
----
-
-### `secedgar_get_material_events`
-
-A company's 8-K history with item codes decoded and filterable — the only surface that can scope by what the event actually was rather than by form.
-
-- Filter with `items` (e.g. `["2.02"]` for results of operations, `["5.02"]` for officer departures, `["4.02"]` for non-reliance); `secedgar_search_filings` and `secedgar_company_search` cannot see items at all
-- Two numbering regimes are both accepted and decoded: the dotted scheme in force since 2004-08-23, and the single integers before it (legacy `12` is the ancestor of `2.02`, `9` of `7.01`). Decoding keys off the code's shape, so a filing straddling the changeover is never mis-decoded, and a window spanning it needs both codes in the filter
-- `item_distribution` counts every code across the scanned window before the filter, so a zero-hit filter comes back with the items that *are* present rather than a dead end
-- A date window pages into the older submissions archive, reaching 8-K filings that predate the ~1000-filing recent window; `history_scanned_through` discloses the scan depth
-- The full decode table is in the `secedgar://filing-types` resource
-- The full filtered set materializes as a `df_<id>` dataframe with item codes on every row — item frequency over time is one `secedgar_dataframe_query` away
+- Positions come back largest-first by percent of net assets, one page of `limit` rows from `offset`; the full report registers as `df_<id>` for aggregation and for joining the 13F and insider dataframes on CUSIP
 
 ---
 
-### `secedgar_fetch_frames`
-
-Fetch SEC XBRL frames for one concept × one period across all reporting companies.
+### `secedgar_fetch_frames` <sub>tool</sub>
 
-- Same friendly concept names as `secedgar_get_financials`
+- Same friendly concept names as `secedgar_get_financials`, or a raw XBRL tag
 - Supports annual (`CY2023`), quarterly (`CY2024Q2`), and instant (`CY2023Q4I`) periods
-- Inline response returns one page of the ranked companies (sort + limit), with ticker enrichment
-- Walk further down the ranking with `offset` — the response echoes the effective `offset` and returns `next_offset` while companies remain, so ranks past the first page stay reachable even when the canvas is disabled
-- The full frames response (all reporters, typically 2k–10k rows) is materialized as a `df_<id>` dataframe — query it with `secedgar_dataframe_query`
+- Inline response returns one page of the ranked companies (sort + limit), with ticker enrichment; walk further down the ranking with `offset`, which returns `next_offset` while companies remain
+- The full frames response (all reporters, typically 2k–10k rows) materializes as `df_<id>`
 - `related_tags` flags alternate-definition tags some filers use as their primary line (e.g. `cash` → restricted-cash-inclusive total, `equity` → NCI-inclusive total), so a whole-universe screen on the base tag isn't silently under-inclusive — query those separately
+- One call hits one XBRL tag; when a friendly name maps to multiple same-meaning tags, `unqueried_tags` lists the others to query and combine with an analysis-specific priority
 
 ---
 
-### `secedgar_compare_companies`
-
-Compare 2-10 named companies across 1-8 concepts, aligned on calendar periods — the middle shape between `secedgar_get_financials` (one company over time) and `secedgar_fetch_frames` (one period across the market).
+### `secedgar_compare_companies` <sub>tool</sub>
 
+- Compares 2-10 named companies across 1-8 concepts, aligned on calendar periods — the middle shape between `secedgar_get_financials` (one company over time) and `secedgar_fetch_frames` (one period across the market)
 - One companyfacts read per company, resolved through the same frame dedup and tag priority as `secedgar_get_financials`
 - Balance-sheet and entity-info concepts align on the calendar year or quarter their point-in-time snapshot falls in, so they sit in the same matrix as income-statement lines; each cell keeps its underlying XBRL frame
-- `periods` bounds the inline matrix (1-12, default 4) and the window shrinks further when companies x concepts x periods is too large to return in one response; the full aligned series is always materialized as a `df_<id>` dataframe for growth rates and spreads via `secedgar_dataframe_query`
-- A company that fails to resolve is reported in `failed_companies` with a machine-readable reason and the comparison proceeds with the rest
-- A company that does not report a concept is reported in `gaps` with the tags that were tried — never interpolated
-- `caveats` surface a filer missing one or two calendar quarters, a concept that resolved to a retired XBRL tag for one company, period ends that differ inside one aligned period, and concepts whose unit differs across companies
+- `periods` bounds the inline matrix (1-12, default 4), shrinking further when companies × concepts × periods is too large for one response; the full aligned series always materializes as `df_<id>`
+- A company that fails to resolve is reported in `failed_companies` and the comparison proceeds with the rest; a company that does not report a concept is reported in `gaps` with the tags that were tried — never interpolated
+- `caveats` surface a filer missing calendar quarters, a concept that resolved to a retired tag for one company, differing period ends inside one aligned period, and unit mismatches across companies
 
 ---
 
-### `secedgar_search_concepts`
-
-Discover supported XBRL concept names before querying financials or cross-company comparisons.
+### `secedgar_search_concepts` <sub>tool</sub>
 
-- Search by friendly name, label, or raw XBRL tag
+- Search by friendly name, label, or raw XBRL tag; an empty search with no filters returns the full catalog
 - Filter by statement group (`income_statement`, `balance_sheet`, `cash_flow`, `per_share`, `entity_info`) or taxonomy
 - Reverse-lookup raw tags like `NetIncomeLoss` to the supported friendly names
 - Surfaces `related_tags` for concepts with a high-coverage alternate-definition tag (e.g. restricted-cash-inclusive cash) so callers can discover them before screening
-- Filtering by `taxonomy: "ifrs-full"` narrows the catalog to concepts with an IFRS tag confirmed against live 20-F filings; a concept with no IFRS equivalent is left out rather than mapped to a guess
+- Filtering by `taxonomy: "ifrs-full"` narrows the catalog to concepts with an IFRS tag confirmed against live 20-F filers — a concept with no IFRS equivalent is left out rather than mapped to a guess
 - Returns the same catalog used by `secedgar_get_financials`, `secedgar_fetch_frames`, and `secedgar://concepts`
 
 ---
 
-### `secedgar_dataframe_describe` / `secedgar_dataframe_query` / `secedgar_dataframe_drop`
+### `secedgar_dataframe_describe` <sub>tool</sub>
 
-In-conversation SQL analytics over the dataframes that `secedgar_fetch_frames`, `secedgar_compare_companies`, `secedgar_search_filings`, `secedgar_get_financials`, `secedgar_get_material_events`, `secedgar_get_insider_transactions`, `secedgar_get_institutional_holdings`, and `secedgar_find_holders` materialize on a shared DuckDB-backed canvas. Each data-returning call adds a `dataset` field with a `df_XXXXX_XXXXX` handle; pass that handle to `secedgar_dataframe_query` for joins, aggregates, window functions, percentiles — standard DuckDB SQL.
+- Lists every dataframe (`df_XXXXX_XXXXX`) registered by the data-returning `secedgar_*` tools — any response carrying a `dataset` field holds one
+- Optional `name` describes a single dataframe; omit to list every dataframe for the tenant
+- Each entry surfaces source tool, query parameters, creation/expiry timestamps, row count, column schema, and whether the dataframe is truncated relative to the upstream source
+- Read the column schema here before writing SQL for `secedgar_dataframe_query`
 
-- **Read-only by default.** Writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected by the framework SQL gate. System catalogs (`information_schema`, `pg_catalog`, `sqlite_master`, `duckdb_*`) are denied at the bridge layer so callers can't enumerate dataframes they don't already hold a handle for. `secedgar_dataframe_drop` is the only destructive tool and is opt-in (`EDGAR_DATAFRAME_DROP_ENABLED=true`); TTL handles cleanup otherwise.
-- **Per-table TTL.** Each dataframe ages on its own clock (default 24h, override with `EDGAR_DATASET_TTL_SECONDS`). The canvas itself uses the framework's sliding TTL.
-- **`register_as` chaining.** `secedgar_dataframe_query` can persist its result as a new dataframe (`df_XXXXX_XXXXX`) with a fresh TTL — pipe analyses without re-running the source query.
+---
 
-## Resources
+### `secedgar_dataframe_query` <sub>tool</sub>
 
-| URI | Description |
-|:---|:---|
-| `secedgar://concepts` | Common XBRL financial concepts grouped by statement, mapping friendly names to XBRL tags |
-| `secedgar://filing-types` | Common SEC filing types with descriptions, cadence, and use cases, plus the full 8-K item-code decode tables for both numbering regimes |
+- Runs a single-statement SELECT (standard DuckDB SQL — joins, aggregates, window functions, CTEs) against the dataframes registered by the data-returning `secedgar_*` tools
+- Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected by the framework SQL gate; system catalogs (`information_schema`, `pg_catalog`, `sqlite_master`, `duckdb_*`) are denied at the bridge layer so callers can't enumerate dataframes they don't already hold a handle for
+- `row_limit` caps rows materialized in the response (default 1000, max 10000); a capped result reports `row_count_capped: true` with `row_count` as that cap rather than a total — a SQL `LIMIT` exactly equal to the cap is indistinguishable from an exact result and reported as such
+- `register_as` persists the result as a new dataframe (`df_XXXXX_XXXXX`) with a fresh TTL, to chain analyses without re-running the source query
+- BIGINT columns (XBRL `value`, COUNT/SUM results) serialize as JSON strings to preserve precision past 2^53 — cast to `DOUBLE` in projections for inline arithmetic
 
-## Prompts
+---
 
-| Prompt | Description |
-|:---|:---|
-| `secedgar_company_analysis` | Guides a structured analysis of a public company's SEC filings: identify recent filings, extract financial trends, surface risk factors, and note material events |
+### `secedgar_dataframe_drop` <sub>tool</sub>
+
+- Drops a canvas dataframe by name; idempotent — returns `dropped: false` when nothing matched
+- Opt-in via `EDGAR_DATAFRAME_DROP_ENABLED=true` — off by default since the per-table TTL already reclaims canvas tables, and this is the only destructive tool on the server
+- Off, the tool is registered through `disabledTool()`: absent from `tools/list` and uncallable, but shown on the HTTP landing page in a `disabled` group naming the reason and the flag that enables it
+
+---
+
+### `secedgar://concepts` <sub>resource</sub>
+
+- XBRL financial concepts grouped by statement (Income Statement, Balance Sheet, Cash Flow, Per Share, Entity Info), returned as `text/markdown`
+- Maps the friendly names accepted by `secedgar_get_financials` and `secedgar_fetch_frames` to their underlying XBRL tags
+
+---
+
+### `secedgar://filing-types` <sub>resource</sub>
+
+- Common SEC filing types with descriptions, cadence, and typical use cases, returned as `text/markdown`
+- Includes the full 8-K item-code decode tables for both numbering regimes (the current dotted scheme and the pre-2004-08-23 legacy integers)
+- Helps choose the `forms` parameter for `secedgar_search_filings`, the `form_types` filter for `secedgar_company_search`, or the `items` filter for `secedgar_get_material_events`
+
+---
+
+### `secedgar_company_analysis` <sub>prompt</sub>
+
+- Arguments: `company` (name, ticker, or CIK) required; `focus_areas` free-text optional (e.g. `"revenue growth, debt levels, insider activity"`) — omitted, it performs a general analysis
+- Baseline workflow: company identification, financial trends, recent-filing review, and material events, each routed through the corresponding `secedgar_*` tool, closing with a peer comparison via `secedgar_fetch_frames`
+- `focus_areas` mentioning insider, institutional, or blockholder/activist terms adds the matching ownership step — insider transactions (Form 4/4-A), institutional holdings (`secedgar_find_holders` then `secedgar_get_institutional_holdings`), or 5%+ blockholders (13D/13G) — the generic word "ownership" adds all three
+- Returns a single user-role message carrying the numbered workflow and a findings template to fill in
 
 ## Features
 
-Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
+
+EDGAR-specific:
 
-- Declarative tool definitions — single file per tool, framework handles registration and validation
-- Structured output schemas with automatic formatting for human-readable display
-- Unified error handling across all tools
-- Pluggable auth (`none`, `jwt`, `oauth`)
-- Structured logging with request-scoped context
-- Runs locally (stdio/HTTP) from the same codebase
+- Rate-limited HTTP client honoring SEC's 10 req/s limit with automatic inter-request delay; a 429 fails fast with a cool-down hint instead of retrying, since SEC's own block window outlasts any retry budget
+- CIK resolution from tickers (including ETFs and mutual funds via `company_tickers_mf.json`), current and former company names, or raw CIK numbers, with local caching, corporate-suffix normalization, and near-match trigram suggestions on zero-result queries
+- Friendly XBRL concept name mapping with historical tag-change handling and a searchable, reverse-lookupable concept catalog
+- HTML-to-text conversion for filing documents, with heading detection and offset-based paging for oversized filings
+- Opt-in local SQLite mirror of `company_tickers` + XBRL company-facts (`EDGAR_MIRROR_ENABLED`) serves CIK resolution and financials from disk instead of the live API
 
-SEC EDGAR–specific:
+Agent-friendly output:
 
-- Rate-limited HTTP client respecting SEC's 10 req/s limit with automatic inter-request delay
-- CIK resolution from tickers (including ETFs and mutual funds via `company_tickers_mf.json`), company names (current and former), or raw CIK numbers with local caching; corporate-suffix normalization on the name passes and dotted share-class tickers (`BRK.B`) resolved to SEC's hyphenated form; near-match trigram suggestions on zero-result name and ticker queries; committed `former-names.json` asset for prior-name resolution (`Facebook` → Meta, `Square` → Block)
-- Friendly XBRL concept name mapping with historical tag change handling
-- Searchable concept catalog with statement-group metadata and reverse XBRL tag lookup
-- HTML-to-text conversion for filing documents via `html-to-text`
-- In-conversation SQL analytics: `secedgar_fetch_frames`, `secedgar_compare_companies`, `secedgar_search_filings`, `secedgar_get_financials`, `secedgar_get_material_events`, `secedgar_get_insider_transactions`, `secedgar_get_institutional_holdings`, and `secedgar_find_holders` materialize their full result as a DuckDB-backed canvas dataframe queryable via `secedgar_dataframe_query`
-- No API keys required — SEC EDGAR is a free, public API
+- In-conversation SQL analytics — data-returning tools materialize their full result as a DuckDB-backed canvas dataframe (`df_<id>`); inspect its columns with `secedgar_dataframe_describe`, then query with `secedgar_dataframe_query`
+- Discriminated outputs — `source` fields on merged filing-search rows (`efts`/`submissions`/`full-index`), typed `caveats` entries for series staleness and fiscal-Q4 gaps, and `gaps`/`failed_companies` rows instead of silent omission
+- Graceful partial failure — `secedgar_compare_companies` returns every resolved company alongside `failed_companies` and per-concept `gaps` rather than failing the whole request
+- Provenance on scan and staleness — `history_scanned_through`, `publication_lag_days`, and `dataset.truncated` let agents reason about scan depth, report lag, and completeness
 
 ## Getting started
 
@@ -337,6 +342,25 @@ Or with npx (no Bun required):
 }
 ```
 
+Or with Docker:
+
+```json
+{
+  "mcpServers": {
+    "secedgar-mcp-server": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "MCP_TRANSPORT_TYPE=stdio",
+        "-e", "EDGAR_USER_AGENT=YourAppName your-email@example.com",
+        "ghcr.io/cyanheads/secedgar-mcp-server:latest"
+      ]
+    }
+  }
+}
+```
+
 For Streamable HTTP, set the transport and start the server:
 
 ```sh
@@ -346,7 +370,8 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
 
 ### Prerequisites
 
-- [Bun v1.3.0](https://bun.sh/) or higher.
+- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).
+- A SEC EDGAR User-Agent string — any `"AppName contact@email.com"` format works; no account or key required.
 
 ### Installation
 
@@ -384,18 +409,20 @@ All configuration is validated at startup via Zod schemas in `src/config/server-
 | `EDGAR_RATE_LIMIT_RPS` | Max requests/second to SEC APIs. Do not exceed 10. | `10` |
 | `EDGAR_TICKER_CACHE_TTL` | Seconds to cache the company tickers lookup file. | `3600` |
 | `EDGAR_DATASET_TTL_SECONDS` | Per-table TTL for canvas-registered dataframes. Sliding window touched on every dataframe op. | `86400` |
-| `EDGAR_DATAFRAME_DROP_ENABLED` | Set to `true` to expose `secedgar_dataframe_drop` — the only destructive tool on this server. Off by default; TTL handles cleanup. | `false` |
+| `EDGAR_DATAFRAME_DROP_ENABLED` | Set to `true` to expose `secedgar_dataframe_drop` — the only destructive tool on this server. Off by default; TTL handles cleanup, and the tool is still listed on the HTTP landing page as disabled, with the flag that enables it. | `false` |
 | `EDGAR_MIRROR_ENABLED` | Enable the local SQLite mirror of `company_tickers` + XBRL company-facts so CIK resolution and financials read from disk instead of the live API. Node/Bun only (skipped on Workers). Bootstrap once with `bun run mirror:init`. | `false` |
 | `EDGAR_MIRROR_PATH` | Directory holding the mirror SQLite databases. | `./data/edgar-mirror` |
 | `EDGAR_MIRROR_REFRESH_CRON` | Cron for the in-process nightly refresh (HTTP transport only). Recommended `0 9 * * *`. Omit to refresh out-of-band via `bun run mirror:refresh`. | — |
 | `EDGAR_MIRROR_FALLBACK_LIVE` | When the mirror misses (not yet synced, or a filing newer than the last refresh), fall back to the live SEC API. Set `false` for strict mirror-only reads. | `true` |
-| `CANVAS_PROVIDER_TYPE` | Canvas engine. Defaults to `duckdb`; set to `none` to disable the canvas (e.g. when running on Cloudflare Workers, where DuckDB has no V8-isolate build). | `duckdb` |
+| `CANVAS_PROVIDER_TYPE` | Canvas engine. Defaults to `duckdb`; set to `none` to disable the canvas. | `duckdb` |
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |
 | `MCP_HTTP_PORT` | HTTP server port | `3010` |
 | `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth` | `none` |
 | `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.) | `info` |
 | `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
 
+See [`.env.example`](./.env.example) for the full list of optional overrides.
+
 ## Running the server
 
 ### Local development
@@ -432,7 +459,7 @@ docker exec <container> bun run mirror:refresh   # re-ingest when the archive ha
 
 | Directory | Purpose |
 |:---|:---|
-| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). Ten SEC EDGAR tools plus three `dataframe_*` tools for SQL analytics. |
+| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). Fourteen SEC EDGAR tools plus three `dataframe_*` tools for SQL analytics. |
 | `src/mcp-server/resources/definitions/` | Resource definitions. XBRL concepts and filing types. |
 | `src/mcp-server/prompts/definitions/` | Prompt definitions. Company analysis prompt. |
 | `src/services/edgar/` | SEC EDGAR API client, XBRL concept mapping, HTML-to-text conversion. |
@@ -447,10 +474,11 @@ See [`CLAUDE.md`](./CLAUDE.md) and [`AGENTS.md`](./AGENTS.md) for development gu
 - Handlers throw, framework catches — no `try/catch` in tool logic
 - Use `ctx.log` for logging, `ctx.state` for storage
 - Register new tools and resources in the `createApp()` arrays
+- Wrap external SEC EDGAR calls: validate the raw response → normalize to a domain type → return the output schema; never fabricate a missing XBRL field — report it under `gaps` instead
 
 ## Contributing
 
-Issues and pull requests are welcome. Run checks and tests before submitting:
+Issues are welcome. Run checks and tests before submitting:
 
 ```sh
 bun run devcheck

package/changelog/0.1.x/0.1.0.md

@@ -0,0 +1,33 @@
+---
+summary: "Initial release. MCP server for SEC EDGAR — company lookups, filing search/retrieval, XBRL financial data, and cross-company comparison."
+breaking: false
+---
+
+# 0.1.0 — 2026-03-24
+
+Initial release. MCP server for SEC EDGAR — company lookups, filing search/retrieval, XBRL financial data, and cross-company comparison.
+
+## Added
+
+- **Tools**
+  - `secedgar_company_search` — find companies and retrieve entity info with optional recent filings
+  - `secedgar_search_filings` — full-text search across all EDGAR filing documents since 1993
+  - `secedgar_get_filing` — fetch a specific filing's metadata and document content
+  - `secedgar_get_financials` — get historical XBRL financial data for a company (friendly concept names supported)
+  - `secedgar_compare_metric` — compare a financial metric across all reporting companies for a period
+- **Resources**
+  - `secedgar://concepts` — XBRL financial concepts grouped by statement, mapping friendly names to tags
+  - `secedgar://filing-types` — common SEC filing types with descriptions, cadence, and use cases
+- **Prompts**
+  - `secedgar_company_analysis` — guided structured analysis of a company's SEC filings
+- **Services**
+  - `EdgarApiService` — rate-limited HTTP client with CIK resolution and ticker caching
+  - `concept-map` — static friendly name → XBRL tag mapping (handles ASC 606 historical tag changes)
+  - `filing-to-text` — HTML → readable plain text conversion via `html-to-text`
+- **Infrastructure**
+  - Dockerfile and `.dockerignore` for containerized deployment
+  - Biome for linting and formatting
+  - Vitest test scaffolding
+  - Build scripts (build, clean, rebuild, devcheck, tree, lint-mcp)
+  - Stdio and HTTP transport support
+  - Design document (`docs/sec-edgar-mcp-design.md`)

package/changelog/0.1.x/0.1.1.md

@@ -0,0 +1,27 @@
+---
+summary: "Metadata, documentation, and packaging polish — no functional changes."
+breaking: false
+---
+
+# 0.1.1 — 2026-03-24
+
+Metadata, documentation, and packaging polish — no functional changes.
+
+## Added
+
+- `README.md` with full tool/resource/prompt docs, configuration, and getting started guide
+- `LICENSE` file (Apache 2.0)
+- `bunfig.toml` for Bun runtime configuration
+- `docs/tree.md` directory structure
+
+## Changed
+
+- `.env.example` — replaced template placeholders with SEC EDGAR env vars
+- `CLAUDE.md` — added `lint:mcp` command, fixed import example to use real service path
+- `Dockerfile` — added OCI description and source labels
+- `package.json` — filled in description, mcpName, keywords, repository URLs, author, bun engine, packageManager
+- `server.json` — filled in name/description/repo URL, set runtimeHint to bun, added `EDGAR_USER_AGENT` env var
+
+## Removed
+
+- Template echo tests (`echo.tool.test.ts`, `echo.resource.test.ts`, `echo.prompt.test.ts`)