@coinpaprika/mcp 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to the CoinPaprika MCP Server will be documented in this file.
 
+## [1.3.0] - 2026-07-27
+
+### Changed
+
+- **Intent-first tool descriptions.** Every tool description was rewritten so agents select the right tool from the description alone, each leading with what the tool returns plus `Use when asked '...'` cues (e.g. `getTickers` vs `getCoinById` vs `getContracts`). Matches the descriptions now served by the hosted worker at `mcp.coinpaprika.com`, so hosted and self-host read identically.
+- `getCapabilities` description aligned with the hosted worker (onboarding-first wording; clarifies it describes the MCP server itself, not crypto data).
+
+### Added
+
+- `server.json` manifest for publication to the official MCP Registry (`registry.modelcontextprotocol.io`).
+
 ## [1.1.1] - 2026-05-05
 
 ### Fixed

package/README.md

@@ -12,7 +12,7 @@ npm install -g @coinpaprika/mcp
 coinpaprika-mcp
 
 # Or run directly without installation
-npx @coinpaprika/mcp
+npx @coinpaprika/mcp@latest
 ```
 
 CoinPaprika MCP connects Claude to live crypto market data for 8,000+ coins. No API key required for free-tier features. [Installation](#installation) | [Configuration](#claude-desktop-integration) | [API Reference](https://api.coinpaprika.com)
@@ -25,7 +25,7 @@ CoinPaprika MCP connects Claude to live crypto market data for 8,000+ coins. No
 - **Coin Analysis Tools**: Deep-dive into any cryptocurrency — price, team, events, exchanges, and markets
 - **Price Trackers**: Track prices across multiple quote currencies with historical OHLCV data
 - **Exchange Comparisons**: Compare trading pairs and volumes across 200+ exchanges
-- **Portfolio Valuations**: Convert between currencies and track price changes over time
+- **Portfolio Valuations**: Convert an amount between currencies ('0.5 BTC in USD') and track price changes over time
 - **Contract Lookup**: Find tokens by their smart contract address across multiple platforms
 
 ## Installation
@@ -59,7 +59,7 @@ Add the following to your Claude Desktop configuration file:
   "mcpServers": {
     "coinpaprika": {
       "command": "npx",
-      "args": ["@coinpaprika/mcp"]
+      "args": ["@coinpaprika/mcp@latest"]
     }
   }
 }
@@ -72,7 +72,7 @@ Add the following to your Claude Desktop configuration file:
   "mcpServers": {
     "coinpaprika": {
       "command": "npx",
-      "args": ["@coinpaprika/mcp"],
+      "args": ["@coinpaprika/mcp@latest"],
       "env": {
         "COINPAPRIKA_API_KEY": "your-api-key-here"
       }
@@ -85,10 +85,10 @@ Add the following to your Claude Desktop configuration file:
 
 ```bash
 # Add as MCP server in Claude Code
-claude mcp add coinpaprika -- npx @coinpaprika/mcp
+claude mcp add coinpaprika -- npx @coinpaprika/mcp@latest
 
 # With API key
