@guiie/buda-mcp 1.4.2 → 1.5.1

package/.cursor/rules/marketplace-docs-sync.mdc

@@ -0,0 +1,32 @@
+---
+description: Keep marketplace documentation in sync with tool changes
+globs: src/tools/**/*.ts
+alwaysApply: false
+---
+
+# Marketplace Documentation Sync
+
+Any change to `src/tools/` that adds, removes, or modifies a tool **must** be accompanied by matching updates to all three marketplace files.
+
+## Files to keep in sync
+
+| File | What to update |
+|------|----------------|
+| `marketplace/claude-listing.md` | Add/remove/update `### \`tool_name\`` section in the correct group (Public or Authenticated) |
+| `marketplace/gemini-tools.json` | Add/remove/update entry in `functionDeclarations[]` with Gemini types (`STRING`, `INTEGER`, `NUMBER`, `OBJECT`) |
+| `marketplace/openapi.yaml` | Add/remove/update path + response schema — **public tools only** (auth tools are excluded intentionally) |
+
+## When each file needs updating
+
+- **New tool added** → add to all applicable files above
+- **Tool removed** → remove from all files
+- **Parameter added/changed/removed** → update description and `required` array in all files
+- **Tool description changed** → update all files
+- **Auth status changed** (public ↔ auth) → move between sections in `claude-listing.md`, update `gemini-tools.json`, add/remove from `openapi.yaml`
+
+## Quick checklist before committing
+
+- [ ] `claude-listing.md` reflects all 46+ tools (run `grep "^### \`" marketplace/claude-listing.md | wc -l` to count)
+- [ ] `gemini-tools.json` `functionDeclarations` count matches
+- [ ] `openapi.yaml` paths count matches public tool count
+- [ ] `CHANGELOG.md` has an entry describing the change

package/CHANGELOG.md

