@guiie/buda-mcp 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ This project uses [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.2.0] – 2026-04-11
+
+### Added
+
+- **`src/validation.ts`** — new `validateMarketId` helper that enforces `/^[A-Z0-9]{2,10}-[A-Z0-9]{2,10}$/i` on all market ID inputs before URL interpolation. Returns a structured `isError: true` response with a helpful message on failure. Applied to all tools that accept `market_id`.
+- **`.env.example`** — documents `BUDA_API_KEY` and `BUDA_API_SECRET` with comments and a link to the Buda token management page. Referenced in the README auth section.
+- **`scripts/sync-version.mjs`** — reads `package.json` version and writes it to `server.json`. Run via `npm run sync-version` to keep the MCP registry manifest in sync after a version bump.
+- **`test/unit.ts`** — 23 unit tests (no live API required):
+  - **HMAC signing** (3 tests): exact output verified for GET (no body) and POST (with base64 body); determinism check.
+  - **Cache deduplication** (3 tests): concurrent `getOrFetch` calls share the same in-flight promise; expiry triggers a new fetch; rejected fetcher clears the entry so the next call retries.
+  - **confirmation_token guard** (4 tests): `place_order` and `cancel_order` return `isError: true` without `"CONFIRM"`.
+  - **Input sanitization** (9 tests): malformed market IDs (path traversal, no hyphen, empty, oversized segments, special characters) all return a validation error; valid IDs (uppercase, lowercase, USDC) pass.
+  - **429 retry** (4 tests): mock 429→200 asserts fetch is called exactly twice and the 200 data is returned; double-429 asserts `BudaApiError` with `retryAfterMs`; `Retry-After: 2` header parsed as 2000 ms (RFC 7231 seconds); absent header defaults to 1000 ms.
+- **`npm run test:unit`** and **`npm run test:integration`** scripts for running test subsets independently.
+
+### Changed
+
+- **Single version source-of-truth** — all version references now derive from `package.json` at startup:
+  - `src/version.ts` (new shared module): reads `package.json` via `readFileSync` + `fileURLToPath`.
+  - `src/client.ts`, `src/index.ts`, `src/http.ts` import `VERSION` from `src/version.ts`.
+  - `server.json` is kept in sync via `npm run sync-version`.
+- **`http.ts` server-card generated programmatically** — the `/.well-known/mcp/server-card.json` endpoint now assembles tool schemas from each tool module's exported `toolSchema` constant instead of a 100-line hardcoded JSON block. Adding a tool only requires exporting its `toolSchema`.
+- **All tool files** export a `toolSchema` constant `{ name, description, inputSchema }` used by both `register()` and the server-card endpoint, ensuring descriptions are always in sync.
+- **`place_order.ts` and `cancel_order.ts`** expose their handler logic via exported `handlePlaceOrder` / `handleCancelOrder` functions, used by the register wrapper and directly testable in unit tests.
+- **`get_price_history`** improvements:
+  - Shallow-window limitation moved to the **front** of the description (was buried in a `note` field).
+  - UTC bucket boundary format documented explicitly in tool description and `note` field.
+  - `limit` max raised from `100` to `1000`; description updated accordingly.
+- **429 retry with Retry-After** — `BudaClient.get`, `.post`, and `.put` now retry once on a 429 response. The `Retry-After` header is parsed as integer seconds (per RFC 7231; Buda's docs describe 429 but do not document the header — the standard interpretation applies). Defaults to 1 second if the header is absent. A double-429 throws `BudaApiError` with `retryAfterMs` set.
+- **`test/run-all.ts`** — integration tests now perform a 3-second connectivity pre-check at startup and skip gracefully (exit 0 with a message) when the Buda API is unreachable, preventing CI failures on networks without internet access.
+- **`package.json`** version bumped to `1.2.0`.
+- **`marketplace/`** and **`PUBLISH_CHECKLIST.md`** updated to reflect v1.2.0 changes.
+
+---
+
 ## [1.1.2] – 2026-04-10
 
 ### Fixed

package/PUBLISH.md

@@ -1,4 +1,4 @@
-# Publishing checklist
+# Publishing checklist — v1.2.0
 
 Everything that could be automated is already done.
 This file contains only what requires your manual action, in order.
@@ -63,7 +63,7 @@ mcp-publisher login github
 mcp-publisher publish
 ```
 
-You'll see: `✓ Successfully published — io.github.gtorreal/buda-mcp version 1.0.0`
+You'll see: `✓ Successfully published — io.github.gtorreal/buda-mcp version 1.2.0`
 
 ### 2b. Put your MCP Registry token into GitHub Actions (for auto-publish on release)
 
@@ -177,9 +177,9 @@ For the Gemini Extensions marketplace (currently invite-only):
 Once npm token and MCP registry token are set in GitHub Actions secrets (Steps 1c and 2b):
 
 ```bash
-gh release create v1.0.0 \
-  --title "v1.0.0 — Initial release" \
-  --notes "5 public market data tools for Buda.com: get_markets, get_ticker, get_orderbook, get_trades, get_market_volume." \
+gh release create v1.2.0 \
+  --title "v1.2.0 — Input validation, 429 retry, unit tests" \
+  --notes "Input sanitization, 429 Retry-After support, get_price_history limit raised to 1000, 23 unit tests, single version source-of-truth." \
   --latest
 ```
 

package/PUBLISH_CHECKLIST.md

@@ -1,6 +1,6 @@
-# Publish Checklist — buda-mcp v1.1.0
+# Publish Checklist — buda-mcp v1.2.0
 
-Steps to publish `v1.1.0` to npm, the MCP registry, and notify community directories.
+Steps to publish `v1.2.0` to npm, the MCP registry, and notify community directories.
 
 ---
 
@@ -8,12 +8,15 @@ Steps to publish `v1.1.0` to npm, the MCP registry, and notify community directo
 
 ```bash
 # Confirm version
-node -e "console.log(require('./package.json').version)"  # should print 1.1.0
+node -e "console.log(require('./package.json').version)"  # should print 1.2.0
 
 # Build and test
 npm run build
 npm test
 
+# Sync server.json version (already done, but run again to confirm)
+npm run sync-version
+
 # Verify no credentials are logged (audit)
 grep -r "apiKey\|apiSecret\|BUDA_API" dist/ --include="*.js" | grep -v "process.env\|hasAuth\|X-SBTC-APIKEY\|authHeaders\|constructor"
 # Should return empty or only header name strings — never credential values
@@ -36,17 +39,18 @@ Verify: https://www.npmjs.com/package/@guiie/buda-mcp
 
 ```bash
 git add -A
-git commit -m "chore: release v1.1.0
-
-- 3 new public tools: get_spread, compare_markets, get_price_history
-- HMAC-SHA384 auth scaffold (BUDA_API_KEY / BUDA_API_SECRET)
-- 4 auth-gated tools: get_balances, get_orders, place_order, cancel_order
-- TTL caching (markets 60s, tickers 5s, orderbooks 3s)
-- MCP Resources: buda://markets, buda://ticker/{market}
-- Structured error responses for all tools
-- Updated README, marketplace files, CHANGELOG"
-
-git tag v1.1.0
+git commit -m "chore: release v1.2.0
+
+- Single version source-of-truth via src/version.ts (no more hardcoded strings)
+- Programmatic server-card in http.ts (toolSchema exported per tool)
+- .env.example with documented BUDA_API_KEY / BUDA_API_SECRET
+- Input sanitization: validateMarketId regex on all market_id inputs
+- 429 retry with Retry-After (seconds, per RFC 7231), default 1s
+- get_price_history: limit raised to 1000, UTC bucketing documented
+- 23 unit tests: HMAC signing, cache dedup, confirmation guard, sanitization, 429 retry
+- Integration tests: graceful skip when Buda API is unreachable"
+
+git tag v1.2.0
 git push origin main --tags
 ```
 
@@ -57,25 +61,27 @@ Then create a GitHub Release from the tag with the following release notes:
 **Release notes template (GitHub):**
 
 ```
-## buda-mcp v1.1.0
+## buda-mcp v1.2.0
 
 ### What's new
 
-**3 new public tools**
-- `get_spread` — bid/ask spread (absolute and %) for any market
-- `compare_markets` — side-by-side ticker data for a base currency across all quote currencies
-- `get_price_history` — OHLCV candles derived from recent trades (1h / 4h / 1d)
+**Bug fixes & maintenance**
+- Single version source-of-truth: all version strings now read from `package.json` at startup via `src/version.ts` — no more drift between files
+- `http.ts` server-card assembled programmatically from exported `toolSchema` constants — adding a tool no longer requires touching `http.ts`
+
+**Security / reliability**
+- Input sanitization: all `market_id` inputs validated against `/^[A-Z0-9]{2,10}-[A-Z0-9]{2,10}$/i` before URL interpolation — rejects path traversal and malformed IDs with structured errors
+- 429 retry: `BudaClient` retries once on rate-limit responses, honoring the `Retry-After` header (seconds, per RFC 7231; defaults to 1s if absent). Double-429 throws `BudaApiError` with `retryAfterMs`.
 
-**HMAC auth scaffold**
-- Set `BUDA_API_KEY` + `BUDA_API_SECRET` to unlock 4 authenticated tools
-- `get_balances`, `get_orders`, `place_order`, `cancel_order`
-- Public-only mode unchanged when no credentials are set
+**DX improvements**
+- `.env.example` added for easy credential setup
+- `get_price_history` limit raised from 100 to 1000 trades; UTC bucketing documented prominently
+- `npm run sync-version` syncs `server.json` from `package.json` automatically
 
-**Platform improvements**
-- TTL caching: markets (60s), tickers (5s), order books (3s)
-- MCP Resources: `buda://markets` and `buda://ticker/{market}`
-- Structured `isError: true` responses for all tools
-- Updated README with npx quickstart and per-tool examples
+**Test suite**
+- 23 new unit tests (no live API needed): HMAC signing exactness, cache deduplication, confirmation_token guards, input sanitization, 429 retry behavior
+- Integration tests skip gracefully when Buda API is unreachable (CI-friendly)
+- New scripts: `npm run test:unit`, `npm run test:integration`
 
 ```bash
 npx @guiie/buda-mcp
@@ -86,16 +92,13 @@ npx @guiie/buda-mcp
 
 ## 4. MCP Registry update
 
-The GitHub Actions workflow (`.github/workflows/publish.yml`) runs automatically on GitHub release. It runs `mcp publish` via `mcp-publisher`. Verify the registry entry at:
+The GitHub Actions workflow (`.github/workflows/publish.yml`) runs automatically on GitHub release. Verify at:
 
 https://registry.modelcontextprotocol.io/servers/io.github.gtorreal/buda-mcp
 
 If the workflow doesn't trigger, run manually:
 
 ```bash
-# Download mcp-publisher from GitHub releases (check for latest version)
-curl -L https://github.com/modelcontextprotocol/mcp-publisher/releases/latest/download/mcp-publisher-macos -o mcp-publisher
-chmod +x mcp-publisher
 MCP_REGISTRY_TOKEN=<token> ./mcp-publisher publish
 ```
 
@@ -111,23 +114,22 @@ Verify: https://smithery.ai/server/@guiie/buda-mcp
 
 ## 6. Notify mcp.so
 
-**Method:** Submit via the mcp.so listing update form or open a PR to their repository.
-
 **Email/message template:**
 
 ```
-Subject: [Update] buda-mcp v1.1.0 — new tools + auth
+Subject: [Update] buda-mcp v1.2.0 — input sanitization, 429 retry, 23 unit tests
 
 Hi mcp.so team,
 
-I've released v1.1.0 of buda-mcp (@guiie/buda-mcp on npm).
+I've released v1.2.0 of buda-mcp (@guiie/buda-mcp on npm).
 
 Key changes:
-- 3 new public tools: get_spread, compare_markets, get_price_history (OHLCV)
-- Optional HMAC auth scaffold (BUDA_API_KEY / BUDA_API_SECRET) unlocks 4 private tools: get_balances, get_orders, place_order, cancel_order
-- TTL caching for all repeated data fetches
-- MCP Resources: buda://markets and buda://ticker/{market}
-- Structured error responses
+- Input sanitization: all market IDs validated against a strict regex before URL use
+- 429 rate-limit retry: honors Retry-After header (seconds, RFC 7231), defaults to 1s
+- get_price_history: limit raised to 1000 trades for deeper history
+- 23 unit tests added (no live API required): HMAC, cache dedup, confirmation guards, sanitization, retry
+- Single version source-of-truth (package.json → all files via src/version.ts)
+- .env.example added for easy credential setup
 
 Links:
 - npm: https://www.npmjs.com/package/@guiie/buda-mcp
@@ -143,31 +145,25 @@ Thank you!
 
 ## 7. Notify Glama.ai
 
-**Method:** Use Glama's submission form at https://glama.ai/mcp/servers or open an issue/PR on their directory repository.
-
 **Message template:**
 
 ```
-Subject: [Update] buda-mcp v1.1.0
+Subject: [Update] buda-mcp v1.2.0
 
 Hi Glama team,
 
-buda-mcp has been updated to v1.1.0. Here's a summary of what's new:
+buda-mcp has been updated to v1.2.0.
 
 Package: @guiie/buda-mcp (npm)
 Registry: io.github.gtorreal/buda-mcp (MCP Registry)
-Version: 1.1.0
-
-New tools added:
-- get_spread: bid/ask spread for any market
-- compare_markets: cross-currency price comparison for a base asset
-- get_price_history: OHLCV candles from trade history (1h/4h/1d)
-- get_balances, get_orders, place_order, cancel_order (authenticated, local-only)
+Version: 1.2.0
 
-New capabilities:
-- MCP Resources protocol: buda://markets, buda://ticker/{market}
-- TTL caching (60s/5s/3s by data type)
-- Structured error responses (isError: true)
+Changes:
+- Input validation on all market_id inputs (structured isError: true on failure)
+- 429 retry with Retry-After support (RFC 7231 seconds; default 1s)
+- get_price_history limit raised to 1000 trades; UTC bucket timestamps documented
+- 23 unit tests: HMAC signing, cache deduplication, confirmation guards, sanitization, retry
+- Single version source (package.json); .env.example added
 
 Quick start:
   npx @guiie/buda-mcp
@@ -182,11 +178,12 @@ Thank you!
 
 ## 8. Post-publish verification
 
-- [ ] `npx @guiie/buda-mcp@1.1.0` starts successfully
-- [ ] `npm info @guiie/buda-mcp version` returns `1.1.0`
-- [ ] GitHub release tag `v1.1.0` is visible
-- [ ] MCP Registry entry reflects v1.1.0
-- [ ] Smithery server card lists 8 public tools
+- [ ] `npx @guiie/buda-mcp@1.2.0` starts successfully
+- [ ] `npm info @guiie/buda-mcp version` returns `1.2.0`
+- [ ] GitHub release tag `v1.2.0` is visible
+- [ ] MCP Registry entry reflects v1.2.0
+- [ ] Smithery server card lists 8 public tools (with updated get_price_history description)
+- [ ] `GET /health` returns `"version":"1.2.0"` on Railway deployment
+- [ ] `GET /.well-known/mcp/server-card.json` returns tools with updated schemas (no hardcoded JSON)
 - [ ] mcp.so listing updated
 - [ ] Glama.ai listing updated
-- [ ] Railway deployment health check returns `"version":"1.1.0"` at `/health`

package/README.md

@@ -161,13 +161,13 @@ Side-by-side ticker data for all pairs of a given base currency (CLP, COP, PEN,
 ---
 
 #### `get_price_history`
-OHLCV candles derived from recent trade history (no native candlestick endpoint exists on Buda — candles are aggregated client-side from up to 100 raw trades).
+OHLCV candles derived from recent trade history (Buda has no native candlestick endpoint — candles are aggregated client-side from raw trades). Candle timestamps are UTC bucket boundaries. Increasing `limit` gives deeper history at the cost of a slower response.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `market_id` | string | Yes | Market ID. |
 | `period` | `1h` \| `4h` \| `1d` | No | Candle period (default `1h`). |
-| `limit` | number | No | Raw trades to fetch before aggregation (default 100, max 100). |
+| `limit` | number | No | Raw trades to fetch before aggregation (default 100, max 1000). |
 
 **Example prompts:**
 - *"Show me hourly price candles for BTC-CLP"*
@@ -252,7 +252,7 @@ In addition to tools, the server exposes two MCP Resources that clients can read
 
 The server defaults to **public-only mode** — no API key needed, no breaking changes for existing users.
 
-To enable authenticated tools, set environment variables before running:
+To enable authenticated tools, copy `.env.example` to `.env` and fill in your credentials, then set them as environment variables before running:
 
 ```bash
 BUDA_API_KEY=your_api_key BUDA_API_SECRET=your_api_secret npx @guiie/buda-mcp

package/marketplace/README.md

@@ -1,4 +1,4 @@
-# Marketplace Submission Assets
+# Marketplace Submission Assets — v1.2.0
 
 Ready-to-use assets for submitting buda-mcp to every major AI marketplace.
 Replace `gtorreal` / `gtorreal` with your actual handles before submitting.

package/marketplace/claude-listing.md

@@ -50,8 +50,8 @@ Side-by-side ticker data for all trading pairs of a given base currency across a
 **Parameters:** `base_currency` *(required)* — e.g. `BTC`, `ETH`, `XRP`.
 
 ### `get_price_history`
-OHLCV (open/high/low/close/volume) candles derived from recent trade history. Supports `1h`, `4h`, and `1d` periods.  
-**Parameters:** `market_id` *(required)*, `period` *(optional: `1h`/`4h`/`1d`, default `1h`)*, `limit` *(optional, max 100 trades)*.
+OHLCV (open/high/low/close/volume) candles derived from recent trade history (Buda has no native candlestick endpoint). Supports `1h`, `4h`, and `1d` periods. Candle timestamps are UTC bucket boundaries.  
+**Parameters:** `market_id` *(required)*, `period` *(optional: `1h`/`4h`/`1d`, default `1h`)*, `limit` *(optional, default 100, max 1000 trades — more = deeper history)*.
 
 ### Authenticated tools (require `BUDA_API_KEY` + `BUDA_API_SECRET`)
 

package/marketplace/gemini-tools.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Gemini function declarations for buda-mcp v1.1.0. Pass this array as the `tools[0].functionDeclarations` field when calling the Gemini API. See: https://ai.google.dev/gemini-api/docs/function-calling",
+  "_comment": "Gemini function declarations for buda-mcp v1.2.0. Pass this array as the `tools[0].functionDeclarations` field when calling the Gemini API. See: https://ai.google.dev/gemini-api/docs/function-calling",
   "functionDeclarations": [
     {
       "name": "get_markets",
@@ -113,7 +113,7 @@
     },
     {
       "name": "get_price_history",
-      "description": "Get OHLCV (open/high/low/close/volume) price history for a Buda.com market, derived from recent trade history. Candles are aggregated client-side from up to 100 raw trades. Supports 1h, 4h, and 1d candle periods.",
+      "description": "IMPORTANT: Candles are aggregated client-side from raw trades (Buda has no native candlestick endpoint) — increase 'limit' for deeper history. Returns OHLCV (open/high/low/close/volume) price history for a Buda.com market. Candle timestamps are UTC bucket boundaries. Supports 1h, 4h, and 1d candle periods.",
       "parameters": {
         "type": "OBJECT",
         "properties": {
@@ -127,7 +127,7 @@
           },
           "limit": {
             "type": "INTEGER",
-            "description": "Number of raw trades to fetch before aggregation. Default is 100, maximum is 100."
+            "description": "Number of raw trades to fetch before aggregation. Default is 100, maximum is 1000. More trades = deeper history."
           }
         },
         "required": ["market_id"]

package/marketplace/openapi.yaml

@@ -11,7 +11,7 @@ info:
     stdio server. Deploy locally with mcp-proxy:
       mcp-proxy --port 8000 -- npx -y @guiie/buda-mcp
     Or point `servers[0].url` at your hosted instance.
-  version: 1.1.0
+  version: 1.2.0
   contact:
     url: https://github.com/gtorreal/buda-mcp
 
@@ -231,9 +231,10 @@ paths:
       operationId: getPriceHistory
       summary: OHLCV price history derived from trade history
       description: |
-        Returns OHLCV (open/high/low/close/volume) candles derived from recent trade history.
-        Buda.com has no native candlestick endpoint; candles are aggregated client-side from
-        up to 100 raw trades. Supports 1h, 4h, and 1d candle periods.
+        IMPORTANT: Candles are aggregated client-side from raw trades (Buda has no native
+        candlestick endpoint) — increase 'limit' for deeper history but expect slower responses.
+        Returns OHLCV (open/high/low/close/volume) candles. Candle timestamps are UTC bucket
+        boundaries. Supports 1h, 4h, and 1d candle periods.
       parameters:
         - name: market_id
           in: query
@@ -253,11 +254,11 @@ paths:
         - name: limit
           in: query
           required: false
-          description: Number of raw trades to fetch before aggregation (default 100, max 100).
+          description: Number of raw trades to fetch before aggregation (default 100, max 1000). More trades = deeper history.
           schema:
             type: integer
             minimum: 1
-            maximum: 100
+            maximum: 1000
       responses:
         "200":
           description: OHLCV candles

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiie/buda-mcp",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "mcpName": "io.github.gtorreal/buda-mcp",
   "description": "MCP server for Buda.com's public cryptocurrency exchange API (Chile, Colombia, Peru)",
   "type": "module",
@@ -14,7 +14,10 @@
     "start:stdio": "node dist/index.js",
     "dev:http": "tsx src/http.ts",
     "dev": "tsx src/index.ts",
-    "test": "tsx test/run-all.ts"
+    "test": "npm run test:unit && npm run test:integration",
+    "test:unit": "tsx test/unit.ts",
+    "test:integration": "tsx test/run-all.ts",
+    "sync-version": "node scripts/sync-version.mjs"
   },
   "engines": {
     "node": ">=18"

package/scripts/sync-version.mjs

@@ -0,0 +1,19 @@
+/**
+ * Reads the version from package.json and writes it into server.json.
+ * Run after bumping the version in package.json:
+ *   node scripts/sync-version.mjs
+ */
+import { readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const server = JSON.parse(readFileSync(join(root, "server.json"), "utf8"));
+
+server.version = pkg.version;
+server.packages[0].version = pkg.version;
+
+writeFileSync(join(root, "server.json"), JSON.stringify(server, null, 2) + "\n");
+console.log(`server.json synced to v${pkg.version}`);

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/gtorreal/buda-mcp",
     "source": "github"
   },
-  "version": "1.1.2",
+  "version": "1.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@guiie/buda-mcp",
-      "version": "1.1.2",
+      "version": "1.2.0",
       "transport": {
         "type": "stdio"
       }

package/src/client.ts

@@ -1,4 +1,5 @@
 import { createHmac } from "crypto";
+import { VERSION } from "./version.js";
 
 const BASE_URL = "https://www.buda.com/api/v2";
 
@@ -7,6 +8,7 @@ export class BudaApiError extends Error {
     public readonly status: number,
     public readonly path: string,
     message: string,
+    public readonly retryAfterMs?: number,
   ) {
     super(message);
     this.name = "BudaApiError";
@@ -56,24 +58,51 @@ export class BudaClient {
     };
   }
 
-  async get<T>(path: string, params?: Record<string, string | number>): Promise<T> {
-    const url = new URL(`${this.baseUrl}${path}.json`);
+  /**
+   * Parses the Retry-After header value into milliseconds.
+   * Per RFC 7231, Retry-After is an integer number of seconds.
+   * Defaults to 1000ms (1 second) if absent or unparseable.
+   */
+  private parseRetryAfterMs(headers: Headers): number {
+    const raw = headers.get("Retry-After");
+    if (!raw) return 1000;
+    const secs = parseInt(raw, 10);
+    return isNaN(secs) ? 1000 : secs * 1000;
+  }
 
-    if (params) {
-      for (const [key, value] of Object.entries(params)) {
-        url.searchParams.set(key, String(value));
-      }
+  /**
+   * Executes a fetch call with a single 429 retry.
+   * On the first 429, waits for Retry-After seconds (default 1s), then retries once.
+   * If the retry also returns 429, throws a BudaApiError with retryAfterMs set.
+   */
+  private async fetchWithRetry(
+    url: URL,
+    options: RequestInit,
+    path: string,
+  ): Promise<Response> {
+    const response = await fetch(url.toString(), options);
+
+    if (response.status !== 429) return response;
+
+    const retryAfterMs = this.parseRetryAfterMs(response.headers);
+    await new Promise((r) => setTimeout(r, retryAfterMs));
+
+    const retry = await fetch(url.toString(), options);
+
+    if (retry.status === 429) {
+      const retryAgainMs = this.parseRetryAfterMs(retry.headers);
+      throw new BudaApiError(
+        429,
+        path,
+        `Buda API rate limit exceeded. Retry after ${retryAgainMs}ms.`,
+        retryAgainMs,
+      );
     }
 
-    const urlPath = url.pathname + url.search;
-    const headers: Record<string, string> = {
-      Accept: "application/json",
-      "User-Agent": "buda-mcp/1.1.1",
-      ...this.authHeaders("GET", urlPath),
-    };
-
-    const response = await fetch(url.toString(), { headers });
+    return retry;
+  }
 
+  private async handleResponse<T>(response: Response, path: string): Promise<T> {
     if (!response.ok) {
       let detail = response.statusText;
       try {
@@ -84,10 +113,29 @@ export class BudaClient {
       }
       throw new BudaApiError(response.status, path, `Buda API ${response.status}: ${detail}`);
     }
-
     return response.json() as Promise<T>;
   }
 
+  async get<T>(path: string, params?: Record<string, string | number>): Promise<T> {
+    const url = new URL(`${this.baseUrl}${path}.json`);
+
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+
+    const urlPath = url.pathname + url.search;
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      "User-Agent": `buda-mcp/${VERSION}`,
+      ...this.authHeaders("GET", urlPath),
+    };
+
+    const response = await this.fetchWithRetry(url, { headers }, path);
+    return this.handleResponse<T>(response, path);
+  }
+
   async post<T>(path: string, payload: unknown): Promise<T> {
     const url = new URL(`${this.baseUrl}${path}.json`);
     const bodyStr = JSON.stringify(payload);
@@ -95,28 +143,16 @@ export class BudaClient {
     const headers: Record<string, string> = {
       Accept: "application/json",
       "Content-Type": "application/json",
-      "User-Agent": "buda-mcp/1.1.1",
+      "User-Agent": `buda-mcp/${VERSION}`,
       ...this.authHeaders("POST", urlPath, bodyStr),
     };
 
-    const response = await fetch(url.toString(), {
-      method: "POST",
-      headers,
-      body: bodyStr,
-    });
-
-    if (!response.ok) {
-      let detail = response.statusText;
-      try {
-        const body = (await response.json()) as { message?: string };
-        if (body.message) detail = body.message;
-      } catch {
-        // ignore parse error, use statusText
-      }
-      throw new BudaApiError(response.status, path, `Buda API ${response.status}: ${detail}`);
-    }
-
-    return response.json() as Promise<T>;
+    const response = await this.fetchWithRetry(
+      url,
+      { method: "POST", headers, body: bodyStr },
+      path,
+    );
+    return this.handleResponse<T>(response, path);
   }
 
   async put<T>(path: string, payload: unknown): Promise<T> {
@@ -126,27 +162,15 @@ export class BudaClient {
     const headers: Record<string, string> = {
       Accept: "application/json",
       "Content-Type": "application/json",
-      "User-Agent": "buda-mcp/1.1.1",
+      "User-Agent": `buda-mcp/${VERSION}`,
       ...this.authHeaders("PUT", urlPath, bodyStr),
     };
 
-    const response = await fetch(url.toString(), {
-      method: "PUT",
-      headers,
-      body: bodyStr,
-    });
-
-    if (!response.ok) {
-      let detail = response.statusText;
-      try {
-        const body = (await response.json()) as { message?: string };
-        if (body.message) detail = body.message;
-      } catch {
-        // ignore parse error, use statusText
-      }
-      throw new BudaApiError(response.status, path, `Buda API ${response.status}: ${detail}`);
-    }
-
-    return response.json() as Promise<T>;
+    const response = await this.fetchWithRetry(
+      url,
+      { method: "PUT", headers, body: bodyStr },
+      path,
+    );
+    return this.handleResponse<T>(response, path);
   }
 }