@guiie/buda-mcp 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to `buda-mcp` are documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).  
+This project uses [Semantic Versioning](https://semver.org/).
+
+---
+
+## [1.1.0] – 2026-04-10
+
+### Added
+
+**Phase 1: New public tools**
+
+- **`get_spread`** — calculates the bid/ask spread (absolute and as a percentage of the ask price) for any market using the ticker endpoint. Cached with the same 5-second TTL as tickers.
+- **`compare_markets`** — receives a base currency (e.g. `BTC`) and returns side-by-side ticker data for all its pairs across CLP, COP, PEN, USDC, and BTC quote currencies. Uses `GET /tickers` (all-tickers endpoint).
+- **`get_price_history`** — returns OHLCV (open/high/low/close/volume) candles for a market and period (`1h`, `4h`, `1d`). Buda has no native candlestick endpoint; candles are aggregated client-side from up to 100 raw trades fetched via the trades endpoint.
+
+**Input validation and error handling**
+
+- All tools now wrap their handlers in `try/catch` and return structured `{ error, code, path }` JSON with `isError: true` on failure, instead of letting unhandled exceptions propagate.
+- Zod schemas on all tool inputs remain the primary validation layer.
+
+**In-memory TTL caching** (`src/cache.ts`)
+
+- New `MemoryCache` class with `getOrFetch<T>(key, ttlMs, fetcher)` pattern.
+- TTLs: markets list = 60 s, tickers = 5 s, order books = 3 s.
+- Shared singleton for stdio; per-request instance for the stateless HTTP transport.
+
+**Phase 2: Authentication scaffold**
+
+- **`BudaClient`** extended with optional `apiKey` / `apiSecret` constructor params.
+- `hasAuth()` method returns true when both env vars are set.
+- HMAC-SHA384 signing implemented per [Buda API auth docs](https://api.buda.com/en/#authentication): nonce (microseconds), sign string `{METHOD} {path.json?query} {base64body} {nonce}`, headers `X-SBTC-APIKEY`, `X-SBTC-NONCE`, `X-SBTC-SIGNATURE`.
+- `post<T>()` and `put<T>()` methods added to `BudaClient` for private endpoints.
+- Credentials are read from `BUDA_API_KEY` / `BUDA_API_SECRET` environment variables. If not set, server runs in **public-only mode** — no breaking change for existing users.
+
+**Authenticated tools** (only registered when API keys are present)
+
+- **`get_balances`** — all currency balances (`GET /balances`).
+- **`get_orders`** — orders for a given market, filterable by state (`GET /markets/{id}/orders`).
+- **`place_order`** — places a limit or market order (`POST /markets/{id}/orders`). Requires `confirmation_token="CONFIRM"` to prevent accidental execution from ambiguous prompts.
+- **`cancel_order`** — cancels an order by ID (`PUT /orders/{id}`). Requires `confirmation_token="CONFIRM"`.
+
+**Phase 3: DX improvements**
+
+- **MCP Resources protocol**: two resources registered in both stdio and HTTP transports:
+  - `buda://markets` — JSON list of all markets (60 s cache).
+  - `buda://ticker/{market}` — JSON ticker for a specific market (5 s cache).
+- **README** rewritten: npx quick-start, npm/license/node badges, per-tool example prompts, authentication mode documentation, resources section.
+- **`CHANGELOG.md`** introduced (this file).
+- **`PUBLISH_CHECKLIST.md`** added with steps and message templates for notifying mcp.so and Glama.ai of the v1.1.0 release.
+- **`marketplace/`** files updated: `claude-listing.md`, `cursor-mcp.json`, `gemini-tools.json`, `openapi.yaml` all reflect new tools, auth mode, npx quick-start, and MCP Resources.
+
+### Changed
+
+- `BudaClient` `User-Agent` header updated from `buda-mcp/1.0.0` to `buda-mcp/1.1.0`.
+- All 5 existing tool `register()` functions updated to accept a `MemoryCache` parameter and apply TTL caching.
+- Server version string in `McpServer`, `http.ts` health endpoint, and server-card JSON updated to `1.1.0`.
+- `package.json` version bumped to `1.1.0`.
+- `marketplace/cursor-mcp.json` npm package name corrected to `@gtorreal/buda-mcp`.
+- `marketplace/claude-listing.md` npm package name corrected to `@gtorreal/buda-mcp`.
+
+### Security
+
+- API credentials (`BUDA_API_KEY`, `BUDA_API_SECRET`) are never logged at any level. All `console.log` / `console.error` calls in `http.ts` and `client.ts` were audited to confirm this.
+- Authenticated instances are documented as **local-only** — never to be exposed publicly.
+
+---
+
+## [1.0.0] – 2025-01-01
+
+### Added
+
+- Initial release: 5 public MCP tools for Buda.com market data.
+  - `get_markets` — list all trading pairs or get details for one.
+  - `get_ticker` — current price, bid/ask, volume, and price change.
+  - `get_orderbook` — full order book with bid/ask levels.
+  - `get_trades` — recent trade history with pagination.
+  - `get_market_volume` — 24h and 7-day volume by side.
+- Dual transports: **stdio** (`index.ts`) and **Streamable HTTP** (`http.ts`).
+- Railway deployment with health check at `GET /health`.
+- Smithery-compatible static server card at `GET /.well-known/mcp/server-card.json`.
+- Published to npm as `@gtorreal/buda-mcp`.
+- Registered on MCP Registry as `io.github.gtorreal/buda-mcp`.
+- Listed on Smithery, mcp.so, Glama.ai, PulseMCP, and awesome-mcp-servers.

package/PUBLISH_CHECKLIST.md

@@ -0,0 +1,192 @@
+# Publish Checklist — buda-mcp v1.1.0
+
+Steps to publish `v1.1.0` to npm, the MCP registry, and notify community directories.
+
+---
+
+## 1. Pre-publish verification
+
+```bash
+# Confirm version
+node -e "console.log(require('./package.json').version)"  # should print 1.1.0
+
+# Build and test
+npm run build
+npm test
+
+# 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
+```
+
+---
+
+## 2. npm publish
+
+```bash
+npm login   # if not already logged in
+npm publish --access public --provenance
+```
+
+Verify: https://www.npmjs.com/package/@gtorreal/buda-mcp
+
+---
+
+## 3. GitHub release
+
+```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 push origin main --tags
+```
+
+Then create a GitHub Release from the tag with the following release notes:
+
+---
+
+**Release notes template (GitHub):**
+
+```
+## buda-mcp v1.1.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)
+
+**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
+
+**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
+
+```bash
+npx @gtorreal/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:
+
+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
+```
+
+---
+
+## 5. Smithery
+
+Smithery auto-detects updates via the `/.well-known/mcp/server-card.json` endpoint on the Railway deployment. No manual action required after deploying.
+
+Verify: https://smithery.ai/server/@gtorreal/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
+
+Hi mcp.so team,
+
+I've released v1.1.0 of buda-mcp (@gtorreal/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
+
+Links:
+- npm: https://www.npmjs.com/package/@gtorreal/buda-mcp
+- GitHub: https://github.com/gtorreal/buda-mcp
+- Changelog: https://github.com/gtorreal/buda-mcp/blob/main/CHANGELOG.md
+
+Quick start: npx @gtorreal/buda-mcp
+
+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
+
+Hi Glama team,
+
+buda-mcp has been updated to v1.1.0. Here's a summary of what's new:
+
+Package: @gtorreal/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)
+
+New capabilities:
+- MCP Resources protocol: buda://markets, buda://ticker/{market}
+- TTL caching (60s/5s/3s by data type)
+- Structured error responses (isError: true)
+
+Quick start:
+  npx @gtorreal/buda-mcp
+
+Changelog: https://github.com/gtorreal/buda-mcp/blob/main/CHANGELOG.md
+GitHub: https://github.com/gtorreal/buda-mcp
+
+Thank you!
+```
+
+---
+
+## 8. Post-publish verification
+
+- [ ] `npx @gtorreal/buda-mcp@1.1.0` starts successfully
+- [ ] `npm info @gtorreal/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
+- [ ] mcp.so listing updated
+- [ ] Glama.ai listing updated
+- [ ] Railway deployment health check returns `"version":"1.1.0"` at `/health`