Bitnovo Pay

MCP Bitnovo Pay

Yapay zeka aracıları için Bitnovo Pay entegrasyonuna yönelik MCP sunucusu

Yapay zeka aracılarına Bitnovo Pay API entegrasyonu aracılığıyla kripto para ödeme yetenekleri sağlayan bir Model Bağlam Protokolü (MCP) sunucusu. Bu sunucu, yapay zeka modellerinin ödeme oluşturmasına, ödeme durumunu kontrol etmesine, QR kodlarını yönetmesine ve kripto para kataloglarına erişmesine olanak tanır.

🚀 Özellikler

• Kapsamlı ödeme yönetimi için 8 MCP Aracı:

  • create_payment_onchain - Doğrudan ödemeler için kripto para adresleri oluşturur
  • create_payment_link - Yönlendirme işlemeli web ödeme URL'leri oluşturur
  • get_payment_status - Ayrıntılı bilgilerle ödeme durumunu sorgular
  • list_currencies_catalog - Filtreleme ile desteklenen kripto paraları getirir
  • generate_payment_qr - Mevcut ödemelerden özel QR kodları oluşturur
  • get_webhook_events - Gerçek zamanlı olarak alınan webhook olaylarını sorgular
  • get_webhook_url - Yapılandırma talimatlarıyla genel webhook URL'sini getirir
  • get_tunnel_status - Tünel bağlantı durumunu teşhis eder

• 3 tünel sağlayıcılı Otomatik Webhook Sistemi:

  • 🔗 ngrok: Ücretsiz kalıcı URL (hesap başına 1 statik alan adı)
  • 🌐 zrok: Kalıcı URL'lerle %100 ücretsiz açık kaynak
  • 🏢 manuel: Genel IP'ye sahip sunucular için (N8N, Opal, VPS)

• Çoklu LLM Desteği - Şunlarla uyumlu:

  • 🤖 OpenAI ChatGPT (GPT-5, GPT-4o, Responses API, Agents SDK)
  • 🧠 Google Gemini (Gemini 2.5 Flash/Pro Eylül 2025, CLI, FastMCP)
  • 🔮 Claude (Claude Desktop, Claude Code)

