@pipeworx/mcp-alphavantage 0.1.0 → 0.1.2
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 +159 -9
- package/bin/cli.js +17 -0
- package/package.json +15 -3
- package/server.json +2 -2
- package/src/index.ts +968 -37
- package/src/server.ts +45 -0
- package/tsconfig.json +5 -1
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,17 +1,93 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Alpha Vantage — Stock and Market Data
|
|
2
2
|
|
|
3
|
-
Alpha Vantage
|
|
3
|
+
Alpha Vantage's REST API for stock prices, fundamentals, technical indicators, forex, crypto, and economic indicators. ~20+ years of historical equities data, real-time-ish quotes (15-minute delayed on free tier), and structured fundamental data parsed from SEC filings.
|
|
4
4
|
|
|
5
|
-
Part of
|
|
5
|
+
Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1683+ live data sources.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Why this matters for AI agents
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
Where SEC EDGAR gives you raw filings, Alpha Vantage gives you cleaned-up structured data ready for analysis: income statements, balance sheets, cash flow, key ratios, recent earnings, technical indicators. For real-time-ish quotes during market hours, this is the source.
|
|
10
|
+
|
|
11
|
+
Common flows:
|
|
12
|
+
|
|
13
|
+
- **Quote.** "Where's AAPL trading?" → `av_quote({symbol: "AAPL"})` → latest price, change, volume.
|
|
14
|
+
- **Income statement.** "Apple's last 4 quarters of revenue/income." → `av_income_statement({symbol: "AAPL"})`.
|
|
15
|
+
- **Earnings.** "When does NVDA report next?" → `av_earnings({symbol: "NVDA"})`.
|
|
16
|
+
- **Daily price history.** "AAPL 1-year history." → `av_daily({symbol: "AAPL"})`.
|
|
17
|
+
|
|
18
|
+
Used by the `fintech_company_deep_dive` compound for the quote + income statement layer alongside SEC EDGAR.
|
|
19
|
+
|
|
20
|
+
## Auth — bring your own PAID key (Pipeworx fronts none)
|
|
21
|
+
|
|
22
|
+
**This pack is BYO-only as of 2026-09-02** (Bruce's ruling on fleet #1117). Pipeworx
|
|
23
|
+
does not supply a key: the gateway entry no longer names
|
|
24
|
+
`PLATFORM_ALPHAVANTAGE_KEY`, so `_apiKey` is whatever you pass and nothing else.
|
|
25
|
+
Call it with no key and you get a refusal that says the pack requires an API key
|
|
26
|
+
and names two working substitutes — no upstream call is spent producing it.
|
|
27
|
+
|
|
28
|
+
**A FREE Alpha Vantage key will not work here, whoever it belongs to.** Alpha
|
|
29
|
+
Vantage meters its free tier by SOURCE IP and never validates the key at all —
|
|
30
|
+
measured 2026-09-02 on three real keys plus the invented string
|
|
31
|
+
`ZZZZINVALIDKEY99`, which drew the same "25 requests per day" refusal from our
|
|
32
|
+
gateway that a real key did, and returned real IBM data from a laptop in the same
|
|
33
|
+
minute (fleet #1070; the full measurement is in the header of `src/index.ts`).
|
|
34
|
+
Because the address the call leaves from is what is spent, your free key is
|
|
35
|
+
refused through the gateway for exactly the reason ours was. That also means a
|
|
36
|
+
laptop test proves nothing about this pack: any string "works" from an IP with
|
|
37
|
+
budget left.
|
|
38
|
+
|
|
39
|
+
**What does work: a PAID key.** Premium ($50–250/mo) is the one thing Alpha
|
|
40
|
+
Vantage actually authenticates — its premium endpoints refuse a free key by name.
|
|
41
|
+
Untested from here, since we do not hold one, so treat it as an inference rather
|
|
42
|
+
than a measurement. Pass it via `_apiKey`.
|
|
43
|
+
|
|
44
|
+
**If you have no paid key**, use the substitutes the refusal names, both of which
|
|
45
|
+
answer these questions today:
|
|
46
|
+
|
|
47
|
+
- `get_company_financials` (**sec-xbrl** pack) — US income statements, balance
|
|
48
|
+
sheets and cash flow, **keyless**, no daily cap. Covers everything
|
|
49
|
+
`av_overview` / `av_income_statement` / `av_balance_sheet` / `av_earnings` do
|
|
50
|
+
for US filers.
|
|
51
|
+
- **finnhub** — real-time quotes, free key, 60 calls/min and no daily cap.
|
|
52
|
+
Covers `av_quote`, and non-US symbols.
|
|
53
|
+
|
|
54
|
+
**The "demo" key**: Alpha Vantage advertises `demo` as a no-signup key, but it
|
|
55
|
+
returns errors for most calls, and through the gateway it hits the same IP meter
|
|
56
|
+
as any other free key. The pack refuses it explicitly.
|
|
57
|
+
|
|
58
|
+
## Update cadence
|
|
59
|
+
|
|
60
|
+
- **Quotes**: real-time on paid tiers, 15-minute delayed on free, market hours only
|
|
61
|
+
- **Daily / weekly / monthly history**: end-of-day, refreshes after market close
|
|
62
|
+
- **Fundamentals**: refreshes within ~24h of new SEC filings
|
|
63
|
+
- **Earnings**: refreshes after each company reports
|
|
64
|
+
|
|
65
|
+
Pipeworx caches with TTLs aligned to these.
|
|
66
|
+
|
|
67
|
+
## Common pitfalls
|
|
68
|
+
|
|
69
|
+
- **Free-tier 5/min limit.** Bursting fails. Pace agent calls or upgrade. Moot
|
|
70
|
+
from Pipeworx, where a free key never gets as far as the per-minute limit.
|
|
71
|
+
- **A spent daily allowance is an error, not an empty answer.** Once the 25-a-day
|
|
72
|
+
cap on YOUR key is gone, every tool in this pack fails with `auth_required` and
|
|
73
|
+
the words "the daily request allowance behind this key is spent" —
|
|
74
|
+
deliberately, so the gateway can attach a `credential` block saying whose key
|
|
75
|
+
ran out. It used to answer `{found:false, reason:"quota_exceeded"}`, which reads
|
|
76
|
+
as a successful call to every consumer that does not parse prose, and a spent
|
|
77
|
+
key was reported healthy for weeks (fleet #1091). A SHORT throttle — a notice
|
|
78
|
+
naming only a per-minute frequency — is still a soft
|
|
79
|
+
`{found:false, reason:"rate_limit"}`, because that one really does clear on its
|
|
80
|
+
own. Since #1117 that block can only ever say `caller`: the pack left the
|
|
81
|
+
platform-key probe rotation along with the platform key, so there is no
|
|
82
|
+
Pipeworx allowance left to spend.
|
|
83
|
+
- **Symbol vs ticker.** Mostly the same on Alpha Vantage, but a few non-US tickers need a suffix (e.g., `BARC.LON`). Default endpoints assume US-listed.
|
|
84
|
+
- **"Real-time" definition.** Free tier is 15-min delayed end-of-day-style snapshots. For algo trading, you want a paid tier. For agent research, free is fine.
|
|
85
|
+
- **Earnings calendar isn't always accurate.** Companies move report dates; Alpha Vantage updates eventually but sometimes lags by a day or two.
|
|
86
|
+
- **Adjusted vs unadjusted prices.** Daily-adjusted returns split- and dividend-adjusted closes; daily returns raw closes. For long-horizon analysis you almost always want adjusted.
|
|
11
87
|
|
|
12
88
|
## Quick Start
|
|
13
89
|
|
|
14
|
-
Add to your MCP client
|
|
90
|
+
Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
|
|
15
91
|
|
|
16
92
|
```json
|
|
17
93
|
{
|
|
@@ -23,12 +99,86 @@ Add to your MCP client config:
|
|
|
23
99
|
}
|
|
24
100
|
```
|
|
25
101
|
|
|
26
|
-
|
|
102
|
+
### What this endpoint actually serves
|
|
103
|
+
|
|
104
|
+
`tools/list` at `https://gateway.pipeworx.io/alphavantage/mcp` returns the tools in the table
|
|
105
|
+
above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
|
|
106
|
+
`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
|
|
107
|
+
gateway-wide set. So the tool count you see is larger than this table: a
|
|
108
|
+
single-pack endpoint currently lists roughly 30 shared tools alongside the
|
|
109
|
+
pack's own. The connection's `initialize` response states its exact scope, and
|
|
110
|
+
is the authoritative answer for a given day.
|
|
111
|
+
|
|
112
|
+
This is deliberate, not multiplexing by accident. The meta-tools are what let a
|
|
113
|
+
scoped connection answer a question this pack does not cover — via
|
|
114
|
+
`ask_pipeworx`, which routes across the whole catalog — without you adding a
|
|
115
|
+
second MCP server. There is currently no way to mount a pack endpoint without
|
|
116
|
+
them; if the extra schemas cost you more context than the routing is worth,
|
|
117
|
+
connect to the full gateway once rather than to several pack endpoints.
|
|
118
|
+
|
|
119
|
+
Or connect to the full Pipeworx gateway to get every pack's tools listed
|
|
120
|
+
directly, instead of just this one's:
|
|
121
|
+
|
|
122
|
+
```json
|
|
123
|
+
{
|
|
124
|
+
"mcpServers": {
|
|
125
|
+
"pipeworx": {
|
|
126
|
+
"url": "https://gateway.pipeworx.io/mcp"
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Both URLs reach the same gateway and the same 1683+ data sources. The
|
|
133
|
+
only difference is which pack's tools are listed **directly**; `ask_pipeworx`
|
|
134
|
+
reaches all of them from either one.
|
|
135
|
+
|
|
136
|
+
## No MCP client? Call it over HTTP
|
|
137
|
+
|
|
138
|
+
Our alphavantage key is reserved for paid accounts, so an anonymous call to `POST https://gateway.pipeworx.io/v1/tools/av_quote` needs your own key passed as `_apiKey` alongside the arguments. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/av_quote`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
|
|
139
|
+
|
|
140
|
+
## Standalone (no gateway account)
|
|
141
|
+
|
|
142
|
+
This package also runs as a local stdio MCP server — no Pipeworx account, no
|
|
143
|
+
gateway round-trip:
|
|
144
|
+
|
|
145
|
+
```json
|
|
146
|
+
{
|
|
147
|
+
"mcpServers": {
|
|
148
|
+
"alphavantage": {
|
|
149
|
+
"command": "npx",
|
|
150
|
+
"args": ["-y", "@pipeworx/mcp-alphavantage"]
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Or run it directly to confirm it starts:
|
|
27
157
|
|
|
28
158
|
```bash
|
|
29
|
-
npx pipeworx
|
|
159
|
+
npx -y @pipeworx/mcp-alphavantage
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
It speaks MCP over stdin/stdout and answers `initialize`/`tools/list`/`tools/call`
|
|
163
|
+
for **only** this pack's tools — none of the shared meta-tools the gateway
|
|
164
|
+
connection above adds. Same source, same tools, no ask_pipeworx routing.
|
|
165
|
+
|
|
166
|
+
## Using with ask_pipeworx
|
|
167
|
+
|
|
168
|
+
Instead of calling tools directly, you can ask questions in plain English —
|
|
169
|
+
this works on the pack endpoint above as well as on the full gateway:
|
|
170
|
+
|
|
171
|
+
```
|
|
172
|
+
ask_pipeworx({ question: "your question about Alphavantage data" })
|
|
30
173
|
```
|
|
31
174
|
|
|
175
|
+
The gateway picks the right tool and fills the arguments automatically.
|
|
176
|
+
|
|
177
|
+
## More
|
|
178
|
+
|
|
179
|
+
- [Docs and guides](https://pipeworx.io/docs)
|
|
180
|
+
- [pipeworx.io](https://pipeworx.io)
|
|
181
|
+
|
|
32
182
|
## License
|
|
33
183
|
|
|
34
184
|
MIT
|
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-alphavantage",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "Alpha Vantage MCP — Stock market data, fundamentals, and earnings",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "src/index.ts",
|
|
7
7
|
"types": "src/index.ts",
|
|
8
|
+
"bin": {
|
|
9
|
+
"mcp-alphavantage": "bin/cli.js"
|
|
10
|
+
},
|
|
8
11
|
"keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "alphavantage"],
|
|
9
12
|
"license": "MIT",
|
|
10
13
|
"repository": {
|
|
11
14
|
"type": "git",
|
|
12
|
-
"url": "https://github.com/pipeworx-io/mcp-alphavantage"
|
|
15
|
+
"url": "git+https://github.com/pipeworx-io/mcp-alphavantage.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-4bd2ef4fc9381b2f41120ae56ceb56b5483131fe8ffe7a563287ffe2558df64b",
|
|
30
|
+
"sourceCommit": "dca20ba6e13a9aa1c9f2918fc2ddaffe4cc30e5c"
|
|
19
31
|
}
|
|
20
32
|
}
|
package/server.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
3
|
"name": "io.github.pipeworx-io/alphavantage",
|
|
4
|
-
"title": "
|
|
4
|
+
"title": "Alphavantage",
|
|
5
5
|
"description": "Alpha Vantage MCP — Stock market data, fundamentals, and earnings",
|
|
6
|
-
"version": "0.1.
|
|
6
|
+
"version": "0.1.2",
|
|
7
7
|
"websiteUrl": "https://pipeworx.io/packs/alphavantage",
|
|
8
8
|
"repository": {
|
|
9
9
|
"url": "https://github.com/pipeworx-io/mcp-alphavantage",
|