English Français العربية

io.github.LembaGang/headless-oracle-mcp

Official registry Other

Ed25519-signed market-state receipts for 28 exchanges. Fail-closed pre-trade gate.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package headless-oracle-mcp
Claude Code 
claude mcp add headless-oracle-mcp -- npx -y headless-oracle-mcp@1.0.3
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "headless-oracle-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "headless-oracle-mcp@1.0.3"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Headless Oracle
  2. What It Does
  3. Quick Start
  4. Architecture
  5. API
  6. Exchanges
  7. Testing
  8. Security
  9. Documentation
  10. License

Headless Oracle

Ed25519-signed market-state attestations for 28 global exchanges.

What It Does

Autonomous trading agents need to know if an exchange is open before executing trades. Headless Oracle answers that question with a cryptographically signed receipt that any agent can verify independently — no trust in the operator required. UNKNOWN states are always treated as CLOSED (fail-closed).

Quick Start

# MCP (Claude Desktop, Cursor, any MCP client)
npx headless-oracle-mcp

# REST API — demo receipt (no auth required)
curl https://headlessoracle.com/v5/demo?mic=XNYS

# Sandbox key (200 calls, 7 days, no card) - POST with an email
curl -X POST https://headlessoracle.com/v5/sandbox \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'

Architecture

Single TypeScript Cloudflare Worker. Ed25519 signing via @noble/ed25519. Three KV namespaces (overrides, API keys, telemetry). Two Durable Objects (webhooks, SSE streams). Runs on Cloudflare's edge network - no origin server.

4-tier fail-closed: KV override check -> schedule engine -> UNKNOWN fallback -> unsigned critical failure.

See docs/architecture/overview.md for the full architecture.

API

Four MCP tools - get_market_status, get_market_schedule, list_exchanges, get_payment_options. Receipt verification is REST-only (POST /v5/verify) or offline with @headlessoracle/verify.

The REST surface is enumerated in the OpenAPI 3.1 spec, which is served live and is the list of record. Full references:

Exchanges

23 traditional markets (XNYS, XNAS, XLON, XJPX, XPAR, XHKG, XSES, XASX, XBOM, XNSE, XSHG, XSHE, XKRX, XJSE, XBSP, XSWX, XMIL, XIST, XSAU, XDFM, XNZE, XHEL, XSTO) plus 5 extended (XCBT, XNYM, XCBO, XCOI, XBIN). DST handled automatically via IANA timezone names. Lunch breaks, half-days, and holidays for 2026-2027.

Testing

npm test              # the full unit/integration suite
npm run test:smoke    # 11 smoke tests against live production

The passing count is published by the worker itself at /v5/metrics/public as tests_passing, and CI fails if that number and the suite disagree. It is not restated here, because a number in a README is a number nothing checks.

Security

Ed25519 signatures on every response. 60-second receipt TTL. Fail-closed architecture (UNKNOWN = CLOSED). Security headers on all responses (HSTS, CSP, X-Content-Type-Options, X-Frame-Options).

See SECURITY.md for the responsible disclosure policy.

Documentation

Full documentation organized by audience:

See docs/README.md for the full index.

License

MIT — see LICENSE

Frequently asked questions

What is io.github.LembaGang/headless-oracle-mcp?

Ed25519-signed market-state receipts for 28 exchanges. Fail-closed pre-trade gate.

How do I install io.github.LembaGang/headless-oracle-mcp?

It runs on your machine. In Claude Code: claude mcp add headless-oracle-mcp -- npx -y headless-oracle-mcp@1.0.3. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.LembaGang/headless-oracle-mcp need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is io.github.LembaGang/headless-oracle-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.LembaGang/headless-oracle-mcp?

It is published by LembaGang. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.