Ripple10Hub MCP Server

Model Context Protocol Server untuk Ripple10Hub Streams API

Version 1.0.0 • Built with Go & MCP SDK

Pendahuluan

Ripple10Hub MCP Server adalah implementasi Model Context Protocol (MCP) server yang memungkinkan Large Language Models (LLMs) seperti Claude, GPT, atau model AI lainnya untuk berinteraksi dengan Ripple10Hub Streams API secara langsung.

Server ini menyediakan 15 tools MCP yang mencakup:

  • CRUD operations untuk streams (Create, Read, Update, Delete)
  • Update enrichment data (Topic, Sentiment, Emotion, OCEAN)
  • Summary & Analytics API (Breakdown, Emotions, OCEAN, Engagement)
  • Filtering, sorting, dan pagination
  • High-concurrency safe untuk production use

Catatan: MCP Server ini dirancang khusus untuk integrasi dengan AI Assistants (Claude Desktop, ChatGPT plugins, dll) sehingga AI dapat secara otomatis mengakses dan menganalisis data social media streams tanpa perlu manual API calls.

Instalasi & Konfigurasi

1. Prerequisites

  • • Go 1.22 atau lebih baru
  • • Akses ke Ripple10Hub Streams API
  • • API Key yang valid dari Ripple10Hub

2. Clone & Install Dependencies

# Clone repository
git clone https://github.com/yourusername/mcp-r10hub.git
cd mcp-r10hub

# Install dependencies
go mod tidy

3. Konfigurasi Environment Variables

Buat file .env di root directory:

# Ripple10Hub API Configuration
R10_BASE_URL=http://localhost:8080
R10_API_KEY=your-api-key-here
R10_HTTP_TIMEOUT_SECONDS=15

# MCP Server Configuration
PORT=8081
LOG_LEVEL=info

Penting: Ganti your-api-key-here dengan API key Ripple10Hub yang valid. Tanpa API key, semua tools akan gagal (kecuali health_check).

4. Menjalankan Server

# Production build (recommended)
go build -o mcp-server ./cmd/server/main.go

# Server akan dijalankan otomatis oleh Claude Desktop (stdio transport)

Catatan: Server ini menggunakan stdio transport (standard input/output) yang merupakan metode standar untuk MCP servers. Server akan di-launch secara otomatis oleh Claude Desktop dan berkomunikasi via stdin/stdout menggunakan JSON-RPC 2.0.

Tips: Anda tidak perlu menjalankan server secara manual. Claude Desktop akan otomatis start/stop server sesuai kebutuhan.

Daftar MCP Tools

Tool Name Deskripsi API Endpoint
health_check Cek status kesehatan API Ripple10Hub GET /health
create_stream Membuat stream baru POST /api/streams
get_streams Mengambil list streams dengan filter & pagination GET /api/streams
get_stream_by_id Mengambil detail satu stream berdasarkan ID GET /api/streams/:id
update_stream Update data stream yang sudah ada PUT /api/streams/:id
delete_stream Menghapus stream berdasarkan ID DELETE /api/streams/:id
update_topic Update topic enrichment untuk stream PUT /api/streams/:id/topic
update_sentiment Update sentiment enrichment untuk stream PUT /api/streams/:id/sentiment
update_emotion Update emotion scores (8 dimensi) untuk stream PUT /api/streams/:id/emotion
update_ocean Update OCEAN personality scores untuk stream PUT /api/streams/:id/ocean
summary_main Mendapatkan comprehensive summary data GET /api/streams/summary
summary_breakdown Mendapatkan breakdown/count matrices GET /api/streams/summary/breakdown
summary_emotions Mendapatkan agregat emotion scores GET /api/streams/summary/emotions
summary_ocean Mendapatkan agregat OCEAN personality scores GET /api/streams/summary/ocean
summary_engagement Mendapatkan agregat engagement metrics GET /api/streams/summary/engagement

Contoh Penggunaan

Skenario: Analisis Sentiment Twitter tentang Bank BRI

Misalkan Anda ingin menganalisis sentimen mention Bank BRI di Twitter pada bulan Oktober 2025. Berikut adalah contoh prompt yang bisa diberikan ke AI Assistant (Claude/ChatGPT) yang sudah terhubung dengan MCP server ini:

Prompt ke AI:

"Buatkan analisis sentiment untuk mention Bank BRI di Twitter dari tanggal 1 Oktober 2025 sampai 31 Oktober 2025. Tampilkan breakdown berdasarkan sentiment (positif, negatif, netral) dan juga top 5 user yang paling aktif mention."

