@commoditypriceapi/mcp 1.0.1 → 1.1.0

package/README.md

@@ -221,22 +221,22 @@ Try these after setup:
 
 ## Tool Reference
 
-All 8 tools map 1:1 to CommodityPriceAPI v2 endpoints. Tools that take `symbols` accept a comma-separated list (e.g. `XAU,XAG,BRENTOIL-SPOT`). Use `list_symbols` to look up valid symbols — there are 148 across Metals, Energy, Agriculture, and more.
+All 8 tools map 1:1 to CommodityPriceAPI v3 endpoints. Tools that take `symbols` accept a comma-separated list (e.g. `XAU,XAG,BRENTOIL-SPOT`). Use `list_symbols` to look up valid symbols — there are 148 across Metals, Energy, Agriculture, and more.
 
 ### get_latest_rates
 
-`GET /v2/rates/latest` — latest rates for one or more symbols. Rates may lag up to 10 minutes depending on plan.
+`GET /v3/rates/latest` — latest rates for one or more symbols. Rates may lag up to 10 minutes depending on plan.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | `symbols` | Yes | Comma-separated symbols, e.g. `XAU,XAG,BRENTOIL-SPOT` |
 | `quote` | No | Target quote currency (e.g. `EUR`). Premium/Plus plans only; omit for each symbol's default currency. |
 
-Note: if a symbol in a multi-symbol request is invalid, the API silently omits it from the response rather than returning an error. A missing symbol in the result means the symbol is wrong — check `list_symbols`.
+Note: if some symbols in a multi-symbol request are invalid, the API returns the valid rates (HTTP 206) plus an `unresolved` map — one entry per missing symbol with a message and, where available, `suggestions` ("did you mean"). If no symbol resolves, the tool returns a `SYMBOL_NOT_FOUND` error carrying the same `unresolved` map. The same applies to `get_historical_rates`, `get_time_series`, and `get_fluctuation`.
 
 ### get_gold_price
 
-`GET /v2/rates/latest/xau` — shortcut for the latest gold (XAU) rate, including bid/ask.
+`GET /v3/rates/latest/xau` — shortcut for the latest gold (XAU) rate, including bid/ask.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
@@ -244,7 +244,7 @@ Note: if a symbol in a multi-symbol request is invalid, the API silently omits i
 
 ### get_silver_price
 
-`GET /v2/rates/latest/xag` — shortcut for the latest silver (XAG) rate.
+`GET /v3/rates/latest/xag` — shortcut for the latest silver (XAG) rate.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
@@ -252,7 +252,7 @@ Note: if a symbol in a multi-symbol request is invalid, the API silently omits i
 
 ### get_historical_rates
 
-`GET /v2/rates/historical` — open/high/low/close rates for one or more symbols on a specific past date, available back to 1990-01-01. If no rate exists for that exact date, the API returns the nearest available date.
+`GET /v3/rates/historical` — open/high/low/close rates for one or more symbols on a specific past date, available back to 1990-01-01. If no rate exists for that exact date, the API returns the nearest available date.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
@@ -261,7 +261,7 @@ Note: if a symbol in a multi-symbol request is invalid, the API silently omits i
 
 ### get_time_series
 
-`GET /v2/rates/time-series` — daily historical rates for one or more symbols between two dates. Max span: 1 year.
+`GET /v3/rates/time-series` — daily historical rates for one or more symbols between two dates. Max span: 1 year.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
@@ -271,7 +271,7 @@ Note: if a symbol in a multi-symbol request is invalid, the API silently omits i
 
 ### get_fluctuation
 
-`GET /v2/rates/fluctuation` — how each symbol changed between two dates: start rate, end rate, absolute change, and percent change.
+`GET /v3/rates/fluctuation` — how each symbol changed between two dates: start rate, end rate, absolute change, and percent change.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
@@ -281,11 +281,11 @@ Note: if a symbol in a multi-symbol request is invalid, the API silently omits i
 
 ### list_symbols
 
-`GET /v2/symbols` — all supported commodity symbols with name, category, quote currency, unit, and update interval. Takes no parameters. Call this before rate tools when unsure of a symbol.
+`GET /v3/symbols` — all supported commodity symbols with name, category, quote currency, unit, and update interval. Takes no parameters. Call this before rate tools when unsure of a symbol.
 
 ### get_usage
 
-`GET /v2/usage` — current plan, quota, and usage for the configured API key. Takes no parameters.
+`GET /v3/usage` — current plan, quota, and usage for the configured API key. Takes no parameters.
 
 ## Prompt Examples
 
@@ -412,7 +412,7 @@ Example error result for an invalid symbol:
 
 ## How It Works
 
-This is a stdio MCP server that wraps the CommodityPriceAPI v2 REST API.
+This is a stdio MCP server that wraps the CommodityPriceAPI v3 REST API.
 
 At runtime:
 
