@commoditypriceapi/mcp 1.0.1 → 1.2.0

package/README.md

@@ -221,38 +221,48 @@ 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,XPT,BRENTOIL-SPOT`). Use `list_symbols` to look up valid symbols — there are 245 across Metals, Energy, Agriculture, and more.
+
+Precious metals use ISO 4217 codes: `XAU` (gold), `XAG` (silver), `XPT` (platinum), `XPD` (palladium). Copper is `XCU`. The retired codes `PL`, `PA`, and `HG` still work on v3 — they are auto-resolved to the new symbol (see the note below).
 
 ### 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 on `unresolved`: v3 appends an `unresolved` map, keyed by the symbol you typed, in three cases. The same applies to `get_historical_rates`, `get_time_series`, and `get_fluctuation`.
+
+| Case | HTTP | What the entry holds |
+|------|------|----------------------|
+| Symbol is not a catalogue code but has exactly one match (e.g. `GOLD`, or retired `PL`) | `200` | `message` + `resolvedTo` — the rate was returned under `resolvedTo` in `rates`. Informational, not a failure. |
+| Some symbols could not be returned | `206` | `message` + optional `suggestions` ("did you mean"). Valid rates are still in `rates`. |
+| No symbol resolved | `404` | Tool returns a `SYMBOL_NOT_FOUND` error carrying the same `unresolved` map. |
 
 ### 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 |
 |-----------|----------|-------------|
 | `quote` | No | Target quote currency. Premium/Plus plans only. |
+| `include` | No | `gram`, `carat`, or `tola` — adds a per-gram rate, per-gram rates at each purity from 24k to 8k, or a per-tola rate alongside the ounce rate. |
 
 ### 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, including bid/ask.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | `quote` | No | Target quote currency. Premium/Plus plans only. |
+| `include` | No | `gram`, `carat`, or `tola` — adds a per-gram, per-carat, or per-tola rate alongside the ounce rate. |
 
 ### 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 +271,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 +281,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,18 +291,19 @@ 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
 
 ### Live prices
 
 - What's the current gold price?
-- Get the latest prices for silver, copper, and WTI crude.
+- What's gold per gram right now?
+- Get the latest prices for silver, platinum, copper, and WTI crude.
 - What's gold trading at in euros?
 
 ### Historical data
@@ -385,6 +396,35 @@ The text answers show what a client might say; exact wording depends on the mode
 }
 ```
 
+### Auto-resolved symbol
+
+**Prompt:** What's the price of GOLD and platinum?
+
+**Example answer:** Gold (XAU) is $4,386.23 and platinum (XPT) is $1,412.50 per troy ounce. Note: `GOLD` isn't a symbol code, so the API returned it under `XAU`.
+
+```json
+{
+  "success": true,
+  "timestamp": 1786617187,
+  "rates": {
+    "XAU": 4386.23,
+    "XPT": 1412.5
+  },
+  "metadata": {
+    "XAU": { "unit": "T.oz", "quote": "USD" },
+    "XPT": { "unit": "T.oz", "quote": "USD" }
+  },
+  "unresolved": {
+    "GOLD": {
+      "message": "GOLD is not a symbol code used by this API. Gold is available as \"XAU\", so its rate was returned under that symbol.",
+      "resolvedTo": "XAU"
+    }
+  }
+}
+```
+
+Status is `200` — an entry with `resolvedTo` never downgrades the response.
+
 ## Error Codes
 
 Tool calls never crash the server. Upstream errors are returned as structured tool results with `error`, `code`, `message`, and a `guidance` field so the client can explain what went wrong instead of echoing a status code.