AI akan secara otomatis:

  1. 1
    Memanggil tool summary_breakdown dengan parameter: 
    {
  "start_date": "2025-10-01",
  "end_date": "2025-10-31",
  "channel": "twitter",
  "project_id": 9701
}
  2. 2 Menganalisis response JSON yang diterima
  3. 3 Menyajikan insight dalam bahasa natural yang mudah dipahami

Integrasi dengan Claude Desktop

Untuk menghubungkan MCP server dengan Claude Desktop:

  1. 1
    Build binary server terlebih dahulu: 
    cd /path/to/mcp-r10hub
go build -o mcp-server ./cmd/server/main.go
  2. 2
    Buka file konfigurasi Claude Desktop: 
    # macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows  
%APPDATA%\Claude\claude_desktop_config.json
  3. 3
    Tambahkan konfigurasi MCP server: 
    {
  "mcpServers": {
    "ripple10hub": {
      "command": "/full/path/to/mcp-r10hub/mcp-server",
      "env": {
        "R10_BASE_URL": "http://localhost:8080",
        "R10_API_KEY": "your-api-key-here",
        "R10_HTTP_TIMEOUT_SECONDS": "15",
        "LOG_LEVEL": "info"
      }
    }
  }
}

    Penting: Ganti /full/path/to/mcp-r10hub/mcp-server dengan absolute path ke binary server Anda.

  4. 4 Restart Claude Desktop
  5. 5 Verifikasi dengan menanyakan: "Cek apakah Ripple10Hub API berjalan dengan baik?" (Claude akan memanggil tool health_check)

Keuntungan stdio transport:

  • • Claude Desktop otomatis start/stop server sesuai kebutuhan
  • • Tidak perlu manage port atau network configuration
  • • Lebih aman karena tidak expose HTTP endpoint
  • • Sesuai dengan standar MCP protocol terbaru

Contoh Prompt Lainnya

  • Analytics

    "Tampilkan top 5 topik yang paling banyak dibahas di Instagram minggu ini"

  • Emotion Analysis

    "Analisis emotion profile user yang mention produk X di bulan November"

  • Engagement

    "Hitung total engagement (views, likes, shares, comments) untuk channel YouTube bulan ini"

  • Filtering

    "Cari semua tweet negatif tentang customer service yang belum di-enrich sentimentnya"

Error Handling & Batasan

Common Errors

"R10_API_KEY is not configured"

Penyebab: API key tidak diset di environment variable.
Solusi: Pastikan R10_API_KEY diisi dengan benar di file .env

"ripple10hub API error: status=401"

Penyebab: API key tidak valid atau sudah expired.
Solusi: Verifikasi API key dengan team Ripple10Hub atau regenerate API key baru

"ripple10hub API error: status=404"

Penyebab: Data stream tidak ditemukan (ID tidak valid).
Solusi: Periksa kembali ID stream yang digunakan

"request failed: context deadline exceeded"

Penyebab: Request timeout (lebih dari 15 detik).
Solusi: Periksa koneksi network atau naikkan R10_HTTP_TIMEOUT_SECONDS

Batasan & Best Practices

  • Concurrency Safe: Server ini aman untuk handle multiple request simultan
  • Stateless: Tidak ada shared mutable state, cocok untuk horizontal scaling
  • Rate Limiting: Ikuti rate limit dari Ripple10Hub API (biasanya ada di dokumentasi API)
  • Pagination: Untuk dataset besar, gunakan pagination (page & limit) agar response tetap cepat
  • Date Format: Enrichment date harus format YYYY-MM-DD HH:MM:SS
  • Security: Jangan expose API key di client-side atau public repository

Tips: Untuk debugging, set LOG_LEVEL=debug di environment variable untuk melihat detail request/response di console.

Alur Request MCP

Berikut adalah flow data dari AI Assistant hingga Ripple10Hub API:

1

AI Assistant (Claude/GPT)

User memberikan prompt natural language

2

MCP Client (di AI)

AI mengidentifikasi tool yang tepat & menyusun parameters

3

MCP Server (Go) - Tool Handler

Menerima request, validasi, dan routing ke R10Client

4

R10Client (HTTP Client)

Build HTTP request dengan header X-API-KEY, query params, body JSON

5

Ripple10Hub Streams API

Proses request, query database, return JSON response

6

Response Flow (balik ke AI)

R10Client → MCP Server → AI Assistant → User (natural language)

Teknologi Stack:

  • • Language: Go 1.22+
  • • MCP SDK: github.com/mark3labs/mcp-go
  • • Transport: Server-Sent Events (SSE)
  • • HTTP Client: Standard lib net/http dengan connection pooling
  • • Config: Environment variables (.env)