agentleFS
QBT-LabsQBT-Labs/openmm-mcp/CLAUDE.md

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
  1. Very specific:

    All tools use Zod schemas from src/utils/validators.ts for parameter validation.

    line 45
  2. Distinctive:

    NEVER add "Generated by Claude", "Co-authored-by: Claude", or any AI attribution to commits

    line 88
  3. Distinctive:

    Never commit directly to main — always branch + PR

    line 89
  4. Distinctive:

    No credentials, private keys, or socket paths in source files

    line 93
  5. Very specific:

    Do NOT suggest storing OPENMM_PASSWORD in claude.json or any config — defeats the vault

    line 97
  6. Very specific:

    Do NOT use require() — this project is ESM (NodeNext modules)

    line 98
  7. Very specific:

    Run npm run typecheck after any series of changes, not just at the end

    line 99

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 --check

CI 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. Exports createServer() 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 /health and /mcp endpoints 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_KEY env 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 via openmm-vault.
  • Unified IPC (src/ipc/) — Single Unix socket at /tmp/openmm.sock serving credentials and payment signing. Started by openmm 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 templates
  • src/prompts/ — Trading and market analysis prompts providing guardrails for AI agents

Key Patterns

  • Symbol format: Accepts BTC/USDT or BTCUSDT, 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_TRANSPORT env 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/x402 packages
  • x402 modules have manual mocks in src/tests/__mocks__/ to prevent real payment calls in tests

Git Conventions

  • Branch: feat/QBT-xxx for features, fix/QBT-xxx for 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.sock via OPENMM_SOCKET env 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 typecheck after 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.