headless-oracle-mcp 1.0.1 → 1.0.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.
Files changed (2) hide show
  1. package/README.md +115 -31
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,29 +1,40 @@
1
1
  # headless-oracle-mcp
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/headless-oracle-mcp)](https://npmjs.com/package/headless-oracle-mcp)
3
+ [![npm](https://img.shields.io/npm/v/headless-oracle-mcp)](https://npmjs.com/package/headless-oracle-mcp)
4
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
5
 
6
6
  Local stdio MCP server for [Headless Oracle](https://headlessoracle.com) — Ed25519-signed market-state receipts for 28 global exchanges.
7
7
 
8
+ ---
9
+
10
+ ## What is this?
11
+
12
+ Headless Oracle is a cryptographically signed market-state oracle for AI agents. It tells you whether a stock exchange is `OPEN`, `CLOSED`, `HALTED`, or `UNKNOWN` — and proves it with an Ed25519 signature.
13
+
14
+ This package lets any MCP-compatible AI client (Claude Desktop, Cursor, Cline, Windsurf, Continue.dev) call Headless Oracle tools directly. It runs as a local stdio MCP server that proxies tool calls to the Headless Oracle remote endpoint.
15
+
16
+ **Coverage:** NYSE, NASDAQ, London, Tokyo, Paris, Hong Kong, Singapore, Sydney, Mumbai (BSE + NSE), Shanghai, Shenzhen, Seoul, Johannesburg, São Paulo, Zurich, Milan, Istanbul, Riyadh, Dubai, Auckland, Helsinki, Stockholm — plus CME, NYMEX, Cboe, Coinbase, and Binance (28 total).
17
+
8
18
  **Critical safety rule for agents:** treat `UNKNOWN` and `HALTED` as `CLOSED` — halt all execution.
9
19
 
10
20
  ---
11
21
 
12
- ## Quick start
22
+ ## Install
13
23
 
14
24
  ```bash
15
25
  npx headless-oracle-mcp
16
26
  ```
17
27
 
18
- No install required. Works with Claude Desktop, Cursor, Cline, Windsurf, and Continue.dev.
28
+ No install required. Requires Node.js 18+.
19
29
 
20
30
  ---
21
31
 
22
- ## MCP client setup
32
+ ## Client setup
23
33
 
24
34
  ### Claude Desktop
25
35
 
26
- Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
36
+ **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
37
+ **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
27
38
 
28
39
  ```json
29
40
  {
@@ -36,6 +47,24 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
36
47
  }
37
48
  ```
38
49
 
50
+ With API key:
51
+
52
+ ```json
53
+ {
54
+ "mcpServers": {
55
+ "headless-oracle": {
56
+ "command": "npx",
57
+ "args": ["-y", "headless-oracle-mcp"],
58
+ "env": {
59
+ "HEADLESS_ORACLE_API_KEY": "your-key-here"
60
+ }
61
+ }
62
+ }
63
+ }
64
+ ```
65
+
66
+ ---
67
+
39
68
  ### Cursor
40
69
 
41
70
  Edit `~/.cursor/mcp.json`:
@@ -51,9 +80,27 @@ Edit `~/.cursor/mcp.json`:
51
80
  }
52
81
  ```
53
82
 
83
+ With API key:
84
+
85
+ ```json
86
+ {
87
+ "mcpServers": {
88
+ "headless-oracle": {
89
+ "command": "npx",
90
+ "args": ["-y", "headless-oracle-mcp"],
91
+ "env": {
92
+ "HEADLESS_ORACLE_API_KEY": "your-key-here"
93
+ }
94
+ }
95
+ }
96
+ }
97
+ ```
98
+
99
+ ---
100
+
54
101
  ### Cline
55
102
 
56
- Edit `cline_mcp_settings.json` (accessible via Cline settings → MCP Servers):
103
+ Edit `cline_mcp_settings.json` (Cline settings → MCP Servers):
57
104
 
58
105
  ```json
59
106
  {
@@ -66,6 +113,24 @@ Edit `cline_mcp_settings.json` (accessible via Cline settings → MCP Servers):
66
113
  }
67
114
  ```
68
115
 
116
+ With API key:
117
+
118
+ ```json
119
+ {
120
+ "mcpServers": {
121
+ "headless-oracle": {
122
+ "command": "npx",
123
+ "args": ["-y", "headless-oracle-mcp"],
124
+ "env": {
125
+ "HEADLESS_ORACLE_API_KEY": "your-key-here"
126
+ }
127
+ }
128
+ }
129
+ }
130
+ ```
131
+
132
+ ---
133
+
69
134
  ### Windsurf
70
135
 
71
136
  Edit `~/.codeium/windsurf/mcp_config.json`:
@@ -81,6 +146,24 @@ Edit `~/.codeium/windsurf/mcp_config.json`:
81
146
  }
82
147
  ```
83
148
 
149
+ With API key:
150
+
151
+ ```json
152
+ {
153
+ "mcpServers": {
154
+ "headless-oracle": {
155
+ "command": "npx",
156
+ "args": ["-y", "headless-oracle-mcp"],
157
+ "env": {
158
+ "HEADLESS_ORACLE_API_KEY": "your-key-here"
159
+ }
160
+ }
161
+ }
162
+ }
163
+ ```
164
+
165
+ ---
166
+
84
167
  ### Continue.dev
85
168
 
86
169
  Edit `~/.continue/config.json`:
@@ -101,43 +184,42 @@ Edit `~/.continue/config.json`:
101
184
  }
102
185
  ```
103
186
 
104
- ---
105
-
106
- ## With API key
107
-
108
- For authenticated access (higher rate limits, `/v5/status` endpoint):
187
+ With API key:
109
188
 
110
189
  ```json
111
190
  {
112
- "mcpServers": {
113
- "headless-oracle": {
114
- "command": "npx",
115
- "args": ["-y", "headless-oracle-mcp"],
116
- "env": {
117
- "HEADLESS_ORACLE_API_KEY": "your-key-here"
191
+ "experimental": {
192
+ "modelContextProtocolServers": [
193
+ {
194
+ "transport": {
195
+ "type": "stdio",
196
+ "command": "npx",
197
+ "args": ["-y", "headless-oracle-mcp"],
198
+ "env": {
199
+ "HEADLESS_ORACLE_API_KEY": "your-key-here"
200
+ }
201
+ }
118
202
  }
119
- }
203
+ ]
120
204
  }
121
205
  }
122
206
  ```
123
207
 
124
- Get a free sandbox key at [headlessoracle.com](https://headlessoracle.com) or via the `/v5/sandbox` endpoint.
125
-
126
208
  ---
127
209
 
128
210
  ## Tools
129
211
 
130
212
  | Tool | Description |
131
213
  |------|-------------|
132
- | `get_market_status` | Returns an Ed25519-signed receipt: `OPEN`, `CLOSED`, `HALTED`, or `UNKNOWN`. Treat UNKNOWN/HALTED as CLOSED. |
133
- | `get_market_schedule` | Returns next open/close times in UTC for a given exchange. |
214
+ | `get_market_status` | Returns an Ed25519-signed receipt: `OPEN`, `CLOSED`, `HALTED`, or `UNKNOWN`. Always treat `UNKNOWN`/`HALTED` as `CLOSED`. |
215
+ | `get_market_schedule` | Returns next open/close times in UTC, including lunch break windows for XJPX, XHKG, XSHG, XSHE. |
134
216
  | `list_exchanges` | Lists all 28 supported exchanges with MIC codes, names, and timezones. |
135
- | `verify_receipt` | Verifies an Ed25519 receipt locally — checks signature, TTL, and fields. |
136
- | `get_payment_options` | Returns the upgrade ladder (sandbox → x402 → credits → Builder). |
217
+ | `verify_receipt` | Verifies an Ed25519-signed receipt locally — checks signature, TTL expiry, and required fields. |
218
+ | `get_payment_options` | Returns the upgrade ladder: sandbox → x402 per-request → credits → Builder subscription. |
137
219
 
138
- ### Supported exchanges (28 total)
220
+ ### Supported MIC codes (28 total)
139
221
 
140
- XNYS, XNAS, XBSP, XLON, XPAR, XSWX, XMIL, XHEL, XSTO, XIST, XSAU, XDFM, XJSE, XSHG, XSHE, XHKG, XJPX, XKRX, XBOM, XNSE, XSES, XASX, XNZE, XCBT, XNYM, XCBO, XCOI, XBIN
222
+ `XNYS` `XNAS` `XBSP` `XLON` `XPAR` `XSWX` `XMIL` `XHEL` `XSTO` `XIST` `XSAU` `XDFM` `XJSE` `XSHG` `XSHE` `XHKG` `XJPX` `XKRX` `XBOM` `XNSE` `XSES` `XASX` `XNZE` `XCBT` `XNYM` `XCBO` `XCOI` `XBIN`
141
223
 
142
224
  ---
143
225
 
@@ -159,17 +241,18 @@ XNYS, XNAS, XBSP, XLON, XPAR, XSWX, XMIL, XHEL, XSTO, XIST, XSAU, XDFM, XJSE, XS
159
241
  }
160
242
  ```
161
243
 
162
- All receipts are signed with Ed25519. Verify with [`@headlessoracle/verify`](https://npmjs.com/package/@headlessoracle/verify).
244
+ Receipts expire after 60 seconds (`expires_at`). Verify with [`@headlessoracle/verify`](https://npmjs.com/package/@headlessoracle/verify).
163
245
 
164
246
  ---
165
247
 
166
248
  ## How it works
167
249
 
168
- This package is a local stdio MCP server that proxies tool calls to the [Headless Oracle remote endpoint](https://headlessoracle.com/mcp). Your MCP client (Claude Desktop, Cursor, etc.) communicates with this process over stdin/stdout using JSON-RPC 2.0. The process forwards `tools/list` and `tools/call` requests to the remote endpoint and returns the results.
250
+ Your MCP client communicates with this process over stdin/stdout (JSON-RPC 2.0). `initialize` and `ping` are handled locally; `tools/list` and `tools/call` are forwarded to `https://headlessoracle.com/mcp`.
169
251
 
170
252
  - Zero npm dependencies — uses Node.js built-ins only (`readline`, `https`)
171
253
  - Requires Node.js 18+
172
- - Errors are logged to stderr only; stdout is reserved for the MCP transport
254
+ - Errors are written to stderr only; stdout is reserved for the MCP transport
255
+ - Set `HEADLESS_ORACLE_API_KEY` for authenticated access and higher rate limits
173
256
 
174
257
  ---
175
258
 
@@ -177,8 +260,9 @@ This package is a local stdio MCP server that proxies tool calls to the [Headles
177
260
 
178
261
  - **Website**: [headlessoracle.com](https://headlessoracle.com)
179
262
  - **Docs**: [headlessoracle.com/docs](https://headlessoracle.com/docs)
180
- - **npm**: [npmjs.com/package/@headlessoracle/verify](https://npmjs.com/package/@headlessoracle/verify) (JS verification SDK)
181
- - **Remote MCP endpoint**: `https://headlessoracle.com/mcp` (MCP Streamable HTTP, protocol `2024-11-05`)
263
+ - **Get a free key**: [headlessoracle.com/v5/sandbox](https://headlessoracle.com/v5/sandbox) (instant, no sign-up)
264
+ - **Verify SDK (JS)**: [npmjs.com/package/@headlessoracle/verify](https://npmjs.com/package/@headlessoracle/verify)
265
+ - **Remote MCP endpoint**: `https://headlessoracle.com/mcp` (protocol `2024-11-05`)
182
266
  - **GitHub**: [github.com/LembaGang/headless-oracle-v5](https://github.com/LembaGang/headless-oracle-v5)
183
267
 
184
268
  ---
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "headless-oracle-mcp",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "Local MCP server for Headless Oracle — Ed25519-signed market-state receipts for 28 global exchanges",
5
5
  "main": "bin/cli.js",
6
6
  "bin": "./bin/cli.js",