• Yüksek Kaliteli QR Kodları (v1.1.0+):

  • 📱 Modern ekranlar için 512px varsayılan çözünürlük (300px'den yükseltildi)
  • 🖨️ Profesyonel baskı için 2000px'e kadar destek
  • ✨ Optimize edilmiş interpolasyon algoritmalarıyla keskin kenarlar
  • 🎨 Pürüzsüz logo ölçeklendirme ile özel Bitnovo Pay markalaması

• Varsayılan Olarak Gizlilik - Günlüklerde hassas veriler maskelenir, minimum veri ifşası

• Güvenli - HTTPS zorunluluğu, HMAC imza doğrulaması, güvenli gizli anahtar yönetimi

• Güvenilir - Dahili yeniden deneme mantığı, zaman aşımı yönetimi, durumsuz çalışma

📋 Ön Koşullar

• Node.js 18+
• Cihaz Kimliği ve isteğe bağlı Cihaz Gizli Anahtarı ile Bitnovo Pay Hesabı
• Ortam Yapılandırması (aşağıdaki kurulum kılavuzlarına bakın)

⚡ Hızlı Başlangıç

1. Bitnovo Kimlik Bilgilerinizi Alın

1. Bitnovo Pay adresinden kaydolun
2. Bitnovo panelinden Cihaz Kimliğinizi edinin
3. (İsteğe bağlı) Webhook imza doğrulaması için bir Cihaz Gizli Anahtarı oluşturun

2. MCP İstemcinizi Yapılandırın

Bu yapılandırmayı MCP istemci yapılandırma dosyanıza ekleyin:

Claude Desktop için (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

OpenAI ChatGPT için (OpenAI Kurulum Kılavuzu sayfasına bakın):

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

3. MCP İstemcinizi Yeniden Başlatın

Sunucuyu yüklemek için Claude Desktop, ChatGPT veya MCP istemcinizi yeniden başlatın.

4. Entegrasyonu Test Edin

Yapay zeka asistanınıza şunu sorun: "10 euro için bir ödeme oluştur"

---

☁️ Bulut Dağıtımı (v1.2.0'da YENİ)

MCP Bitnovo Pay artık HTTP aktarım modu ile bulut platformlarında uzaktan dağıtımı desteklemektedir. Bu, claude.ai gibi yapay zeka platformlarının MCP sunucunuza uzaktan bağlanmasını sağlar.

Railway'e Dağıtın (Önerilir)

Hızlı Kurulum:

1. "Railway'e Dağıt"a tıklayın veya yeni bir proje oluşturun
2. Ortam değişkenlerini ayarlayın:
   • BITNOVO_DEVICE_ID - Bitnovo cihaz kimliğiniz
   • BITNOVO_BASE_URL - https://pos.bitnovo.com
3. Dağıtın (Railway Dockerfile'ı otomatik algılar)
4. Genel URL'nizi alın: https://your-app.up.railway.app

claude.ai'ye bağlanın:

• Ayarlar → Model Bağlam Protokolü'nden sunucu ekleyin
• Sunucu URL'si: https://your-app.up.railway.app/mcp

📖 Tam Kılavuz: Ayrıntılı dağıtım talimatları, sorun giderme ve yapılandırma için RAILWAY.md sayfasına bakın.

Docker'a Dağıtın

# Build the image
docker build -t mcp-bitnovo-pay .

# Run with environment variables
docker run -d \
  -p 3000:3000 \
  -e PORT=3000 \
  -e BITNOVO_DEVICE_ID=your_device_id \
  -e BITNOVO_BASE_URL=https://pos.bitnovo.com \
  mcp-bitnovo-pay

Diğer Platformlara Dağıtın

Sunucu, Node.js ve Docker'ı destekleyen herhangi bir platformda çalışır:

• Heroku: Ortam değişkenleriyle Dockerfile'ı gönderin
• Fly.io: fly.toml yapılandırmasıyla dağıtın
• Google Cloud Run: Docker konteynerini dağıtın
• AWS ECS/Fargate: Görev tanımıyla dağıtın

Gerekli Ortam Değişkenleri:

• PORT - HTTP portu (çoğu platform tarafından otomatik ayarlanır)
• BITNOVO_DEVICE_ID - Bitnovo cihaz kimliğiniz
• BITNOVO_BASE_URL - Bitnovo API URL'si

Aktarım Modu Tespiti:

• PORT ortam değişkeni ayarlanmışsa → HTTP modu (uzak bağlantılar)
• PORT ayarlanmamışsa → stdio modu (yerel bağlantılar)

---

📦 Kurulum Seçenekleri

Seçenek A: npx Kullanma (Önerilir)

Kurulum gerekmez! npx komutu en son sürümü otomatik olarak indirir ve çalıştırır.

npx -y @bitnovopay/mcp-bitnovo-pay

Avantajlar:

• ✅ Her zaman en son sürümü alın
• ✅ Manuel güncelleme gerekmez
• ✅ Yerel kurulum gerekmez
• ✅ Hemen çalışır

Seçenek B: Depoyu Klonlama (Geliştirme İçin)

Kodu değiştirmesi gereken katkıda bulunanlar veya ileri düzey kullanıcılar için:

# Clone the repository
git clone https://github.com/bitnovo/mcp-bitnovo-pay.git
cd mcp-bitnovo-pay

# Or install from npm
npm install -g @bitnovopay/mcp-bitnovo-pay

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
npm start

Avantajlar:

• ✅ Kaynak kodun tam kontrolü
• ✅ Değişiklikleri yapma ve test etme yeteneği
• ✅ Projeye katkıda bulunmak için ideal

🔧 LLM Platformuna Göre Yapılandırma

Yapay zeka platformunuzu seçin ve özel kurulum kılavuzunu izleyin:

Claude Desktop (Anthropic)

Yapılandırma Dosyası Konumu: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) Kılavuz: Claude Kurulum Kılavuzu

Temel Yapılandırma:

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

Webhook'larla (gerçek zamanlı ödeme bildirimleri için):

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com",
        "BITNOVO_DEVICE_SECRET": "your_device_secret_hex",
        "WEBHOOK_ENABLED": "true",
        "TUNNEL_ENABLED": "true",
        "TUNNEL_PROVIDER": "ngrok",
        "NGROK_AUTHTOKEN": "your_ngrok_token",
        "NGROK_DOMAIN": "your-domain.ngrok-free.app"
      }
    }
  }
}

OpenAI ChatGPT

Kılavuz: OpenAI Kurulum Kılavuzu Desteklenenler: GPT-5, GPT-4o, Responses API, Agents SDK

Temel Yapılandırma:

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

Google Gemini

Kılavuz: Gemini Kurulum Kılavuzu Desteklenenler: Gemini 2.5 Flash/Pro (Eylül 2025), CLI, FastMCP

Temel Yapılandırma:

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

Ortam Değişkenleri

