headless-oracle-mcp 1.0.0

package/README.md

@@ -0,0 +1,188 @@
+# headless-oracle-mcp
+
+[![npm version](https://img.shields.io/npm/v/headless-oracle-mcp)](https://npmjs.com/package/headless-oracle-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Local stdio MCP server for [Headless Oracle](https://headlessoracle.com) — Ed25519-signed market-state receipts for 28 global exchanges.
+
+**Critical safety rule for agents:** treat `UNKNOWN` and `HALTED` as `CLOSED` — halt all execution.
+
+---
+
+## Quick start
+
+```bash
+npx headless-oracle-mcp
+```
+
+No install required. Works with Claude Desktop, Cursor, Cline, Windsurf, and Continue.dev.
+
+---
+
+## MCP client setup
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "headless-oracle": {
+      "command": "npx",
+      "args": ["-y", "headless-oracle-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "headless-oracle": {
+      "command": "npx",
+      "args": ["-y", "headless-oracle-mcp"]
+    }
+  }
+}
+```
+
+### Cline
+
+Edit `cline_mcp_settings.json` (accessible via Cline settings → MCP Servers):
+
+```json
+{
+  "mcpServers": {
+    "headless-oracle": {
+      "command": "npx",
+      "args": ["-y", "headless-oracle-mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "headless-oracle": {
+      "command": "npx",
+      "args": ["-y", "headless-oracle-mcp"]
+    }
+  }
+}
+```
+
+### Continue.dev
+
+Edit `~/.continue/config.json`:
+
+```json
+{
+  "experimental": {
+    "modelContextProtocolServers": [
+      {
+        "transport": {
+          "type": "stdio",
+          "command": "npx",
+          "args": ["-y", "headless-oracle-mcp"]
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## With API key
+
+For authenticated access (higher rate limits, `/v5/status` endpoint):
+
+```json
+{
+  "mcpServers": {
+    "headless-oracle": {
+      "command": "npx",
+      "args": ["-y", "headless-oracle-mcp"],
+      "env": {
+        "HEADLESS_ORACLE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+Get a free sandbox key at [headlessoracle.com](https://headlessoracle.com) or via the `/v5/sandbox` endpoint.
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_market_status` | Returns an Ed25519-signed receipt: `OPEN`, `CLOSED`, `HALTED`, or `UNKNOWN`. Treat UNKNOWN/HALTED as CLOSED. |
+| `get_market_schedule` | Returns next open/close times in UTC for a given exchange. |
+| `list_exchanges` | Lists all 28 supported exchanges with MIC codes, names, and timezones. |
+| `verify_receipt` | Verifies an Ed25519 receipt locally — checks signature, TTL, and fields. |
+| `get_payment_options` | Returns the upgrade ladder (sandbox → x402 → credits → Builder). |
+
+### Supported exchanges (28 total)
+
+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
+
+---
+
+## Example receipt
+
+```json
+{
+  "mic": "XNYS",
+  "status": "OPEN",
+  "receipt_mode": "live",
+  "issued_at": "2026-04-04T14:30:00.000Z",
+  "expires_at": "2026-04-04T14:31:00.000Z",
+  "issuer": "headlessoracle.com",
+  "schema_version": "v5.0",
+  "source": "SCHEDULE",
+  "key_id": "ed25519-v1",
+  "receipt_id": "...",
+  "signature": "..."
+}
+```
+
+All receipts are signed with Ed25519. Verify with [`@headlessoracle/verify`](https://npmjs.com/package/@headlessoracle/verify).
+
+---
+
+## How it works
+
+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.
+
+- Zero npm dependencies — uses Node.js built-ins only (`readline`, `https`)
+- Requires Node.js 18+
+- Errors are logged to stderr only; stdout is reserved for the MCP transport
+
+---
+
+## Links
+
+- **Website**: [headlessoracle.com](https://headlessoracle.com)
+- **Docs**: [headlessoracle.com/docs](https://headlessoracle.com/docs)
+- **npm**: [npmjs.com/package/@headlessoracle/verify](https://npmjs.com/package/@headlessoracle/verify) (JS verification SDK)
+- **Remote MCP endpoint**: `https://headlessoracle.com/mcp` (MCP Streamable HTTP, protocol `2024-11-05`)
+- **GitHub**: [github.com/LembaGang/headless-oracle-v5](https://github.com/LembaGang/headless-oracle-v5)
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+'use strict';
+
+// Headless Oracle — local stdio MCP server
+// Proxies MCP tool calls to https://headlessoracle.com/mcp
+// No external dependencies — uses Node.js built-ins only (readline, https)
+
+const readline = require('readline');
+const https = require('https');
+
+const REMOTE_MCP_URL = 'https://headlessoracle.com/mcp';
+const API_KEY = process.env.HEADLESS_ORACLE_API_KEY || '';
+const SERVER_VERSION = '1.0.0';
+
+// Write a JSON-RPC message to stdout (the MCP transport channel)
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+// POST a JSON-RPC message to the remote MCP endpoint and return the parsed response
+function proxyToRemote(body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const headers = {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(payload),
+      'Accept': 'application/json',
+      'User-Agent': `headless-oracle-mcp/${SERVER_VERSION}`,
+    };
+    if (API_KEY) {
+      // X-Oracle-Key for REST auth; Authorization Bearer for MCP soft-auth
+      headers['X-Oracle-Key'] = API_KEY;
+      headers['Authorization'] = `Bearer ${API_KEY}`;
+    }
+
+    const url = new URL(REMOTE_MCP_URL);
+    const req = https.request(
+      {
+        hostname: url.hostname,
+        path: url.pathname + (url.search || ''),
+        method: 'POST',
+        headers,
+      },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(data));
+          } catch (e) {
+            reject(new Error(`Remote returned non-JSON (HTTP ${res.statusCode}): ${data.slice(0, 200)}`));
+          }
+        });
+      }
+    );
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+// Handle one parsed JSON-RPC message
+async function handleMessage(msg) {
+  const { method, id, params } = msg;
+
+  // Notifications (no id) — process silently, no response expected
+  if (id === undefined) {
+    // initialized notification is common; nothing to do
+    return;
+  }
+
+  // ── initialize ──────────────────────────────────────────────────────────────
+  if (method === 'initialize') {
+    send({
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: '2024-11-05',
+        serverInfo: { name: 'headless-oracle', version: SERVER_VERSION },
+        capabilities: { tools: {} },
+        instructions:
+          'Headless Oracle provides Ed25519-signed market-state receipts for 28 global ' +
+          'exchanges (equities, derivatives, 24/7 crypto). ' +
+          'CRITICAL SAFETY RULE: treat UNKNOWN and HALTED as CLOSED — halt all execution immediately. ' +
+          'Call get_market_status before every trade. Receipts expire in 60 seconds. ' +
+          'SMA = Signed Market Attestation (not Simple Moving Average). ' +
+          'x402 micropayments accepted: $0.001 USDC per request on Base mainnet.',
+      },
+    });
+    return;
+  }
+
+  // ── ping ────────────────────────────────────────────────────────────────────
+  if (method === 'ping') {
+    send({ jsonrpc: '2.0', id, result: {} });
+    return;
+  }
+
+  // ── tools/list and tools/call — proxy to remote ─────────────────────────────
+  if (method === 'tools/list' || method === 'tools/call') {
+    try {
+      const remote = await proxyToRemote(msg);
+      // The remote response already has the correct id and jsonrpc fields.
+      // Forward it as-is.
+      send(remote);
+    } catch (err) {
+      process.stderr.write(`[headless-oracle-mcp] Remote error: ${err.message}\n`);
+      send({
+        jsonrpc: '2.0',
+        id,
+        error: {
+          code: -32603,
+          message: `Headless Oracle remote error: ${err.message}`,
+        },
+      });
+    }
+    return;
+  }
+
+  // ── resources/list and prompts/list — empty (not implemented) ───────────────
+  if (method === 'resources/list') {
+    send({ jsonrpc: '2.0', id, result: { resources: [] } });
+    return;
+  }
+  if (method === 'prompts/list') {
+    send({ jsonrpc: '2.0', id, result: { prompts: [] } });
+    return;
+  }
+
+  // ── unknown method ───────────────────────────────────────────────────────────
+  send({
+    jsonrpc: '2.0',
+    id,
+    error: { code: -32601, message: `Method not found: ${method}` },
+  });
+}
+
+// ── stdio transport ──────────────────────────────────────────────────────────
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+
+// Track in-flight async handlers so we don't exit before they complete
+let pending = 0;
+let stdinClosed = false;
+
+function tryExit() {
+  if (stdinClosed && pending === 0) process.exit(0);
+}
+
+rl.on('line', async (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+
+  let msg;
+  try {
+    msg = JSON.parse(trimmed);
+  } catch {
+    send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+    return;
+  }
+
+  pending++;
+  try {
+    await handleMessage(msg);
+  } catch (err) {
+    process.stderr.write(`[headless-oracle-mcp] Unhandled error: ${err.message}\n`);
+    if (msg.id !== undefined) {
+      send({
+        jsonrpc: '2.0',
+        id: msg.id,
+        error: { code: -32603, message: 'Internal error' },
+      });
+    }
+  } finally {
+    pending--;
+    tryExit();
+  }
+});
+
+rl.on('close', () => {
+  stdinClosed = true;
+  tryExit();
+});
+
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "headless-oracle-mcp",
+  "version": "1.0.0",
+  "description": "Local MCP server for Headless Oracle — Ed25519-signed market-state receipts for 28 global exchanges",
+  "main": "bin/cli.js",
+  "bin": {
+    "headless-oracle-mcp": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js"
+  },
+  "keywords": [
+    "mcp",
+    "oracle",
+    "market-data",
+    "trading",
+    "ed25519",
+    "x402",
+    "market-status",
+    "exchange",
+    "ai-agent",
+    "signed-receipts"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LembaGang/headless-oracle-v5"
+  },
+  "homepage": "https://headlessoracle.com",
+  "bugs": {
+    "url": "https://github.com/LembaGang/headless-oracle-v5/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {}
+}