FastCampus_mcp_a2a_stock_project

# FastCampus! LangGraph, MCP, A2A Protocol Based Multi-Agent System A **fully automated intelligent stock investment system** that integrates the entire investment process from real-time data collection to risk management and Human-in-the-Loop approval. ---  --- ## Key Components ### Agent Configuration #### **SupervisorAgent** - Master Orchestrator - **Workflow**: Orchestrator - **Core Functions**: Request analysis, agent coordination, sequential/parallel execution strategies - **Features**: Task delegation to sub-agents through LLM-based request parsing #### **DataCollectorAgent** - Integrated Data Collection - **Workflow**: 8-node data pipeline (collection → validation → integration → quality assessment) - **Core Functions**: Multi-source data collection, quality validation, standardization - **Features**: Integration of 5 domain MCP servers, calculation of data quality score (0.0~1.0) #### **AnalysisAgent** - 4D Analysis Engine - **Workflow**: 9-node analysis pipeline (individual analysis → integration → recommendations) - **Core Functions**: Integrated analysis of Technical, Fundamental, Macro, and Sentiment - **Features**: Category-based signal system, weighted average integration, reliability calculation #### **TradingAgent** - Human-in-the-Loop Trading - **Workflow**: Stock trading pipeline (strategy → optimization → risk → human approval → execution) - **Core Functions**: Strategy formulation, portfolio optimization, VaR-based risk assessment - **Features**: Conditional routing for human approval, real-time monitoring ### MCP Server Configuration #### **5 Kiwoom Securities REST API Based MCP Servers** - `market_domain` (Port 8031): Real-time quotes, charts, rankings, technical indicators - `info_domain` (Port 8032): Stock information, ETFs, themes, company information - `trading_domain` (Port 8030): Order management, account information, transaction history, mock trading - `investor_domain` (Port 8033): Institutional/foreign trends, investor behavior analysis - `portfolio_domain` (Port 8034): Asset management, VaR calculation, Sharpe ratio, risk metrics #### **3 External Data Collection & Analysis MCP Servers** - `financial_analysis_mcp` (Port 8040): Financial analysis, valuation tools - `naver_news_mcp` (Port 8050): News collection, sentiment analysis - `tavily_search_mcp` (Port 3020): Web search, market trend investigation #### **Agent-Specific MCP Server Connection Mapping** | Agent | Connected MCP Servers | Primary Functions | |-------|----------------------|------------------| | **DataCollectorAgent** | market_domain, info_domain, investor_domain, naver_news_mcp, tavily_search_mcp | Multi-source data collection, quality validation | | **AnalysisAgent** | market_domain, info_domain, financial_analysis_mcp, portfolio_domain | 4D integrated analysis, signal generation | | **TradingAgent** | trading_domain, portfolio_domain | Order execution, risk management, Human approval | | **SupervisorAgent** | (No direct connections) | Workflow coordination, agent orchestration | ### Methodology for Stock Data Analysis #### **Technical Analysis (技术分析)** - Integration of RSI, MACD, Moving Averages, Volume indicators - Automatic calculation of support/resistance levels, trend direction analysis - **Output**: BULLISH|BEARISH|NEUTRAL + STRONG_BUY~STRONG_SELL #### **Fundamental Analysis (基本分析)** - Evaluation of P/E, P/B, ROE, debt ratio, profitability indicators - **Output**: UNDERVALUED|FAIR|OVERVALUED + Investment signals #### **Macro Analysis (宏观经济分析)** - Analysis of GDP, inflation, interest rates, exchange rate impacts - **Output**: EXPANSION|STABLE|CONTRACTION + Sector recommendations #### **Sentiment Analysis (情感分析)** - Measurement of market sentiment based on news headlines/summaries - **Output**: POSITIVE|NEUTRAL|NEGATIVE + Response strategies ## 🛠️ Tech Stack ### **Backend & AI Framework** #### **Core AI Framework** - **LangGraph** 0.6.4 - State-based multi-agent workflow - **LangChain** 0.3.27 - LLM integration and chain management - **A2A SDK** 0.3.0 - Agent-to-Agent communication protocol #### **MCP Server Ecosystem** - **FastMCP** 2.11.3 - High-performance MCP server framework - **langchain-mcp-adapters** 0.1.9 - LangChain-MCP bridge #### **Data & Analysis** - **pandas** 2.3.1 - Data manipulation and analysis - **finance-datareader** 0.9.96 - Collection of Korean financial data - **fredapi** 0.5.2 - U.S. Federal Reserve economic data - **publicdatareader** 1.1.0 - Integration of Korean public data ### **Frontend & User Interface** #### **Core Framework** - **Next.js** 15.4.6 - Full-stack framework based on React - **React** 19.1.1 - Latest React ecosystem #### **AI Conversation Interface** - **@assistant-ui/react** 0.10.42 - AI assistant conversation UI - **@assistant-ui/react-hook-form** 0.10.8 - Form integration - **@assistant-ui/react-markdown** 0.10.9 - Markdown rendering #### **Charts & Visualization** - **lightweight-charts** 5.0.8 - TradingView lightweight chart library - **recharts** 3.1.2 - React chart library - **framer-motion** 12.23.12 - Advanced animations #### **State Management & Communication** - **zustand** 5.0.7 - Lightweight state management - **@a2a-js/sdk** 0.3.1 - A2A client SDK #### **UI Components** - **@radix-ui** - Accessibility-optimized Headless UI components - **Tailwind CSS** 4.1.12 - Utility-first CSS framework - **Lucide React** 0.536.0 - Icon library ### **Frontend Application Structure** #### **Core Implementation Features** - **🤖 AI Conversation Interface**: Natural language investment commands based on assistant-ui - **📊 Real-time Charts**: Visualization of quotes using TradingView lightweight charts - **💼 Portfolio Dashboard**: Integrated view of asset status, returns, and risk metrics - **🔔 Human-in-the-Loop**: Real-time approval UI for high-risk trades - **📈 Investment Analysis Tools**: Visualization of Technical/Fundamental/Macro/Sentiment analysis results - **⚡ Real-time Notifications**: WebSocket-based notifications for trading status and market changes #### **Page Structure** ```text frontend/src/app/ ├── page.tsx # Main dashboard ├── trading/ # Trading management page ├── portfolio/ # Portfolio management ├── analysis/ # Investment analysis tools ├── agents/ # Agent status monitoring ├── test-hitl/ # Human-in-the-Loop testing └── health/ # System status check ``` #### **Component Architecture** ```text src/components/ ├── agents/ # Agent interaction components ├── analysis/ # 4D analysis visualization ├── charts/ # TradingView & Recharts integration ├── trading/ # Order and Human approval UI ├── portfolio/ # Portfolio management tools ├── market/ # Market data display └── system/ # System status monitoring ``` ### **Development Environment & Deployment** #### **Runtime & Package Management** - **Python** 3.12+ - Backend runtime - **Node.js** 20+ - Frontend runtime - **Docker** & **Docker Compose** - Containerized deployment #### **Code Quality & Testing** - **Ruff** - Python linter and formatter - **Jest** & **Testing Library** - React testing - **TypeScript** 5 - Type safety ### **🎯 Production Ready Status** (As of January 2025) | Component | Implementation | Documentation | Testing | Status | |-----------|---------------|---------------|---------|---------| | **SupervisorAgent** | ✅ Complete | ✅ Ultra-detailed | 🔄 In Progress | 🟢 **Production Ready** | | **DataCollectorAgent** | ✅ Complete | ✅ Ultra-detailed | 🔄 In Progress | 🟢 **Production Ready** | | **AnalysisAgent** | ✅ Complete | ✅ Ultra-detailed | 🔄 In Progress | 🟢 **Production Ready** | | **TradingAgent** | ✅ Complete | ✅ Ultra-detailed | 🔄 In Progress | 🟢 **Production Ready** | | **MCP Servers** | ✅ Complete | ✅ Complete | 🔄 In Progress | 🟢 **Production Ready** | | **A2A Integration** | ✅ Complete | ✅ Complete | 🔄 In Progress | 🟢 **Production Ready** | | **Frontend** | ✅ Complete | ✅ Complete | 🔄 In Progress | 🟢 **Production Ready** | ### **Architecture Diagram** ```mermaid graph TB subgraph "Layer 4: A2A Agent Protocol" A2A_Agents[A2A Agents<br/>📡 External Interface] end subgraph "Layer 3: A2A Integration Bridge" A2A_Integration[A2A Integration<br/>🌐 Protocol Bridge] end subgraph "Layer 2: LangGraph Core Agents" LG_Agents[LangGraph Agents<br/>🤖 Core Intelligence] end subgraph "Layer 1: MCP Tool Ecosystem" MCP_Servers[MCP Servers<br/>🔧 Data & Tools] end A2A_Agents --> A2A_Integration A2A_Integration --> LG_Agents LG_Agents --> MCP_Servers ``` ### **Data Flow & Communication Patterns** ```mermaid sequenceDiagram participant User participant Supervisor as SupervisorAgent participant DataCollector as DataCollectorAgent participant Analysis as AnalysisAgent participant Trading as TradingAgent participant Human as Human-in-the-Loop participant MCP as MCP Servers User->>Supervisor: Investment request Supervisor->>DataCollector: Delegate data collection DataCollector->>MCP: Multi-source data collection MCP-->>DataCollector: Return raw data DataCollector-->>Analysis: Deliver refined data Analysis->>MCP: Utilize analysis tools MCP-->>Analysis: Analysis results Analysis-->>Trading: Deliver investment signals Trading->>MCP: Query portfolio information MCP-->>Trading: Account/position information Trading->>Trading: Risk assessment alt High Risk Trading->>Human: Approval request Human-->>Trading: Approve/Reject end Trading->>MCP: Execute order MCP-->>Trading: Execution results Trading-->>Supervisor: Report trade completion Supervisor-->>User: Deliver final results ``` ## **Code Reference** - **[src/code_index.md](src/code_index.md)** - Documentation of the entire system architecture and structure ## **Reference Information for Key Components** - **[LangGraph Agents](src/lg_agents/code_index.md)** - Agents configured with 4 Supervisor Patterns - **[MCP Servers](src/mcp_servers/code_index.md)** - MCP servers composed of a total of 8 domain-specific microservices - **[A2A Integration Layer](src/a2a_integration/code_index.md)** - A2A-LangGraph bridge - **[A2A Agents](src/a2a_agents/code_index.md)** - A2A protocol wrapper ## 📋 Installation Guide ### System Requirements - Python 3.12 or higher - Latest updated Docker Desktop (or Docker Engine and Docker Compose) - Recommended 16GB or more RAM - 30GB or more of free disk space ### Docker Environment ```bash # 1. Clone the project git clone <repository-url> cd project_1_stock_practice # 2. Set API keys (edit .env file) cp .env.example .env vi .env # Change required API keys to actual values # 3. Start the entire system (production mode) ./1-run-all-services.sh # 4. Start the entire system (including build) ./1-run-all-services.sh build # 5. Stop the system ./2-stop-all-services.sh ``` --- ### Environment Variable Setup ```bash # Copy template file cp .env.example .env # Edit .env file to set required values ``` Required environment variables: ```env # LLM API (required) OPENAI_API_KEY=your_openai_api_key # Kiwoom Securities API (required) KIWOOM_API_KEY=your_api_key KIWOOM_SECRET_KEY=your_secret_key KIWOOM_ACCOUNT_NO=your_account_number # TAVILY API KEY (required) TAVILY_API_KEY=your_tavily_key # Naver Search API NAVER_CLIENT_ID=your_naver_client_id NAVER_CLIENT_SECRET=your_naver_client_secret # FRED API FRED_API_KEY=your_fred_api_key # DART (Financial Supervisory Service electronic disclosure system) API DART_API_KEY=your_dart_api_key ``` --- ### Reference #### A2A (Agent-to-Agent) Protocol - [a2a-js_0.3.1.txt](docs/a2a-js_0.3.1.txt) - A2A JavaScript protocol documentation - [a2a-python_0.3.0.txt](docs/a2a-python_0.3.0.txt) - A2A Python protocol documentation - [a2a-samples_0.3.0.txt](docs/a2a-samples_0.3.0.txt) - A2A sample code and examples #### LangGraph & LangChain - [langgraph-llms_0.6.2.txt](docs/langgraph-llms_0.6.2.txt) - LangGraph 0.6.2 LLMs integration documentation - [langgraph-llms-full_0.6.2.txt](docs/langgraph-llms-full_0.6.2.txt) - LangGraph 0.6.2 LLMs complete guide - [langchain-llms.txt](docs/langchain-llms.txt) - LangChain LLMs integration documentation - [langchain-mcp-adapters.txt](docs/langchain-mcp-adapters.txt) - LangChain MCP adapter documentation #### MCP (Model Context Protocol) - [fastmcp_2.11.3_llms-full.txt](docs/fastmcp_2.11.3_llms-full.txt) - FastMCP 2.11.3 complete guide - [prompt-kit-llms-full.txt](docs/prompt-kit-llms-full.txt) - Prompt Kit LLMs complete guide #### Kiwoom Securities API Documentation - [kiwoom_rest_api_180_docs.md](docs/kiwoom_rest_api_180_docs.md) - Kiwoom Securities REST API 180 documentation - [kiwoom_rest_api_official_docs.pdf](docs/kiwoom_rest_api_official_docs.pdf) - Kiwoom Securities REST API official documentation (PDF) - [kiwoom_rest_api_official_docs.xlsx](docs/kiwoom_rest_api_official_docs.xlsx) - Kiwoom Securities REST API official documentation (Excel) #### Frontend & State Management - [useful_zustand_docs.txt](docs/useful_zustand_docs.txt) - Zustand state management library documentation