Değişken	Gerekli	Açıklama	Örnek
BITNOVO_DEVICE_ID	✅ Evet	Bitnovo Pay cihaz tanımlayıcınız	12345678-abcd-1234-abcd-1234567890ab
BITNOVO_BASE_URL	✅ Evet	Bitnovo API uç noktası	https://pos.bitnovo.com (üretim) https://payments.pre-bnvo.com (geliştirme)
BITNOVO_DEVICE_SECRET	⚠️ İsteğe bağlı	Webhook doğrulaması için HMAC gizli anahtarı	your_hex_secret
WEBHOOK_ENABLED	⚠️ İsteğe bağlı	Webhook sunucusunu etkinleştir	true veya false
TUNNEL_ENABLED	⚠️ İsteğe bağlı	Webhook'lar için tüneli otomatik başlat	true veya false
TUNNEL_PROVIDER	⚠️ İsteğe bağlı	Tünel sağlayıcı	ngrok, zrok veya manual

Güvenlik Notu: Kimlik bilgilerini asla sürüm kontrolüne kaydetmeyin. Ortam değişkenleri veya güvenli gizli anahtar yönetimi kullanın.

🛠️ MCP Araçları Referansı

Ödeme Oluşturma

create_payment_onchain

Doğrudan işlemler için belirli bir adresle kripto para ödemesi oluşturur.

Kullanım zamanı: Kullanıcı bir kripto para birimi belirttiğinde (Bitcoin, ETH, USDC, vb.)

{
  "amount_eur": 50.0,
  "input_currency": "BTC",
  "notes": "Coffee payment"
}

create_payment_link

Müşterilerin kripto para birimlerini seçebileceği web tabanlı bir ödeme URL'si oluşturur.

Kullanım zamanı: Belirli bir kripto para belirtilmeyen genel ödeme talebi (VARSAYILAN SEÇENEK)

{
  "amount_eur": 50.0,
  "url_ok": "https://mystore.com/success",
  "url_ko": "https://mystore.com/cancel",
  "notes": "Order #1234"
}

Ödeme Yönetimi

get_payment_status

Ayrıntılı bilgilerle mevcut ödeme durumunu getirir.

{
  "identifier": "payment_id_here"
}

Durum Kodları:

• NR (Hazır Değil): Ön ödeme oluşturuldu, kripto atanmadı
• PE (Beklemede): Müşteri ödemesi bekleniyor
• AC (Tamamlanma Bekleniyor): Mempool'da kripto tespit edildi
• CO (Tamamlandı): Ödeme blok zincirinde onaylandı
• EX (Süresi Doldu): Ödeme süre sınırı aşıldı
• CA (İptal Edildi): Ödeme iptal edildi
• FA (Başarısız): İşlem onaylanamadı

list_currencies_catalog

İsteğe bağlı tutar bazlı filtreleme ile mevcut kripto paraları getirir.

{
  "filter_by_amount": 25.0
}

generate_payment_qr

Yüksek kaliteli çıktı ile mevcut ödemeler için özel QR kodları oluşturur.

{
  "identifier": "payment_id_here",
  "qr_type": "both",
  "size": 512,
  "style": "branded"
}

QR Türleri:

• address: Yalnızca kripto adresi (müşteri tutarı manuel girer)
• payment_uri: Adres + tutar dahil (önerilir)
• both: Her iki türü de oluştur (önerilir)
• gateway_url: Ödeme ağ geçidi URL'sinin QR'ı

QR Boyut Seçenekleri (v1.1.0+):

• Varsayılan: 512px (modern ekranlar için optimize edildi)
• Aralık: 100px - 2000px
• Önerilen boyutlar:
  • 512px: Mobil ve web ekranları
  • 800-1200px: Standart baskı
  • 1600-2000px: Yüksek kaliteli baskı (posterler, standlar)

Kalite İyileştirmeleri (v1.1.0):

• ✨ QR desenleri için nearest çekirdek interpolasyonu ile keskin kenarlar
• 🎯 lanczos3 çekirdeği ile yüksek kaliteli logo ölçeklendirme
• 📦 Uyarlanabilir filtreleme ile PNG sıkıştırma seviyesi 6
• 🖼️ Daha iyi netlik için varsayılan boyut 300px'den 512px'e çıkarıldı

Webhook Araçları

get_webhook_events

Bitnovo Pay API'sinden gerçek zamanlı olarak alınan webhook olaylarını sorgular.

Kullanılabilir olduğunda: WEBHOOK_ENABLED=true

{
  "identifier": "payment_id_here",
  "limit": 50,
  "validated_only": true
}

get_webhook_url

Bitnovo paneli için yapılandırma talimatlarıyla genel webhook URL'sini getirir.

