@coinpaprika/mcp 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to the CoinPaprika MCP Server will be documented in this file.
 
+## [1.3.1] - 2026-07-29
+
+### Changed
+
+- **Registered tool descriptions now carry the full intent-first text.** The 1.3.0 rewrite reached the `getCapabilities` manifest and the hosted worker, but the actual `server.tool()` registrations still shipped two-word stubs (`"Exchange details"`, `"Tag details"`), which is what MCP clients and catalogs read from `tools/list`. All 29 data-tool descriptions were rewritten to state the action and return value, give usage guidance and sibling alternatives, disclose that every tool is read-only and note plan requirements for paid-tier tools, and add parameter intent beyond the schema. No behavior, parameter, or output change.
+
+## [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 || '';
@@ -277,17 +279,17 @@ function buildCapabilitiesDocument() {
     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" },
@@ -295,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"] },
@@ -303,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" },
@@ -311,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" },
@@ -322,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" },
@@ -333,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" },
@@ -344,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" },
@@ -359,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"] },
@@ -367,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" },
@@ -378,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" },
@@ -389,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" },
@@ -401,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" },
@@ -412,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" },
@@ -427,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" },
@@ -435,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 },
@@ -446,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 },
@@ -457,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 },
@@ -468,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 },
@@ -479,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 },
@@ -491,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" },
@@ -499,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 },
@@ -510,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 },
@@ -521,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 },
@@ -537,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 },
@@ -550,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"] },
@@ -562,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 },
@@ -574,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" },
@@ -582,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 },
@@ -597,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 },
@@ -668,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",
       },
