crypto-intel-mcp 0.1.0__tar.gz

crypto_intel_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Amigo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crypto_intel_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: crypto-intel-mcp
+Version: 0.1.0
+Summary: Crypto market intelligence (price, momentum, trending) over MCP.
+Author-email: Cristian Amigo <cstamigo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cstamigo-droid/crypto-intel-mcp
+Project-URL: Repository, https://github.com/cstamigo-droid/crypto-intel-mcp
+Project-URL: Bug Tracker, https://github.com/cstamigo-droid/crypto-intel-mcp/issues
+Keywords: mcp,model-context-protocol,crypto,cryptocurrency,coingecko,momentum,llm,agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: requests>=2.31
+Dynamic: license-file
+
+# crypto-intel-mcp
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org) [![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-7C3AED.svg)](https://modelcontextprotocol.io) [![crypto-intel-mcp MCP server](https://glama.ai/mcp/servers/cstamigo-droid/crypto-intel-mcp/badges/score.svg)](https://glama.ai/mcp/servers/cstamigo-droid/crypto-intel-mcp)
+
+![crypto-intel-mcp - coin analysis demo](docs/demo.png)
+
+
+**Crypto market intelligence for any LLM, over the [Model Context Protocol](https://modelcontextprotocol.io).**
+
+Gives any MCP client (Claude Desktop, Claude Code, agents) clean tools for crypto
+price, momentum, and what's trending — and blends them into a single scored
+verdict. Runs entirely on **CoinGecko's free public API (no key)**, fails
+gracefully (a missing source returns *"no data"*, never a fabricated value), and
+outputs Markdown by default or JSON on demand.
+
+```
+# Crypto Intelligence — BTC
+
+**Signal:** Lean positive  `[........|##......]` +22/100  · confidence 80%
+
+Building momentum → LEAN LONG. BTC momentum: 24h +1.9% · 7d +4.4% · 30d -17.0%.
+- In CoinGecko trending (elevated attention).
+- Total crypto market cap +1.8% 24h, BTC dominance 57%.
+```
+
+---
+
+## Tools
+
+| Tool | What it does | Source | Status |
+|------|--------------|--------|:------:|
+| `crypto_analyze` | **Hero tool.** Blends momentum + trending + market tide into one scored verdict (RISK-ON → AVOID). | composite | ✅ |
+| `crypto_get_quote` | Live price, 24h change, market-cap rank, volume, distance from ATH. | CoinGecko | ✅ |
+| `crypto_momentum` | Multi-timeframe momentum (24h/7d/30d) scored into one directional signal. | CoinGecko | ✅ |
+| `crypto_trending` | The coins the market is searching for most right now. | CoinGecko | ✅ |
+
+Every tool returns **Markdown** (human-readable, default) or **JSON**
+(`response_format="json"`) for programmatic use.
+
+---
+
+## Live demo output (2026-06-15)
+
+```
+crypto_get_quote bitcoin:
+  BTC $66,504.00  +3.4% 24h  · rank #1  · -47% from ATH
+
+crypto_momentum bitcoin:
+  Lean positive  [........|##......] +21/100  · confidence 80%
+  BTC momentum: 24h +3.4% · 7d +4.9% · 30d -14.8%
+
+crypto_trending:
+  ZEC, PENGU, SIREN, TAO, NEAR, BTC, HYPE, GRAM, SUI, H
+
+crypto_analyze bitcoin:
+  Lean positive  [........|###.....] +35/100  · confidence 80%
+  Building momentum → LEAN LONG. In CoinGecko trending (elevated attention).
+  Total crypto market cap +3.6% 24h, BTC dominance 57%.
+```
+
+All values are live from CoinGecko's free public API — no key, no fabrication.
+
+---
+
+## Quick start
+
+```bash
+git clone https://github.com/cstamigo-droid/crypto-intel-mcp crypto-intel-mcp
+cd crypto-intel-mcp
+python -m venv .venv && .venv\Scripts\activate     # Windows
+pip install -r requirements.txt
+
+python -m crypto_intel_mcp     # starts the MCP server over stdio (no .env needed)
+```
+
+**Smoke test** (hits the live CoinGecko API and prints each signal):
+
+```bash
+python tests/test_smoke.py bitcoin
+```
+
+---
+
+## Use it in Claude Desktop
+
+Add this to `claude_desktop_config.json`
+(`%APPDATA%\Claude\` on Windows, `~/Library/Application Support/Claude/` on macOS),
+then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "crypto-intel-mcp": {
+      "command": "python",
+      "args": ["-m", "crypto_intel_mcp"],
+      "cwd": "C:/path/to/crypto-intel-mcp"
+    }
+  }
+}
+```
+
+---
+
+## Why it's built this way
+
+- **Uniform result contract.** Every source returns the same `Result` shape, so
+  an LLM can reason across tools instead of parsing N formats.
+- **Graceful degradation.** A source with no data returns *"no data"*, not a fake
+  value. Missing data never invents an answer.
+- **Resilient + cached.** A short per-source TTL cache avoids hammering
+  rate-limited endpoints when an agent calls several tools in one turn.
+
+---
+
+## Disclaimer
+
+For research and educational use only. Data comes from third-party sources and
+may be delayed or incomplete.
+
+## License
+
+MIT

crypto_intel_mcp-0.1.0/README.md

@@ -0,0 +1,122 @@
+# crypto-intel-mcp
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org) [![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-7C3AED.svg)](https://modelcontextprotocol.io) [![crypto-intel-mcp MCP server](https://glama.ai/mcp/servers/cstamigo-droid/crypto-intel-mcp/badges/score.svg)](https://glama.ai/mcp/servers/cstamigo-droid/crypto-intel-mcp)
+
+![crypto-intel-mcp - coin analysis demo](docs/demo.png)
+
+
+**Crypto market intelligence for any LLM, over the [Model Context Protocol](https://modelcontextprotocol.io).**
+
+Gives any MCP client (Claude Desktop, Claude Code, agents) clean tools for crypto
+price, momentum, and what's trending — and blends them into a single scored
+verdict. Runs entirely on **CoinGecko's free public API (no key)**, fails
+gracefully (a missing source returns *"no data"*, never a fabricated value), and
+outputs Markdown by default or JSON on demand.
+
+```
+# Crypto Intelligence — BTC
+
+**Signal:** Lean positive  `[........|##......]` +22/100  · confidence 80%
+
+Building momentum → LEAN LONG. BTC momentum: 24h +1.9% · 7d +4.4% · 30d -17.0%.
+- In CoinGecko trending (elevated attention).
+- Total crypto market cap +1.8% 24h, BTC dominance 57%.
+```
+
+---
+
+## Tools
+
+| Tool | What it does | Source | Status |
+|------|--------------|--------|:------:|
+| `crypto_analyze` | **Hero tool.** Blends momentum + trending + market tide into one scored verdict (RISK-ON → AVOID). | composite | ✅ |
+| `crypto_get_quote` | Live price, 24h change, market-cap rank, volume, distance from ATH. | CoinGecko | ✅ |
+| `crypto_momentum` | Multi-timeframe momentum (24h/7d/30d) scored into one directional signal. | CoinGecko | ✅ |
+| `crypto_trending` | The coins the market is searching for most right now. | CoinGecko | ✅ |
+
+Every tool returns **Markdown** (human-readable, default) or **JSON**
+(`response_format="json"`) for programmatic use.
+
+---
+
+## Live demo output (2026-06-15)
+
+```
+crypto_get_quote bitcoin:
+  BTC $66,504.00  +3.4% 24h  · rank #1  · -47% from ATH
+
+crypto_momentum bitcoin:
+  Lean positive  [........|##......] +21/100  · confidence 80%
+  BTC momentum: 24h +3.4% · 7d +4.9% · 30d -14.8%
+
+crypto_trending:
+  ZEC, PENGU, SIREN, TAO, NEAR, BTC, HYPE, GRAM, SUI, H
+
+crypto_analyze bitcoin:
+  Lean positive  [........|###.....] +35/100  · confidence 80%
+  Building momentum → LEAN LONG. In CoinGecko trending (elevated attention).
+  Total crypto market cap +3.6% 24h, BTC dominance 57%.
+```
+
+All values are live from CoinGecko's free public API — no key, no fabrication.
+
+---
+
+## Quick start
+
+```bash
+git clone https://github.com/cstamigo-droid/crypto-intel-mcp crypto-intel-mcp
+cd crypto-intel-mcp
+python -m venv .venv && .venv\Scripts\activate     # Windows
+pip install -r requirements.txt
+
+python -m crypto_intel_mcp     # starts the MCP server over stdio (no .env needed)
+```
+
+**Smoke test** (hits the live CoinGecko API and prints each signal):
+
+```bash
+python tests/test_smoke.py bitcoin
+```
+
+---
+
+## Use it in Claude Desktop
+
+Add this to `claude_desktop_config.json`
+(`%APPDATA%\Claude\` on Windows, `~/Library/Application Support/Claude/` on macOS),
+then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "crypto-intel-mcp": {
+      "command": "python",
+      "args": ["-m", "crypto_intel_mcp"],
+      "cwd": "C:/path/to/crypto-intel-mcp"
+    }
+  }
+}
+```
+
+---
+
+## Why it's built this way
+
+- **Uniform result contract.** Every source returns the same `Result` shape, so
+  an LLM can reason across tools instead of parsing N formats.
+- **Graceful degradation.** A source with no data returns *"no data"*, not a fake
+  value. Missing data never invents an answer.
+- **Resilient + cached.** A short per-source TTL cache avoids hammering
+  rate-limited endpoints when an agent calls several tools in one turn.
+
+---
+
+## Disclaimer
+
+For research and educational use only. Data comes from third-party sources and
+may be delayed or incomplete.
+
+## License
+
+MIT

crypto_intel_mcp-0.1.0/crypto_intel_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""crypto-intel-mcp — Crypto market intelligence (price, momentum, trending) over MCP.
+
+An MCP server giving any MCP client (Claude Desktop, Claude Code, agents) clean,
+uniform tools with graceful degradation. Generated from mcp-factory.
+"""
+
+__version__ = "0.1.0"

crypto_intel_mcp-0.1.0/crypto_intel_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m crypto_intel_mcp` to launch the server."""
+from .server import main
+
+if __name__ == "__main__":
+    main()

crypto_intel_mcp-0.1.0/crypto_intel_mcp/analyze.py

@@ -0,0 +1,80 @@
+"""Composite crypto verdict — momentum, adjusted for attention and market tide.
+
+Base score is the multi-timeframe momentum. Two context adjustments:
+  - In CoinGecko's trending list  -> small boost (the market is watching).
+  - Total crypto market cap 24h move -> a small tide nudge (rising tide lifts).
+The result is one scored Result, so it renders with the gauge like any signal.
+"""
+from __future__ import annotations
+
+from . import coingecko
+from .result import Result, clamp
+from .sources import momentum, trending
+
+
+def _verdict(score: float) -> tuple[str, str]:
+    if score >= 40:
+        return "Strong momentum", "RISK-ON"
+    if score >= 15:
+        return "Building momentum", "LEAN LONG"
+    if score > -15:
+        return "Neutral", "WAIT"
+    if score > -40:
+        return "Weakening", "LEAN SHORT / AVOID"
+    return "Breaking down", "AVOID"
+
+
+def analyze(query: str) -> Result:
+    coin_id = coingecko.resolve(query)
+    if not coin_id:
+        return Result.failed("analyze", f"no coin matches '{query}'")
+
+    mom = momentum.fetch(query)
+    if not mom.ok or mom.score is None:
+        return Result.failed("analyze", mom.error or "no momentum data")
+
+    score = mom.score
+    notes = []
+
+    # Attention: is the coin trending right now?
+    tr = trending.fetch()
+    is_trending = False
+    if tr.ok:
+        is_trending = any(coin_id == c.split(" ")[0].lower() for c in tr.data.get("trending", []))
+        # trending stores symbols; also check the symbol from momentum summary
+        sym = mom.summary.split(" ")[0].lower()
+        is_trending = is_trending or any(sym == c.split(" ")[0].lower() for c in tr.data.get("trending", []))
+    if is_trending:
+        score = clamp(score + 10, -100, 100)
+        notes.append("In CoinGecko trending (elevated attention).")
+
+    # Market tide: total crypto market cap 24h direction.
+    mcap_chg = None
+    try:
+        g = coingecko.global_data()
+        mcap_chg = g.get("market_cap_change_percentage_24h_usd")
+        btc_dom = g.get("market_cap_percentage", {}).get("btc")
+    except Exception:
+        btc_dom = None
+    if mcap_chg is not None:
+        score = clamp(score + clamp(mcap_chg, -5, 5), -100, 100)
+        notes.append(f"Total crypto market cap {mcap_chg:+.1f}% 24h"
+                     + (f", BTC dominance {btc_dom:.0f}%." if btc_dom is not None else "."))
+
+    verdict, action = _verdict(score)
+    return Result(
+        source="analyze",
+        ok=True,
+        score=round(score, 1),
+        confidence=mom.confidence,
+        summary=f"{verdict} → {action}. {mom.summary}",
+        data={
+            "verdict": verdict,
+            "action": action,
+            "momentum_score": mom.score,
+            "is_trending": is_trending,
+            "market_cap_change_24h_pct": round(mcap_chg, 2) if mcap_chg is not None else None,
+            "notes": notes,
+            "url": f"https://www.coingecko.com/en/coins/{coin_id}",
+        },
+    )

crypto_intel_mcp-0.1.0/crypto_intel_mcp/cache.py

@@ -0,0 +1,40 @@
+"""Tiny thread-safe TTL cache.
+
+External APIs are slow and rate-limited. A short in-process cache means an agent
+that calls several tools on the same input in one turn — or a composite tool that
+fans out to every source — doesn't refetch the same data seconds apart. TTLs are
+per-key, chosen by each source to match how fast its data goes stale.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Callable
+
+_lock = threading.Lock()
+_store: dict[str, tuple[float, Any]] = {}
+
+
+def get_or_fetch(key: str, ttl_s: float, fetch: Callable[[], Any]) -> Any:
+    """Return a cached value if fresh, otherwise call `fetch()` and store it.
+
+    `fetch` runs OUTSIDE the lock so a slow network call never blocks other
+    cache readers. A rare duplicate fetch under concurrency is acceptable.
+    """
+    now = time.monotonic()
+    with _lock:
+        hit = _store.get(key)
+        if hit is not None and (now - hit[0]) < ttl_s:
+            return hit[1]
+
+    value = fetch()
+
+    with _lock:
+        _store[key] = (time.monotonic(), value)
+    return value
+
+
+def clear() -> None:
+    """Drop all cached entries (used by tests)."""
+    with _lock:
+        _store.clear()

crypto_intel_mcp-0.1.0/crypto_intel_mcp/coingecko.py

@@ -0,0 +1,58 @@
+"""Low-level CoinGecko client (free public API, no key required). Cached raw pulls.
+
+CoinGecko's free tier is generous and keyless, which makes this server run out of
+the box — ideal for demos. TTLs are short for prices, longer for slow data.
+"""
+from __future__ import annotations
+
+import requests
+
+from . import cache
+
+_BASE = "https://api.coingecko.com/api/v3"
+_TTL_RESOLVE = 3600.0   # symbol -> id mapping barely changes
+_TTL_MARKET = 60.0      # prices age fast
+_TTL_TRENDING = 300.0
+_TTL_GLOBAL = 300.0
+
+
+def _get(path: str, params: dict | None = None) -> object:
+    resp = requests.get(_BASE + path, params=params or {}, timeout=15)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def resolve(query: str) -> str | None:
+    """Resolve a symbol/name/id to a CoinGecko coin id (cached). None if not found."""
+    q = query.strip().lower()
+
+    def _do():
+        data = _get("/search", {"query": q})
+        coins = data.get("coins", [])
+        return coins[0]["id"] if coins else None
+
+    return cache.get_or_fetch(f"cg:resolve:{q}", _TTL_RESOLVE, _do)
+
+
+def market(coin_id: str) -> dict | None:
+    """Rich market data for one coin id, incl. multi-timeframe % (cached)."""
+
+    def _do():
+        data = _get("/coins/markets", {
+            "vs_currency": "usd",
+            "ids": coin_id,
+            "price_change_percentage": "24h,7d,30d",
+        })
+        return data[0] if data else None
+
+    return cache.get_or_fetch(f"cg:market:{coin_id}", _TTL_MARKET, _do)
+
+
+def trending() -> dict:
+    """The current most-searched coins on CoinGecko (cached)."""
+    return cache.get_or_fetch("cg:trending", _TTL_TRENDING, lambda: _get("/search/trending"))
+
+
+def global_data() -> dict:
+    """Global market data: total market cap, BTC dominance, 24h change (cached)."""
+    return cache.get_or_fetch("cg:global", _TTL_GLOBAL, lambda: _get("/global").get("data", {}))

crypto_intel_mcp-0.1.0/crypto_intel_mcp/formatting.py

@@ -0,0 +1,90 @@
+"""Render a Result as Markdown (human, default) or JSON (machine) for MCP output."""
+from __future__ import annotations
+
+import json
+from enum import Enum
+
+from .result import Result, clamp
+
+
+class ResponseFormat(str, Enum):
+    """Output format for tool responses."""
+
+    MARKDOWN = "markdown"
+    JSON = "json"
+
+
+def label(score: float) -> str:
+    """Human label for a -100..+100 directional score."""
+    if score >= 40:
+        return "Strong positive"
+    if score >= 12:
+        return "Lean positive"
+    if score > -12:
+        return "Neutral"
+    if score > -40:
+        return "Lean negative"
+    return "Strong negative"
+
+
+def _gauge(score: float) -> str:
+    """A compact ASCII gauge for a -100..+100 score.
+
+    Negative fills left of center, positive fills right, e.g.
+    -100 -> `[########|........]`, +50 -> `[........|####....]`.
+    """
+    n = 8  # half-width
+    s = clamp(score, -100, 100)
+    filled = int(round(abs(s) / 100 * n))
+    if s < 0:
+        left, right = "." * (n - filled) + "#" * filled, "." * n
+    elif s > 0:
+        left, right = "." * n, "#" * filled + "." * (n - filled)
+    else:
+        left = right = "." * n
+    return f"[{left}|{right}]"
+
+
+def _fmt_value(v: object) -> str:
+    if isinstance(v, bool):
+        return "yes" if v else "no"
+    if isinstance(v, float):
+        return f"{v:,.2f}"
+    if isinstance(v, int):
+        return f"{v:,}"
+    if isinstance(v, list):
+        return ", ".join(str(x) for x in v[:12]) + (" …" if len(v) > 12 else "")
+    return str(v)
+
+
+def render(result: Result, title: str, fmt: ResponseFormat) -> str:
+    """Format a single Result for return to an MCP client."""
+    if fmt == ResponseFormat.JSON:
+        return json.dumps(result.to_dict(), indent=2, default=str)
+
+    lines = [f"# {title}"]
+    if not result.ok:
+        lines += ["", f"⚠️ No data available — {result.error}"]
+        return "\n".join(lines)
+
+    if result.score is not None:
+        conf = f"  · confidence {result.confidence:.0%}" if result.confidence is not None else ""
+        lines += [
+            "",
+            f"**Signal:** {label(result.score)}  "
+            f"`{_gauge(result.score)}` {result.score:+.0f}/100{conf}",
+        ]
+    if result.summary:
+        lines += ["", result.summary]
+
+    if result.data:
+        lines += ["", "## Details"]
+        for k, v in result.data.items():
+            if v is None or k == "url":
+                continue
+            lines.append(f"- **{k.replace('_', ' ')}:** {_fmt_value(v)}")
+        url = result.data.get("url")
+        if url:
+            lines += ["", f"Source: {url}"]
+
+    return "\n".join(lines)

crypto_intel_mcp-0.1.0/crypto_intel_mcp/result.py

@@ -0,0 +1,52 @@
+"""The single return type every source and tool produces.
+
+A uniform shape lets an LLM reason *across* heterogeneous tools without each one
+inventing its own format. Plain-data tools fill `summary` + `data`. Analysis
+tools additionally set `score` (-100..+100) and `confidence` (0..1), which unlocks
+the gauge rendering in `formatting.py`.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+def clamp(x: float, lo: float, hi: float) -> float:
+    """Constrain x to the inclusive [lo, hi] range."""
+    return max(lo, min(hi, x))
+
+
+@dataclass
+class Result:
+    """Uniform result object returned by every source in `sources/`.
+
+    Attributes:
+        source:     short id of the producing source, e.g. "weather".
+        ok:         True if data was fetched and the result is meaningful.
+        summary:    one-line human-readable takeaway.
+        data:       raw structured details (source-specific). Put a `url`
+                    permalink here so an agent can cite the source.
+        score:      optional -100..+100 directional score (analysis tools only).
+        confidence: optional 0..1 — how much to trust this result.
+        error:      failure reason when ok is False; None otherwise.
+    """
+
+    source: str
+    ok: bool
+    summary: str = ""
+    data: dict[str, Any] = field(default_factory=dict)
+    score: float | None = None
+    confidence: float | None = None
+    error: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def failed(cls, source: str, error: str) -> "Result":
+        """Graceful degradation: a missing source NEVER fabricates a value.
+
+        Returns ok=False with no score, so a composite tool can simply skip it
+        and the agent sees an honest "no data".
+        """
+        return cls(source=source, ok=False, summary=f"no data ({error})", error=error)

crypto_intel_mcp-0.1.0/crypto_intel_mcp/server.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""crypto-intel-mcp — Crypto market intelligence (price, momentum, trending) over MCP.
+
+Transport: stdio (local — Claude Desktop / Claude Code / agents).
+
+Each tool returns a uniform Result rendered as Markdown (default) or JSON.
+Sources fail gracefully: a missing data source returns "no data", never a
+fabricated value. Powered by CoinGecko's free public API — no key required.
+"""
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+from pydantic import BaseModel, ConfigDict, Field
+
+from . import analyze
+from .formatting import ResponseFormat, render
+from .sources import momentum, quote, trending
+
+# Load .env from the project root (parent of this package), if present.
+load_dotenv(Path(__file__).resolve().parent.parent / ".env")
+
+mcp = FastMCP("crypto_intel_mcp")
+
+
+# ─── shared helpers ──────────────────────────────────────────────────────────
+
+async def _run(fn, *args):
+    """Run a blocking source function in a thread so the event loop stays free."""
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, lambda: fn(*args))
+
+
+class CoinInput(BaseModel):
+    """Input for single-coin tools."""
+
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    coin: str = Field(
+        ...,
+        description="Coin symbol, name, or id — e.g. 'BTC', 'bitcoin', 'ETH', 'solana'.",
+        min_length=1,
+        max_length=50,
+    )
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN,
+        description="'markdown' for a human-readable report or 'json' for structured data.",
+    )
+
+
+class MarketInput(BaseModel):
+    """Input for market-wide tools that take no specific coin."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN,
+        description="'markdown' for a human-readable report or 'json' for structured data.",
+    )
+
+
+# ─── tools ───────────────────────────────────────────────────────────────────
+
+@mcp.tool(
+    name="crypto_get_quote",
+    annotations={"title": "Crypto Price Snapshot", "readOnlyHint": True,
+                 "destructiveHint": False, "idempotentHint": True, "openWorldHint": True},
+)
+async def crypto_get_quote(params: CoinInput) -> str:
+    """Get a current price snapshot for a cryptocurrency.
+
+    Informational (not a buy/sell signal): live price, 24h change, market-cap
+    rank, 24h volume, and distance from all-time high.
+
+    Examples:
+        - "What's bitcoin trading at?" -> coin='BTC'
+        - "How far is ETH from its all-time high?" -> coin='ethereum'
+    """
+    sig = await _run(quote.fetch, params.coin)
+    return render(sig, f"Quote — {params.coin}", params.response_format)
+
+
+@mcp.tool(
+    name="crypto_momentum",
+    annotations={"title": "Crypto Momentum Signal", "readOnlyHint": True,
+                 "destructiveHint": False, "idempotentHint": True, "openWorldHint": True},
+)
+async def crypto_momentum(params: CoinInput) -> str:
+    """Score a coin's price momentum across 24h, 7d and 30d into one signal.
+
+    Returns a directional score from -100 (breaking down) to +100 (strong
+    broad-based upward momentum), weighting recent action more heavily.
+
+    Examples:
+        - "Does solana have momentum?" -> coin='SOL'
+        - "Is bitcoin trending up or down?" -> coin='bitcoin'
+    """
+    sig = await _run(momentum.fetch, params.coin)
+    return render(sig, f"Momentum — {params.coin}", params.response_format)
+
+
+@mcp.tool(
+    name="crypto_trending",
+    annotations={"title": "Trending Coins", "readOnlyHint": True,
+                 "destructiveHint": False, "idempotentHint": True, "openWorldHint": True},
+)
+async def crypto_trending(params: MarketInput) -> str:
+    """List the coins the market is searching for most right now (CoinGecko trending).
+
+    A breadth/attention indicator — useful for spotting where retail interest is
+    concentrating. Takes no coin.
+
+    Examples:
+        - "What crypto is trending right now?"
+        - "Show me the hot coins today."
+    """
+    sig = await _run(trending.fetch, "")
+    return render(sig, "Trending Crypto", params.response_format)
+
+
+@mcp.tool(
+    name="crypto_analyze",
+    annotations={"title": "Full Crypto Analysis (Composite)", "readOnlyHint": True,
+                 "destructiveHint": False, "idempotentHint": True, "openWorldHint": True},
+)
+async def crypto_analyze(params: CoinInput) -> str:
+    """Run a full analysis of a coin and return one scored verdict.
+
+    Blends multi-timeframe momentum with whether the coin is trending and the
+    overall crypto market tide into a single verdict (RISK-ON → AVOID) with a
+    gauge and the reasoning behind it.
+
+    This is the primary tool — prefer it for "should I look at X?" questions.
+
+    Examples:
+        - "Give me a full read on bitcoin" -> coin='BTC'
+        - "Should I be looking at SOL?" -> coin='solana'
+    """
+    sig = await _run(analyze.analyze, params.coin)
+    return render(sig, f"Crypto Intelligence — {params.coin}", params.response_format)
+
+
+def main() -> None:
+    """Console entrypoint — runs the MCP server over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

crypto_intel_mcp-0.1.0/crypto_intel_mcp/sources/__init__.py

@@ -0,0 +1,6 @@
+"""Data sources. Each module exposes `fetch(query: str) -> Result`.
+
+Add one module per external API/endpoint. Keep the network call dumb, wrap it in
+`cache.get_or_fetch`, and return `Result.failed(...)` on any missing data —
+never a fabricated value.
+"""

crypto_intel_mcp-0.1.0/crypto_intel_mcp/sources/momentum.py

@@ -0,0 +1,65 @@
+"""Crypto momentum signal — blends 24h / 7d / 30d price trend into one score.
+
+Score -100..+100: positive = broad upward momentum across timeframes, negative =
+breaking down. Each timeframe has its own volatility scale (a +8% day is as
+significant as a +40% month) and weight (recent action counts more).
+"""
+from __future__ import annotations
+
+from .. import coingecko
+from ..result import Result, clamp
+
+# (field, weight, scale) — |pct| == scale contributes ±100 at that timeframe.
+_TIMEFRAMES = [
+    ("price_change_percentage_24h_in_currency", 0.5, 8.0),
+    ("price_change_percentage_7d_in_currency", 0.3, 20.0),
+    ("price_change_percentage_30d_in_currency", 0.2, 40.0),
+]
+
+
+def fetch(query: str) -> Result:
+    coin_id = coingecko.resolve(query)
+    if not coin_id:
+        return Result.failed("momentum", f"no coin matches '{query}'")
+    try:
+        m = coingecko.market(coin_id)
+    except Exception as e:
+        return Result.failed("momentum", str(e))
+    if not m:
+        return Result.failed("momentum", f"no market data for {coin_id}")
+
+    num = den = 0.0
+    used = 0
+    for field, weight, scale in _TIMEFRAMES:
+        pct = m.get(field)
+        if pct is None:
+            continue
+        num += clamp(pct / scale * 100, -100, 100) * weight
+        den += weight
+        used += 1
+    if den == 0:
+        return Result.failed("momentum", "no timeframe data")
+
+    score = clamp(num / den, -100, 100)
+    confidence = min(0.2 + 0.2 * used, 1.0)  # 0.8 with all three timeframes
+
+    c24 = m.get("price_change_percentage_24h_in_currency")
+    c7 = m.get("price_change_percentage_7d_in_currency")
+    c30 = m.get("price_change_percentage_30d_in_currency")
+
+    def f(x):
+        return f"{x:+.1f}%" if x is not None else "n/a"
+
+    return Result(
+        source="momentum",
+        ok=True,
+        score=round(score, 1),
+        confidence=round(confidence, 2),
+        summary=f"{(m.get('symbol') or '').upper()} momentum: 24h {f(c24)} · 7d {f(c7)} · 30d {f(c30)}.",
+        data={
+            "change_24h_pct": round(c24, 2) if c24 is not None else None,
+            "change_7d_pct": round(c7, 2) if c7 is not None else None,
+            "change_30d_pct": round(c30, 2) if c30 is not None else None,
+            "url": f"https://www.coingecko.com/en/coins/{coin_id}",
+        },
+    )

crypto_intel_mcp-0.1.0/crypto_intel_mcp/sources/quote.py

@@ -0,0 +1,49 @@
+"""Crypto price snapshot — price, 24h move, market cap rank, volume, ATH distance.
+
+Informational (no directional score): use it to anchor any analysis with the
+current state of a coin.
+"""
+from __future__ import annotations
+
+from .. import coingecko
+from ..result import Result
+
+
+def fetch(query: str) -> Result:
+    coin_id = coingecko.resolve(query)
+    if not coin_id:
+        return Result.failed("quote", f"no coin matches '{query}'")
+    try:
+        m = coingecko.market(coin_id)
+    except Exception as e:
+        return Result.failed("quote", str(e))
+    if not m:
+        return Result.failed("quote", f"no market data for {coin_id}")
+
+    price = m.get("current_price")
+    chg = m.get("price_change_percentage_24h")
+    ath_dist = m.get("ath_change_percentage")
+    sym = (m.get("symbol") or "").upper()
+    # Adaptive price format: commas for >=$1, more decimals for sub-dollar coins.
+    price_str = f"{price:,.2f}" if price is None or price >= 1 else f"{price:.8f}".rstrip("0")
+    summary = (
+        f"{sym} ${price_str} · {chg:+.1f}% 24h · rank #{m.get('market_cap_rank', '?')} "
+        f"· {ath_dist:+.0f}% from ATH"
+    )
+    return Result(
+        source="quote",
+        ok=True,
+        summary=summary,
+        data={
+            "name": m.get("name"),
+            "symbol": sym,
+            "price_usd": price,
+            "change_24h_pct": round(chg, 2) if chg is not None else None,
+            "market_cap": m.get("market_cap"),
+            "market_cap_rank": m.get("market_cap_rank"),
+            "volume_24h": m.get("total_volume"),
+            "ath": m.get("ath"),
+            "pct_from_ath": round(ath_dist, 1) if ath_dist is not None else None,
+            "url": f"https://www.coingecko.com/en/coins/{coin_id}",
+        },
+    )

crypto_intel_mcp-0.1.0/crypto_intel_mcp/sources/trending.py

@@ -0,0 +1,34 @@
+"""What's trending on CoinGecko right now — the most-searched coins.
+
+A breadth/attention signal: coins the market is actively looking at. Takes no
+specific coin (the optional query argument is ignored).
+"""
+from __future__ import annotations
+
+from .. import coingecko
+from ..result import Result
+
+
+def fetch(query: str = "") -> Result:
+    try:
+        t = coingecko.trending()
+    except Exception as e:
+        return Result.failed("trending", str(e))
+    coins = t.get("coins", [])
+    if not coins:
+        return Result.failed("trending", "no trending data")
+
+    symbols = [c["item"]["symbol"].upper() for c in coins[:10]]
+    detail = [
+        f"{c['item']['symbol'].upper()} (#{c['item'].get('market_cap_rank') or '?'})"
+        for c in coins[:10]
+    ]
+    return Result(
+        source="trending",
+        ok=True,
+        summary="Trending now: " + ", ".join(symbols),
+        data={
+            "trending": detail,
+            "url": "https://www.coingecko.com/en/highlights/trending-crypto",
+        },
+    )

crypto_intel_mcp-0.1.0/crypto_intel_mcp.egg-info/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: crypto-intel-mcp
+Version: 0.1.0
+Summary: Crypto market intelligence (price, momentum, trending) over MCP.
+Author-email: Cristian Amigo <cstamigo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cstamigo-droid/crypto-intel-mcp
+Project-URL: Repository, https://github.com/cstamigo-droid/crypto-intel-mcp
+Project-URL: Bug Tracker, https://github.com/cstamigo-droid/crypto-intel-mcp/issues
+Keywords: mcp,model-context-protocol,crypto,cryptocurrency,coingecko,momentum,llm,agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: requests>=2.31
+Dynamic: license-file
+
+# crypto-intel-mcp
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org) [![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-7C3AED.svg)](https://modelcontextprotocol.io) [![crypto-intel-mcp MCP server](https://glama.ai/mcp/servers/cstamigo-droid/crypto-intel-mcp/badges/score.svg)](https://glama.ai/mcp/servers/cstamigo-droid/crypto-intel-mcp)
+
+![crypto-intel-mcp - coin analysis demo](docs/demo.png)
+
+
+**Crypto market intelligence for any LLM, over the [Model Context Protocol](https://modelcontextprotocol.io).**
+
+Gives any MCP client (Claude Desktop, Claude Code, agents) clean tools for crypto
+price, momentum, and what's trending — and blends them into a single scored
+verdict. Runs entirely on **CoinGecko's free public API (no key)**, fails
+gracefully (a missing source returns *"no data"*, never a fabricated value), and
+outputs Markdown by default or JSON on demand.
+
+```
+# Crypto Intelligence — BTC
+
+**Signal:** Lean positive  `[........|##......]` +22/100  · confidence 80%
+
+Building momentum → LEAN LONG. BTC momentum: 24h +1.9% · 7d +4.4% · 30d -17.0%.
+- In CoinGecko trending (elevated attention).
+- Total crypto market cap +1.8% 24h, BTC dominance 57%.
+```
+
+---
+
+## Tools
+
+| Tool | What it does | Source | Status |
+|------|--------------|--------|:------:|
+| `crypto_analyze` | **Hero tool.** Blends momentum + trending + market tide into one scored verdict (RISK-ON → AVOID). | composite | ✅ |
+| `crypto_get_quote` | Live price, 24h change, market-cap rank, volume, distance from ATH. | CoinGecko | ✅ |
+| `crypto_momentum` | Multi-timeframe momentum (24h/7d/30d) scored into one directional signal. | CoinGecko | ✅ |
+| `crypto_trending` | The coins the market is searching for most right now. | CoinGecko | ✅ |
+
+Every tool returns **Markdown** (human-readable, default) or **JSON**
+(`response_format="json"`) for programmatic use.
+
+---
+
+## Live demo output (2026-06-15)
+
+```
+crypto_get_quote bitcoin:
+  BTC $66,504.00  +3.4% 24h  · rank #1  · -47% from ATH
+
+crypto_momentum bitcoin:
+  Lean positive  [........|##......] +21/100  · confidence 80%
+  BTC momentum: 24h +3.4% · 7d +4.9% · 30d -14.8%
+
+crypto_trending:
+  ZEC, PENGU, SIREN, TAO, NEAR, BTC, HYPE, GRAM, SUI, H
+
+crypto_analyze bitcoin:
+  Lean positive  [........|###.....] +35/100  · confidence 80%
+  Building momentum → LEAN LONG. In CoinGecko trending (elevated attention).
+  Total crypto market cap +3.6% 24h, BTC dominance 57%.
+```
+
+All values are live from CoinGecko's free public API — no key, no fabrication.
+
+---
+
+## Quick start
+
+```bash
+git clone https://github.com/cstamigo-droid/crypto-intel-mcp crypto-intel-mcp
+cd crypto-intel-mcp
+python -m venv .venv && .venv\Scripts\activate     # Windows
+pip install -r requirements.txt
+
+python -m crypto_intel_mcp     # starts the MCP server over stdio (no .env needed)
+```
+
+**Smoke test** (hits the live CoinGecko API and prints each signal):
+
+```bash
+python tests/test_smoke.py bitcoin
+```
+
+---
+
+## Use it in Claude Desktop
+
+Add this to `claude_desktop_config.json`
+(`%APPDATA%\Claude\` on Windows, `~/Library/Application Support/Claude/` on macOS),
+then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "crypto-intel-mcp": {
+      "command": "python",
+      "args": ["-m", "crypto_intel_mcp"],
+      "cwd": "C:/path/to/crypto-intel-mcp"
+    }
+  }
+}
+```
+
+---
+
+## Why it's built this way
+
+- **Uniform result contract.** Every source returns the same `Result` shape, so
+  an LLM can reason across tools instead of parsing N formats.
+- **Graceful degradation.** A source with no data returns *"no data"*, not a fake
+  value. Missing data never invents an answer.
+- **Resilient + cached.** A short per-source TTL cache avoids hammering
+  rate-limited endpoints when an agent calls several tools in one turn.
+
+---
+
+## Disclaimer
+
+For research and educational use only. Data comes from third-party sources and
+may be delayed or incomplete.
+
+## License
+
+MIT

crypto_intel_mcp-0.1.0/crypto_intel_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+README.md
+pyproject.toml
+crypto_intel_mcp/__init__.py
+crypto_intel_mcp/__main__.py
+crypto_intel_mcp/analyze.py
+crypto_intel_mcp/cache.py
+crypto_intel_mcp/coingecko.py
+crypto_intel_mcp/formatting.py
+crypto_intel_mcp/result.py
+crypto_intel_mcp/server.py
+crypto_intel_mcp.egg-info/PKG-INFO
+crypto_intel_mcp.egg-info/SOURCES.txt
+crypto_intel_mcp.egg-info/dependency_links.txt
+crypto_intel_mcp.egg-info/entry_points.txt
+crypto_intel_mcp.egg-info/requires.txt
+crypto_intel_mcp.egg-info/top_level.txt
+crypto_intel_mcp/sources/__init__.py
+crypto_intel_mcp/sources/momentum.py
+crypto_intel_mcp/sources/quote.py
+crypto_intel_mcp/sources/trending.py
+tests/test_smoke.py

crypto_intel_mcp-0.1.0/crypto_intel_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

crypto_intel_mcp-0.1.0/crypto_intel_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+crypto-intel-mcp = crypto_intel_mcp.server:main

crypto_intel_mcp-0.1.0/crypto_intel_mcp.egg-info/requires.txt

@@ -0,0 +1,4 @@
+mcp>=1.2.0
+pydantic>=2.6
+python-dotenv>=1.0
+requests>=2.31

crypto_intel_mcp-0.1.0/crypto_intel_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+crypto_intel_mcp

crypto_intel_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "crypto-intel-mcp"
+version = "0.1.0"
+description = "Crypto market intelligence (price, momentum, trending) over MCP."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Cristian Amigo", email = "cstamigo@gmail.com" }]
+keywords = ["mcp", "model-context-protocol", "crypto", "cryptocurrency", "coingecko", "momentum", "llm", "agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "mcp>=1.2.0",
+    "pydantic>=2.6",
+    "python-dotenv>=1.0",
+    "requests>=2.31",
+]
+
+[project.urls]
+Homepage = "https://github.com/cstamigo-droid/crypto-intel-mcp"
+Repository = "https://github.com/cstamigo-droid/crypto-intel-mcp"
+"Bug Tracker" = "https://github.com/cstamigo-droid/crypto-intel-mcp/issues"
+
+[project.scripts]
+crypto-intel-mcp = "crypto_intel_mcp.server:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["crypto_intel_mcp*"]

crypto_intel_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

crypto_intel_mcp-0.1.0/tests/test_smoke.py

@@ -0,0 +1,41 @@
+"""Smoke test — hits the real CoinGecko API and prints each Result.
+
+Run:  python tests/test_smoke.py [COIN]
+This is a live network test, not a unit test.
+"""
+import sys
+from pathlib import Path
+
+# Make stdout UTF-8 safe so the live demo output (em-dashes, arrows) prints on
+# Windows consoles (cp1252) without crashing. No PYTHONUTF8 env var required.
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from dotenv import load_dotenv  # noqa: E402
+
+load_dotenv(Path(__file__).resolve().parent.parent / ".env")
+
+from crypto_intel_mcp import analyze  # noqa: E402
+from crypto_intel_mcp.formatting import ResponseFormat, render  # noqa: E402
+from crypto_intel_mcp.sources import momentum, quote, trending  # noqa: E402
+
+
+def main() -> None:
+    coin = sys.argv[1] if len(sys.argv) > 1 else "bitcoin"
+    print(f"\n{'=' * 70}\n  QUOTE\n{'=' * 70}")
+    print(render(quote.fetch(coin), f"quote — {coin}", ResponseFormat.MARKDOWN))
+
+    print(f"\n{'=' * 70}\n  MOMENTUM\n{'=' * 70}")
+    print(render(momentum.fetch(coin), f"momentum — {coin}", ResponseFormat.MARKDOWN))
+
+    print(f"\n{'=' * 70}\n  TRENDING\n{'=' * 70}")
+    print(render(trending.fetch(), "trending", ResponseFormat.MARKDOWN))
+
+    print(f"\n{'=' * 70}\n  ANALYZE (composite)\n{'=' * 70}")
+    print(render(analyze.analyze(coin), f"analyze — {coin}", ResponseFormat.MARKDOWN))
+
+
+if __name__ == "__main__":
+    main()