trading-mcp-gateway 0.2.0-alpha.1

package/.env.example

@@ -0,0 +1,34 @@
+# Trading MCP Gateway example configuration.
+# Copy values into your local MCP client env block or a local .env file.
+# Keep API keys out of prompts, chat logs, shell history, and committed files.
+
+TRADING_BROKER=bybit
+TRADING_MODE=testnet
+
+# Use keys without withdrawal permission. Public market tools work without keys.
+BYBIT_API_KEY=your_bybit_api_key
+BYBIT_API_SECRET=your_bybit_api_secret
+BYBIT_RECV_WINDOW=5000
+BYBIT_REGION=global
+
+# Safe defaults: read-only/testnet unless explicitly changed by the user.
+TRADING_ALLOW_ORDER=false
+TRADING_ALLOW_LIVE=false
+TRADING_REQUIRE_CONFIRMATION=true
+TRADING_ALLOW_MARKET_ORDER=false
+TRADING_ALLOW_LEVERAGE=false
+TRADING_ALLOW_SHORT=false
+
+# Local risk policy.
+TRADING_ALLOWED_SYMBOLS=BTCUSDT,ETHUSDT
+TRADING_ALLOWED_CATEGORIES=spot,linear
+TRADING_DEFAULT_CATEGORY=linear
+TRADING_MAX_ORDER_USDT=50
+TRADING_MAX_ACTIVE_CAPITAL_USDT=100
+TRADING_MAX_SINGLE_ORDER_CAPITAL_USDT=50
+TRADING_CAPITAL_BUFFER_RATE=0.01
+
+# Local audit logging. Audit logs must not contain raw API keys, secrets, or signatures.
+TRADING_AUDIT_LOG=true
+TRADING_AUDIT_LOG_DIR=~/.trading-mcp-gateway/logs
+TRADING_LOG_LEVEL=info

package/AGENT.MD

