MCP Server Node.js

Bu proje, Model Context Protocol (MCP) kullanarak finansal analiz ve portföy yönetimi hizmetleri sunan Node.js tabanlı bir AI agent sistemidir. LangChain ve Ollama kullanarak yerel olarak çalışan yapay zeka modelleri ile kullanıcılara akıllı finansal danışmanlık hizmetleri sunar.

🚀 Özellikler

🤖 AI Agent Sistemi

• Master Agent: Gelen sorguları analiz ederek uygun uzman ajana yönlendirir
• Portfolio Analysis Agent: Yatırım portföylerini analiz eder ve strateji önerileri sunar
• Risk Analysis Agent: Portföy risk değerlendirmesi ve risk azaltma önerileri
• General Chatbot Agent: Genel finansal sorular ve sohbet

📊 Piyasa Verileri

• Finnhub API entegrasyonu ile gerçek zamanlı borsa verileri
• Hisse senedi fiyatları, değişim oranları ve piyasa analizi
• Portföy varlıklarının güncel piyasa değerlendirmesi

🔧 Teknik Özellikler

• Express.js web framework'ü
• LangChain ile AI model entegrasyonu
• Ollama ile yerel AI model desteği (Gemma 3:4B)
• RESTful API yapısı
• CORS desteği ile frontend entegrasyonu

📋 Gereksinimler

Sistem Gereksinimleri

• Node.js 18+
• npm veya yarn
• Ollama (yerel AI modeli için)
• Finnhub API Key (piyasa verileri için)

AI Model Kurulumu

# Ollama'yı indirin ve kurun: https://ollama.ai/
# Gemma 3 modelini çekin:
ollama pull gemma3:4b

# Ollama servisini başlatın:
ollama serve

🛠️ Kurulum

1. Proje Kurulumu

# Repoyu klonlayın
git clone <repo-url>
cd mcpServerNode

# Bağımlılıkları yükleyin
npm install

2. Ortam Değişkenleri

.env dosyası oluşturun:

# Finnhub API Key (piyasa verileri için)
FINNHUB_API_KEY=your_finnhub_api_key_here

# Ollama API URL
OLLAMA_BASE_URL=http://127.0.0.1:11434

# Server Port
PORT=8001

# LLM Model
LLM_MODEL=gemma3:4b

3. Finnhub API Key Alma

1. Finnhub.io sitesine kayıt olun
2. Ücretsiz API key alın
3. .env dosyasına ekleyin

🚀 Çalıştırma

Master Agent Server

# Master agent serverini başlatın
node master-server.js

Server http://localhost:8001 adresinde çalışacak.

Portfolio Analysis Server (Alternatif)

# Portfolio analysis serverini başlatın
node server.js

📡 API Endpoints

Master Agent Endpoint

POST /master-agent

Gelen sorguları analiz ederek uygun ajana yönlendirir.

Request:

{
  "query": "Portföyümü analiz edebilir misin?",
  "oid": "customer-123"
}

Response:

{
  "source": "portfolio_analysis_agent",
  "response": "Portföy analizi raporu burada gösterilecek..."
}

Portfolio Analysis Endpoint

POST /analyze-portfolio

Detaylı portföy analizi yapar.

Request:

{
  "oid": "customer-123"
}

Response:

{
  "portfolio_summary": "Portföy özeti...",
  "market_analysis": "Piyasa analizi...", 
  "final_strategy": "Yatırım stratejisi..."
}

🤖 Agent Tipleri ve Kullanım

1. Portfolio Analysis Agent

Tetikleyici kelimeler: portföy, analiz, yatırım, strateji

Örnek sorgular:

• "Portföyümü analiz et"
• "Yatırım tavsiyesi ver"
• "Hangi hisse senetlerini almalıyım?"

2. Risk Analysis Agent

Tetikleyici kelimeler: risk, volatilite, beta, var

Örnek sorgular:

• "Portföyümün riski nedir?"
• "Risk seviyemi değerlendir"
• "Volatilite analizi yap"

3. General Chatbot Agent

Diğer tüm sorgular

Örnek sorgular:

• "Merhaba"
• "Finansal piyasalar hakkında bilgi ver"
• "Borsada ne olup bitiyor?"

🏗️ Proje Yapısı

mcpServerNode/
├── master-server.js      # Master agent server (ana sunucu)
├── server.js            # Portfolio analysis server (alternatif)
├── tools.js             # AI agent araçları ve sınıfları
├── package.json         # Proje bağımlılıkları
├── .env                 # Ortam değişkenleri
├── .gitignore          # Git ignore dosyası
└── README.md           # Bu dosya

Dosya Açıklamaları

master-server.js

• Ana sunucu dosyası
• Gelen sorguları analiz eder ve uygun ajana yönlendirir
• LLM tabanlı akıllı routing sistemi