Kullanılabilir olduğunda: WEBHOOK_ENABLED=true

{
  "validate": true
}

get_tunnel_status

Tünel bağlantı durumunu teşhis eder (ngrok, zrok veya manuel).

Kullanılabilir olduğunda: WEBHOOK_ENABLED=true

{}

📚 Dokümantasyon

• API Araçları Referansı - Tüm MCP araçları için ayrıntılı dokümantasyon
• Kullanım Örnekleri - Gerçek dünya kullanım örnekleri
• Hata Yönetimi - Hata kodları ve sorun giderme
• Webhook Sistemi - Webhook yapılandırması ve tünel yönetimi

🏗️ Geliştirme

Kullanılabilir Betikler

npm run build        # Compile TypeScript to JavaScript
npm run dev          # Run development server with hot reload
npm start            # Start production server
npm test             # Run test suite
npm run test:watch   # Run tests in watch mode
npm run lint         # Run ESLint
npm run format       # Format code with Prettier

Mimari

┌─────────────────┐
│   MCP Tools     │ ← 8 tools: 5 payment + 3 webhook
│ (src/tools/)    │
├─────────────────┤
│   Services      │ ← Business logic: PaymentService, CurrencyService
│ (src/services/) │
├─────────────────┤
│   API Client    │ ← Bitnovo API integration with retry logic
│ (src/api/)      │
├─────────────────┤
│ Webhook Server  │ ← HTTP Express + Event Store + Tunnel Manager
│ (src/webhook-*) │
├─────────────────┤
│   Utilities     │ ← Logging, validation, error handling, crypto
│ (src/utils/)    │
└─────────────────┘

Çift Sunuculu Mimari

MCP sunucusu aynı anda iki sunucu çalıştırabilir:

┌─────────────────────────────────────────────────────────┐
│             MCP Bitnovo Pay Server                      │
│                                                         │
│  ┌──────────────┐  ┌──────────────────┐ ┌────────────┐│
│  │ MCP Server   │  │ Webhook Server   │ │  Tunnel    ││
│  │ (stdio)      │  │ (HTTP :3000)     │ │  Manager   ││
│  └──────┬───────┘  └────────┬─────────┘ └──────┬─────┘│
│         │                   │                   │      │
│         │    Event Store    │     Public URL    │      │
│         │   (in-memory)     │   (ngrok/zrok)    │      │
│         └──────────┬────────┴──────────┬────────┘      │
└────────────────────┼───────────────────┼───────────────┘
                     │                   │
            ┌────────┴────────┐  ┌───────┴────────┐
            │                 │  │                │
       Claude Desktop   Bitnovo API    Tunnel Provider
       (MCP Tools)      (Webhooks)    (ngrok/zrok/manual)

🔒 Güvenlik

• Yalnızca HTTPS - Tüm API çağrıları HTTPS kullanır
• HMAC Doğrulaması - SHA-256 ile webhook imza doğrulaması
• Tekrar Saldırısı Önleme - 5 dakikalık TTL ile nonce önbellekleme
• Veri Gizliliği - Hassas bilgiler günlüklerde maskelenir
• Kur Verisi Yok - Yanlışlıkları önlemek için döviz kurları ifşa edilmez
• Durumsuz Tasarım - Yerel kalıcılık yok, gerçek zamanlı API sorguları
• Otomatik Yeniden Bağlanma - Tüneller için 10 yeniden denemeye kadar üstel geri çekilme
• Sağlık İzleme - Her 60 saniyede bir bağlantı doğrulaması

📄 Lisans

Bu proje MIT Lisansı altında lisanslanmıştır - ayrıntılar için LICENSE dosyasına bakın.

🤝 Katkıda Bulunma

1. Depoyu çatallayın
2. Özellik dalınızı oluşturun (git checkout -b feature/amazing-feature)
3. Değişikliklerinizi işleyin (git commit -m 'Add amazing feature')
4. Dala gönderin (git push origin feature/amazing-feature)
5. Bir Çekme İsteği açın

📞 Destek

• Sorunlar: GitHub Sorunları
• Bitnovo Desteği: https://www.bitnovo.com/
• MCP Protokolü: https://modelcontextprotocol.io/

🌟 İlgili

• Model Bağlam Protokolü - Resmi MCP spesifikasyonu
• Bitnovo Pay - Kripto para ödeme platformu
• Bitnovo Pay - Dokümantasyon - Bitnovo Pay Resmi Dokümantasyonu
• Bitnovo Pay - İspanyolca Dokümantasyon - Bitnovo Pay Resmi Dokümantasyonu
• MCP SDK - TypeScript için resmi MCP SDK'sı