# `deribit-mcp` design documentation
Start here. The documents below cover the project from product to wire
format. Suggested reading order depends on what you are doing.
## Reading paths
**I'm a stakeholder, what is this?**
1. [PRD.md](PRD.md) — vision, users, scope, success metrics.
2. [COMPETITIVE-ANALYSIS.md](COMPETITIVE-ANALYSIS.md) — vs other
trading-platform MCP servers and the do-it-yourself path.
3. [ROADMAP.md](ROADMAP.md) — when each piece lands.
**I'm an LLM-app builder about to depend on the server.**
1. [DOMAIN-MODEL.md](DOMAIN-MODEL.md) — the tools, resources, and
prompts the server exposes.
2. [MCP-SPEC.md](MCP-SPEC.md) — wire protocol summary and how this
server uses it.
3. [DERIBIT-INTEGRATION.md](DERIBIT-INTEGRATION.md) — what the server
talks to upstream and how auth flows.
**I'm contributing to the repo.**
1. [ARCHITECTURE.md](ARCHITECTURE.md) and the [ADRs](adr/) — why
things are shaped the way they are.
2. [DERIBIT-INTEGRATION.md](DERIBIT-INTEGRATION.md) — the four
sibling crates this server adapts.
3. [TESTING.md](TESTING.md) — what CI runs and how to add a test.
**I want to extend the server with a new tool or resource.**
1. [DOMAIN-MODEL.md §6](DOMAIN-MODEL.md) — the tool-registration
contract.
2. [ADR-0003](adr/0003-tool-taxonomy.md) — read-only vs write
classification.
3. [ADR-0010](adr/0010-trading-tools-opt-in.md) — the safety gate
for any tool that places, edits, or cancels orders.
## Document inventory
### Internal design documents
| [PRD.md](PRD.md) | All | Draft v1.0 |
| [ARCHITECTURE.md](ARCHITECTURE.md) | Engineers | Draft v1.0 |
| [DOMAIN-MODEL.md](DOMAIN-MODEL.md) | Engineers | Draft v1.0 |
| [MCP-SPEC.md](MCP-SPEC.md) | Implementers | Draft v1.0 |
| [DERIBIT-INTEGRATION.md](DERIBIT-INTEGRATION.md) | Engineers, ops | Draft v1.0 |
| [TESTING.md](TESTING.md) | Contributors | Draft v1.0 |
| [ROADMAP.md](ROADMAP.md) | All | Living |
| [COMPETITIVE-ANALYSIS.md](COMPETITIVE-ANALYSIS.md) | Decision-makers | Draft v1.0 |
### External specifications (reference)
| [specs/mcp-2025-06-18.md](specs/mcp-2025-06-18.md) | Model Context Protocol, revision 2025-06-18 |
| [specs/deribit-api-v2.1.1.md](specs/deribit-api-v2.1.1.md) | Deribit API v2.1.1 (HTTP + WebSocket + FIX 4.4) |
| [specs/README.md](specs/README.md) | How to update these specs |
## Architecture Decision Records
Lightweight ADRs in **Context → Decision → Consequences → Alternatives**
format. Every non-obvious technical choice is captured here.
| [0001](adr/0001-thin-adapter-over-siblings.md) | Thin adapter over the four `deribit-*` sibling crates |
| [0002](adr/0002-stdio-transport-first.md) | Both stdio and HTTP/SSE MCP transports from v0.1 |
| [0003](adr/0003-tool-taxonomy.md) | Tool taxonomy: read-only / account / trading |
| [0004](adr/0004-credentials-out-of-band.md) | Credentials in environment variables only; `.env` supported |
| [0005](adr/0005-rmcp-rust-sdk.md) | Use `rmcp` (official Rust MCP SDK) for the server runtime |
| [0006](adr/0006-http-for-tools-ws-for-streams.md) | `deribit-http` for tools, `deribit-websocket` for resources |
| [0007](adr/0007-single-binary-crate.md) | Single binary crate, not a layered family |
| [0008](adr/0008-rate-limit-at-adapter.md) | Rate limiting in the adapter layer, not pushed to the LLM |
| [0009](adr/0009-testnet-default.md) | Default endpoint is `test.deribit.com`; mainnet opt-in |
| [0010](adr/0010-trading-tools-opt-in.md) | Trading tools opt-in via `--allow-trading` |
| [0011](adr/0011-container-friendly-deployment.md) | Container-friendly deployment (Docker / docker-compose / Portainer) |
## Conventions used in these docs
- **Tool names** use the MCP convention `snake_case` (`get_ticker`,
`place_order`).
- **Resource URIs** follow the `deribit://` scheme
(e.g. `deribit://ticker/BTC-PERPETUAL`).
- **Diagrams** use box-drawing characters; no images, so they render in
any terminal, IDE, and on GitHub.
- **Code samples** are illustrative — the canonical reference is the
source under `src/`.
- **Status** values: `Draft`, `Accepted`, `Deprecated`, `Superseded by …`.
## Coding rules (binding)
These design documents describe **what** to build. The **how** lives
in two binding documents at the repo root:
- [`../CLAUDE.md`](../CLAUDE.md) — high-level architecture summary
and key decisions.
- [`../rules/global_rules.md`](../rules/global_rules.md) — Rust
coding rules (compiler attributes, type safety, error handling,
concurrency, MCP discipline, performance, security,
pre-submission checklist).
Any code change must satisfy both. If a design document conflicts
with `rules/global_rules.md`, the rules document wins — the design
doc is the bug.
## How to update these docs
1. Open a PR with the prose change.
2. If the change reflects a non-obvious decision, add or update an ADR.
3. Bump the document's `Status` and `Last edit` block at the top.
4. Reference the change from `ROADMAP.md` if it affects scope.