candlefeed-mcp 0.1.0__tar.gz

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.
Files changed (12) hide show
  1. candlefeed_mcp-0.1.0/PKG-INFO +147 -0
  2. candlefeed_mcp-0.1.0/README.md +128 -0
  3. candlefeed_mcp-0.1.0/candlefeed_mcp/__init__.py +2 -0
  4. candlefeed_mcp-0.1.0/candlefeed_mcp/kit.py +489 -0
  5. candlefeed_mcp-0.1.0/candlefeed_mcp/schema.py +157 -0
  6. candlefeed_mcp-0.1.0/candlefeed_mcp/server.py +133 -0
  7. candlefeed_mcp-0.1.0/pyproject.toml +43 -0
  8. candlefeed_mcp-0.1.0/tests/conftest.py +55 -0
  9. candlefeed_mcp-0.1.0/tests/test_kit.py +352 -0
  10. candlefeed_mcp-0.1.0/tests/test_packaging.py +20 -0
  11. candlefeed_mcp-0.1.0/tests/test_schema.py +114 -0
  12. candlefeed_mcp-0.1.0/tests/test_server.py +54 -0
candlefeed_mcp-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,147 @@
1
+ Metadata-Version: 2.5
2
+ Name: candlefeed-mcp
3
+ Version: 0.1.0
4
+ Summary: MCP server for CandleFeed: download Binance USD-M order book days, rebuild the book, and query spreads and depth, plus candles, funding, open interest and liquidations.
5
+ Project-URL: Homepage, https://candlefeed.ai
6
+ Project-URL: Documentation, https://candlefeed.ai/docs/order-book
7
+ Author-email: CandleFeed <support@candlefeed.ai>
8
+ License: MIT
9
+ Keywords: claude,crypto,l2,market-data,mcp,model-context-protocol,order-book
10
+ Requires-Python: >=3.10
11
+ Requires-Dist: candlefeed[l2]<0.4,>=0.3.0
12
+ Requires-Dist: mcp<3,>=2.3
13
+ Requires-Dist: requests>=2.25
14
+ Provides-Extra: dev
15
+ Requires-Dist: pytest>=7.0; extra == 'dev'
16
+ Requires-Dist: responses>=0.23; extra == 'dev'
17
+ Requires-Dist: ruff>=0.4; extra == 'dev'
18
+ Description-Content-Type: text/markdown
19
+
20
+ # candlefeed-mcp
21
+
22
+ An MCP server that gives Claude Code, Claude Desktop, Cursor or any MCP client the CandleFeed order book files as tools: find a published day, download it with SHA-256 checks, rebuild the Binance USD-M book, and ask for the book, spread or depth at any moment. It also wraps four REST datasets (candles, funding, open interest, liquidations). It runs locally over stdio, and order book files are rebuilt on your machine, not on ours.
23
+
24
+ The data is historical. Order book days are published the morning after each UTC day ends, and every known gap is listed in the public gap log.
25
+
26
+ ## Tools
27
+
28
+ | Tool | What it does | Key needed |
29
+ |---|---|---|
30
+ | `l2_coverage` | Published book and trade days per symbol, with unpublished days and the reason | no |
31
+ | `l2_gaps` | The public gap log: every stretch no capture node recorded, with times, size and reason | no |
32
+ | `l2_download_day` | Downloads one UTC day (`book` or `trades`) into the cache, size and SHA-256 checked; cached files are skipped | yes |
33
+ | `l2_book_at` | Top N bids and asks at a moment, best bid/ask, mid, spread in bps, and the snapshot it was anchored on | no (local) |
34
+ | `l2_spread_summary` | Spread statistics for a day or window, sampled every 100ms to 5min, plus the biggest 1-minute mid move | no (local) |
35
+ | `l2_depth_summary` | Resting size within each bps band of the mid at a moment, in the base asset and USDT, optionally averaged over a window | no (local) |
36
+ | `candles` | OHLCV, intervals 1m to 1d | yes |
37
+ | `funding_rates` | Funding settlements per exchange | yes |
38
+ | `open_interest` | Open interest in contracts and USD | yes (Builder) |
39
+ | `liquidations` | Bucketed or tick liquidations | yes (Builder) |
40
+
41
+ Depth outside the anchor snapshot's known price window is partial. Report completeness per band and exclude incomplete samples from full-depth statistics. `l2_depth_summary` flags each band and averages complete samples only.
42
+
43
+ The SHA-256 checks prove the files are consistent with what CandleFeed published for that day. They aren't a signature: hashes delivered by the same service as the files can't detect that service itself being compromised or malicious.
44
+
45
+ The rebuild follows the published rule (the same code as `candlefeed.l2book`): anchor on a snapshot that isn't `in_gap`, apply the event that contains its `lastUpdateId` whole, and report nothing between a chain break and the next snapshot. A moment with no trustworthy book comes back as an error that says why.
46
+
47
+ ## What it costs to use
48
+
49
+ The 1st of every month is a free sample day on every plan, Free included, for every order book symbol. Sample downloads count against 10 GiB of new files per account per month; downloading the same file again that month is free. Every other day needs the Pro plan ($149/mo). A BTCUSDT book day is about 0.35 GB, so ask for days on purpose. REST tools follow the usual plan limits: Free gets BTC, ETH, SOL, XRP and DOGE on Binance for the last 30 days. Plans: https://candlefeed.ai/pricing?ref=mcp
50
+
51
+ CandleFeed data, including samples, is licensed for internal use under Terms §5.3. Published charts, statistics, and research must not include Raw Data or Substantially Raw Derivatives. The raw files and row-level data aren't to be shared.
52
+
53
+ ## Install
54
+
55
+ Needs Python 3.10+ (CPython) on Linux or macOS. Downloads rely on directory-relative, no-follow file operations to stay inside the cache, and refuse to run where those don't exist (Windows).
56
+
57
+ ```bash
58
+ pip install candlefeed-mcp # pulls in candlefeed[l2] 0.3.0 or later
59
+ which candlefeed-mcp # use this absolute path below if your client can't find the command
60
+ ```
61
+
62
+ Neither `candlefeed-mcp` nor client 0.3.0 is on PyPI yet. Until they are, install from a source tree: `pip install "./clients/python[l2]" ./integrations/mcp`.
63
+
64
+ Get a key at https://candlefeed.ai/signup?ref=mcp (free, no card). The server reads it from `CANDLEFEED_API_KEY` in its own environment and never takes it as a tool argument. It never prints it either: every result and error is scrubbed of the key and of download-link signatures.
65
+
66
+ ## Claude Code
67
+
68
+ ```bash
69
+ claude mcp add candlefeed --env CANDLEFEED_API_KEY=cf_live_... -- candlefeed-mcp
70
+ ```
71
+
72
+ Or in `.mcp.json` at the project root:
73
+
74
+ ```json
75
+ {
76
+ "mcpServers": {
77
+ "candlefeed": {
78
+ "command": "candlefeed-mcp",
79
+ "env": { "CANDLEFEED_API_KEY": "cf_live_..." }
80
+ }
81
+ }
82
+ }
83
+ ```
84
+
85
+ A full BTC day download can take a minute or more. If a call times out, raise `MCP_TOOL_TIMEOUT` (milliseconds) before starting `claude`, and run the download again: files that finished are kept and skipped.
86
+
87
+ ## Claude Desktop
88
+
89
+ Settings, Developer, Edit Config, then add to `claude_desktop_config.json`:
90
+
91
+ ```json
92
+ {
93
+ "mcpServers": {
94
+ "candlefeed": {
95
+ "command": "/absolute/path/to/candlefeed-mcp",
96
+ "env": { "CANDLEFEED_API_KEY": "cf_live_..." }
97
+ }
98
+ }
99
+ }
100
+ ```
101
+
102
+ Restart Claude Desktop. It doesn't inherit your shell's PATH, so use the absolute path from `which candlefeed-mcp`.
103
+
104
+ ## Cursor
105
+
106
+ `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):
107
+
108
+ ```json
109
+ {
110
+ "mcpServers": {
111
+ "candlefeed": {
112
+ "command": "candlefeed-mcp",
113
+ "env": { "CANDLEFEED_API_KEY": "cf_live_..." }
114
+ }
115
+ }
116
+ }
117
+ ```
118
+
119
+ ## Settings
120
+
121
+ | Variable | Default | Meaning |
122
+ |---|---|---|
123
+ | `CANDLEFEED_API_KEY` | none | Your key. Needed for downloads and REST tools |
124
+ | `CANDLEFEED_CACHE_DIR` | `~/.cache/candlefeed-mcp` | Where files go. On Linux and macOS (CPython), downloads write only inside it: each folder is opened without following symlinks and every write is relative to that folder's handle, temporary files are created exclusively, and file names and dates must be the ones requested. On a Python without those operations (Windows) downloads refuse to run. Before rebuilding a day the tools check that its folder contains no symlinks; that's a check at load time, not a guarantee against another process changing the cache while the server runs |
125
+ | `CANDLEFEED_BASE_URL` | `https://candlefeed.ai/api/v1` | API base; must be https |
126
+ | `CANDLEFEED_L2_STORAGE_HOST` | `candlefeed-l2-canonical.sgp1.digitaloceanspaces.com` | The only host files are downloaded from (https, port 443) |
127
+ | `CANDLEFEED_MCP_MAX_DAY_BYTES` | 2 GiB | Most new bytes one `l2_download_day` call will fetch |
128
+ | `CANDLEFEED_CACHE_MAX_BYTES` | 20 GiB | Cache quota; a download that wouldn't fit is refused before it starts |
129
+ | `CANDLEFEED_MCP_DOWNLOAD_DEADLINE` | 1800 | Seconds for one download. Checked before every request and after each chunk of a response body (8 KiB requested; compressed responses can yield larger decoded chunks). Not a hard limit: a server sending bytes slowly enough can stretch one chunk's read past it |
130
+ | `CANDLEFEED_MCP_ROW_CACHE_BYTES` | 2 GiB | Decoded diff rows kept in memory for the loaded day. It limits that cache only, not the server's total memory; the event index, snapshots and read buffers come on top |
131
+
132
+ Downloaded days sit under `<cache>/book/binance/<SYMBOL>/<YYYY-MM-DD>/`, the same layout `CandleFeed().download_l2` writes, so you can open them with `candlefeed.l2book.L2Book.load(<cache>, "BTCUSDT", "2026-09-01")` in your own code.
133
+
134
+ ## Try it
135
+
136
+ > Download the free BTCUSDT order book sample for 2026-09-01, find the biggest 1-minute move of the day, and show me the spread and the depth within 10 and 50 bps for ten minutes either side of it.
137
+
138
+ The agent calls `l2_download_day`, `l2_spread_summary` (which reports the biggest 1-minute move) and `l2_depth_summary` with `window_minutes=10`. `examples/l2_agent_demo.py` in the repo does the same in plain Python, with a chart.
139
+
140
+ ## Development
141
+
142
+ ```bash
143
+ pip install -e "./clients/python[l2,dev]" -e "./integrations/mcp[dev]"
144
+ pytest integrations/mcp/tests
145
+ ```
146
+
147
+ Tests mock every HTTP call and build synthetic order book days with a known true book.
candlefeed_mcp-0.1.0/README.md ADDED
@@ -0,0 +1,128 @@
1
+ # candlefeed-mcp
2
+
3
+ An MCP server that gives Claude Code, Claude Desktop, Cursor or any MCP client the CandleFeed order book files as tools: find a published day, download it with SHA-256 checks, rebuild the Binance USD-M book, and ask for the book, spread or depth at any moment. It also wraps four REST datasets (candles, funding, open interest, liquidations). It runs locally over stdio, and order book files are rebuilt on your machine, not on ours.
4
+
5
+ The data is historical. Order book days are published the morning after each UTC day ends, and every known gap is listed in the public gap log.
6
+
7
+ ## Tools
8
+
9
+ | Tool | What it does | Key needed |
10
+ |---|---|---|
11
+ | `l2_coverage` | Published book and trade days per symbol, with unpublished days and the reason | no |
12
+ | `l2_gaps` | The public gap log: every stretch no capture node recorded, with times, size and reason | no |
13
+ | `l2_download_day` | Downloads one UTC day (`book` or `trades`) into the cache, size and SHA-256 checked; cached files are skipped | yes |
14
+ | `l2_book_at` | Top N bids and asks at a moment, best bid/ask, mid, spread in bps, and the snapshot it was anchored on | no (local) |
15
+ | `l2_spread_summary` | Spread statistics for a day or window, sampled every 100ms to 5min, plus the biggest 1-minute mid move | no (local) |
16
+ | `l2_depth_summary` | Resting size within each bps band of the mid at a moment, in the base asset and USDT, optionally averaged over a window | no (local) |
17
+ | `candles` | OHLCV, intervals 1m to 1d | yes |
18
+ | `funding_rates` | Funding settlements per exchange | yes |
19
+ | `open_interest` | Open interest in contracts and USD | yes (Builder) |
20
+ | `liquidations` | Bucketed or tick liquidations | yes (Builder) |
21
+
22
+ Depth outside the anchor snapshot's known price window is partial. Report completeness per band and exclude incomplete samples from full-depth statistics. `l2_depth_summary` flags each band and averages complete samples only.
23
+
24
+ The SHA-256 checks prove the files are consistent with what CandleFeed published for that day. They aren't a signature: hashes delivered by the same service as the files can't detect that service itself being compromised or malicious.
25
+
26
+ The rebuild follows the published rule (the same code as `candlefeed.l2book`): anchor on a snapshot that isn't `in_gap`, apply the event that contains its `lastUpdateId` whole, and report nothing between a chain break and the next snapshot. A moment with no trustworthy book comes back as an error that says why.
27
+
28
+ ## What it costs to use
29
+
30
+ The 1st of every month is a free sample day on every plan, Free included, for every order book symbol. Sample downloads count against 10 GiB of new files per account per month; downloading the same file again that month is free. Every other day needs the Pro plan ($149/mo). A BTCUSDT book day is about 0.35 GB, so ask for days on purpose. REST tools follow the usual plan limits: Free gets BTC, ETH, SOL, XRP and DOGE on Binance for the last 30 days. Plans: https://candlefeed.ai/pricing?ref=mcp
31
+
32
+ CandleFeed data, including samples, is licensed for internal use under Terms §5.3. Published charts, statistics, and research must not include Raw Data or Substantially Raw Derivatives. The raw files and row-level data aren't to be shared.
33
+
34
+ ## Install
35
+
36
+ Needs Python 3.10+ (CPython) on Linux or macOS. Downloads rely on directory-relative, no-follow file operations to stay inside the cache, and refuse to run where those don't exist (Windows).
37
+
38
+ ```bash
39
+ pip install candlefeed-mcp # pulls in candlefeed[l2] 0.3.0 or later
40
+ which candlefeed-mcp # use this absolute path below if your client can't find the command
41
+ ```
42
+
43
+ Neither `candlefeed-mcp` nor client 0.3.0 is on PyPI yet. Until they are, install from a source tree: `pip install "./clients/python[l2]" ./integrations/mcp`.
44
+
45
+ Get a key at https://candlefeed.ai/signup?ref=mcp (free, no card). The server reads it from `CANDLEFEED_API_KEY` in its own environment and never takes it as a tool argument. It never prints it either: every result and error is scrubbed of the key and of download-link signatures.
46
+
47
+ ## Claude Code
48
+
49
+ ```bash
50
+ claude mcp add candlefeed --env CANDLEFEED_API_KEY=cf_live_... -- candlefeed-mcp
51
+ ```
52
+
53
+ Or in `.mcp.json` at the project root:
54
+
55
+ ```json
56
+ {
57
+ "mcpServers": {
58
+ "candlefeed": {
59
+ "command": "candlefeed-mcp",
60
+ "env": { "CANDLEFEED_API_KEY": "cf_live_..." }
61
+ }
62
+ }
63
+ }
64
+ ```
65
+
66
+ A full BTC day download can take a minute or more. If a call times out, raise `MCP_TOOL_TIMEOUT` (milliseconds) before starting `claude`, and run the download again: files that finished are kept and skipped.
67
+
68
+ ## Claude Desktop
69
+
70
+ Settings, Developer, Edit Config, then add to `claude_desktop_config.json`:
71
+
72
+ ```json
73
+ {
74
+ "mcpServers": {
75
+ "candlefeed": {
76
+ "command": "/absolute/path/to/candlefeed-mcp",
77
+ "env": { "CANDLEFEED_API_KEY": "cf_live_..." }
78
+ }
79
+ }
80
+ }
81
+ ```
82
+
83
+ Restart Claude Desktop. It doesn't inherit your shell's PATH, so use the absolute path from `which candlefeed-mcp`.
84
+
85
+ ## Cursor
86
+
87
+ `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):
88
+
89
+ ```json
90
+ {
91
+ "mcpServers": {
92
+ "candlefeed": {
93
+ "command": "candlefeed-mcp",
94
+ "env": { "CANDLEFEED_API_KEY": "cf_live_..." }
95
+ }
96
+ }
97
+ }
98
+ ```
99
+
100
+ ## Settings
101
+
102
+ | Variable | Default | Meaning |
103
+ |---|---|---|
104
+ | `CANDLEFEED_API_KEY` | none | Your key. Needed for downloads and REST tools |
105
+ | `CANDLEFEED_CACHE_DIR` | `~/.cache/candlefeed-mcp` | Where files go. On Linux and macOS (CPython), downloads write only inside it: each folder is opened without following symlinks and every write is relative to that folder's handle, temporary files are created exclusively, and file names and dates must be the ones requested. On a Python without those operations (Windows) downloads refuse to run. Before rebuilding a day the tools check that its folder contains no symlinks; that's a check at load time, not a guarantee against another process changing the cache while the server runs |
106
+ | `CANDLEFEED_BASE_URL` | `https://candlefeed.ai/api/v1` | API base; must be https |
107
+ | `CANDLEFEED_L2_STORAGE_HOST` | `candlefeed-l2-canonical.sgp1.digitaloceanspaces.com` | The only host files are downloaded from (https, port 443) |
108
+ | `CANDLEFEED_MCP_MAX_DAY_BYTES` | 2 GiB | Most new bytes one `l2_download_day` call will fetch |
109
+ | `CANDLEFEED_CACHE_MAX_BYTES` | 20 GiB | Cache quota; a download that wouldn't fit is refused before it starts |
110
+ | `CANDLEFEED_MCP_DOWNLOAD_DEADLINE` | 1800 | Seconds for one download. Checked before every request and after each chunk of a response body (8 KiB requested; compressed responses can yield larger decoded chunks). Not a hard limit: a server sending bytes slowly enough can stretch one chunk's read past it |
111
+ | `CANDLEFEED_MCP_ROW_CACHE_BYTES` | 2 GiB | Decoded diff rows kept in memory for the loaded day. It limits that cache only, not the server's total memory; the event index, snapshots and read buffers come on top |
112
+
113
+ Downloaded days sit under `<cache>/book/binance/<SYMBOL>/<YYYY-MM-DD>/`, the same layout `CandleFeed().download_l2` writes, so you can open them with `candlefeed.l2book.L2Book.load(<cache>, "BTCUSDT", "2026-09-01")` in your own code.
114
+
115
+ ## Try it
116
+
117
+ > Download the free BTCUSDT order book sample for 2026-09-01, find the biggest 1-minute move of the day, and show me the spread and the depth within 10 and 50 bps for ten minutes either side of it.
118
+
119
+ The agent calls `l2_download_day`, `l2_spread_summary` (which reports the biggest 1-minute move) and `l2_depth_summary` with `window_minutes=10`. `examples/l2_agent_demo.py` in the repo does the same in plain Python, with a chart.
120
+
121
+ ## Development
122
+
123
+ ```bash
124
+ pip install -e "./clients/python[l2,dev]" -e "./integrations/mcp[dev]"
125
+ pytest integrations/mcp/tests
126
+ ```
127
+
128
+ Tests mock every HTTP call and build synthetic order book days with a known true book.
candlefeed_mcp-0.1.0/candlefeed_mcp/__init__.py ADDED
@@ -0,0 +1,2 @@
1
+ """CandleFeed MCP server: L2 order book files and the REST datasets as MCP tools."""
2
+ __version__ = "0.1.0"