@coinpaprika/mcp 1.1.1 → 1.2.0

package/dist/index.js

@@ -32,6 +32,21 @@ const ErrorCodes = {
 // Coin ID validation regex
 const COIN_ID_REGEX = /^[a-z0-9]+-[a-z0-9-]+$/;
 
+// Canonical-slug guidance shared by every tool that takes a coin id. Agents
+// kept passing ticker symbols ("BTC") or guessing slugs, then retry-looping on
+// "resource not found" (devrel#5). The slug is NOT derivable from the symbol,
+// so steer them to search / resolveId first.
+const COIN_ID_DESCRIPTION =
+  "Canonical CoinPaprika coin slug in 'symbol-name' format, e.g. 'btc-bitcoin', " +
+  "'eth-ethereum', 'ada-cardano'. Do NOT pass ticker symbols ('BTC', 'AAVE') " +
+  "or guess the slug — it is not derivable from the symbol (e.g. AAVE resolves " +
+  "to 'aave-new', which you could not guess). Call search or resolveId first to " +
+  "resolve a symbol or name to its canonical id.";
+
+// Known misspellings, surfaced in getCapabilities so MCP catalogs / tool
+// routers / agent frameworks can match fuzzy references back to us (devrel#6).
+const SERVER_ALIASES = ["coinparika", "coinpapika", "coinaprika", "coin-paprika", "coin paprika"];
+
 // Structured error response builder
 function buildErrorResponse(code, message, retryable, suggestion, correctedExample, metadata) {
   const error = {
@@ -97,7 +112,7 @@ function parseAPIError(status, statusText, endpoint) {
       ErrorCodes.CP404_NOT_FOUND,
       'Resource not found',
       false,
-      'The requested resource does not exist. Check the ID format and try again',
+      'No resource with that id exists — it may be misspelled, retired, or for a different entity. Call search or resolveId to get the current canonical id, then retry.',
       undefined,
       { endpoint }
     );
@@ -260,6 +275,7 @@ async function withGuidance(exec, hint) {
 function buildCapabilitiesDocument() {
   return {
     service: "coinpaprika",
+    aliases: SERVER_ALIASES,
     version: SERVER_VERSION,
     description: "Cryptocurrency market data for 8000+ coins",
     server: {
@@ -721,6 +737,34 @@ const server = new McpServer({
   description: 'MCP server for accessing CoinPaprika cryptocurrency market data',
 });
 
+// devrel#5 parity: validate coin/currency id format BEFORE the handler runs,
+// returning the structured CP400_INVALID_COIN_ID guidance (matches the hosted
+// MCP). Wrapping server.tool centralizes this for every id-bearing tool
+// (coinId / baseCurrencyId / quoteCurrencyId) instead of repeating it in each
+// handler — so a ticker symbol like "BTC" gets actionable guidance to call
+// search/resolveId instead of a bare upstream 404.
+const _registerTool = server.tool.bind(server);
+server.tool = (...regArgs) => {
+  const handler = regArgs[regArgs.length - 1];
+  const schema = regArgs.length >= 4 && regArgs[2] && typeof regArgs[2] === 'object' ? regArgs[2] : null;
+  if (typeof handler === 'function' && schema) {
+    const idFields = ['coinId', 'baseCurrencyId', 'quoteCurrencyId'].filter((f) => f in schema);
+    if (idFields.length > 0) {
+      regArgs[regArgs.length - 1] = async (args, ...rest) => {
+        for (const f of idFields) {
+          const v = args && args[f];
+          if (typeof v === 'string') {
+            const err = validateCoinId(v);
+            if (err) return formatMcpError(err);
+          }
+        }
+        return handler(args, ...rest);
+      };
+    }
+  }
+  return _registerTool(...regArgs);
+};
+
 // ─── Tool 1: status ───
 server.tool(
   'status',
@@ -801,7 +845,7 @@ server.tool(
   'getCoinOHLCVLatest',
   'OHLCV last full day',
   {
-    coinId: z.string().describe("Coin ID in format: symbol-name (e.g., btc-bitcoin)"),
+    coinId: z.string().describe(COIN_ID_DESCRIPTION),
     quote: z.string().optional().default('usd').describe("Quote currency (default: usd)")
   },
   async ({ coinId, quote = 'usd' }) => {
@@ -819,7 +863,7 @@ server.tool(
   'getCoinOHLCVToday',
   'OHLCV today',
   {
-    coinId: z.string().describe("Coin ID in format: symbol-name (e.g., btc-bitcoin)"),
+    coinId: z.string().describe(COIN_ID_DESCRIPTION),
     quote: z.string().optional().default('usd').describe("Quote currency (default: usd)")
   },
   async ({ coinId, quote = 'usd' }) => {
@@ -837,7 +881,7 @@ server.tool(
   'getCoinOHLCVHistorical',
   'OHLCV historical (plan-dependent)',
   {
-    coinId: z.string().describe("Coin ID in format: symbol-name (e.g., btc-bitcoin)"),
+    coinId: z.string().describe(COIN_ID_DESCRIPTION),
     start: z.string().describe("Start date (ISO 8601 or yyyy-mm-dd)"),
     end: z.string().optional().describe("End date (ISO 8601 or yyyy-mm-dd)"),
     limit: z.number().optional().default(50).describe("Number of data points (default: 50, max: 250)"),
@@ -858,7 +902,7 @@ server.tool(
 server.tool(
   'getCoinById',
   'Coin details (descriptive info)',
-  { coinId: z.string().describe("Coin ID in format: symbol-name (e.g., btc-bitcoin)") },
+  { coinId: z.string().describe(COIN_ID_DESCRIPTION) },
   async ({ coinId }) => {
     try {
       const response = await fetchFromAPI(`/coins/${encodeURIComponent(coinId)}`);
@@ -874,7 +918,7 @@ server.tool(
   'getCoinEvents',
   'Events for a coin',
   {
-    coinId: z.string().describe("Coin ID in format: symbol-name (e.g., btc-bitcoin)"),
+    coinId: z.string().describe(COIN_ID_DESCRIPTION),
     limit: z.number().optional().default(50).describe("Number of events to return (default: 50, max: 250)")
   },
   async ({ coinId, limit = 50 }) => {
@@ -895,7 +939,7 @@ server.tool(
   'getCoinExchanges',
   'Exchanges for a coin',
   {
-    coinId: z.string().describe("Coin ID in format: symbol-name (e.g., btc-bitcoin)"),
+    coinId: z.string().describe(COIN_ID_DESCRIPTION),
     limit: z.number().optional().default(50).describe("Number of exchanges to return (default: 50, max: 250)")
   },
   async ({ coinId, limit = 50 }) => {
@@ -916,7 +960,7 @@ server.tool(
   'getCoinMarkets',
   'Markets for a coin',
   {
-    coinId: z.string().describe("Coin ID in format: symbol-name (e.g., btc-bitcoin)"),
+    coinId: z.string().describe(COIN_ID_DESCRIPTION),
     quotes: z.string().optional().describe("Comma-separated quote currencies"),
     limit: z.number().optional().default(50).describe("Number of markets to return (default: 50, max: 250)")
   },
@@ -939,7 +983,7 @@ server.tool(
   'getTickersById',
   'Ticker for a specific coin',
   {
-    coinId: z.string().describe("Coin ID in format: symbol-name (e.g., btc-bitcoin)"),
+    coinId: z.string().describe(COIN_ID_DESCRIPTION),
     quotes: z.string().optional().describe("Comma-separated quote currencies")
   },
   async ({ coinId, quotes }) => {
@@ -958,7 +1002,7 @@ server.tool(
   'getTickersHistoricalById',
   'Historical ticks for a coin (plan dependent)',
   {
-    coinId: z.string().describe("Coin ID in format: symbol-name (e.g., btc-bitcoin)"),
+    coinId: z.string().describe(COIN_ID_DESCRIPTION),
     start: z.string().describe("Start date (ISO 8601 or yyyy-mm-dd)"),
     end: z.string().optional().describe("End date"),
     limit: z.number().optional().default(50).describe("Number of data points (default: 50, max: 250)"),
@@ -1228,8 +1272,8 @@ server.tool(
   'priceConverter',
   'Convert base -> quote',
   {
-    baseCurrencyId: z.string().describe("Base currency ID (e.g., btc-bitcoin)"),
-    quoteCurrencyId: z.string().describe("Quote currency ID (e.g., usd-us-dollars)"),
+    baseCurrencyId: z.string().describe("Required. Source CoinPaprika coin slug (e.g., 'btc-bitcoin'). Full slugs only; ticker symbols like 'BTC' are rejected upstream. Call search or resolveId first."),
+    quoteCurrencyId: z.string().describe("Required. Target CoinPaprika coin slug (e.g., 'usd-us-dollars', 'eth-ethereum'). Full slugs only; ticker symbols like 'USD' are rejected upstream."),
     amount: z.number().optional().default(0).describe("Amount to convert (default: 0)")
   },
   async ({ baseCurrencyId, quoteCurrencyId, amount = 0 }) => {
@@ -1280,7 +1324,10 @@ server.tool(
   },
   async (params) => {
     const qs = new URLSearchParams();
-    for (const [k, v] of Object.entries(params)) {
+    // Allowlist the upstream-recognized mapping params only — never forward
+    // MCP-only or unexpected fields, which the upstream rejects with a 400.
+    for (const k of ['coinpaprika', 'coinmarketcap', 'coingecko', 'cryptocompare', 'isin', 'dti']) {
+      const v = params[k];
       if (v) qs.set(k, String(v));
     }
     return withGuidance(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinpaprika/mcp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "A Model Context Protocol server for CoinPaprika cryptocurrency market data — prices, tickers, exchanges, and more",
   "main": "dist/index.js",
   "type": "module",