@@ -7,6 +7,85 @@ This project uses [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [Unreleased]
+
+---
+
+## [1.5.1] – 2026-04-11
+
+### Security
+
+- **HTTP startup guard for missing `MCP_AUTH_TOKEN`** — when `BUDA_API_KEY`/`BUDA_API_SECRET` are present but `MCP_AUTH_TOKEN` is not set, the HTTP server now exits with a `FATAL` error at startup instead of silently leaving the `/mcp` endpoint publicly accessible. This closes the opt-in footgun where operators could deploy credentials without a protecting token.
+
+- **Rate limiting on `/mcp`** — `express-rate-limit` middleware (120 req/min per IP by default) is applied to `POST /mcp` and `GET /mcp` before auth, preventing looping agents from saturating the Buda API. Configurable via the `MCP_RATE_LIMIT` environment variable.
+
+- **Crypto address format validation in `create_withdrawal`** — the `address` field is now validated against per-currency regex rules for BTC, ETH, USDC, USDT, LTC, BCH, and XRP before any API call. Unknown currencies pass through to the exchange. Returns `INVALID_ADDRESS` on failure. Tool description now explicitly warns that crypto withdrawals are irreversible.
+
+- **BOLT-11 invoice format validation in `lightning_withdrawal`** — the `invoice` field is now checked against a prefix regex (`/^ln(bc|tb|bcrt)\d/i`) before the API call, rejecting non-invoice strings (e.g. a Bitcoin address pasted by mistake). Zod minimum length tightened from 1 to 50 characters.
+
+- **Dead man's switch blocked on HTTP transport** — `schedule_cancel_all` now returns `TRANSPORT_NOT_SUPPORTED` when called via the HTTP server, where a process restart (deploy, crash, autoscale) silently drops all in-memory timers. `renew_cancel_timer` and `disarm_cancel_timer` remain callable. The `register()` function accepts a new `transport: "stdio" | "http"` parameter (default `"stdio"`).
+
+### Added
+
+- **Batch orders optional notional cap** — `place_batch_orders` now accepts an optional `max_notional` parameter. If the sum of `amount × limit_price` across all limit orders exceeds the cap, the entire batch is rejected before any API call with `NOTIONAL_CAP_EXCEEDED`. Market orders contribute 0 (execution price unknown).
+
+### Fixed
+
+- **Security: path traversal in MCP resource handlers** — `buda://ticker/{market}` and `buda://summary/{market}` resource handlers now call `validateMarketId` before interpolating the parameter into the API URL, preventing path traversal to unintended Buda API endpoints.
+- **Security: bearer token auth for HTTP server** — `src/http.ts` now supports an optional `MCP_AUTH_TOKEN` environment variable. When set, all requests to `/mcp` must include `Authorization: Bearer <token>`. Health check and server-card endpoints remain public.
+- **Bug: NaN propagation in `flattenAmount`** — now throws an explicit error on invalid amount strings instead of silently returning `NaN`.
+- **Bug: nonce collision on concurrent HTTP requests** — `BudaClient` now uses a per-instance counter to guarantee unique nonces even when multiple requests land within the same millisecond.
+- **Bug: `version.ts` crash on missing `package.json`** — `readFileSync` is now wrapped in `try/catch` with fallback `"unknown"` to prevent process crash in deployments without `package.json`.
+- **Bug: incorrect PUT payload in `cancel_order` and `dead_mans_switch`** — body is now `{ order: { state: "canceling" } }` per Buda API Rails convention, matching `cancel_order_by_client_id` and `remittances`.
+- **Bug: `ttl_seconds` bounds not enforced in `handleScheduleCancelAll`** — added explicit validation (10–300, integer) in the handler itself, independent of Zod schema; a negative TTL would previously have fired the timer immediately.
+- **Bug: `gtd_timestamp` not validated in `place_order`** — now checks that the value is a valid ISO 8601 datetime and is in the future before sending it to the API.
+- **Bug: `sma_50` returned incorrect partial average** — `get_technical_indicators` now returns `null` for `sma_50` (with an `sma_50_warning` field) when fewer than 50 candles are available, instead of silently computing an average over fewer points.
+- **Security: `quote_remittance` now requires `confirmation_token="CONFIRM"`** — this tool is non-idempotent (each call creates a new remittance record); the confirmation guard prevents accidental or repeated invocations.
+- **Security: `create_receive_address` now requires `confirmation_token="CONFIRM"`** — this tool is non-idempotent (each call generates a new blockchain address); the confirmation guard prevents accidental repeated calls.
+- **Marketplace docs updated** — `gemini-tools.json`, `claude-listing.md`, `openapi.yaml`, and `README.md` updated to reflect all changes.
+- **Marketplace documentation gap** — `claude-listing.md`, `gemini-tools.json`, and `openapi.yaml` were missing 18 tools that were already implemented and registered in the server. All three files now reflect the full set of 46 tools.
+
+---
+
+## [1.5.0] – 2026-04-11
+
+### Added
+
+- **`cancel_all_orders`** (`src/tools/cancel_all_orders.ts`) — auth-gated tool to cancel all open orders in a specific market or across all markets (`market_id="*"`). Confirmation guard fires before market validation or API call. Uses new `DELETE /orders` endpoint via `client.delete<T>()`. Exports `handleCancelAllOrders` for unit testing.
+
+- **`cancel_order_by_client_id`** (`src/tools/cancel_order_by_client_id.ts`) — auth-gated tool to cancel an open order by its client-assigned string ID (`PUT /orders/by-client-id/{client_id}`). Confirmation guard first; returns the same flat order shape as `get_order`. Exports `handleCancelOrderByClientId` for unit testing.
+
+- **`place_batch_orders`** (`src/tools/batch_orders.ts`) — auth-gated tool to place up to 20 orders sequentially. Pre-validates **all** orders (market ID format + `limit_price` presence) before any API call — a single validation failure aborts with zero orders placed. API failures mid-batch do not roll back placed orders; a `warning` field surfaces this. Returns `{ results, total, succeeded, failed, warning? }`. Exports `handlePlaceBatchOrders` for unit testing.
+
+- **`place_order` extended (optional TIF + stop fields)** — backward-compatible additions:
+  - **Time-in-force flags**: `ioc` (immediate-or-cancel), `fok` (fill-or-kill), `post_only`, `gtd_timestamp` (ISO 8601 expiry). Mutually exclusive — specifying more than one returns `VALIDATION_ERROR`.
+  - **Stop orders**: `stop_price` + `stop_type` (`">="` or `"<="`) — both must be present together or both absent, otherwise `VALIDATION_ERROR`.
+  - All validation happens after the confirmation guard but before the API call.
+
+- **`create_withdrawal`** (added to `src/tools/withdrawals.ts`) — auth-gated `POST /currencies/{currency}/withdrawals`. Supports crypto (via `address` + optional `network`) and fiat (via `bank_account_id`). Exactly one destination must be provided; both or neither → `VALIDATION_ERROR`. Confirmation guard preview includes `{ currency, amount, destination }`. Returns flat `Withdrawal` shape. Exports `handleCreateWithdrawal` and `createWithdrawalToolSchema`.
+
+- **`create_fiat_deposit`** (added to `src/tools/deposits.ts`) — auth-gated `POST /currencies/{currency}/deposits`. Guard is critical — calling twice creates duplicate records. Validates currency before API call. Returns flat `Deposit` shape. Exports `handleCreateFiatDeposit` and `createFiatDepositToolSchema`.
+
+- **`lightning_withdrawal`** + **`create_lightning_invoice`** (`src/tools/lightning.ts`) — two auth-gated Lightning Network tools:
+  - `lightning_withdrawal` — pays a BOLT-11 invoice from the LN-BTC reserve (`POST /reserves/ln-btc/withdrawals`). Confirmation guard truncates the invoice in the preview (`invoice_preview: first 20 chars + "..."`). Returns `{ id, state, amount, amount_currency, fee, fee_currency, payment_hash, created_at }`.
+  - `create_lightning_invoice` — creates a receive invoice (`POST /lightning_network_invoices`). No confirmation required. Inputs: `amount_satoshis`, optional `description` (max 140 chars), optional `expiry_seconds` (60–86400). Returns `{ id, payment_request, amount_satoshis, description, expires_at, state, created_at }`.
+
+- **`delete<T>()` on `BudaClient`** (`src/client.ts`) — follows the same HMAC auth headers + 429 retry pattern as `put<T>()`. Supports optional query params.
+
+- **New types** in `src/types.ts`: `CancelAllOrdersResponse`, `LightningWithdrawal`, `LightningWithdrawalResponse`, `LightningInvoice`, `LightningInvoiceResponse`.
+
+- **Unit tests (32 new, 138 total)** in `test/unit.ts`:
+  - `cancel_all_orders` (5 tests): no confirmation; `*` + CONFIRM; specific market + CONFIRM; invalid market with CONFIRM; 404 passthrough.
+  - `cancel_order_by_client_id` (3 tests): no confirmation; happy path with flat order; 404 passthrough.
+  - `place_batch_orders` (5 tests): no confirmation; all valid; invalid market pre-validation; missing limit_price pre-validation; mid-batch API error partial success.
+  - `place_order extended` (4 tests): existing limit order unchanged; IOC → `limit.type='ioc'`; stop_price without stop_type; mutually exclusive TIF flags.
+  - `create_withdrawal` (6 tests): no confirmation; both address+bank_account_id; neither; crypto path; fiat path; 422 passthrough.
+  - `create_fiat_deposit` (4 tests): no confirmation; invalid currency; happy path; 422 passthrough.
+  - `lightning_withdrawal` (3 tests): no confirmation with preview; happy path; 422 passthrough.
+  - `create_lightning_invoice` (2 tests): happy path; 422 passthrough.
+
+---
+
 ## [1.4.2] – 2026-04-11
 
 ### Added

package/PUBLISH_CHECKLIST.md

@@ -1,8 +1,6 @@
-# Publish Checklist — buda-mcp v1.4.0
+# Publish Checklist — buda-mcp v1.5.1
 
-Steps to publish `v1.4.0` to npm, the MCP registry, and notify community directories.
-
-> **Important for v1.4.0:** The new `schedule_cancel_all` tool uses in-memory timer state that is lost on server restart. This is prominently documented in the tool description, README auth section, and CHANGELOG. Do NOT encourage users to rely on this tool in hosted/Railway deployments.
+Steps to publish `v1.5.1` to npm, the MCP registry, and notify community directories.
 
 ---
 
@@ -10,13 +8,13 @@ Steps to publish `v1.4.0` to npm, the MCP registry, and notify community directo
 
 ```bash
 # Confirm version
-node -e "console.log(require('./package.json').version)"  # should print 1.4.0
+node -e "console.log(require('./package.json').version)"  # should print 1.5.1
 
 # Build and test
 npm run build
 npm test
 
-# Sync server.json version (already done, but run again to confirm)
+# Sync server.json version (already done, but confirm)
 npm run sync-version
 
 # Verify no credentials are logged (audit)
@@ -39,58 +37,9 @@ Verify: https://www.npmjs.com/package/@guiie/buda-mcp
 
 ## 3. GitHub release
 
-```bash
-git add -A
-git commit -m "chore: release v1.4.0
-
-- simulate_order: live order cost simulation (no order placed, simulation: true)
-- calculate_position_size: Kelly-style sizing from capital/risk/entry/stop (client-side)
-- get_market_sentiment: composite score -100..+100 from price/volume/spread
-- get_technical_indicators: RSI/MACD/BB/SMA20/SMA50 from trade history (no libs)
-- schedule_cancel_all + renew_cancel_timer + disarm_cancel_timer: in-memory dead man's switch (auth-gated)
-- aggregateTradesToCandles() extracted to utils.ts (shared by price_history + technical_indicators)
-- OhlcvCandle interface moved to types.ts
-- 59 unit tests (24 new)"
-
-git tag v1.4.0
-git push origin main --tags
-```
-
-Then create a GitHub Release from the tag:
-
----
-
-**Release notes template (GitHub):**
-
-```
-## buda-mcp v1.4.0 — Trading Tools
-
-### 5 new tools
+Tag and release already created via `gh release create v1.5.1`. Verify at:
 
-**`simulate_order`** (public)
-Simulates a buy or sell order using live ticker data — no order placed. Returns estimated fill price, fee (actual taker rate from market data: 0.8% crypto / 0.5% stablecoin), total cost, and slippage vs mid. All outputs include simulation: true.
-
-**`calculate_position_size`** (public)
-Kelly-style position sizing from capital, risk %, entry, and stop-loss. Fully client-side. Returns units, capital_at_risk, position_value, fee_impact, and a plain-text risk note.
-
-**`get_market_sentiment`** (public)
-Composite sentiment score (−100 to +100) from price variation 24h (40%), volume vs 7d average (35%), and spread vs market-type baseline (25%). Returns score, label, component breakdown, and disclaimer.
-
-**`get_technical_indicators`** (public)
-RSI (14), MACD (12/26/9), Bollinger Bands (20, 2σ), SMA 20, SMA 50 — computed server-side from Buda trade history with no external libraries. Returns signal interpretations and structured warning if insufficient candles.
-
-**`schedule_cancel_all` + `renew_cancel_timer` + `disarm_cancel_timer`** (auth-gated)
-In-memory dead man's switch: arms a timer that cancels all open orders if not renewed. WARNING: timer state is lost on server restart. Use only on locally-run instances.
-
-### Infrastructure
-- `aggregateTradesToCandles()` extracted to `utils.ts` — shared by `get_price_history` and `get_technical_indicators`
-- `OhlcvCandle` interface exported from `types.ts`
-- 59 unit tests (was 35)
-
-```bash
-npx @guiie/buda-mcp
-```
-```
+https://github.com/gtorreal/buda-mcp/releases/tag/v1.5.1
 
 ---
 
@@ -115,19 +64,20 @@ Verify: https://smithery.ai/server/@guiie/buda-mcp
 **Email/message template:**
 
 ```
-Subject: [Update] buda-mcp v1.4.0 — simulate_order, technical indicators, sentiment, position sizing, dead man's switch
+Subject: [Update] buda-mcp v1.5.1 — Security hardening release
 
 Hi mcp.so team,
 
-I've released v1.4.0 of buda-mcp (@guiie/buda-mcp on npm).
+I've released v1.5.1 of buda-mcp (@guiie/buda-mcp on npm).
 
-Key changes (5 new tools + 3 sub-tools):
-- simulate_order: live order cost simulation with actual fee rates (no order placed)
-- calculate_position_size: Kelly-style position sizing (fully client-side)
-- get_market_sentiment: composite score -100..+100 from price/volume/spread microstructure
-- get_technical_indicators: RSI/MACD/Bollinger Bands/SMA (no external libs, from trade history)
-- schedule_cancel_all / renew_cancel_timer / disarm_cancel_timer: in-memory dead man's switch (auth-gated)
-- 59 unit tests (was 35)
+Key changes (security hardening, no new tools):
+- HTTP startup guard: server exits if credentials are set without MCP_AUTH_TOKEN
+- Rate limiting: 120 req/min per IP on /mcp (configurable via MCP_RATE_LIMIT)
+- Crypto address validation in create_withdrawal (BTC, ETH, USDC, USDT, LTC, BCH, XRP)
+- BOLT-11 invoice format validation in lightning_withdrawal
+- Dead man's switch blocked on HTTP transport (process restarts drop timers)
+- place_batch_orders: optional max_notional spending cap
+- 156 unit tests (was 136)
 
 Links:
 - npm: https://www.npmjs.com/package/@guiie/buda-mcp
@@ -146,23 +96,24 @@ Thank you!
 **Message template:**
 
 ```
-Subject: [Update] buda-mcp v1.4.0
+Subject: [Update] buda-mcp v1.5.1
 
 Hi Glama team,
 
-buda-mcp has been updated to v1.4.0.
+buda-mcp has been updated to v1.5.1.
 
 Package: @guiie/buda-mcp (npm)
 Registry: io.github.gtorreal/buda-mcp (MCP Registry)
-Version: 1.4.0
+Version: 1.5.1
 
-Changes (5 new tools + 3 sub-tools):
-- simulate_order: order simulation with live data, simulation: true always set
-- calculate_position_size: client-side position sizing
-- get_market_sentiment: composite sentiment score with disclaimers
-- get_technical_indicators: RSI/MACD/BB/SMA from trade history
-- schedule_cancel_all + renew/disarm: in-memory dead man's switch (auth-gated, local use only)
-- 59 unit tests
+Changes (security hardening):
+- HTTP startup guard for missing MCP_AUTH_TOKEN
+- Rate limiting on /mcp (120 req/min per IP)
+- Crypto address format validation in create_withdrawal
+- BOLT-11 invoice validation in lightning_withdrawal
+- Dead man's switch blocked on HTTP transport
+- place_batch_orders: optional max_notional cap
+- 156 unit tests
 
 Quick start:
   npx @guiie/buda-mcp
@@ -177,21 +128,22 @@ Thank you!
 
 ## 8. Post-publish verification
 
-- [ ] `npx @guiie/buda-mcp@1.4.0` starts successfully
-- [ ] `npm info @guiie/buda-mcp version` returns `1.4.0`
-- [ ] GitHub release tag `v1.4.0` is visible
-- [ ] MCP Registry entry reflects v1.4.0
-- [ ] Smithery server card lists 14 public tools (including 4 new: simulate_order, calculate_position_size, get_market_sentiment, get_technical_indicators)
-- [ ] Smithery server card lists 7 auth tools (including schedule_cancel_all, renew_cancel_timer, disarm_cancel_timer)
-- [ ] `GET /health` returns `"version":"1.4.0"` on Railway deployment
-- [ ] simulate_order response includes `simulation: true`
-- [ ] get_technical_indicators returns `warning: "insufficient_data"` for markets with few trades
-- [ ] schedule_cancel_all requires `confirmation_token="CONFIRM"` (test with wrong token)
+- [ ] `npx @guiie/buda-mcp@1.5.1` starts successfully
+- [ ] `npm info @guiie/buda-mcp version` returns `1.5.1`
+- [ ] GitHub release tag `v1.5.1` is visible
+- [ ] MCP Registry entry reflects v1.5.1
+- [ ] Smithery server card lists all tools
+- [ ] `GET /health` returns `"version":"1.5.1"` on Railway deployment
+- [ ] HTTP server exits if `BUDA_API_KEY` set but `MCP_AUTH_TOKEN` is absent
+- [ ] `create_withdrawal` rejects a truncated BTC address with `INVALID_ADDRESS`
+- [ ] `lightning_withdrawal` rejects a non-BOLT11 string with `INVALID_INVOICE`
+- [ ] `place_batch_orders` with `max_notional` rejects over-cap batch before API call
+- [ ] `schedule_cancel_all` via HTTP returns `TRANSPORT_NOT_SUPPORTED`
 - [ ] mcp.so listing updated
 - [ ] Glama.ai listing updated
 
 ---
 
-## ARCHIVED: v1.3.0 checklist
+## ARCHIVED: previous checklists
 
-See git tag `v1.3.0` for the v1.3.0 release notes and verification steps.
+See git tags `v1.5.0`, `v1.4.0`, `v1.4.1`, `v1.4.2` for previous release notes and verification steps.