deribit-mcp: Instructions file for Codex

AGENTS.md

A local stdio MCP server for the Deribit JSON-RPC v2 API. src/ is the only implementation; dist/ is build output.

Commands

npm run dev         # run the sources directly via tsx, no build (development only)
npm run build       # tsc -> dist/
npm run typecheck
npm test            # = npm run smoke
npm run smoke       # real stdio client + testnet regression, needs no credentials
npm run check:api   # documentation drift detection; exit 1 = time to bump the version
npm run docs:coverage

Run at least npm test after any code change.

tsx is a devDependency only. The published artifact must be compiled JS, and bin points at dist/index.js: tsx drags startup from 77ms to 160ms (an MCP client launches the server once per session), grows a cold install from 24MB to 35MB (esbuild ships 26 platform binaries, and environments such as Alpine/musl then fail to run at all), and it bypasses the prepublishOnly type check, letting type errors ship silently to users' machines.

Non-negotiable conventions

1. stdout carries JSON-RPC only. Every human-facing message goes to process.stderr. One extra stdout line breaks client parsing.
2. Writes are never retried. privateCall(..., { readOnly: false }) sends exactly once. A replay is one extra real order.
3. Deribit's error responses come back as HTTP 400 and carry no id. So the id is validated on successful responses only, and the body must be parsed before the status code is inspected. Keep this rule when editing src/deribit/client.ts — losing it degrades every business error into a useless id-mismatch message.
4. Handlers throw plain Error / InvalidParamsError, which the SDK wraps into an isError: true tool result the model can read and retry from. Do not throw McpError: that becomes a protocol error, which most clients render as a bare "call failed".
5. Every tool must declare methods: [...]. It is the single source of truth check:api reconciles against, so a changed call must be mirrored there.
6. Declare no outputSchema and return no structuredContent. Only a single text block. Responses such as an option chain are already large, and a structured copy would double the payload.
7. Cross-field constraints live in the handler, not in a Zod .superRefine() — that keeps the error message under our control and delivers it as an isError result to the model.