@@ -412,7 +452,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 +497,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. If the entry has `resolvedTo`, nothing is missing — the rate is in `rates` under that symbol (e.g. `GOLD` → `XAU`, `PL` → `XPT`). Otherwise each missing symbol has a message and usually `suggestions` (e.g. `OIL` → `WTIOIL-SPOT`, `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,15 @@ 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, and 200 with an
+ * `unresolved` map when a symbol was auto-resolved to its single match
+ * (`resolvedTo`). The body is passed through as-is so tool results include
+ * those notes and suggestions.
  */
 export async function callCommodityApi(path, params = {}) {
     const apiKey = getApiKey();
@@ -64,7 +72,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,8 +3,20 @@ 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,XPT,BRENTOIL-SPOT'. Precious metals use ISO 4217 codes (XAU gold, XAG silver, XPT platinum, XPD palladium); copper is XCU. See the list_symbols tool for valid values. " +
+    "The response may include an 'unresolved' map keyed by the symbol you typed. Three cases: " +
+    "(1) HTTP 200 with an entry carrying 'resolvedTo' — the symbol was not a catalogue code but had exactly one match (e.g. GOLD -> XAU, retired PL -> XPT), so its rate was returned under the 'resolvedTo' symbol in 'rates'; this is informational, not a failure. " +
+    "(2) HTTP 206 — some symbols could not be returned; each entry has a message and, where available, 'did you mean' suggestions, while the valid rates are still in 'rates'. " +
+    "(3) If none resolve, the error result carries the same 'unresolved' map.");
 const dateParam = z.string().describe("Date in YYYY-MM-DD format.");
+const quoteParam = z
+    .string()
+    .optional()
+    .describe("Target quote currency code (e.g. 'USD', 'EUR'). Premium/Plus plans only; omit to use each symbol's default currency.");
+const includeParam = z
+    .enum(["gram", "carat", "tola"])
+    .optional()
+    .describe("Add a per-unit breakdown alongside the per-troy-ounce rate: 'gram' adds a per-gram rate, 'tola' adds a per-tola rate, 'carat' adds per-gram rates at each purity from 24k down to 8k. Omit for the ounce rate only.");
 function textResult(data) {
     return {
         content: [
@@ -26,6 +38,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 +65,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 +77,7 @@ function guidanceFor(code, errorType) {
 export function createServer() {
     const server = new McpServer({
         name: "commoditypriceapi-mcp",
-        version: "1.0.1",
+        version: "1.2.0",
     });
     server.registerTool("get_usage", {
         title: "Get API usage",
@@ -81,7 +94,7 @@ export function createServer() {
     });
     server.registerTool("list_symbols", {
         title: "List supported commodity symbols",
-        description: "Returns all commodity symbols supported by CommodityPriceAPI, including category, default currency, and unit. Use this to look up a symbol before calling rate tools.",
+        description: "Returns all commodity symbols supported by CommodityPriceAPI, including category, default currency, and unit. Use this to look up a symbol before calling rate tools. Precious metals use ISO 4217 codes (XAU, XAG, XPT, XPD); copper is XCU.",
         inputSchema: {},
     }, async () => {
         try {
@@ -94,13 +107,10 @@ export function createServer() {
     });
     server.registerTool("get_latest_rates", {
         title: "Get latest commodity rates",
-        description: "Returns the latest rates for one or more commodity symbols (e.g. gold, silver, crude oil). Rates may lag up to 10 minutes depending on plan. Use 'quote' to convert to a specific currency (Premium/Plus plans only).",
+        description: "Returns the latest rates for one or more commodity symbols (e.g. gold, silver, crude oil). Rates may lag up to 10 minutes depending on plan. Use 'quote' to convert to a specific currency (Premium/Plus plans only). Common names with a single match (e.g. GOLD) are auto-resolved to the real symbol and flagged in 'unresolved' with 'resolvedTo'.",
         inputSchema: {
             symbols: symbolsParam,
-            quote: z
-                .string()
-                .optional()
-                .describe("Target quote currency code (e.g. 'USD', 'EUR'). Premium/Plus plans only; omit to use each symbol's default currency."),
+            quote: quoteParam,
         },
     }, async ({ symbols, quote }) => {
         try {
@@ -113,16 +123,14 @@ export function createServer() {
     });
     server.registerTool("get_gold_price", {
         title: "Get latest gold (XAU) price",
-        description: "Shortcut for the latest gold (XAU) rate without needing to pass a symbols list.",
+        description: "Shortcut for the latest gold (XAU) rate, with bid/ask, without needing to pass a symbols list. Use 'include' to add a per-gram, per-tola, or per-carat breakdown.",
         inputSchema: {
-            quote: z
-                .string()
-                .optional()
-                .describe("Target quote currency code. Premium/Plus plans only."),
+            quote: quoteParam,
+            include: includeParam,
         },
-    }, async ({ quote }) => {
+    }, async ({ quote, include }) => {
         try {
-            const data = await callCommodityApi("/rates/latest/xau", { quote });
+            const data = await callCommodityApi("/rates/latest/xau", { quote, include });
             return textResult(data);
         }
         catch (err) {
@@ -131,16 +139,14 @@ export function createServer() {
     });
     server.registerTool("get_silver_price", {
         title: "Get latest silver (XAG) price",
-        description: "Shortcut for the latest silver (XAG) rate without needing to pass a symbols list.",
+        description: "Shortcut for the latest silver (XAG) rate, with bid/ask, without needing to pass a symbols list. Use 'include' to add a per-gram, per-tola, or per-carat breakdown.",
         inputSchema: {
-            quote: z
-                .string()
-                .optional()
-                .describe("Target quote currency code. Premium/Plus plans only."),
+            quote: quoteParam,
+            include: includeParam,
         },
-    }, async ({ quote }) => {
+    }, async ({ quote, include }) => {
         try {
-            const data = await callCommodityApi("/rates/latest/xag", { quote });
+            const data = await callCommodityApi("/rates/latest/xag", { quote, include });
             return textResult(data);
         }
         catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commoditypriceapi/mcp",
-  "version": "1.0.1",
+  "version": "1.2.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",