Financial AI Agent System

# 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 ```bash # 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 ```bash # 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: ```env # 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](https://finnhub.io/) sitesine kayıt olun 2. Ücretsiz API key alın 3. `.env` dosyasına ekleyin ## 🚀 Çalıştırma ### Master Agent Server ```bash # Master agent serverini başlatın node master-server.js ``` Server `http://localhost:8001` adresinde çalışacak. ### Portfolio Analysis Server (Alternatif) ```bash # 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:** ```json { "query": "Portföyümü analiz edebilir misin?", "oid": "customer-123" } ``` **Response:** ```json { "source": "portfolio_analysis_agent", "response": "Portföy analizi raporu burada gösterilecek..." } ``` ### Portfolio Analysis Endpoint **POST** `/analyze-portfolio` Detaylı portföy analizi yapar. **Request:** ```json { "oid": "customer-123" } ``` **Response:** ```json { "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ı ```javascript // 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 ```javascript // 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 ```javascript 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: ```javascript // 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 ```bash # 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:** ```json {"query": "Yatırım portföyümü değerlendir", "oid": "user123"} ``` 2. **Risk Analysis Test:** ```json {"query": "Risk seviyemi analiz et", "oid": "user123"} ``` 3. **General Chat Test:** ```json {"query": "Merhaba, nasılsın?", "oid": "user123"} ``` ## 🚨 Sorun Giderme ### Ollama Bağlantı Sorunu ```bash # 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ı ```bash # 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: ```javascript 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.