-COINPAPRIKA_API_KEY=your-key claude mcp add coinpaprika -- npx @coinpaprika/mcp
+COINPAPRIKA_API_KEY=your-key claude mcp add coinpaprika -- npx @coinpaprika/mcp@latest
 ```
 
 ### Hosted Alternative (No Installation)
@@ -122,27 +122,27 @@ If you prefer zero setup, point any MCP-compatible client directly at the hosted
 |------|-------------|
 | `getCapabilities` | Server capabilities, workflow patterns, validation rules, and best practices. **Start here.** |
 | `status` | Server status and configuration |
-| `getGlobal` | Global crypto market overview (market cap, volume, BTC dominance) |
+| `getGlobal` | Global market overview: total market cap, 24h volume, BTC dominance ('how is the market doing') |
 
 ### Coins
 
 | Tool | Description | Required Parameters |
 |------|-------------|---------------------|
-| `getCoins` | List all coins (id, name, symbol, rank) | — |
-| `getCoinById` | Coin details (description, team, links) | `coinId` |
+| `getCoins` | List all coins (id, name, symbol, rank); no prices, use getTickers for prices | — |
+| `getCoinById` | Coin project details (description, team, links); no price, use getTickersById | `coinId` |
 | `getCoinEvents` | Upcoming events for a coin | `coinId` |
 | `getCoinExchanges` | Exchanges listing a coin | `coinId` |
-| `getCoinMarkets` | Markets/trading pairs for a coin | `coinId` |
+| `getCoinMarkets` | Markets/exchanges trading a coin ('where to buy X', 'X price on Binance') | `coinId` |
 
 ### Tickers & Prices
 
 | Tool | Description | Required Parameters |
 |------|-------------|---------------------|
-| `getTickers` | All tickers with price quotes | — |
-| `getTickersById` | Ticker for a specific coin | `coinId` |
-| `getCoinOHLCVLatest` | OHLCV for the last full day | `coinId` |
-| `getCoinOHLCVToday` | OHLCV for today (in progress) | `coinId` |
-| `priceConverter` | Convert between currencies | `baseCurrencyId`, `quoteCurrencyId` |
+| `getTickers` | Current prices + market caps for top coins by market cap ('top 5 coins', market snapshot) | — |
+| `getTickersById` | Current price, market cap & 24h change of one coin ('BTC price', 'how much is ETH') | `coinId` |
+| `getCoinOHLCVLatest` | Latest full-day OHLC candle (not the live price) | `coinId` |
+| `getCoinOHLCVToday` | Today's in-progress OHLC candle | `coinId` |
+| `priceConverter` | Convert an amount between currencies ('0.5 BTC in USD') | `baseCurrencyId`, `quoteCurrencyId` |
 
 ### Exchanges
 
@@ -166,14 +166,14 @@ If you prefer zero setup, point any MCP-compatible client directly at the hosted
 |------|-------------|---------------------|
 | `getPlatforms` | List contract platforms | — |
 | `getContracts` | Contracts on a platform | `platformId` |
-| `getTickerByContract` | Ticker by contract address | `platformId`, `contractAddress` |
+| `getTickerByContract` | Token price by contract address (on-chain/DeFi tokens) | `platformId`, `contractAddress` |
 
 ### Search & Resolution
 
 | Tool | Description | Required Parameters |
 |------|-------------|---------------------|
-| `search` | Search coins, exchanges, ICOs, people, tags | `q` |
-| `resolveId` | Resolve fuzzy query to canonical CoinPaprika IDs | `type`, `query` |
+| `search` | Search coins/exchanges/people/tags by name; use FIRST to get an id | `q` |
+| `resolveId` | Resolve a name/symbol to canonical id; call FIRST before price tools | `type`, `query` |
 
 ### Paid-Tier Tools
 
@@ -198,7 +198,7 @@ export COINPAPRIKA_API_KEY=your-api-key-here
 coinpaprika-mcp
 
 # Or pass inline
-COINPAPRIKA_API_KEY=your-api-key-here npx @coinpaprika/mcp
+COINPAPRIKA_API_KEY=your-api-key-here npx @coinpaprika/mcp@latest
 ```
 
 Get an API key at [coinpaprika.com/api/pricing](https://coinpaprika.com/api/pricing/).

package/dist/index.js

@@ -1,10 +1,12 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createRequire } from 'module';
 import fetch from 'node-fetch';
 import { z } from 'zod';
 
-// Server version
-const SERVER_VERSION = '1.0.0';
+// Server version, read from package.json so the banner, capabilities
+// document, and status tool always report the published version.
+const SERVER_VERSION = createRequire(import.meta.url)('../package.json').version;
 
 // Optional API key from environment
 const API_KEY = process.env.COINPAPRIKA_API_KEY || '';
