Metadata-Version: 2.4
Name: btcvision-mcp
Version: 0.1.0
Summary: MCP Server that exposes Bitcoin analytics, predictions, halving countdown, and crypto news from btcvision.org as tools for AI assistants
Keywords: mcp,model-context-protocol,bitcoin,btc,crypto,btcvision
Author: MiniMax Agent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: lxml>=5.0.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pytest>=8.0.0 ; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0 ; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0 ; extra == "dev"
Requires-Dist: mypy>=1.8.0 ; extra == "dev"
Requires-Dist: ruff>=0.3.0 ; extra == "dev"
Provides-Extra: dev

# BTCvision MCP Server

> **Model Context Protocol (MCP) server that exposes Bitcoin analytics, AI price
> predictions, halving countdowns, market signals, and crypto news from
> [btcvision.org](https://btcvision.org) as tools for AI assistants.**

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-1.0+-green.svg)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## Features

The server exposes **10 tools** that any MCP-compatible client (Claude
Desktop, Claude Code, Cursor, Cline, Continue, etc.) can call:

| # | Tool | Description |
|---|------|-------------|
| 1 | `get_bitcoin_price` | Current BTC/USD ticker |
| 2 | `get_bitcoin_predictions` | AI price targets 2027–2030 |
| 3 | `get_halving_countdown` | Live countdown + next block reward |
| 4 | `get_market_signals` | 6 bullish signals + market phase |
| 5 | `get_latest_news` | Latest crypto headlines |
| 6 | `get_fear_greed_index` | Fear & Greed Index value & label |
| 7 | `get_ai_stats` | Model version, confidence, accuracy |
| 8 | `get_donation_info` | BTC/ETH/SOL/BNB addresses |
| 9 | `get_faq_answer` | Look up an FAQ answer by question |
| 10 | `get_site_summary` | High-level site overview |

## Installation

### 1. Clone & install

```bash
git clone https://github.com/your-user/btcvision-mcp.git
cd btcvision-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

### 2. Run standalone (for debugging)

```bash
btcvision-mcp
# or
python -m btcvision_mcp.server
```

The server communicates over **stdio** (the standard MCP transport), so it
will appear to "hang" — that's expected. It waits for JSON-RPC messages
from an MCP client.

## Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "btcvision": {
      "command": "python",
      "args": ["-m", "btcvision_mcp.server"],
      "cwd": "/absolute/path/to/btcvision-mcp"
    }
  }
}
```

If you installed the package in a virtual environment, point `command` at
the venv's Python:

```json
{
  "mcpServers": {
    "btcvision": {
      "command": "/absolute/path/to/btcvision-mcp/.venv/bin/python",
      "args": ["-m", "btcvision_mcp.server"]
    }
  }
}
```

### Claude Code

In `.mcp.json` at your project root:

```json
{
  "mcpServers": {
    "btcvision": {
      "command": "python",
      "args": ["-m", "btcvision_mcp.server"]
    }
  }
}
```

### Cursor / Cline / Continue

The same JSON shape works in their respective MCP config files.

## Usage Examples

Once configured, you can ask your AI assistant things like:

- *"What's Bitcoin's price right now according to btcvision?"*
- *"Show me the BTC price predictions for 2027 through 2030."*
- *"How many days until the next Bitcoin halving?"*
- *"What bullish signals is the BTCvision AI tracking?"*
- *"What's the current Fear & Greed Index?"*
- *"What's the BTCvision AI model version and accuracy?"*
- *"Look up: What is the Bitcoin halving?"*
- *"Give me the latest crypto news."*

The assistant will call the relevant tool and return structured data.

## Architecture

```
btcvision-mcp/
├── btcvision_mcp/
│   ├── __init__.py
│   ├── models.py       # Pydantic data models
│   ├── scraper.py      # Async HTTP scraping + parsing
│   └── server.py       # MCP server (stdio transport)
├── tests/
│   ├── __init__.py
│   └── test_server.py  # Unit + integration tests
├── pyproject.toml
├── README.md
└── .gitignore
```

- **`scraper.py`** — async web scraper with a 5-minute in-memory cache.
  Falls back to hard-coded signals and FAQ content if the site structure
  changes.
- **`models.py`** — strongly-typed Pydantic models for every response.
- **`server.py`** — the MCP server, using `mcp.server.Server` with
  stdio transport. 10 tools, each with an explicit JSON schema.
- **`tests/`** — 25+ tests covering scraping, parsing, tool dispatch,
  and an end-to-end in-process MCP session.

## Development

Run the tests:

```bash
pytest
```

Run the linter:

```bash
ruff check .
```

Type-check:

```bash
mypy btcvision_mcp
```

## Tool Return Format

All tools return **JSON-formatted text** so any MCP client can render the
output directly. Example:

```json
{
  "ai_confidence_percent": 82.0,
  "projected_roi_multiplier": 3.4,
  "long_term_target": { "year": 2030, "price_usd": 350000.0 },
  "predictions": [
    { "year": 2027, "price_usd": 130000.0, "percent_change": 26.0,
      "drivers": "Post-2024-halving supply reduction, ETF inflows" },
    { "year": 2028, "price_usd": 200000.0, "percent_change": 94.0,
      "drivers": "4th Halving supply shock (block reward cut to 1.5625 BTC)" },
    { "year": 2029, "price_usd": 280000.0, "percent_change": 172.0,
      "drivers": "Bull run peak, new ATH" },
    { "year": 2030, "price_usd": 350000.0, "percent_change": 240.0,
      "drivers": "Post-cycle consolidation, nation-state adoption" }
  ],
  "source": "btcvision.org"
}
```

## Caching

The scraper caches the homepage HTML for **5 minutes** per process to
avoid hammering the site. Use `force=True` (or restart the server) to
bust the cache.

## License

MIT — see `LICENSE`.

## Disclaimer

All data is fetched from btcvision.org and is provided for **educational
and informational purposes only**. It is **not financial advice**.
Cryptocurrency investments carry significant risk. Always do your own
research.

