@commoditypriceapi/mcp 1.0.0 → 1.1.0

package/README.md

@@ -1,17 +1,29 @@
 # CommodityPriceAPI MCP Server
 
-Official MCP server for [CommodityPriceAPI](https://commoditypriceapi.com). Exposes 8 MCP tools for real-time and historical commodity rates — gold, silver, oil, and 130+ other commodities — to any MCP-compatible client (Claude Desktop, Cursor, Windsurf, VS Code, Cline, etc).
+[![npm version](https://img.shields.io/npm/v/%40commoditypriceapi%2Fmcp?logo=npm&label=npm&color=CB3837)](https://www.npmjs.com/package/@commoditypriceapi/mcp)
+[![GitHub](https://img.shields.io/badge/GitHub-Commodity--Price--API-181717?logo=github)](https://github.com/Commodity-Price-API/commoditypriceapi-mcp)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-5FA04E?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/license-MIT-16A34A)](https://github.com/Commodity-Price-API/commoditypriceapi-mcp/blob/main/LICENSE)
 
-| Item      | Value                    |
-| --------- | ------------------------ |
-| Package   | `@commoditypriceapi/mcp` |
-| Transport | `stdio`                  |
-| Node.js   | `>=18`                   |
+Official MCP server for [CommodityPriceAPI](https://commoditypriceapi.com). Exposes 8 MCP tools for real-time and historical commodity prices — gold, silver, oil, natural gas, wheat, coffee, and 140+ other commodities. Your AI assistant queries the market in plain English; the MCP server handles the API calls.
+
+Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Cline, Codex, and any other MCP-compatible client.
+
+| Item | Value |
+|------|-------|
+| Package | `@commoditypriceapi/mcp` |
+| Transport | `stdio` |
+| Node.js | `>=18` |
 
 ## Quick Start
 
-1. [Get a free CommodityPriceAPI key](https://commoditypriceapi.com/auth/signup)
-2. Add this to your MCP client config:
+1. [Get a free CommodityPriceAPI key](https://commoditypriceapi.com/auth/signup) — free 7-day trial, 2,000 requests, no card required.
+
+2. Cursor users can install in one click:
+
+   [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=commoditypriceapi&config=eyJjb21tYW5kIjoibnB4IC15IEBjb21tb2RpdHlwcmljZWFwaS9tY3AiLCJlbnYiOnsiQ09NTU9ESVRZUFJJQ0VBUElfS0VZIjoiIn19)
+
+3. Everyone else: add this to your MCP client config (see [Install by Client](#install-by-client) for the exact file path):
 
 ```json
 {
@@ -27,20 +39,161 @@ Official MCP server for [CommodityPriceAPI](https://commoditypriceapi.com). Expo
 }
 ```
 
-3. Restart your client.
-4. Test it: ask **"What's the current gold price?"**
+4. Restart your client.
+
+5. Test it: ask **"What's the current gold price?"**
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Install by Client](#install-by-client)
+- [Verify It Works](#verify-it-works)
+- [Tool Reference](#tool-reference)
+- [Prompt Examples](#prompt-examples)
+- [Example Answers and Tool Output](#example-answers-and-tool-output)
+- [Error Codes](#error-codes)
+- [How It Works](#how-it-works)
+- [Environment Variables](#environment-variables)
+- [Building from Source](#building-from-source)
+- [Troubleshooting](#troubleshooting)
+- [Pricing](#pricing)
+- [Links](#links)
+- [License](#license)
 
 ## Install by Client
 
+### Requirements
+
+- Node.js 18 or later
+- `npx` available in your terminal
+- A CommodityPriceAPI key — [sign up free](https://commoditypriceapi.com/auth/signup)
+
 ### Claude Desktop
 
-Add the block above to `claude_desktop_config.json`, then restart Claude Desktop.
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
 
-### Cursor / Windsurf / Cline / VS Code
+```json
+{
+  "mcpServers": {
+    "commoditypriceapi": {
+      "command": "npx",
+      "args": ["-y", "@commoditypriceapi/mcp"],
+      "env": {
+        "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
+      }
+    }
+  }
+}
+```
 
-Add the same `commoditypriceapi` block to that client's MCP server config file and restart the client.
+Restart Claude Desktop after saving.
 
-### Any other MCP client
+### Claude Code
+
+```bash
+claude mcp add commoditypriceapi --env COMMODITYPRICEAPI_KEY=<YOUR_API_KEY> -- npx -y @commoditypriceapi/mcp
+```
+
+Start a new Claude Code session after adding the server.
+
+### Cursor
+
+One-click install:
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=commoditypriceapi&config=eyJjb21tYW5kIjoibnB4IC15IEBjb21tb2RpdHlwcmljZWFwaS9tY3AiLCJlbnYiOnsiQ09NTU9ESVRZUFJJQ0VBUElfS0VZIjoiIn19)
+
+Or add to `.cursor/mcp.json` manually:
+
+```json
+{
+  "mcpServers": {
+    "commoditypriceapi": {
+      "command": "npx",
+      "args": ["-y", "@commoditypriceapi/mcp"],
+      "env": {
+        "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor after saving.
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "commoditypriceapi": {
+      "command": "npx",
+      "args": ["-y", "@commoditypriceapi/mcp"],
+      "env": {
+        "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
+      }
+    }
+  }
+}
+```
+
+Restart Windsurf after saving.
+
+### VS Code / GitHub Copilot
+
+Add to your VS Code `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "commoditypriceapi": {
+        "command": "npx",
+        "args": ["-y", "@commoditypriceapi/mcp"],
+        "env": {
+          "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
+        }
+      }
+    }
+  }
+}
+```
+
+Restart VS Code after saving.
+
+### Cline
+
+Open MCP Servers panel → **Configure** → **Advanced MCP Settings**. Add to `cline_mcp_settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "commoditypriceapi": {
+      "command": "npx",
+      "args": ["-y", "@commoditypriceapi/mcp"],
+      "env": {
+        "COMMODITYPRICEAPI_KEY": "<YOUR_API_KEY>"
+      }
+    }
+  }
+}
+```
+
+Restart Cline after saving.
+
+### Codex CLI
+
+```bash
+codex mcp add commoditypriceapi --env COMMODITYPRICEAPI_KEY=<YOUR_API_KEY> -- npx -y @commoditypriceapi/mcp
+codex mcp list
+```
+
+Start a new Codex session after adding the server.
+
+### Any Other MCP Client
+
+Use this config:
 
 ```json
 {
@@ -52,38 +205,235 @@ Add the same `commoditypriceapi` block to that client's MCP server config file a
 }
 ```
 
-## Tools
+## Verify It Works
+
+Try these after setup:
+
+| Prompt | Expected tool |
+|--------|---------------|
+| What's the current gold price? | `get_gold_price` |
+| Get the latest silver and Brent crude prices. | `get_latest_rates` with `symbols=XAG,BRENTOIL-SPOT` |
+| What was the gold price on January 2nd, 2020? | `get_historical_rates` |
+| Show daily gold prices for the first week of August 2026. | `get_time_series` |
+| How much did gold change between January and August 2026? | `get_fluctuation` |
+| Which commodity symbols do you support? | `list_symbols` |
+| How much of my API quota is left? | `get_usage` |
+
+## Tool Reference
+
+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 /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 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 /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. |
+
+### get_silver_price
+
+`GET /v3/rates/latest/xag` — shortcut for the latest silver (XAG) rate.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `quote` | No | Target quote currency. Premium/Plus plans only. |
+
+### get_historical_rates
+
+`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 |
+|-----------|----------|-------------|
+| `symbols` | Yes | Comma-separated symbols |
+| `date` | Yes | `YYYY-MM-DD` |
+
+### get_time_series
+
+`GET /v3/rates/time-series` — daily historical rates for one or more symbols between two dates. Max span: 1 year.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `symbols` | Yes | Comma-separated symbols |
+| `startDate` | Yes | `YYYY-MM-DD` |
+| `endDate` | Yes | `YYYY-MM-DD` |
+
+### get_fluctuation
+
+`GET /v3/rates/fluctuation` — how each symbol changed between two dates: start rate, end rate, absolute change, and percent change.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `symbols` | Yes | Comma-separated symbols |
+| `startDate` | Yes | `YYYY-MM-DD` |
+| `endDate` | Yes | `YYYY-MM-DD` |
+
+### list_symbols
+
+`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 /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 trading at in euros?
+
+### Historical data
+
+- What was the price of wheat on January 2nd, 2026?
+- Compare gold and silver prices over the last 30 days.
+- Show me daily natural gas prices for Q1 2026.
+
+### Price changes
+
+- How much did Brent crude fluctuate this quarter?
+- Did gold go up or down since the start of the year, and by how much?
+
+### Discovery and account
+
+- Which commodity symbols do you support for energy?
+- How much of my API quota is left this month?
+
+## Example Answers and Tool Output
+
+The text answers show what a client might say; exact wording depends on the model. JSON blocks are raw tool output.
+
+### Latest gold price
+
+**Prompt:** What's the current gold price?
+
+**Example answer:** Gold (XAU) is currently trading at $4,386.23 per troy ounce (bid $4,385.93 / ask $4,386.23).
+
+```json
+{
+  "success": true,
+  "timestamp": 1786617187,
+  "rates": {
+    "XAU": {
+      "rate": 4386.23,
+      "bid": 4385.93,
+      "ask": 4386.23
+    }
+  },
+  "metadata": {
+    "XAU": {
+      "unit": "T.oz",
+      "quote": "USD"
+    }
+  }
+}
+```
+
+### Historical rate
+
+**Prompt:** What was the gold price on January 2nd, 2020?
+
+**Example answer:** On 2020-01-02, gold opened at $1,518.26 and closed at $1,528.76 per troy ounce (high $1,531.31, low $1,517.15).
+
+```json
+{
+  "success": true,
+  "date": "2020-01-02",
+  "rates": {
+    "XAU": {
+      "date": "2020-01-02",
+      "open": 1518.26,
+      "high": 1531.31,
+      "low": 1517.15,
+      "close": 1528.76
+    }
+  }
+}
+```
+
+### Fluctuation
+
+**Prompt:** How much did gold change between January 2nd and August 12th, 2026?
+
+**Example answer:** Gold rose from $4,332.01 to $4,400.12 per troy ounce — up $68.11, or +1.57%.
+
+```json
+{
+  "success": true,
+  "startDate": "2026-01-02",
+  "endDate": "2026-08-12",
+  "rates": {
+    "XAU": {
+      "startRate": 4332.01,
+      "endRate": 4400.12,
+      "change": 68.11,
+      "changePercent": 1.57
+    }
+  }
+}
+```
+
+## Error Codes
 
-| Tool                   | Endpoint                    | What it does                                                    |
-| ---------------------- | ---------------------------- | ----------------------------------------------------------------|
-| `get_usage`            | `GET /v2/usage`              | Current plan, quota, and usage                                  |
-| `list_symbols`         | `GET /v2/symbols`            | All supported commodity symbols with category/currency/unit     |
-| `get_latest_rates`     | `GET /v2/rates/latest`       | Latest rates for one or more symbols                            |
-| `get_gold_price`       | `GET /v2/rates/latest/xau`   | Shortcut for the latest gold rate                                |
-| `get_silver_price`     | `GET /v2/rates/latest/xag`   | Shortcut for the latest silver rate                              |
-| `get_historical_rates` | `GET /v2/rates/historical`   | OHLC rates for one or more symbols on a specific past date       |
-| `get_time_series`      | `GET /v2/rates/time-series`  | Daily rates between two dates (max 1 year span)                  |
-| `get_fluctuation`      | `GET /v2/rates/fluctuation`  | Start/end rate, change, and % change over a date range           |
+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.
 
-All tools that take `symbols` accept a comma-separated list (e.g. `XAU,XAG,BRENTOIL`). Use `list_symbols` to look up valid symbols.
+| Code | Meaning |
+|------|---------|
+| `401` | Missing or invalid API key — check `COMMODITYPRICEAPI_KEY` in your client config |
+| `402` | Your trial or subscription doesn't cover this request (e.g. `quote` conversion on a non-Premium plan) |
+| `403` | API key usage limit reached — upgrade or wait for quota reset |
+| `404` | Symbol not found — call `list_symbols` for valid symbols |
+| `429` | Rate limited — wait a minute and retry |
+| `499` | Request to the upstream API timed out (see `COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS`) |
+| `502` | Server could not reach the upstream API |
+
+Example error result for an invalid symbol:
+
+```json
+{
+  "error": "SYMBOL_NOT_FOUND",
+  "code": 404,
+  "message": "The symbol is not supported, please visit the documentation for a list of supported symbols",
+  "guidance": "Call list_symbols to see valid commodity symbols."
+}
+```
 
-## Authentication
+## How It Works
 
-The server sends your API key to CommodityPriceAPI via **both** the `x-api-key` header and the `apiKey` query parameter — the upstream API accepts either, so this covers all cases without extra config.
+This is a stdio MCP server that wraps the CommodityPriceAPI v3 REST API.
 
-| Variable                 | Required | Description                       |
-| ------------------------ | -------- | ---------------------------------- |
-| `COMMODITYPRICEAPI_KEY`  | Yes      | Your CommodityPriceAPI key         |
-| `COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS` | No | Upstream request timeout in ms (default `15000`) |
+At runtime:
 
-## Error Handling
+1. Your MCP client starts the server process via `npx`.
+2. The client reads the tool list.
+3. When a prompt matches a tool, the client calls it.
+4. The server validates inputs, calls the CommodityPriceAPI, and returns structured JSON.
 
-Tool calls never crash the server. Upstream errors (invalid symbol, missing date, quota exceeded, etc.) are returned as structured tool results with `error`, `code`, `message`, and a `guidance` field so the client can explain what went wrong instead of just echoing a status code.
+The server sends your API key to CommodityPriceAPI via both the `x-api-key` header and the `apiKey` query parameter — the upstream API accepts either, so this covers all cases without extra config.
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `COMMODITYPRICEAPI_KEY` | Yes | | Your CommodityPriceAPI key |
+| `COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS` | No | `15000` | Upstream request timeout in ms |
 
 ## Building from Source
 
 ```bash
-git clone https://github.com/commoditypriceapi/commoditypriceapi-mcp.git
+git clone https://github.com/Commodity-Price-API/commoditypriceapi-mcp.git
 cd commoditypriceapi-mcp
 npm install
 npm run build
@@ -101,6 +451,30 @@ Inspect with the MCP Inspector:
 COMMODITYPRICEAPI_KEY=<YOUR_KEY> npx @modelcontextprotocol/inspector node dist/cli.js
 ```
 
+## Troubleshooting
+
+**Client uses an old tool list after updating:** Restart the client and confirm it loaded the latest npm version.
+
+**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:** 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).
+
+## Pricing
+
+Free 7-day trial with 2,000 requests, no card required. For plan details, see the [CommodityPriceAPI pricing page](https://commoditypriceapi.com/pricing).
+
+## Links
+
+- [CommodityPriceAPI Website](https://commoditypriceapi.com)
+- [API Documentation](https://commoditypriceapi.com/docs)
+- [Supported Symbols](https://commoditypriceapi.com/symbols)
+- [MCP Integration Guide](https://commoditypriceapi.com/integrations/mcp)
+- [Pricing](https://commoditypriceapi.com/pricing)
+- [Sign Up Free](https://commoditypriceapi.com/auth/signup)
+- [GitHub Repository](https://github.com/Commodity-Price-API/commoditypriceapi-mcp)
+
 ## License
 
-MIT
+[MIT](LICENSE)

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'. See the list_symbols tool for valid values.");
+    .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.0",
+        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.0",
+  "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",
@@ -13,10 +13,10 @@
     "ai-tools"
   ],
   "homepage": "https://commoditypriceapi.com",
-  "bugs": "https://github.com/commoditypriceapi/commoditypriceapi-mcp/issues",
+  "bugs": "https://github.com/Commodity-Price-API/commoditypriceapi-mcp/issues",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/commoditypriceapi/commoditypriceapi-mcp.git"
+    "url": "git+https://github.com/Commodity-Price-API/commoditypriceapi-mcp.git"
   },
   "license": "MIT",
   "author": "CommodityPriceAPI",