@commoditypriceapi/mcp 1.2.0 → 1.2.2

package/README.md

@@ -233,6 +233,7 @@ Precious metals use ISO 4217 codes: `XAU` (gold), `XAG` (silver), `XPT` (platinu
 |-----------|----------|-------------|
 | `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. |
+| `metadata` | No | `true` (default) or `false`. `false` omits the `metadata` map (per-symbol unit and quote currency) from the response. |
 
 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`.
 
@@ -250,6 +251,7 @@ Note on `unresolved`: v3 appends an `unresolved` map, keyed by the symbol you ty
 |-----------|----------|-------------|
 | `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. |
+| `metadata` | No | `true` (default) or `false`. `false` omits the `metadata` map (per-symbol unit and quote currency) from the response. |
 
 ### get_silver_price
 
@@ -259,6 +261,7 @@ Note on `unresolved`: v3 appends an `unresolved` map, keyed by the symbol you ty
 |-----------|----------|-------------|
 | `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. |
+| `metadata` | No | `true` (default) or `false`. `false` omits the `metadata` map (per-symbol unit and quote currency) from the response. |
 
 ### get_historical_rates
 

package/dist/server.js

@@ -17,6 +17,14 @@ 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.");
+const metadataParam = z
+    .boolean()
+    .optional()
+    .describe("Whether to include the 'metadata' map (per-symbol unit and quote currency) in the response. Defaults to true. Set false to omit it and get a smaller payload.");
+/** v3 only honours an explicit `metadata=false`; anything else is the default (true). */
+function metadataFlag(metadata) {
+    return metadata === false ? "false" : undefined;
+}
 function textResult(data) {
     return {
         content: [
@@ -77,7 +85,7 @@ function guidanceFor(code, errorType) {
 export function createServer() {
     const server = new McpServer({
         name: "commoditypriceapi-mcp",
-        version: "1.2.0",
+        version: "1.2.1",
     });
     server.registerTool("get_usage", {
         title: "Get API usage",
@@ -94,11 +102,29 @@ 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. Precious metals use ISO 4217 codes (XAU, XAG, XPT, XPD); copper is XCU.",
-        inputSchema: {},
-    }, async () => {
+        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. " +
+            "Dated futures contracts (e.g. WTIOIL-FUT-DEC26, the December 2026 WTI contract) are listed as their own symbols with 'contract', 'deliveryMonth', 'expiresAt' and 'underlying' (the continuous parent such as WTIOIL-FUT); expired contracts are hidden unless includeExpired is set. Pass 'underlying' to list one parent's live months. A contract's latest price comes from get_latest_rates and its daily open/high/low/close (close = the exchange settlement) from get_historical_rates / get_time_series.",
+        inputSchema: {
+            underlying: z
+                .string()
+                .optional()
+                .describe("Only the dated futures contracts of this continuous parent symbol, e.g. 'WTIOIL-FUT'."),
+            contract: z
+                .enum(["spot", "futures"])
+                .optional()
+                .describe("Only symbols of this contract kind."),
+            includeExpired: z
+                .boolean()
+                .optional()
+                .describe("Also list expired futures contracts (hidden by default)."),
+        },
+    }, async ({ underlying, contract, includeExpired }) => {
         try {
-            const data = await callCommodityApi("/symbols");
+            const data = await callCommodityApi("/symbols", {
+                underlying,
+                contract,
+                includeExpired: includeExpired ? "true" : undefined,
+            });
             return textResult(data);
         }
         catch (err) {
@@ -107,14 +133,19 @@ 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). Common names with a single match (e.g. GOLD) are auto-resolved to the real symbol and flagged in 'unresolved' with 'resolvedTo'.",
+        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'. Set 'metadata' to false to omit the per-symbol unit/quote map.",
         inputSchema: {
             symbols: symbolsParam,
             quote: quoteParam,
+            metadata: metadataParam,
         },
-    }, async ({ symbols, quote }) => {
+    }, async ({ symbols, quote, metadata }) => {
         try {
-            const data = await callCommodityApi("/rates/latest", { symbols, quote });
+            const data = await callCommodityApi("/rates/latest", {
+                symbols,
+                quote,
+                metadata: metadataFlag(metadata),
+            });
             return textResult(data);
         }
         catch (err) {
@@ -123,14 +154,19 @@ export function createServer() {
     });
     server.registerTool("get_gold_price", {
         title: "Get latest gold (XAU) price",
-        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.",
+        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. Set 'metadata' to false to omit the unit/quote map.",
         inputSchema: {
             quote: quoteParam,
             include: includeParam,
+            metadata: metadataParam,
         },
-    }, async ({ quote, include }) => {
+    }, async ({ quote, include, metadata }) => {
         try {
-            const data = await callCommodityApi("/rates/latest/xau", { quote, include });
+            const data = await callCommodityApi("/rates/latest/xau", {
+                quote,
+                include,
+                metadata: metadataFlag(metadata),
+            });
             return textResult(data);
         }
         catch (err) {
@@ -139,14 +175,19 @@ export function createServer() {
     });
     server.registerTool("get_silver_price", {
         title: "Get latest silver (XAG) price",
-        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.",
+        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. Set 'metadata' to false to omit the unit/quote map.",
         inputSchema: {
             quote: quoteParam,
             include: includeParam,
+            metadata: metadataParam,
         },
-    }, async ({ quote, include }) => {
+    }, async ({ quote, include, metadata }) => {
         try {
-            const data = await callCommodityApi("/rates/latest/xag", { quote, include });
+            const data = await callCommodityApi("/rates/latest/xag", {
+                quote,
+                include,
+                metadata: metadataFlag(metadata),
+            });
             return textResult(data);
         }
         catch (err) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@commoditypriceapi/mcp",
-  "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.",
+  "version": "1.2.2",
+  "description": "Official MCP server for CommodityPriceAPI — 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",
     "model-context-protocol",