@pipeworx/mcp-edgar 0.3.1 → 0.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +1 -1
- package/README.md +121 -9
- package/bin/cli.js +17 -0
- package/package.json +15 -3
- package/server.json +1 -1
- package/src/index.ts +3305 -205
- package/src/server.ts +45 -0
- package/tsconfig.json +5 -1
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,13 +1,66 @@
|
|
|
1
|
-
#
|
|
1
|
+
# SEC EDGAR — Public Company Filings
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The Securities and Exchange Commission's filings database. Every public company in the US files here, every filing is timestamped and immutable, and every disclosure (revenue, debt, risk factors, executive compensation, M&A activity, insider trading) is structured for machine retrieval. Free and authoritative.
|
|
4
4
|
|
|
5
|
-
Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to
|
|
5
|
+
Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1679+ live data sources.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Why this matters for AI agents
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
If your agent is answering anything about a US public company — financials, legal exposure, IP, executive turnover, recent material events — the answer is in EDGAR. The data is structured (XBRL), so you don't have to parse PDFs.
|
|
10
|
+
|
|
11
|
+
The two key flows — and the one call that does both:
|
|
12
|
+
|
|
13
|
+
**0. Snapshot (one call).** "Give me the SEC picture on Apple." → `edgar_company_snapshot({ticker_or_cik: "AAPL"})` → CIK + the recent substantive filings (10-K/10-Q/8-K/20-F/40-F/6-K/DEF 14A by default; Form 4 noise excluded unless you ask for `form_type: "all"`) + the headline XBRL figures from the latest annual report (revenue, net income, assets, cash, EPS…). This is flows 1 and 2 collapsed: the resolve → list → pull chain that depth users otherwise assemble by hand three calls at a time. A filer with no XBRL (a fund or trust) still returns its filings with `financials_status: "unavailable"` and the reason. `edgar_ticker_to_cik` now returns a `next` hint pointing here.
|
|
14
|
+
|
|
15
|
+
**1. Filings flow.** "Show me Apple's recent 10-Q." → `edgar_ticker_to_cik("AAPL")` → `edgar_company_filings(cik)` → list of filings with accession numbers, form types, filing dates.
|
|
16
|
+
|
|
17
|
+
**2. Concepts flow.** "What was Apple's revenue trend the last 4 quarters?" → `edgar_company_concept(cik, "Revenues")` → time series of XBRL-tagged values across periods.
|
|
18
|
+
|
|
19
|
+
**3. Peer/competitor flow.** "Who competes with Apple?" → `edgar_companies_by_sic({ticker_or_cik: "AAPL"})` → resolves Apple's own SIC code (3571, Electronic Computers) and returns other SEC filers under that code, listed-ticker peers first. Pass a `sic` code directly instead of a company to browse an industry cold.
|
|
20
|
+
|
|
21
|
+
**4. Entity-resolution flow (parent ↔ subsidiary).** `sponsor_to_filer({sponsor: "Merck Sharp and Dohme"})` resolves a subsidiary/operating name up to its listed parent (MRK). `filer_to_sponsors({ticker_or_cik: "MRK"})` goes the other way — the parent's full disclosed subsidiary list from Exhibit 21 of its latest 10-K, with jurisdiction and filing provenance. Pass `name_filter` to check one candidate name without reading the whole list.
|
|
22
|
+
|
|
23
|
+
**5. Product-level revenue.** "How much revenue did Keytruda generate?" → `edgar_product_revenue({ticker_or_cik: "MRK", product_filter: "Keytruda"})`. `edgar_company_concept`/`edgar_company_facts` only expose undimensioned XBRL totals — a product/segment breakdown is tagged with an XBRL dimension (a "Keytruda [Member]"), invisible to those APIs. This reads SEC's own rendered Financial Report of that dimensional data straight out of the revenue-disaggregation note, with a citation (accession, filing date, report URL). With no `form_type` it resolves 10-K, then 20-F, then 40-F, so foreign private issuers work the same way (`edgar_product_revenue({ticker_or_cik: "NVS", product_filter: "Entresto"})` reads Novartis's 20-F); the form actually used comes back as `resolved_form`. Not every filer tags product-level revenue in XBRL — Neurocrine discloses revenue by major customer and United Therapeutics only its recognition policy, and both return an explicit `not_found` rather than an empty array.
|
|
24
|
+
|
|
25
|
+
Both flows are usually preceded by `edgar_ticker_to_cik` or `resolve_entity({type: "company", value: "AAPL"})` to get the canonical 10-digit CIK.
|
|
26
|
+
|
|
27
|
+
## Auth
|
|
28
|
+
|
|
29
|
+
None. SEC EDGAR is a free, public, no-auth service. Pipeworx forwards a polite User-Agent header to comply with SEC's API guidelines.
|
|
30
|
+
|
|
31
|
+
## Citable URIs
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
pipeworx://edgar/company/{cik}/filings
|
|
35
|
+
pipeworx://edgar/company/{cik}/facts
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Embed in your output. Stable across reorganizations — companies rebrand, but their CIK doesn't change.
|
|
39
|
+
|
|
40
|
+
## Form types worth knowing
|
|
41
|
+
|
|
42
|
+
| Form | What it is | When |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| 10-K | Annual report | ~60 days after fiscal year-end |
|
|
45
|
+
| 10-Q | Quarterly report | ~45 days after quarter-end |
|
|
46
|
+
| 8-K | Material event (M&A, exec changes, earnings, etc.) | Within 4 business days |
|
|
47
|
+
| DEF 14A | Proxy statement (executive comp, governance) | ~6 weeks before annual meeting |
|
|
48
|
+
| Form 4 | Insider trading disclosure | Within 2 business days of trade |
|
|
49
|
+
| 13F | Institutional holdings (>$100M AUM funds) | 45 days after quarter-end |
|
|
50
|
+
| S-1 | IPO registration | When going public |
|
|
51
|
+
| 13D / 13G | >5% beneficial ownership disclosure | Within 10 days of crossing threshold |
|
|
52
|
+
|
|
53
|
+
For insider trades specifically, see the dedicated `insider-trading` pack — it surfaces Form 4 / 13D / 13G changes with cleaner schemas.
|
|
54
|
+
|
|
55
|
+
## Common pitfalls
|
|
56
|
+
|
|
57
|
+
- **Concept name drift.** SEC filers occasionally change the XBRL concept they tag for revenue. The default `Revenues` concept may be stale for newer fiscal years; try `RevenueFromContractWithCustomerExcludingAssessedTax` as a fallback.
|
|
58
|
+
- **Period mismatches.** Fiscal years end at different times across companies (Apple = Sept, Microsoft = June, Google = Dec). When comparing, always disclose the period.
|
|
59
|
+
- **CIK formatting.** Some endpoints want zero-padded 10-digit (`0000320193`), some want unpadded (`320193`). Pipeworx accepts either; the `cik_padded` field in `edgar_ticker_to_cik` is the canonical form for resource URIs.
|
|
60
|
+
- **Real-time-ish, not real-time.** Filings appear on EDGAR within minutes of submission, but Pipeworx caches results. For breaking-news-grade timeliness, set `Cache-Control: no-cache` (anonymous limit applies) or check the `_meta.cache.fresh_until` field.
|
|
61
|
+
- **Concept availability differs.** Smaller filers tag fewer XBRL concepts than large ones. `edgar_company_concept` may return empty arrays for valid concepts that the company simply doesn't report. Use `edgar_company_facts` to see which concepts a company DOES report.
|
|
62
|
+
- **The company argument is spelled three different ways across this pack, and `edgar_company_concept` accepts all of them.** `edgar_company_filings`/`edgar_insider_transactions`/`edgar_product_revenue` name it `ticker_or_cik`, `edgar_fund_holdings`/`edgar_ticker_to_cik` name it `ticker`, and `edgar_company_concept`/`edgar_company_facts` name it `cik` (which takes a ticker too). A model filling arguments reaches for whichever word it read last, so `edgar_company_concept` declares `ticker` and `ticker_or_cik` as aliases of `cik`, and `metric` as an alias of `concept`. Measured before that change (fleet #2058): of 11 times the ask_pipeworx adjudicator selected this tool over 16 never-before-asked questions, 9 calls were rejected by the gateway's required-argument pre-flight — every one of them because it had sent `ticker` or `ticker_or_cik` rather than `cik`, and a third of those sent `metric` rather than `concept` as well. Both calls that used `cik`+`concept` succeeded. The outcome recorded for the rejected ones was `partial`, not an error, because a single-tool selection that arrives as a one-element `tools` array runs the fan-out branch — so the word for "the only lookup never ran" was the same word used for "some of several lookups ran".
|
|
63
|
+
- **`fiscal_year` and `fiscal_period` are filters AND response fields.** They are the names of two fields on every row in `values`, and the description's advice to "match the requested fiscal_year and fiscal_period" used to make argument-fillers send them as arguments, where they were undeclared and silently dropped — so the caller got all 89-230 reported periods back with nothing saying its filter had been ignored. They are now real optional filters: pass either or both and `values`/`latest` come back scoped to it, with a `period_filter` block echoing what was applied. An unmatched filter returns NO rows plus the list of fiscal years and periods the filer actually reports, rather than falling back to every period — `fiscal_year` is the filer's OWN label (NVDA's FY2024 ended January 2024), so a caller thinking in calendar years needs to see the labels rather than be handed a neighbouring year's number.
|
|
11
64
|
|
|
12
65
|
## Quick Start
|
|
13
66
|
|
|
@@ -23,7 +76,25 @@ Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
|
|
|
23
76
|
}
|
|
24
77
|
```
|
|
25
78
|
|
|
26
|
-
|
|
79
|
+
### What this endpoint actually serves
|
|
80
|
+
|
|
81
|
+
`tools/list` at `https://gateway.pipeworx.io/edgar/mcp` returns the tools in the table
|
|
82
|
+
above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
|
|
83
|
+
`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
|
|
84
|
+
gateway-wide set. So the tool count you see is larger than this table: a
|
|
85
|
+
single-pack endpoint currently lists roughly 30 shared tools alongside the
|
|
86
|
+
pack's own. The connection's `initialize` response states its exact scope, and
|
|
87
|
+
is the authoritative answer for a given day.
|
|
88
|
+
|
|
89
|
+
This is deliberate, not multiplexing by accident. The meta-tools are what let a
|
|
90
|
+
scoped connection answer a question this pack does not cover — via
|
|
91
|
+
`ask_pipeworx`, which routes across the whole catalog — without you adding a
|
|
92
|
+
second MCP server. There is currently no way to mount a pack endpoint without
|
|
93
|
+
them; if the extra schemas cost you more context than the routing is worth,
|
|
94
|
+
connect to the full gateway once rather than to several pack endpoints.
|
|
95
|
+
|
|
96
|
+
Or connect to the full Pipeworx gateway to get every pack's tools listed
|
|
97
|
+
directly, instead of just this one's:
|
|
27
98
|
|
|
28
99
|
```json
|
|
29
100
|
{
|
|
@@ -35,9 +106,50 @@ Or connect to the full Pipeworx gateway for access to all 1337+ data sources:
|
|
|
35
106
|
}
|
|
36
107
|
```
|
|
37
108
|
|
|
109
|
+
Both URLs reach the same gateway and the same 1679+ data sources. The
|
|
110
|
+
only difference is which pack's tools are listed **directly**; `ask_pipeworx`
|
|
111
|
+
reaches all of them from either one.
|
|
112
|
+
|
|
113
|
+
## No MCP client? Call it over HTTP
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
curl -X POST https://gateway.pipeworx.io/v1/tools/edgar_search_filings \
|
|
117
|
+
-H 'Content-Type: application/json' \
|
|
118
|
+
-d '{"query":"artificial intelligence","form_type":"10-K","start_date":"2024-01-01","end_date":"2024-12-31","limit":20}'
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/edgar_search_filings`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
|
|
122
|
+
|
|
123
|
+
## Standalone (no gateway account)
|
|
124
|
+
|
|
125
|
+
This package also runs as a local stdio MCP server — no Pipeworx account, no
|
|
126
|
+
gateway round-trip:
|
|
127
|
+
|
|
128
|
+
```json
|
|
129
|
+
{
|
|
130
|
+
"mcpServers": {
|
|
131
|
+
"edgar": {
|
|
132
|
+
"command": "npx",
|
|
133
|
+
"args": ["-y", "@pipeworx/mcp-edgar"]
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Or run it directly to confirm it starts:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
npx -y @pipeworx/mcp-edgar
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
It speaks MCP over stdin/stdout and answers `initialize`/`tools/list`/`tools/call`
|
|
146
|
+
for **only** this pack's tools — none of the shared meta-tools the gateway
|
|
147
|
+
connection above adds. Same source, same tools, no ask_pipeworx routing.
|
|
148
|
+
|
|
38
149
|
## Using with ask_pipeworx
|
|
39
150
|
|
|
40
|
-
Instead of calling tools directly, you can ask questions in plain English
|
|
151
|
+
Instead of calling tools directly, you can ask questions in plain English —
|
|
152
|
+
this works on the pack endpoint above as well as on the full gateway:
|
|
41
153
|
|
|
42
154
|
```
|
|
43
155
|
ask_pipeworx({ question: "your question about Edgar data" })
|
|
@@ -47,7 +159,7 @@ The gateway picks the right tool and fills the arguments automatically.
|
|
|
47
159
|
|
|
48
160
|
## More
|
|
49
161
|
|
|
50
|
-
- [
|
|
162
|
+
- [Docs and guides](https://pipeworx.io/docs)
|
|
51
163
|
- [pipeworx.io](https://pipeworx.io)
|
|
52
164
|
|
|
53
165
|
## License
|
package/bin/cli.js
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
//
|
|
3
|
+
// Entry point for `npx @pipeworx/mcp-<slug>`.
|
|
4
|
+
//
|
|
5
|
+
// Packs ship as raw TypeScript (no build step — see publish-pack.sh for why:
|
|
6
|
+
// tsx sidesteps every extensionless-import / bare-JSON-import edge case a
|
|
7
|
+
// per-pack tsc build would have to solve one pack at a time). This file
|
|
8
|
+
// registers tsx's ESM loader programmatically, then hands off to src/server.ts,
|
|
9
|
+
// which wraps the pack's {tools, callTool} export in a stdio MCP server.
|
|
10
|
+
//
|
|
11
|
+
// Copied verbatim into every published pack repo by scripts/publish-pack.sh —
|
|
12
|
+
// edit this file, not a per-pack copy.
|
|
13
|
+
import { register } from 'tsx/esm/api';
|
|
14
|
+
|
|
15
|
+
register();
|
|
16
|
+
|
|
17
|
+
await import('../src/server.ts');
|
package/package.json
CHANGED
|
@@ -1,20 +1,32 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pipeworx/mcp-edgar",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.3",
|
|
4
4
|
"description": "EDGAR MCP — SEC EDGAR public APIs (free, no auth)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "src/index.ts",
|
|
7
7
|
"types": "src/index.ts",
|
|
8
|
+
"bin": {
|
|
9
|
+
"mcp-edgar": "bin/cli.js"
|
|
10
|
+
},
|
|
8
11
|
"keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "edgar"],
|
|
9
12
|
"license": "MIT",
|
|
10
13
|
"repository": {
|
|
11
14
|
"type": "git",
|
|
12
|
-
"url": "https://github.com/pipeworx-io/mcp-edgar"
|
|
15
|
+
"url": "git+https://github.com/pipeworx-io/mcp-edgar.git"
|
|
13
16
|
},
|
|
14
17
|
"scripts": {
|
|
15
18
|
"typecheck": "tsc --noEmit"
|
|
16
19
|
},
|
|
20
|
+
"dependencies": {
|
|
21
|
+
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
22
|
+
"tsx": "^4.19.0"
|
|
23
|
+
},
|
|
17
24
|
"devDependencies": {
|
|
18
|
-
"typescript": "^5.
|
|
25
|
+
"typescript": "^5.9.3",
|
|
26
|
+
"@cloudflare/workers-types": "^4.20260405.1"
|
|
27
|
+
},
|
|
28
|
+
"pipeworx": {
|
|
29
|
+
"sourceHash": "v1-c758c9386febbe0e91470cf7aa45ee292d3edb8f1b165a1404f258617be43004",
|
|
30
|
+
"sourceCommit": "76aa8f5d9b5dc2f665563030647c68e661478864"
|
|
19
31
|
}
|
|
20
32
|
}
|
package/server.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"name": "io.github.pipeworx-io/edgar",
|
|
4
4
|
"title": "Edgar",
|
|
5
5
|
"description": "EDGAR MCP — SEC EDGAR public APIs (free, no auth)",
|
|
6
|
-
"version": "0.3.
|
|
6
|
+
"version": "0.3.3",
|
|
7
7
|
"websiteUrl": "https://pipeworx.io/packs/edgar",
|
|
8
8
|
"repository": {
|
|
9
9
|
"url": "https://github.com/pipeworx-io/mcp-edgar",
|