server.js

• Alternatif sunucu (portfolio odaklı)
• Adım adım portfolio analizi yapar
• Manuel orchestration işlevi görür

tools.js

• AI agent sınıflarını içerir
• LangChain Tool sınıfından türetilmiş uzman ajanlar
• Finnhub API entegrasyonu

🔧 Teknik Detaylar

Agent Routing Algoritması

// Gelen sorguyu LLM ile analiz et
const routerPrompt = `
    Sen bir yapay zeka yönlendiricisisin. 
    Kullanıcının sorgusunu analiz edip en uygun aracın adını seç.
    
    Araçlar:
    - portfolio_analysis_agent: Portföy analizi
    - risk_analysis_agent: Risk analizi  
    - general_chatbot_agent: Genel sohbet
`;

const response = await llm.invoke([
    new SystemMessage(routerPrompt),
    new HumanMessage(query)
]);

Piyasa Verisi Entegrasyonu

// Finnhub API ile gerçek zamanlı veri
const marketData = await getMarketDataForAssets(portfolioAssets);

// Veri formatı:
// "AAPL: Güncel Fiyat=$150.25, Değişim=+2.5%"

LLM Prompt Engineering

const analysisPrompt = `
    Sen bir Yatırım Stratejisi Danışmanısın.
    Portföy özeti ve güncel piyasa verilerine dayanarak
    3 adet net, uygulanabilir tavsiye sun.
`;

🔗 Entegrasyonlar

Frontend Entegrasyonu

Bu Node.js server, React tabanlı frontend ile çalışacak şekilde tasarlanmıştır:

// Frontend'den API çağrısı
const response = await fetch('http://localhost:8001/master-agent', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: "Portföyümü analiz et",
    oid: "user-123"
  })
});

Python Backend Entegrasyonu

Python FastAPI backend ile birlikte çalışabilir:

• Python backend: http://localhost:8000
• Node.js MCP Server: http://localhost:8001

🧪 Test Etme

Manuel Test

# Server çalışırken test edin
curl -X POST http://localhost:8001/master-agent \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Portföyümü analiz et",
    "oid": "test-user-123"
  }'

Test Senaryoları

1. Portfolio Analysis Test:

   {"query": "Yatırım portföyümü değerlendir", "oid": "user123"}
   

2. Risk Analysis Test:

   {"query": "Risk seviyemi analiz et", "oid": "user123"}
   

3. General Chat Test:

   {"query": "Merhaba, nasılsın?", "oid": "user123"}
   

🚨 Sorun Giderme

Ollama Bağlantı Sorunu

# Ollama servisini kontrol edin
ollama list

# Modeli tekrar çekin
ollama pull gemma3:4b

# Servisi yeniden başlatın
ollama serve

Finnhub API Hatası

• API key'in doğru olduğundan emin olun
• Günlük API limit kontrolü yapın
• .env dosyasının doğru yüklendiğini kontrol edin

Port Çakışması

# 8001 portunu kontrol edin
netstat -an | findstr :8001

# Başka port kullanın
PORT=8002 node master-server.js

📈 Performans ve Optimizasyon

Memory Usage

• Ollama modeli RAM'de tutulur (~4GB for Gemma 3:4B)
• Node.js heap boyutunu ayarlayın: node --max-old-space-size=8192

API Rate Limits

• Finnhub: 60 calls/minute (free tier)
• Ollama: Local, sınırsız

Caching

Portfolio verileri ve piyasa verileri için basit caching implementasyonu:

const cache = new Map();
const CACHE_TTL = 60000; // 1 dakika

🔮 Gelecek Geliştirmeler

Planlanan Özellikler

• Redis cache entegrasyonu
• WebSocket real-time updates
• Multiple LLM model desteği
• Advanced portfolio optimization
• Risk calculation algorithms
• Historical data analysis
• Custom alert system

Teknik İyileştirmeler

• TypeScript migration
• Unit test coverage
• API documentation (OpenAPI/Swagger)
• Docker containerization
• Load balancing support
• Logging framework (Winston)
• Health check endpoints

🤝 Katkıda Bulunma

1. Fork edin
2. Feature branch oluşturun (git checkout -b feature/AmazingFeature)
3. Commit yapın (git commit -m 'Add some AmazingFeature')
4. Push edin (git push origin feature/AmazingFeature)
5. Pull Request açın

📄 Lisans

Bu proje ISC lisansı altında lisanslanmıştır.

🆘 Destek

Sorunlar için:

1. GitHub Issues kullanın
2. Dokümantasyonu kontrol edin
3. Log dosyalarını inceleyin

---

Not: Bu proje eğitim ve demo amaçlıdır. Üretim ortamında kullanmadan önce security review yapın ve rate limiting ekleyin.