@@ -457,7 +457,7 @@ COMMODITYPRICEAPI_KEY=<YOUR_KEY> npx @modelcontextprotocol/inspector node dist/c
 
 **401 errors:** Check that `COMMODITYPRICEAPI_KEY` is set in your MCP client config's `env` block.
 
-**A symbol is missing from a multi-symbol response:** The upstream API silently drops invalid symbols instead of erroring. Call `list_symbols` to find the correct symbol — e.g. Brent crude is `BRENTOIL-SPOT`, not `BRENTOIL`.
+**A symbol is missing from a multi-symbol response:** Look at the `unresolved` map in the result — each missing symbol has a message and usually `suggestions` (e.g. `BRENTOIL` → `BRENTOIL-SPOT`). If there are no suggestions, call `list_symbols` to find the correct symbol.
 
 **499 timeouts:** The upstream API did not respond in time. Increase `COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS` (default: 15000 ms).
 

package/dist/client.js

@@ -1,14 +1,16 @@
-const BASE_URL = "https://api.commoditypriceapi.com/v2";
+const BASE_URL = "https://api.commoditypriceapi.com/v3";
 export class CommodityApiError extends Error {
     code;
     errorType;
     path;
-    constructor(code, errorType, message, path) {
+    unresolved;
+    constructor(code, errorType, message, path, unresolved) {
         super(message);
         this.name = "CommodityApiError";
         this.code = code;
         this.errorType = errorType;
         this.path = path;
+        this.unresolved = unresolved;
     }
 }
 function getApiKey() {
@@ -19,9 +21,13 @@ function getApiKey() {
     return key;
 }
 /**
- * Calls a CommodityPriceAPI v2 endpoint.
+ * Calls a CommodityPriceAPI v3 endpoint.
  * Sends the API key via both the x-api-key header AND the apiKey query
  * param, since the upstream API accepts either.
+ *
+ * v3 answers 206 (still `response.ok`) with an `unresolved` map appended to
+ * the body when some requested symbols could not be returned; the body is
+ * passed through as-is so tool results include those suggestions.
  */
 export async function callCommodityApi(path, params = {}) {
     const apiKey = getApiKey();
@@ -64,7 +70,7 @@ export async function callCommodityApi(path, params = {}) {
         throw new CommodityApiError(response.status, "INVALID_RESPONSE", `CommodityPriceAPI returned a non-JSON response: ${text.slice(0, 500)}`);
     }
     if (!response.ok) {
-        throw new CommodityApiError(response.status, body.error ?? "UNKNOWN_ERROR", body.message ?? `CommodityPriceAPI request failed with status ${response.status}.`, body.path);
+        throw new CommodityApiError(response.status, body.error ?? "UNKNOWN_ERROR", body.message ?? `CommodityPriceAPI request failed with status ${response.status}.`, body.path, body.unresolved);
     }
     return body;
 }

package/dist/server.js

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { callCommodityApi, CommodityApiError } from "./client.js";
 const symbolsParam = z
     .string()
-    .describe("Comma-separated commodity symbols, e.g. 'XAU,XAG,BRENTOIL-SPOT'. See the list_symbols tool for valid values. Invalid symbols in a multi-symbol request are silently omitted from the response, not errored.");
+    .describe("Comma-separated commodity symbols, e.g. 'XAU,XAG,BRENTOIL-SPOT'. See the list_symbols tool for valid values. If some symbols cannot be resolved, the response still succeeds (HTTP 206) with the valid rates plus an 'unresolved' map giving a message and 'did you mean' suggestions for each missing symbol. If none resolve, the error result carries the same 'unresolved' map.");
 const dateParam = z.string().describe("Date in YYYY-MM-DD format.");
 function textResult(data) {
     return {
@@ -26,6 +26,7 @@ function errorResult(err) {
                         error: err.errorType,
                         code: err.code,
                         message: err.message,
+                        ...(err.unresolved ? { unresolved: err.unresolved } : {}),
                         guidance: guidanceFor(err.code, err.errorType),
                     }, null, 2),
                 },
@@ -52,7 +53,7 @@ function guidanceFor(code, errorType) {
             return "You've hit your API key's usage limit. Upgrade your plan or wait for the quota to reset.";
         case 404:
             if (errorType === "SYMBOL_NOT_FOUND") {
-                return "Call list_symbols to see valid commodity symbols.";
+                return "None of the requested symbols are valid. Check the 'unresolved' map above for suggested symbols, or call list_symbols to see all valid commodity symbols.";
             }
             return "The requested resource was not found.";
         case 429:
@@ -64,7 +65,7 @@ function guidanceFor(code, errorType) {
 export function createServer() {
     const server = new McpServer({
         name: "commoditypriceapi-mcp",
-        version: "1.0.1",
+        version: "1.1.0",
     });
     server.registerTool("get_usage", {
         title: "Get API usage",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commoditypriceapi/mcp",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Official MCP server for CommodityPriceAPI \u2014 real-time and historical commodity rates (gold, silver, oil, and 130+ more) as MCP tools for Claude, Cursor, Windsurf, and any MCP client.",
   "keywords": [
     "mcp",