openmm-mcp
CLAUDE.md3 starsChanged 8 months agoMITView on GitHub
@qbtlabs/openmm-mcp is an MCP (Model Context Protocol) server that exposes cryptocurrency trading, market data, and strategy tools to AI agents. It supports two deployment modes: local (stdio transport, user's own API keys) and hosted (HTTP transport on mcp.openmm.io with x402 USDC micropayments on Base). CI runs on Node 20 & 22: typecheck → lint → format:check → test → build. Each tool category exports a register*Tools(server, exchangeManager) function, aggregated in src/tools/index.ts: All tools use Zod schemas from src/utils/validators.ts for parameter…
The file
We split this CLAUDE.md into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 45
All tools use Zod schemas from src/utils/validators.ts for parameter validation.
- Distinctive: line 88
NEVER add "Generated by Claude", "Co-authored-by: Claude", or any AI attribution to commits
- Distinctive: line 89
Never commit directly to main — always branch + PR
- Distinctive: line 93
No credentials, private keys, or socket paths in source files
- Very specific: line 97
Do NOT suggest storing OPENMM_PASSWORD in claude.json or any config — defeats the vault
- Very specific: line 98
Do NOT use require() — this project is ESM (NodeNext modules)
- Very specific: line 99
Run npm run typecheck after any series of changes, not just at the end
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project Overview
@qbtlabs/openmm-mcp is an MCP (Model Context Protocol) server that exposes cryptocurrency trading, market data, and strategy tools to AI agents. It supports two deployment modes: local (stdio transport, user's own API keys) and hosted (HTTP transport on mcp.openmm.io with x402 USDC micropayments on Base).
Build & Development Commands
npm run build # tsc → dist/
npm run dev # ts-node src/index.ts (local development)
npm test # all tests via Jest
npm run test:unit # unit tests only
npm run test:x402 # payment-related tests
npm run test:e2e # E2E tests (requires TEST_E2E=true)
npm run typecheck # tsc --noEmit
npm run lint # eslint
npm run lint:fix # eslint --fix
npm run format # prettier --write
npm run format:check # prettier --checkCI runs on Node 20 & 22: typecheck → lint → format:check → test → build.
Architecture
Entry Points
src/index.ts— Routes between setup wizard (--setup) and normal server startup. ExportscreateServer()for programmatic use.src/server.ts— Core MCP server creation: registers tools/resources/prompts, handles stdio and HTTP transports, auto-loads vault credentials on startup. HTTP mode adds/healthand/mcpendpoints with optional x402 payment gating.src/worker.ts— Cloudflare Workers entrypoint for hosted deployment. Defers heavy imports inside request handlers to avoid Workers global-scope I/O restrictions.
Tool System (src/tools/)
Each tool category exports a register*Tools(server, exchangeManager) function, aggregated in src/tools/index.ts:
- market-data.ts —
get_ticker,get_orderbook,get_trades,get_ohlcv - account.ts —
get_balance,list_orders - trading.ts —
create_order,cancel_order,cancel_all_orders - cardano.ts —
get_cardano_price,discover_pools(Iris API for DEX pools) - strategy.ts —
start_grid_strategy,stop_strategy,get_strategy_status(grid trading with linear/geometric spacing, flat/pyramidal sizing)
All tools use Zod schemas from src/utils/validators.ts for parameter validation. Tools return {content: [{type: 'text', text: JSON.stringify(...)}]}.
Payment Layer (src/payment/)
wrapServerWithPayment() intercepts tool calls with x402 payment verification. Two modes:
- Direct key mode — uses
WALLET_PRIVATE_KEYenv var - Signer mode — isolated x402-signer process (more secure, credentials never in MCP process)
Tool pricing: free (list_exchanges), read ($0.001), write ($0.01).
Exchange Integration (src/exchange/exchange-manager.ts)
Wraps the @3rd-eye-labs/openmm SDK's ExchangeFactory. Supported exchanges: MEXC, Gate.io, Kraken, Bitget. getConnectorSafe() provides graceful error handling around SDK calls.
Credential Management
- Vault (
src/vault/) — AES-256-GCM encrypted storage at~/.openmm/vault.enc. CLI viaopenmm-vault. - Unified IPC (
src/ipc/) — Single Unix socket at/tmp/openmm.sockserving credentials and payment signing. Started byopenmm serve. - Auto-loaded at startup via
src/vault/loader.ts, setting env vars for exchange adapters.
Resources & Prompts
src/resources/— MCP resources listing supported exchanges and strategy templatessrc/prompts/— Trading and market analysis prompts providing guardrails for AI agents
Key Patterns
- Symbol format: Accepts
BTC/USDTorBTCUSDT, normalized to uppercase - Cardano price: Averages ADA/USDT from multiple CEX sources (Binance, MEXC, Coingecko)
- Grid strategy: Supports geometric spacing (cumulative factor) and pyramidal sizing (larger orders near center)
- Smithery:
createSandboxServer()scans tools without real credentials for registry publication - Transport detection:
MCP_TRANSPORTenv var selects stdio vs HTTP; x402 enabled when HTTP + payment env vars present
TypeScript Configuration
- Target: ES2020, Module: NodeNext, strict mode
- Tests use ts-jest with ESM transforms for
@noble/*and@qbtlabs/x402packages - x402 modules have manual mocks in
src/tests/__mocks__/to prevent real payment calls in tests
Git Conventions
- Branch:
feat/QBT-xxxfor features,fix/QBT-xxxfor bugs,chore/for housekeeping - Commits: conventional commits —
feat:,fix:,chore:,refactor:,test: - NEVER add "Generated by Claude", "Co-authored-by: Claude", or any AI attribution to commits
- Never commit directly to main — always branch + PR
Security Rules
- Vault password is interactive-only — never in CLI flags, env vars, or config files
- No credentials, private keys, or socket paths in source files
- Socket default:
/tmp/openmm.sockviaOPENMM_SOCKETenv var (replaces the two-socket model)
What Claude Gets Wrong Here
- Do NOT suggest storing OPENMM_PASSWORD in claude.json or any config — defeats the vault
- Do NOT use
require()— this project is ESM (NodeNext modules) - Run
npm run typecheckafter any series of changes, not just at the end
Status
Last operational check: 2026-04-29 — All tests passing (8 test suites, 43 tests). Node v20+ compatible. Vault and payment systems operational.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

