deribit-mcp 1.0.0

//! # `deribit-mcp`
//!
//! Model Context Protocol (MCP) server for the Deribit cryptocurrency
//! derivatives platform. Single binary crate that adapts the
//! `deribit-base`, `deribit-http`, `deribit-websocket`, and
//! (optional) `deribit-fix` stack onto MCP's tool / resource /
//! prompt surface.
//!
//! This is a **thin adapter** — every MCP tool is a translation
//! step over an upstream call. Auth, rate limiting, reconnect, and
//! wire codecs live in the sibling crates.
//!
//! ## Quick start
//!
//! The fastest path is Docker — clone the repo, drop credentials
//! in `.env`, run compose. The binary also installs with
//! `cargo install`.
//!
//! ### 1. Get credentials
//!
//! Create a Deribit API key at <https://test.deribit.com>
//! (testnet) or <https://www.deribit.com> (mainnet). Account →
//! API → Add new key. You only need `client_id` and
//! `client_secret`. Public `Read` tools work without credentials;
//! `Account` / `Trading` tools require them.
//!
//! ### 2. Configure
//!
//! Copy `.env.example` to `.env` at the repository root and fill
//! in:
//!
//! ```bash
//! DERIBIT_NETWORK=testnet                # or `mainnet`
//! DERIBIT_CLIENT_ID=your_client_id
//! DERIBIT_CLIENT_SECRET=your_client_secret
//! # Optional — gates the HTTP endpoint with a static bearer:
//! DERIBIT_HTTP_BEARER_TOKEN=
//! RUST_LOG=info,deribit_mcp=debug
//! ```
//!
//! `.env` is git-ignored (mode `600` recommended). Credentials
//! never appear on the command line — they live in the
//! environment only.
//!
//! ### 3. Deploy
//!
//! **Docker compose** (recommended):
//!
//! ```bash
//! docker compose -f Docker/docker-compose.yml up -d
//! curl -sf http://127.0.0.1:8723/healthz && echo "ok"
//! ```
//!
//! **`docker run`**:
//!
//! ```bash
//! docker build -f Docker/Dockerfile -t deribit-mcp:local .
//! docker run -d --name deribit-mcp \
//!   --restart unless-stopped \
//!   --env-file .env \
//!   -p 127.0.0.1:8723:8723 \
//!   deribit-mcp:local \
//!   --transport=http --listen=0.0.0.0:8723
//! ```
//!
//! **`cargo install`**:
//!
//! ```bash
//! cargo install --path . --locked
//! deribit-mcp --transport=stdio
//! # or
//! deribit-mcp --transport=http --listen=0.0.0.0:8723
//! ```
//!
//! The HTTP runtime image is distroless — no shell, no package
//! manager, runs as `nonroot`. Health probe is `GET /healthz`
//! (unauthenticated, returns `200 OK` while the server accepts
//! requests).
//!
//! ### 4. Enable trading (opt-in)
//!
//! Trading tools (`place_order`, `edit_order`, `cancel_order`,
//! `cancel_all_by_*`) are absent from `tools/list` unless you
//! launch with `--allow-trading` AND credentials are configured.
//! Add a notional cap to keep blast-radius bounded:
//!
//! ```bash
//! deribit-mcp --transport=http --listen=0.0.0.0:8723 \
//!   --allow-trading --max-order-usd=100
//! ```
//!
//! The cap classifies inverse vs linear instruments and falls
//! back to the upstream mark price for market orders that don't
//! carry a price.
//!
//! ## Use from Claude Desktop
//!
//! Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
//! (macOS) or `%APPDATA%\Claude\claude_desktop_config.json`
//! (Windows).
//!
//! ### Option A — HTTP (uses the running container)
//!
//! ```json
//! {
//!   "mcpServers": {
//!     "deribit": {
//!       "command": "npx",
//!       "args": [
//!         "-y",
//!         "mcp-remote",
//!         "http://127.0.0.1:8723/mcp"
//!       ]
//!     }
//!   }
//! }
//! ```
//!
//! If you set `DERIBIT_HTTP_BEARER_TOKEN`, append
//! `"--header", "Authorization: Bearer YOUR_TOKEN"` to `args`.
//!
//! ### Option B — stdio (no Docker)
//!
//! ```json
//! {
//!   "mcpServers": {
//!     "deribit": {
//!       "command": "/Users/you/.cargo/bin/deribit-mcp",
//!       "args": ["--transport=stdio"],
//!       "env": {
//!         "DERIBIT_NETWORK": "testnet",
//!         "DERIBIT_CLIENT_ID": "...",
//!         "DERIBIT_CLIENT_SECRET": "..."
//!       }
//!     }
//!   }
//! }
//! ```
//!
//! Quit Claude Desktop completely (⌘Q on macOS — including the
//! menubar icon) and relaunch. The slash menu should now show
//! `deribit:get_ticker`, `deribit:get_currencies`, etc.
//!
//! ## Sample prompts
//!
//! Paste any of these into Claude Desktop after the `deribit`
//! connector is active. Each one exercises a specific tool,
//! resource, or curated prompt; together they cover the full
//! MCP surface.
//!
//! ### Public market data — `Read` tools (no credentials)
//!
//! - `get_server_time` — "Using the deribit MCP server, give me
//!   the current Deribit server time as a Unix-ms timestamp."
//! - `get_status` — "Using deribit, call `get_status` and tell me
//!   if any currency is locked."
//! - `get_currencies` — "Using deribit, list all currencies with
//!   their long names, fee precision, and minimum withdrawal
//!   fee."
//! - `get_index_price` — "Using deribit, fetch the BTC USD index
//!   price (`get_index_price`, `index_name=btc_usd`)."
//! - `get_ticker` — "Using deribit, give me the BTC-PERPETUAL
//!   ticker. Summarize in one line: mark, last, best bid, best
//!   ask, 24h volume."
//! - `get_instrument` — "Using deribit, call `get_instrument` for
//!   `BTC-PERPETUAL` and tell me the contract size, tick size,
//!   and minimum trade amount."
//! - `list_instruments` — "Using deribit, list every active
//!   `option` for `ETH` (`list_instruments`,
//!   `currency=ETH, kind=option, expired=false`). Group by
//!   expiration date."
//! - `get_order_book` — "Using deribit, fetch the BTC-PERPETUAL
//!   order book at depth 10 and show me the best 5 levels each
//!   side."
//! - `get_book_summary_by_currency` — "Using deribit, get a book
//!   summary for every BTC future
//!   (`get_book_summary_by_currency`, `currency=BTC,
//!   kind=future`). Sort by 24h volume descending."
//! - `get_book_summary_by_instrument` — "Using deribit, give me
//!   the book summary for `BTC-PERPETUAL` only."
//! - `get_last_trades` — "Using deribit, fetch the last 50 trades
//!   on `BTC-PERPETUAL` (`get_last_trades`, `count=50`). Tell me
//!   the buy/sell ratio."
//! - `get_tradingview_chart_data` — "Using deribit, pull 1-hour
//!   candles for BTC-PERPETUAL covering the last 24 hours via
//!   `get_tradingview_chart_data`. Identify the hour with the
//!   widest range."
//! - `get_funding_rate_history` — "Using deribit, fetch
//!   `get_funding_rate_history` for BTC-PERPETUAL covering the
//!   last 24h. Compute the mean."
//! - `get_historical_volatility` — "Using deribit, fetch
//!   `get_historical_volatility` for BTC and ETH. Compare the
//!   most recent values."
//!
//! ### Authenticated reads — `Account` tools (credentials
//! required)
//!
//! - `get_account_summary` — "Using deribit, give me
//!   `get_account_summary` for BTC with `extended=true`. Show
//!   equity, initial margin, maintenance margin, P&L, available
//!   balance."
//! - `get_positions` — "Using deribit, list my open BTC
//!   positions. Flag any with margin utilization above 70%."
//! - `get_subaccounts` — "Using deribit, list my subaccounts
//!   (`get_subaccounts`, `with_portfolio=true`)."
//! - `get_transaction_log` — "Using deribit,
//!   `get_transaction_log` for BTC over the last 24 hours. Group
//!   by `type`."
//! - `get_deposits` — "Using deribit, show my last 10 BTC
//!   deposits (`get_deposits`, `currency=BTC, count=10`)."
//! - `get_withdrawals` — "Using deribit, show my last 10 BTC
//!   withdrawals."
//! - `get_open_orders_by_currency` — "Using deribit, list every
//!   open BTC order. Mark anything older than 24 hours."
//! - `get_open_orders_by_instrument` — "Using deribit, list open
//!   orders on `BTC-PERPETUAL` only."
//! - `get_user_trades_by_currency` — "Using deribit, fetch the
//!   last 50 BTC user trades (`get_user_trades_by_currency`,
//!   `currency=BTC, count=50`). Compute net realized P&L."
//! - `get_user_trades_by_instrument` — "Using deribit, fetch user
//!   trades for `BTC-PERPETUAL` over the last 24 hours."
//!
//! ### Order entry — `Trading` tools (`--allow-trading`)
//!
//! Always test on testnet first. Use a small `--max-order-usd`
//! cap.
//!
//! - `place_order` (limit buy) — "Using deribit, place a buy
//!   limit order for 10 USD of `BTC-PERPETUAL` at half the
//!   current mark price, post-only, label
//!   `prompt-test`."
//! - `place_order` (stop-limit) — "Using deribit, place a
//!   stop-limit sell on `BTC-PERPETUAL`: amount 10, price 90000,
//!   trigger_price 91000, trigger=`mark_price`."
//! - `edit_order` — "Using deribit, edit order
//!   `<order_id>` to amount 20 and price 51000."
//! - `cancel_order` — "Using deribit, cancel order
//!   `<order_id>`."
//! - `cancel_all_by_currency` — "Using deribit, cancel every
//!   open BTC order (`cancel_all_by_currency`, `currency=BTC`).
//!   Tell me how many were cancelled."
//! - `cancel_all_by_instrument` — "Using deribit, cancel every
//!   open `BTC-PERPETUAL` order."
//!
//! ### Resources
//!
//! - `deribit://currencies` (static) — "Using deribit, read the
//!   resource `deribit://currencies` and list each `currency`
//!   with its `withdrawal_fee`."
//! - `deribit://instruments/{currency}` (template) — "Using
//!   deribit, read `deribit://instruments/BTC` and tell me how
//!   many futures are listed."
//! - `deribit://book/{instrument}` (live) — "Using deribit, read
//!   `deribit://book/BTC-PERPETUAL` and show the top 5 bids and
//!   asks."
//! - `deribit://ticker/{instrument}` (live) — "Using deribit,
//!   read `deribit://ticker/BTC-PERPETUAL`."
//! - `deribit://trades/{instrument}` (live) — "Using deribit,
//!   read `deribit://trades/BTC-PERPETUAL` and tell me the
//!   trade-size distribution."
//!
//! ### Curated prompts
//!
//! MCP prompts are exposed as slash-commands in Claude Desktop —
//! the user (not Claude) types them. Once the slash-command is
//! expanded the curated message pair lands in the conversation
//! and Claude follows the instructions, calling the tools the
//! prompt names. The naming convention is
//! `/mcp__<server>__<prompt>` (double underscores).
//!
//! - `daily_options_summary` — type
//!   `/mcp__deribit__daily_options_summary` and supply
//!   `currency=BTC`, `horizon_days=7`. Drives Claude through
//!   `list_instruments`, `get_book_summary_by_currency`, and
//!   `get_historical_volatility`, then produces a four-section
//!   summary (ATM IV vs RV headline, top calls + puts by OI,
//!   skew commentary, caveats).
//! - `funding_snapshot` — type
//!   `/mcp__deribit__funding_snapshot` and supply `currency=BTC`,
//!   `lookback_hours=24`. Drives Claude through
//!   `list_instruments` (perpetual filter) and
//!   `get_funding_rate_history`, then produces a table (latest,
//!   mean / median / p10 / p90, sign breakdown, outliers,
//!   caveats).
//! - `position_review` — type
//!   `/mcp__deribit__position_review` and supply `currency=BTC`,
//!   `include_history=true`. Drives Claude through
//!   `get_account_summary`, `get_positions`,
//!   `get_open_orders_by_currency`, and (when
//!   `include_history=true`) `get_user_trades_by_currency`, then
//!   produces a report (headline, positions, open orders, flags,
//!   recent trades, caveats). When credentials are missing the
//!   prompt returns a structured warning instead.
//!
//! If you want Claude to perform an equivalent workflow without
//! invoking the slash-command, ask directly — for example: "Using
//! deribit, summarize BTC options expiring in the next 7 days.
//! Run `list_instruments` (kind=option), filter by
//! `expiration_timestamp` within 7 days, then
//! `get_book_summary_by_currency` and `get_historical_volatility`.
//! Produce: ATM IV vs RV headline; top 3 calls and puts by open
//! interest; skew commentary; caveats." That bypasses the
//! curated prompt but reaches the same result.
//!
//! ### Negative paths (gating verification)
//!
//! - "Using deribit, try `place_order` with no credentials
//!   configured. What does the registry say?" (Should be absent
//!   from `tools/list`.)
//! - "Using deribit, call `get_account_summary` for currency
//!   `XYZ`." (Should return a structured `Validation` error.)
//!
//! ## Capability surface (v1.0.0)
//!
//! | Class | Count | Examples |
//! |---|---:|---|
//! | `Read` tools (no auth) | 14 | `get_ticker`, `get_currencies`, `get_order_book`, `get_book_summary_by_currency`, `get_funding_rate_history`, `get_historical_volatility`, `get_last_trades`, `get_tradingview_chart_data`, `get_index_price`, `get_server_time`, `get_status` |
//! | `Account` tools (creds) | 10 | `get_account_summary`, `get_positions`, `get_subaccounts`, `get_open_orders_by_currency`, `get_user_trades_by_currency`, `get_transaction_log`, `get_deposits`, `get_withdrawals` |
//! | `Trading` tools (`--allow-trading`) | 5 | `place_order`, `edit_order`, `cancel_order`, `cancel_all_by_currency`, `cancel_all_by_instrument` |
//! | Resources | 1 + 4 templates | `deribit://currencies`, `deribit://instruments/{currency}`, `deribit://book/{instrument}`, `deribit://ticker/{instrument}`, `deribit://trades/{instrument}` |
//! | Prompts | 3 | `daily_options_summary`, `funding_snapshot`, `position_review` |
//!
//! The MCP wire shape is locked under SemVer from 1.0.0 — adding
//! / renaming / removing tool fields, resource URIs, error
//! variants, or prompt arguments requires a 2.0 major bump (see
//! `CHANGELOG.md`).
//!
//! ## Configuration reference
//!
//! | Setting | CLI | Env var | Default |
//! |---|---|---|---|
//! | Network | `--testnet` / `--mainnet` | `DERIBIT_NETWORK=testnet\|mainnet` or `DERIBIT_ENDPOINT=<url>` | testnet |
//! | Credentials | — | `DERIBIT_CLIENT_ID` / `DERIBIT_CLIENT_SECRET` | none |
//! | Trading opt-in | `--allow-trading` | `DERIBIT_ALLOW_TRADING=1` | off |
//! | Notional cap | `--max-order-usd=N` | `DERIBIT_MAX_ORDER_USD=N` | unlimited |
//! | MCP transport | `--transport=stdio\|http` | `DERIBIT_MCP_TRANSPORT` | stdio |
//! | HTTP listen | `--listen=ADDR:PORT` | `DERIBIT_HTTP_LISTEN` | `127.0.0.1:8723` |
//! | HTTP bearer | — | `DERIBIT_HTTP_BEARER_TOKEN` | none (anonymous) |
//! | Order transport | `--order-transport=http\|fix` | `DERIBIT_ORDER_TRANSPORT` | http |
//! | Log filter | — | `RUST_LOG` | `info` |
//! | Log format | `--log-format=text\|json` | `DERIBIT_LOG_FORMAT` | text on stdio, json on http |
//!
//! CLI flags win over env vars; env vars win over `.env`; `.env`
//! wins over built-in defaults.
//!
//! ## Observability
//!
//! Each MCP request emits two structured events on stderr (stdio)
//! / stdout (http) — entry and outcome — with target
//! `deribit_mcp::request` and `elapsed_ms`:
//!
//! ```bash
//! docker logs -f deribit-mcp 2>&1 | grep deribit_mcp::request
//! ```
//!
//! ```text
//! INFO deribit_mcp::request tools/call tool="get_ticker"
//! INFO deribit_mcp::request tools/call ok tool="get_ticker" elapsed_ms=75
//! WARN deribit_mcp::request tools/call error tool="missing" elapsed_ms=0 error="..."
//! ```
//!
//! Secrets (`client_secret`, `access_token`, `refresh_token`,
//! `http_bearer_token`) are redacted before they reach any
//! tracing sink.
//!
//! ## Troubleshooting
//!
//! | Symptom | Likely cause | Fix |
//! |---|---|---|
//! | `tools/call` returns `-32601 method not found` | Old image without the `ServerHandler::call_tool` override | Rebuild: `docker compose -f Docker/docker-compose.yml build --no-cache` |
//! | Every `/mcp` request returns `401` | `DERIBIT_HTTP_BEARER_TOKEN` set in env (even empty `=` lines) | Remove the line from `.env` or pass `Authorization: Bearer ...` from the client |
//! | `Upstream { error decoding response body }` | Custom endpoint URL missing `/api/v2` suffix | Use `DERIBIT_NETWORK=testnet\|mainnet` instead of `DERIBIT_ENDPOINT`; the canonical paths are auto-applied |
//! | Account / Trading tools missing from `tools/list` | Credentials not loaded | Verify `docker inspect <id>` shows `DERIBIT_CLIENT_ID` and `DERIBIT_CLIENT_SECRET` |
//! | Trading tools missing despite credentials | `--allow-trading` not set | Add it to the `command:` block in compose |
//! | Claude Desktop says "connector not responding" | Cached old session in `mcp-remote` | Quit Claude Desktop with ⌘Q (also the menubar icon), relaunch |
//! | `mcp-remote` rejects with "Invalid input in structuredContent" | Old server before scalar-wrap fix | Pull / rebuild — the adapter wraps non-object payloads in `{"value": ...}` since v1.0 |
//!
//! Build problems? `cargo install` requires `cmake`, `perl`,
//! `pkg-config`, and `libssl-dev` (or `openssl-devel`) for the
//! FIX dependency chain. Docker handles this automatically.
//!
//! ## Crate layout
//!
//! - [`config`] — CLI argument and `.env` resolution.
//! - [`context`] — `AdapterContext` shared across handlers.
//! - [`error`] — `AdapterError` and `From` impls for upstream errors.
//! - [`server`] — `rmcp` Server scaffold.
//! - [`observability`] — `tracing` setup and secret redaction.
//! - [`tools`] — `Read` / `Account` / `Trading` tool families.
//! - [`resources`] — static and live resource families.
//! - [`prompts`] — curated MCP prompts (registry + handlers).
//! - [`prelude`] — curated re-exports for downstream consumers.

#![forbid(unsafe_code)]
#![warn(missing_docs)]
#![warn(rust_2018_idioms)]
#![warn(clippy::all)]

pub mod config;
pub mod context;
pub mod error;
pub mod http_transport;
pub mod observability;
pub mod prelude;
pub mod prompts;
pub mod resources;
pub mod server;
pub mod tools;

pub use crate::context::{AdapterContext, AuthState};
pub use crate::error::{AdapterError, AuthFailureReason, UpstreamErrorKind};
pub use crate::prompts::{PromptEntry, PromptHandlerFn, PromptRegistry};
pub use crate::resources::{
    ResourceContent, ResourceList, ResourceRegistry, ResourceUri, parse_resource_uri,
};
pub use crate::server::{DeribitMcpServer, MCP_PROTOCOL_VERSION};
pub use crate::tools::{ToolClass, ToolEntry, ToolRegistry};