@@ -0,0 +1,362 @@
+# AGENT.MD
+
+이 문서는 `Trading MCP Gateway` 저장소에서 작업하는 AI Coding Agent, 인간 개발자, 리뷰어가 따라야 할 구현 규칙입니다.
+
+---
+
+## 1. 프로젝트 목적
+
+이 프로젝트는 사용자의 로컬 환경에서 실행되는 MCP 서버입니다. 서버는 사용자의 환경변수에 있는 Bybit API 인증정보를 사용해 Bybit V5 API를 호출합니다. AI Agent는 API Key/Secret을 직접 알 수 없어야 하며, MCP Tool 호출을 통해서만 거래 기능에 접근해야 합니다.
+
+최종 목표는 다음과 같습니다.
+
+```text
+npx -y @your-scope/trading-mcp-gateway
+```
+
+으로 실행 가능한 로컬 Trading MCP Gateway를 제공하고, 사용자는 자신의 인증정보와 안전 정책만 설정하면 AI Agent가 로컬에서 시세 조회, 잔고 조회, 주문 검증, 테스트넷 주문, 실전 주문을 수행할 수 있게 합니다.
+
+---
+
+## 2. 절대 원칙
+
+### 2.1 Secret 노출 금지
+
+절대 하지 말 것:
+
+```text
+- BYBIT_API_KEY / BYBIT_API_SECRET을 prompt, tool response, stdout, audit log에 그대로 기록
+- 예외 메시지에 요청 헤더 전체 출력
+- test fixture에 실제 API Key 저장
+- README 예시에 실제 키처럼 보이는 값 사용
+```
+
+반드시 할 것:
+
+```text
+- 모든 secret은 redactSecret() 통과
+- 로그에는 앞 4자리/뒤 4자리 정도만 표시하거나 완전 마스킹
+- private endpoint 요청/응답 audit log에는 민감 헤더 제거
+```
+
+### 2.2 stdio MCP 서버에서 stdout 로그 금지
+
+`StdioServerTransport`를 사용하는 MCP 서버는 stdout을 JSON-RPC 통신에 사용합니다. 따라서 `console.log()`는 서버 프로토콜을 깨뜨릴 수 있습니다.
+
+사용 금지:
+
+```ts
+console.log("server started");
+```
+
+사용 가능:
+
+```ts
+console.error("server started");
+```
+
+또는 파일 기반 logger를 사용합니다.
+
+### 2.3 주문은 항상 Risk Guard를 통과해야 함
+
+`order.place`, `order.place_testnet`, `order.cancel`, `order.cancel_testnet`을 포함한 모든 주문성 Tool은 반드시 아래 순서를 지켜야 합니다.
+
+```text
+Tool input validation
+  ↓
+normalize order request
+  ↓
+load policy
+  ↓
+riskGuard.validateOrder()
+  ↓
+audit pending event
+  ↓
+BrokerAdapter.placeOrder()
+  ↓
+audit result event
+```
+
+BrokerAdapter를 직접 호출해 risk guard를 우회하는 코드를 만들면 안 됩니다.
+
+### 2.4 기본값은 안전해야 함
+
+기본값:
+
+```bash
+TRADING_MODE=testnet
+TRADING_ALLOW_ORDER=false
+TRADING_ALLOW_LIVE=false
+TRADING_ALLOW_MARKET_ORDER=false
+```
+
+mainnet 주문은 다음 두 값이 모두 true일 때만 허용합니다.
+
+```bash
+TRADING_ALLOW_ORDER=true
+TRADING_ALLOW_LIVE=true
+```
+
+---
+
+## 3. 저장소 구조 규칙
+
+```text
+src/
+  index.ts                      # entrypoint only
+  config/                       # env parsing and policy loading
+  mcp/                          # MCP server and tools
+  core/                         # broker-neutral domain logic
+  adapters/                     # broker-specific implementation
+  indicators/                   # broker-neutral technical indicators
+  utils/                        # pure utilities
+```
+
+### 3.1 MCP Tool Layer는 얇게 유지
+
+Tool 파일은 다음만 담당합니다.
+
+```text
+- input schema 선언
+- 설명 작성
+- service/core 호출
+- MCP 응답 포맷 변환
+```
+
+Tool 파일에 직접 Bybit endpoint URL, 서명 로직, fetch 호출을 넣지 마세요.
+
+### 3.2 Core는 브로커 중립
+
+`core/`는 Bybit 전용 용어를 최대한 몰라야 합니다.
+
+허용:
+
+```ts
+MarketCategory = "spot" | "linear" | "inverse" | "option" | "stock";
+OrderSide = "Buy" | "Sell";
+```
+
+주의:
+
+```text
+Bybit의 특수 retCode 처리, header 이름, endpoint path는 adapters/bybit 안에 둡니다.
+```
+
+### 3.3 Adapter는 브로커 전용
+
+`adapters/bybit/`에는 다음을 둡니다.
+
+```text
+bybit.adapter.ts       # BrokerAdapter 구현
+bybit-http-client.ts   # public/private REST 요청
+bybit-signer.ts        # HMAC/RSA signing
+bybit-types.ts         # Bybit raw request/response 타입
+bybit-mapper.ts        # raw response → core domain type
+bybit-ws-client.ts     # v0.5 이후 WebSocket
+```
+
+---
+
+## 4. Tool 이름 규칙
+
+Tool 이름은 `domain.action` 형태로 작성합니다.
+
+```text
+system.get_status
+market.get_ticker
+market.get_candles
+market.get_instruments
+account.get_wallet_balance
+risk.get_policy
+order.create_intent
+order.validate
+order.place_testnet
+order.cancel_testnet
+order.place
+order.cancel
+kill_switch.enable
+kill_switch.disable
+indicator.calculate
+```
+
+금지:
+
+```text
+getTicker
+bybitGetTicker
+placeOrderNow
+trade
+```
+
+이유: 나중에 Binance/KIS/Alpaca Adapter가 들어와도 MCP Tool 이름을 유지해야 합니다.
+
+---
+
+## 5. Tool 응답 규칙
+
+모든 Tool은 사람이 읽을 수 있는 `content`와 기계가 읽을 수 있는 `structuredContent`를 함께 반환합니다.
+
+예시:
+
+```ts
+return {
+  content: [
+    {
+      type: "text",
+      text: `BTCUSDT last price: ${ticker.lastPrice}`
+    }
+  ],
+  structuredContent: ticker
+};
+```
+
+에러는 secret을 제거한 뒤 안전한 메시지로 반환합니다.
+
+```ts
+throw new McpError(
+  ErrorCode.InvalidRequest,
+  "Order rejected by local risk policy: symbol is not allowed"
+);
+```
+
+---
+
+## 6. TypeScript 규칙
+
+- `strict: true` 유지
+- `any` 사용 금지. 외부 raw response는 `unknown`에서 Zod 또는 타입 가드로 좁힐 것
+- 가격/수량은 number가 아니라 string 또는 Decimal로 처리
+- 테스트 fixture의 숫자도 string을 유지
+- HTTP 요청 timeout을 반드시 적용
+- 네트워크 에러, Bybit retCode 에러, MCP input validation 에러를 구분
+
+---
+
+## 7. 환경변수 규칙
+
+`config/env.ts`에서만 `process.env`를 직접 읽습니다. 다른 파일에서 직접 `process.env.BYBIT_API_KEY`를 참조하지 마세요.
+
+필수/선택 config는 시작 시 검증합니다.
+
+```ts
+export interface AppConfig {
+  broker: "bybit";
+  mode: "testnet" | "mainnet";
+  bybit: {
+    apiKey?: string;
+    apiSecret?: string;
+    recvWindow: string;
+    region: "global" | "nl" | "tr" | "kz" | "ge" | "ae" | "eu" | "id";
+  };
+  policy: TradingPolicy;
+}
+```
+
+---
+
+## 8. 구현 순서
+
+순서를 바꾸지 않는 것을 권장합니다.
+
+```text
+Phase 0: MCP 서버 골격
+Phase 1: Bybit public market adapter
+Phase 2: Bybit private auth/account adapter
+Phase 3: local risk guard + dry-run order intent
+Phase 4: testnet order execution
+Phase 5: mainnet readiness + kill switch
+Phase Extra: market order safety
+Phase 6: indicators
+Phase 7: websocket
+Phase 8: strategy runner
+Phase 9: multi-broker
+```
+
+---
+
+## 9. 테스트 필수 조건
+
+PR은 아래 검증을 통과해야 합니다.
+
+```bash
+npm run build
+npm test
+npm run lint
+```
+
+필수 테스트:
+
+```text
+- env parser unit test
+- Bybit signer snapshot test
+- queryString canonicalization test
+- secret redaction test
+- risk guard rejection test
+- MCP tool input validation test
+- adapter mapper fixture test
+- testnet integration test는 opt-in으로 분리
+```
+
+Integration test는 실제 API Key가 필요한 경우 다음 환경변수가 있을 때만 실행합니다.
+
+```bash
+RUN_BYBIT_TESTNET_INTEGRATION=true
+BYBIT_API_KEY=...
+BYBIT_API_SECRET=...
+```
+
+---
+
+## 10. PR 리뷰 체크리스트
+
+- [ ] `console.log()`가 없음
+- [ ] API Key/Secret이 응답/로그/테스트에 노출되지 않음
+- [ ] 주문 Tool은 risk guard를 통과함
+- [ ] mainnet 주문은 `TRADING_ALLOW_LIVE=true` 없이는 불가능함
+- [ ] 모든 Tool input은 Zod schema로 검증됨
+- [ ] Bybit raw response는 mapper를 거쳐 core type으로 변환됨
+- [ ] 가격/수량 연산에 floating point number를 직접 사용하지 않음
+- [ ] 실패 케이스 테스트가 있음
+- [ ] README 또는 docs가 변경 사항을 반영함
+
+---
+
+## 11. 이 저장소에서 하지 않는 것
+
+초기 버전에서는 다음을 구현하지 않습니다.
+
+```text
+- 출금 API
+- 자산 이체 API
+- API Key 생성/관리 UI
+- 레버리지 자동 변경
+- 대출/마진 설정 자동화
+- 사용자 클라우드 키 저장
+- 수익 보장 문구
+- 미검증 전략의 자동 mainnet 주문
+```
+
+---
+
+## 12. Agent에게 주는 작업 방식
+
+작업할 때는 항상 다음 형식을 지키세요.
+
+```text
+1. 변경 대상 phase 명시
+2. 변경 파일 목록 제시
+3. 구현
+4. 테스트 추가
+5. 로컬 검증 명령 제시
+6. 보안 영향 요약
+```
+
+예시:
+
+```text
+Phase 1 market.get_ticker 구현
+- src/adapters/bybit/bybit-http-client.ts
+- src/adapters/bybit/bybit.adapter.ts
+- src/mcp/tools/market.tools.ts
+- tests/unit/bybit-market.test.ts
+```