@@ -768,7 +770,7 @@ server.tool = (...regArgs) => {
 // ─── Tool 1: status ───
 server.tool(
   'status',
-  'Server status and configuration',
+  "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. Read-only; takes no parameters and needs no API key.",
   {},
   async () => {
     const statusData = {
@@ -788,7 +790,7 @@ server.tool(
 // ─── Tool 2: getGlobal ───
 server.tool(
   'getGlobal',
-  'Market overview',
+  "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. Read-only; takes no parameters and needs no API key.",
   {},
   async () => {
     try {
@@ -803,7 +805,7 @@ server.tool(
 // ─── Tool 3: getCoins ───
 server.tool(
   'getCoins',
-  'List coins (limit, mode)',
+  "List all available coins with id, name, symbol and rank. Use to discover coins or map a name to an id. Does NOT include prices; for prices use getTickers or getTickersById. Read-only; limit caps the number of coins returned. No API key required.",
   { limit: z.number().optional().default(50).describe("Number of coins to return (default: 50, max: 250)") },
   async ({ limit = 50 }) => {
     try {
@@ -821,7 +823,7 @@ server.tool(
 // ─── Tool 4: getTickers ───
 server.tool(
   'getTickers',
-  'All tickers (quotes, limit)',
+  "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. Read-only; quotes sets the quote currencies (default USD), limit caps results. No API key required.",
   {
     quotes: z.string().optional().describe("Comma-separated quote currencies (e.g., USD,BTC,ETH)"),
     limit: z.number().optional().default(50).describe("Number of tickers to return (default: 50, max: 250)")
@@ -843,7 +845,7 @@ server.tool(
 // ─── Tool 5: getCoinOHLCVLatest ───
 server.tool(
   'getCoinOHLCVLatest',
-  'OHLCV last full day',
+  "Get the latest full-day OHLC candle (open, high, low, close and volume) for a coin. Use for 'yesterday's candle for BTC'. For the live spot price use getTickersById. Read-only; coinId must be a canonical id (resolve a bare symbol with resolveId first), quote defaults to usd. No API key required.",
   {
     coinId: z.string().describe(COIN_ID_DESCRIPTION),
     quote: z.string().optional().default('usd').describe("Quote currency (default: usd)")
@@ -861,7 +863,7 @@ server.tool(
 // ─── Tool 6: getCoinOHLCVToday ───
 server.tool(
   'getCoinOHLCVToday',
-  'OHLCV today',
+  "Get today's in-progress OHLC candle for a coin. Use for 'today's high and low for ETH'. For the current spot price use getTickersById; for past candles use getCoinOHLCVHistorical. Read-only; coinId is a canonical id (resolve with resolveId). No API key required.",
   {
     coinId: z.string().describe(COIN_ID_DESCRIPTION),
     quote: z.string().optional().default('usd').describe("Quote currency (default: usd)")
@@ -879,7 +881,7 @@ server.tool(
 // ─── Tool 7: getCoinOHLCVHistorical (paid: Starter+) ───
 server.tool(
   'getCoinOHLCVHistorical',
-  'OHLCV historical (plan-dependent)',
+  "Get OHLC candles (open, high, low, close and 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 value use getTickersHistoricalById; not for the current price. Read-only; start and end accept YYYY-MM-DD, interval sets the candle size. Requires a Starter+ plan (COINPAPRIKA_API_KEY); without a valid key the call is rejected.",
   {
     coinId: z.string().describe(COIN_ID_DESCRIPTION),
     start: z.string().describe("Start date (ISO 8601 or yyyy-mm-dd)"),
@@ -901,7 +903,7 @@ server.tool(
 // ─── Tool 8: getCoinById ───
 server.tool(
   'getCoinById',
-  'Coin details (descriptive info)',
+  "Get descriptive project information about a coin: description, links, team and tags. Use for 'tell me about Uniswap', 'what is this project'. Does NOT include price; for price and market cap use getTickersById. Read-only; coinId is a canonical id (resolve with resolveId). No API key required.",
   { coinId: z.string().describe(COIN_ID_DESCRIPTION) },
   async ({ coinId }) => {
     try {
@@ -916,7 +918,7 @@ server.tool(
 // ─── Tool 9: getCoinEvents ───
 server.tool(
   'getCoinEvents',
-  'Events for a coin',
+  "Get the timeline of events for a coin (launches, partnerships, hard forks, conference talks) with dates and descriptions. Use for 'what is happening with X', 'upcoming events for Ethereum', 'X roadmap events'. For prices use getTickersById. Read-only; coinId is a canonical id, limit caps results. No API key required.",
   {
     coinId: z.string().describe(COIN_ID_DESCRIPTION),
     limit: z.number().optional().default(50).describe("Number of events to return (default: 50, max: 250)")
@@ -937,7 +939,7 @@ server.tool(
 // ─── Tool 10: getCoinExchanges ───
 server.tool(
   'getCoinExchanges',
-  'Exchanges for a coin',
+  "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 live price use getTickersById. Read-only; coinId is a canonical id, limit caps results. No API key required.",
   {
     coinId: z.string().describe(COIN_ID_DESCRIPTION),
     limit: z.number().optional().default(50).describe("Number of exchanges to return (default: 50, max: 250)")
@@ -958,7 +960,7 @@ server.tool(
 // ─── Tool 11: getCoinMarkets ───
 server.tool(
   'getCoinMarkets',
-  'Markets for a coin',
+  "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. Read-only; coinId is a canonical id, quotes sets quote currencies, limit caps results. No API key required.",
   {
     coinId: z.string().describe(COIN_ID_DESCRIPTION),
     quotes: z.string().optional().describe("Comma-separated quote currencies"),
@@ -981,7 +983,7 @@ server.tool(
 // ─── Tool 12: getTickersById ───
 server.tool(
   'getTickersById',
-  'Ticker for a specific coin',
+  "Get the current price, market cap, 24h change and volume of one cryptocurrency in USD or another quote currency. Use for 'what is the price of X', 'how much is Bitcoin worth', 'BTC to USD', 'ETH price now'. For past prices use getTickersHistoricalById. Read-only; coinId is a canonical id (resolve a bare symbol with resolveId first), quotes sets the quote currency (default USD). No API key required.",
   {
     coinId: z.string().describe(COIN_ID_DESCRIPTION),
     quotes: z.string().optional().describe("Comma-separated quote currencies")
@@ -1000,7 +1002,7 @@ server.tool(
 // ─── Tool 13: getTickersHistoricalById (paid: Starter+) ───
 server.tool(
   'getTickersHistoricalById',
-  'Historical ticks for a coin (plan dependent)',
+  "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 for the current price (use getTickersById). Read-only; start and end accept YYYY-MM-DD, interval sets the sampling step. Requires a Starter+ plan (COINPAPRIKA_API_KEY).",
   {
     coinId: z.string().describe(COIN_ID_DESCRIPTION),
     start: z.string().describe("Start date (ISO 8601 or yyyy-mm-dd)"),
@@ -1022,7 +1024,7 @@ server.tool(
 // ─── Tool 14: getPeopleById ───
 server.tool(
   'getPeopleById',
-  'Person details',
+  "Get profile information about a person in crypto: bio, roles, and linked projects and accounts. Use for 'who is Vitalik Buterin', 'background on X founder', 'projects tied to this person'. Look up the person id first with search. Read-only; personId is a canonical id from search. No API key required.",
   { personId: z.string().describe("Person ID (e.g., vitalik-buterin)") },
   async ({ personId }) => {
     try {
@@ -1037,7 +1039,7 @@ server.tool(
 // ─── Tool 15: getTags ───
 server.tool(
   'getTags',
-  'List tags',
+  "List all CoinPaprika tags (categories such as defi, stablecoin, memecoin, ai) used to group coins. Use for 'what categories exist', 'list crypto sectors', or to find a tag id before calling getTagById. Read-only; limit caps results. No API key required.",
   {
     additionalFields: z.string().optional().describe("Comma-separated additional fields (e.g., coins,icos)"),
     limit: z.number().optional().default(50).describe("Number of tags to return (default: 50, max: 250)")
@@ -1059,7 +1061,7 @@ server.tool(
 // ─── Tool 16: getTagById ───
 server.tool(
   'getTagById',
-  'Tag details',
+  "Get details for a specific tag: its description and the coins and ICOs grouped under it. Use for 'what coins are in the defi tag', 'show the stablecoin category', 'tokens tagged X'. Get the tag id first from getTags. Read-only; tagId is a tag id from getTags. No API key required.",
   {
     tagId: z.string().describe("Tag ID (e.g., blockchain-service)"),
     additionalFields: z.string().optional().describe("Comma-separated additional fields (e.g., coins,icos)")
@@ -1078,7 +1080,7 @@ server.tool(
 // ─── Tool 17: getExchanges ───
 server.tool(
   'getExchanges',
-  'List exchanges',
+  "List all exchanges tracked by CoinPaprika with rank, trust score and 24h volume. Use for 'top exchanges', 'biggest crypto exchanges', 'list exchanges by volume', or to find an exchange id before calling getExchangeByID. Read-only; quotes sets the volume quote currency, limit caps results. No API key required.",
   {
     quotes: z.string().optional().describe("Comma-separated quote currencies"),
     limit: z.number().optional().default(50).describe("Number of exchanges to return (default: 50, max: 250)")
@@ -1100,7 +1102,7 @@ server.tool(
 // ─── Tool 18: getExchangeByID ───
 server.tool(
   'getExchangeByID',
-  'Exchange details',
+  "Get details for a specific exchange: 24h volume, market count, trust score, links and fiat support. Use for '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. Read-only; exchangeId is an exchange id such as binance. No API key required.",
   {
     exchangeId: z.string().describe("Exchange ID (e.g., binance)"),
     quotes: z.string().optional().describe("Comma-separated quote currencies")
@@ -1119,7 +1121,7 @@ server.tool(
 // ─── Tool 19: getExchangeMarkets ───
 server.tool(
   'getExchangeMarkets',
-  'Markets on exchange',
+  "List the trading pairs (markets) on a specific exchange with price and 24h volume per pair. Use for 'what pairs trade on Binance', 'markets on Kraken', 'BTC pairs on X exchange'. For exchange-level stats use getExchangeByID. Read-only; exchangeId is an exchange id, limit caps results (max 250). No API key required.",
   {
     exchangeId: z.string().describe("Exchange ID (e.g., binance)"),
     quotes: z.string().optional().describe("Comma-separated quote currencies"),
@@ -1142,7 +1144,7 @@ server.tool(
 // ─── Tool 20: getPlatforms ───
 server.tool(
   'getPlatforms',
-  'List contract platforms',
+  "List the smart-contract platforms (blockchains such as ethereum, bnb, polygon) for which CoinPaprika indexes token contracts. Use for 'which chains are supported for contract lookups', 'list contract platforms', or to pick a platform id before calling getContracts. Read-only; limit caps results. No API key required.",
   { limit: z.number().optional().default(50).describe("Number of platforms to return (default: 50, max: 250)") },
   async ({ limit = 50 }) => {
     try {
@@ -1160,7 +1162,7 @@ server.tool(
 // ─── Tool 21: getContracts ───
 server.tool(
   'getContracts',
-  'Contracts for a platform',
+  "List the token contract addresses tracked on a specific platform, mapping each contract to its CoinPaprika coin id. Use for '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. Read-only; platformId is a platform id, limit caps results. No API key required.",
   {
     platformId: z.string().describe("Platform ID (e.g., eth-ethereum)"),
     limit: z.number().optional().default(50).describe("Number of contracts to return (default: 50, max: 250)")
@@ -1181,7 +1183,7 @@ server.tool(
 // ─── Tool 22: getTickerByContract ───
 server.tool(
   'getTickerByContract',
-  'Ticker by contract address (redirect)',
+  "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 contract address (0x...) rather than a name. For history use getHistoricalTickerByContract. Read-only; platformId is the chain (e.g. eth-ethereum) and contractAddress the token address. No API key required.",
   {
     platformId: z.string().describe("Platform ID (e.g., eth-ethereum)"),
     contractAddress: z.string().describe("Contract address")
@@ -1199,7 +1201,7 @@ server.tool(
 // ─── Tool 23: getHistoricalTickerByContract (paid: Starter+) ───
 server.tool(
   'getHistoricalTickerByContract',
-  'Historical by contract address (plan dependent)',
+  "Get historical price and market data of a token by its contract address. Use for 'this token's price on 2024-01-01 by address'. Not for the current price (use getTickerByContract). Read-only; platformId and contractAddress identify the token, start and end accept YYYY-MM-DD. Requires a Starter+ plan (COINPAPRIKA_API_KEY).",
   {
     platformId: z.string().describe("Platform ID (e.g., eth-ethereum)"),
     contractAddress: z.string().describe("Contract address"),
@@ -1222,7 +1224,7 @@ server.tool(
 // ─── Tool 24: search ───
 server.tool(
   'search',
-  'Search currencies, exchanges, icos, people, tags',
+  "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. Read-only; q is the query, categories filters entity types, limit caps results. No API key required.",
   {
     q: z.string().describe("Search query"),
     categories: z.string().optional().describe("Comma-separated categories to search (e.g., currencies,exchanges,icos,people,tags)"),
@@ -1246,7 +1248,7 @@ server.tool(
 // ─── Tool 25: resolveId ───
 server.tool(
   'resolveId',
-  'Resolve fuzzy query to canonical ids',
+  "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. Read-only; query is the name or symbol, type narrows the entity kind. No API key required.",
   {
     type: z.enum(['coin', 'exchange', 'people', 'tags']).describe("Resource type to resolve"),
     query: z.string().describe("Fuzzy search query"),
@@ -1270,7 +1272,7 @@ server.tool(
 // ─── Tool 26: priceConverter ───
 server.tool(
   'priceConverter',
-  'Convert base -> quote',
+  "Convert an amount from one crypto or fiat to another at the current rate, e.g. 'how much is 0.5 BTC in USD', 'convert 100 USDC to EUR'. For a plain coin price without an amount, use getTickersById. Read-only; baseCurrencyId and quoteCurrencyId are canonical ids and amount is the quantity to convert. No API key required.",
   {
     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."),
@@ -1294,7 +1296,7 @@ server.tool(
 // ─── Tool 27: keyInfo (paid: Pro) ───
 server.tool(
   'keyInfo',
-  'Verify API key (Pro)',
+  "Get details and usage for the current CoinPaprika API key: plan, quota, requests remaining and expiry. Use for 'what plan am I on', 'how many requests are left', 'is my API key valid'. Read-only; takes no parameters. Requires a configured COINPAPRIKA_API_KEY (Pro plan); without a key the call is rejected.",
   {},
   async () => {
     if (!API_KEY) {
@@ -1313,7 +1315,7 @@ server.tool(
 // ─── Tool 28: getMappings (paid: Business) ───
 server.tool(
   'getMappings',
-  'API ID mappings (Business)',
+  "Get mappings between CoinPaprika ids and external or legacy identifiers (CoinMarketCap, CoinGecko, CryptoCompare, ISIN, DTI) so you can reconcile ids across systems. Use for 'map CoinPaprika ids to X', 'id crosswalk', 'external id mapping'. Read-only; each source parameter filters by that identifier. Requires a Business plan (COINPAPRIKA_API_KEY).",
   {
     coinpaprika: z.string().optional().describe("CoinPaprika ID to look up"),
     coinmarketcap: z.string().optional().describe("CoinMarketCap ID to look up"),
@@ -1340,7 +1342,7 @@ server.tool(
 // ─── Tool 29: getChangelogIDs (paid: Starter+) ───
 server.tool(
   'getChangelogIDs',
-  'Changelog IDs (Starter+)',
+  "Get the ids of recent changes to CoinPaprika's coin and exchange listings (additions, renames, delistings) for syncing a local dataset. Use for 'what changed recently', 'new or delisted coins', 'listing changelog'. Read-only; page and limit paginate the results. Requires a Starter+ plan (COINPAPRIKA_API_KEY).",
   {
     page: z.number().optional().default(1).describe("Page number (default: 1)"),
     limit: z.number().optional().default(50).describe("Number of results per page (default: 50)")
@@ -1356,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.2.0",
+  "version": "1.3.1",
   "description": "A Model Context Protocol server for CoinPaprika cryptocurrency market data — prices, tickers, exchanges, and more",
   "main": "dist/index.js",
   "type": "module",