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
- Finnhub.io sitesine kayıt olun
- Ücretsiz API key alın
.envdosyası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ı
-
Portfolio Analysis Test:
{"query": "Yatırım portföyümü değerlendir", "oid": "user123"} -
Risk Analysis Test:
{"query": "Risk seviyemi analiz et", "oid": "user123"} -
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
.envdosyası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
- Fork edin
- Feature branch oluşturun (
git checkout -b feature/AmazingFeature) - Commit yapın (
git commit -m 'Add some AmazingFeature') - Push edin (
git push origin feature/AmazingFeature) - Pull Request açın
📄 Lisans
Bu proje ISC lisansı altında lisanslanmıştır.
🆘 Destek
Sorunlar için:
- GitHub Issues kullanın
- Dokümantasyonu kontrol edin
- 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.