@@ -32,6 +34,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 +114,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,18 +277,19 @@ async function withGuidance(exec, hint) {
 function buildCapabilitiesDocument() {
   return {
     service: "coinpaprika",
+    aliases: SERVER_ALIASES,
     version: SERVER_VERSION,
-    description: "Cryptocurrency market data for 8000+ coins",
+    description: "Real-time cryptocurrency prices and market data for 12,000+ coins",
     server: {
       name: "CoinPaprika MCP Server",
       version: SERVER_VERSION,
-      description: "Cryptocurrency market data — prices, tickers, exchanges, OHLCV, and more",
+      description: "Real-time cryptocurrency prices, market caps, 24h changes and volumes for 12,000+ coins (Bitcoin, Ethereum, Solana, and more) and 350+ exchanges. Use for how much a crypto is worth, top coins by market cap, or live market data.",
       documentation_url: "https://api.coinpaprika.com",
     },
     tools: [
       {
         name: "status",
-        description: "Server status and configuration",
+        description: "Get the CoinPaprika MCP server's status and configuration (uptime, mode, enabled features). Use when asked 'is the server up', 'what mode am I in', 'server status'. This reports the MCP server itself, not the crypto market; for market health use getGlobal.",
         category: "system",
         parameters: {},
         returns: { type: "object" },
@@ -279,7 +297,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getGlobal",
-        description: "Get global cryptocurrency market statistics",
+        description: "Get a global crypto market overview: total market cap, total 24h volume, Bitcoin dominance, and market-wide 24h change. Use for 'how is the crypto market doing', 'total market cap', 'BTC dominance'. For a single coin's price use getTickersById.",
         category: "market",
         parameters: {},
         returns: { type: "object", properties: ["market_cap_usd", "volume_24h_usd", "bitcoin_dominance_percentage"] },
@@ -287,7 +305,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getCoins",
-        description: "List all available coins",
+        description: "List available coins (id, name, symbol, rank). Use to discover coins or map a name to an id. Does NOT include prices; for prices use getTickers or getTickersById.",
         category: "coins",
         parameters: { limit: { type: "integer", required: false, default: 50, min: 1, max: 250 } },
         returns: { type: "array", items: "Coin" },
@@ -295,7 +313,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getTickers",
-        description: "Get market data for all active cryptocurrencies",
+        description: "Get current prices, market caps and 24h changes for the top cryptocurrencies ranked by market cap. Use for 'top 5 coins', 'top crypto today', 'biggest cryptocurrencies', or a market snapshot. For one specific coin use getTickersById.",
         category: "market",
         parameters: {
           quotes: { type: "string", required: false, default: "USD", description: "Comma-separated quote currencies" },
@@ -306,7 +324,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getCoinOHLCVLatest",
-        description: "Get OHLCV data for last full day",
+        description: "Get the latest full-day OHLC candle (open/high/low/close plus volume) for a coin. For the live spot price use getTickersById.",
         category: "coins",
         parameters: {
           coinId: { type: "string", required: true, format: "coin-id", example: "btc-bitcoin" },
@@ -317,7 +335,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getCoinOHLCVToday",
-        description: "Get OHLCV data for today",
+        description: "Get today's in-progress OHLC candle for a coin. For the current spot price use getTickersById; for past candles use getCoinOHLCVHistorical.",
         category: "coins",
         parameters: {
           coinId: { type: "string", required: true, format: "coin-id" },
@@ -328,7 +346,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getCoinOHLCVHistorical",
-        description: "Get historical OHLCV data (requires Starter+ plan)",
+        description: "Get OHLC candles (open/high/low/close plus volume) for a coin over a date range, for price charts, backtests and technical analysis. Use for 'daily chart for the last month', 'hourly candles since Jan 1'. For a single past date's spot value use getTickersHistoricalById; not for the current price. Requires Starter+ plan.",
         category: "coins",
         parameters: {
           coinId: { type: "string", required: true, format: "coin-id" },
@@ -343,7 +361,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getCoinById",
-        description: "Get detailed information about a specific cryptocurrency",
+        description: "Get descriptive project information about a coin (description, links, team, tags). Does NOT include price; for price/market cap use getTickersById.",
         category: "coins",
         parameters: { coinId: { type: "string", required: true, format: "coin-id", example: "btc-bitcoin" } },
         returns: { type: "object", properties: ["id", "name", "symbol", "description", "links", "rank"] },
@@ -351,7 +369,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getCoinEvents",
-        description: "Get events for a specific coin",
+        description: "Get the timeline of events for a coin (launches, partnerships, hard forks, conference talks) with dates and descriptions. Use when asked 'what is happening with X', 'upcoming events for Ethereum', 'X roadmap events'. For prices or market data use getTickersById.",
         category: "coins",
         parameters: {
           coinId: { type: "string", required: true, format: "coin-id" },
@@ -362,7 +380,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getCoinExchanges",
-        description: "Get exchanges where a coin is traded",
+        description: "List the exchanges that LIST a specific coin (venue names only). Use for 'which exchanges list X', 'is X on Coinbase', 'where is X listed'. For where to BUY with per-market price and volume use getCoinMarkets; for the coin's live price use getTickersById.",
         category: "coins",
         parameters: {
           coinId: { type: "string", required: true, format: "coin-id" },
@@ -373,7 +391,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getCoinMarkets",
-        description: "Get markets for a specific coin",
+        description: "Get the specific markets and trading pairs where a coin trades, with per-market price and 24h volume. Use for 'where can I buy X', 'X price on Binance', 'best market for X'. For just the list of exchange names use getCoinExchanges.",
         category: "coins",
         parameters: {
           coinId: { type: "string", required: true, format: "coin-id" },
@@ -385,7 +403,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getTickersById",
-        description: "Get ticker data for a specific coin",
+        description: "Get the current price, market cap, 24h change and volume of a specific cryptocurrency in USD (or another quote currency). Use when asked 'what is the price of X', 'how much is Bitcoin worth', 'BTC to USD', 'ETH price now'. For past prices use getTickersHistoricalById.",
         category: "market",
         parameters: {
           coinId: { type: "string", required: true, format: "coin-id" },
@@ -396,7 +414,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getTickersHistoricalById",
-        description: "Get historical ticker data (requires Starter+ plan)",
+        description: "Get a coin's price and market cap at a single past date or time (a point-in-time value). Use for 'price of BTC last Tuesday', 'ETH market cap on 2024-01-01'. For OHLC chart candles over a range use getCoinOHLCVHistorical, not this. Not for the current price (use getTickersById). Requires Starter+ plan.",
         category: "market",
         parameters: {
           coinId: { type: "string", required: true, format: "coin-id" },
@@ -411,7 +429,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getPeopleById",
-        description: "Get information about a person in crypto space",
+        description: "Get profile information about a person in crypto (bio, roles, linked projects and accounts). Use when asked 'who is Vitalik Buterin', 'background on X founder', 'projects tied to this person'. Look up the person id first with search.",
         category: "people",
         parameters: { personId: { type: "string", required: true } },
         returns: { type: "object" },
@@ -419,7 +437,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getTags",
-        description: "Get list of all tags",
+        description: "List all CoinPaprika tags (categories such as defi, stablecoin, memecoin, ai) used to group coins. Use when asked 'what categories exist', 'list crypto sectors', or to find a tag id before calling getTagById.",
         category: "tags",
         parameters: {
           additionalFields: { type: "string", required: false },
@@ -430,7 +448,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getTagById",
-        description: "Get details about a specific tag",
+        description: "Get details for a specific tag: its description and the coins and ICOs grouped under it. Use when asked 'what coins are in the defi tag', 'show the stablecoin category', 'tokens tagged X'. Get the tag id first from getTags.",
         category: "tags",
         parameters: {
           tagId: { type: "string", required: true },
@@ -441,7 +459,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getExchanges",
-        description: "Get list of all exchanges",
+        description: "List all exchanges tracked by CoinPaprika with rank, trust score and volume. Use when asked 'top exchanges', 'biggest crypto exchanges', 'list exchanges by volume', or to find an exchange id before calling getExchangeByID.",
         category: "exchanges",
         parameters: {
           quotes: { type: "string", required: false },
@@ -452,7 +470,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getExchangeByID",
-        description: "Get details about a specific exchange",
+        description: "Get details for a specific exchange (volume, market count, trust score, links, fiat support). Use when asked 'tell me about Binance', 'Coinbase exchange stats', 'is X a trustworthy exchange'. For the pairs traded there use getExchangeMarkets; find the exchange id first with search or getExchanges.",
         category: "exchanges",
         parameters: {
           exchangeId: { type: "string", required: true },
@@ -463,7 +481,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getExchangeMarkets",
-        description: "Get markets on a specific exchange",
+        description: "List the trading pairs (markets) on a specific exchange with price and 24h volume per pair. Use when asked 'what pairs trade on Binance', 'markets on Kraken', 'BTC pairs on X exchange'. For exchange-level stats use getExchangeByID.",
         category: "exchanges",
         parameters: {
           exchangeId: { type: "string", required: true },
@@ -475,7 +493,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getPlatforms",
-        description: "Get list of contract platforms",
+        description: "List the smart-contract platforms (blockchains such as ethereum, bnb, polygon) for which CoinPaprika indexes token contracts. Use when asked 'which chains are supported for contract lookups', 'list contract platforms', or to pick a platform id before calling getContracts.",
         category: "contracts",
         parameters: { limit: { type: "integer", required: false, default: 50 } },
         returns: { type: "array", items: "Platform" },
@@ -483,7 +501,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getContracts",
-        description: "Get contracts for a specific platform",
+        description: "List the token contract addresses tracked on a specific platform, mapping each contract to its CoinPaprika coin id. Use when asked 'contracts on ethereum', 'what tokens does X chain have', or to map a contract address to a coin id. Get the platform id first from getPlatforms; for a single contract's price use getTickerByContract.",
         category: "contracts",
         parameters: {
           platformId: { type: "string", required: true },
@@ -494,7 +512,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getTickerByContract",
-        description: "Get ticker by contract address",
+        description: "Get the current price and market data of a token by its contract address (for on-chain and DeFi tokens). Use when you have a 0x... or contract address rather than a name. For history use getHistoricalTickerByContract.",
         category: "contracts",
         parameters: {
           platformId: { type: "string", required: true },
@@ -505,7 +523,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getHistoricalTickerByContract",
-        description: "Get historical ticker by contract address (requires Starter+ plan)",
+        description: "Get historical price and market data of a token by its contract address. Not for the current price (use getTickerByContract). Requires Starter+ plan.",
         category: "contracts",
         parameters: {
           platformId: { type: "string", required: true },
@@ -521,7 +539,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "search",
-        description: "Search for currencies, exchanges, ICOs, people, and tags",
+        description: "Broadly search CoinPaprika across coins, exchanges, ICOs, people and tags by name or symbol when the entity type is unknown or you are exploring. Use for 'find anything called X'. If you specifically need a coin's canonical id to fetch its price, prefer resolveId.",
         category: "search",
         parameters: {
           q: { type: "string", required: true },
@@ -534,7 +552,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "resolveId",
-        description: "Resolve fuzzy query to canonical coin/exchange/people/tag IDs",
+        description: "Resolve a coin name or symbol ('bitcoin', 'BTC', 'AAVE') to its single canonical CoinPaprika id ('btc-bitcoin', 'aave-new'). Call this FIRST whenever you have a bare symbol or name and want the coin's price, since ids are not derivable from symbols; then pass the id to getTickersById.",
         category: "search",
         parameters: {
           type: { type: "string", required: true, enum: ["coin", "exchange", "people", "tags"] },
@@ -546,7 +564,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "priceConverter",
-        description: "Convert amount from base currency to quote currency",
+        description: "Convert an amount from one crypto or fiat to another at the current rate ('how much is 0.5 BTC in USD', 'convert 100 USDC to EUR'). For a plain coin price without an amount, use getTickersById.",
         category: "tools",
         parameters: {
           baseCurrencyId: { type: "string", required: true },
@@ -558,7 +576,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "keyInfo",
-        description: "Verify API key (requires Pro plan)",
+        description: "Get details and usage for the current CoinPaprika API key (plan, quota, requests remaining, expiry). Use when asked 'what plan am I on', 'how many requests are left', 'is my API key valid'. Requires a Pro plan.",
         category: "system",
         parameters: {},
         returns: { type: "object" },
@@ -566,7 +584,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getMappings",
-        description: "Get API ID mappings (requires Business plan)",
+        description: "Get mappings between CoinPaprika ids and external or legacy identifiers so you can reconcile ids across systems. Use when asked 'map CoinPaprika ids to X', 'id crosswalk', 'external id mapping'. Requires a Business plan.",
         category: "system",
         parameters: {
           coinpaprika: { type: "string", required: false },
@@ -581,7 +599,7 @@ function buildCapabilitiesDocument() {
       },
       {
         name: "getChangelogIDs",
-        description: "Get changelog IDs (requires Starter+ plan)",
+        description: "Get the ids of recent changes to CoinPaprika's coin and exchange listings (additions, renames, delistings) for syncing a local dataset. Use when asked 'what changed recently', 'new or delisted coins', 'listing changelog'. Requires a Starter+ plan.",
         category: "system",
         parameters: {
           page: { type: "integer", required: false, default: 1 },
@@ -652,7 +670,7 @@ function buildCapabilitiesDocument() {
         steps: [
           "getPlatforms - List available contract platforms",
           "getContracts - List contracts on a platform",
-          "getTickerByContract - Get ticker by contract address",
+          "getTickerByContract - Get the current price and market data of a token by its contract address (for on-chain/DeFi tokens). Use when you have a 0x.../contract address rather than a name. For history use getHistoricalTickerByContract.",
         ],
         example_use_case: "Looking up an ERC-20 token by its Ethereum contract",
       },
@@ -721,6 +739,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 +847,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 +865,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 +883,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 +904,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 +920,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 +941,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 +962,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 +985,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 +1004,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 +1274,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 +1326,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(
@@ -1309,7 +1358,7 @@ server.tool(
 // ─── Tool 30: getCapabilities ───
 server.tool(
   'getCapabilities',
-  'Return server capabilities, workflow patterns, validation rules, and best-practice sequences. Use this to onboard agents quickly.',
+  "Get the server's capabilities, supported workflow patterns, validation rules and recommended tool sequences. Use FIRST to onboard as an agent, or when asked 'what can this server do', 'how should I chain these tools', 'what are the parameter rules'. This describes the MCP server itself, not crypto data.",
   {},
   async () => {
     try {

package/package.json

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