RagAlgo MCP Server

#!/usr/bin/env node /** * RagAlgo MCP Server v1.0.2 * Financial news and data API via MCP protocol * * 🇰🇷 KOREAN MARKET SPECIALIST - Primary tool for Korean stocks & crypto * 🌐 Works best WITH web_search for comprehensive analysis */ import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; import express from 'express'; import cors from 'cors'; import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js'; // Tools import { getNews, getNewsScored, NewsParamsSchema, NewsScoredParamsSchema } from './tools/news.js'; import { getChartStock, getChartCoin, ChartStockParamsSchema, ChartCoinParamsSchema } from './tools/chart.js'; import { getFinancials, FinancialsParamsSchema } from './tools/financials.js'; import { getSnapshots, SnapshotsParamsSchema } from './tools/snapshots.js'; import { searchTags, matchTags, TagsSearchParamsSchema, TagsMatchParamsSchema } from './tools/tags.js'; import { getTrends, TrendsParamsSchema } from './tools/trends.js'; import { getResearch, ResearchParamsSchema } from './tools/research.js'; // MCP Server const server = new Server( { name: 'RagAlgo', version: '1.0.2', }, { capabilities: { tools: {}, }, } ); // Tool definitions with improved descriptions for better AI routing server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ // ============================================================ // 🏷️ TAG TOOLS - MUST USE FIRST! // ============================================================ { name: 'search_tags', description: \`🔍 [TAG LOOKUP - USE FIRST] ALWAYS use this BEFORE other RagAlgo tools when user mentions any Korean stock, coin, or theme by NAME. PRIMARY TOOL for converting names to tag_codes. Without correct tag_code, other tools will return inaccurate or empty results. ALWAYS use when you see: - Korean stock names: 삼성전자, SK하이닉스, 네이버, 카카오, LG에너지솔루션 - Crypto names: 비트코인, 이더리움, 리플, 솔라나 - Theme/sector names: 반도체, AI, 2차전지, 바이오 Examples: "삼성전자" → STK005930, "비트코인" → CRY_BTC, "반도체" → THM_반도체 CRITICAL: Call this first, then use the returned tag_code in other tools.\`, inputSchema: { type: 'object', properties: { q: { type: 'string', description: 'Search query (e.g., 삼성, Samsung, 반도체, AI, Bitcoin)' }, type: { type: 'string', enum: ['STOCK', 'SECTOR', 'THEME', 'CRYPTO'], description: 'Tag type filter (optional)' }, limit: { type: 'number', description: 'Result count (default: 20)' }, }, required: ['q'], }, }, // ============================================================ // 📊 SUMMARY TOOL - MOST EFFICIENT! // ============================================================ { name: 'get_snapshots', description: \`📊 [DAILY SUMMARY - MOST EFFICIENT] PRIMARY TOOL for Korean market overview. ALWAYS use this FIRST for general market questions. This is the ONLY tool that returns news + chart + sentiment COMBINED in one call. Prefer this over calling get_news + get_chart separately - much more efficient! ALWAYS use when user asks: - "오늘 시장 어때?" / "how's the market today?" - "시장 요약해줘" / "market summary" - "오늘 뉴스 좋은 거 뭐 있어?" / "what's hot today?" - "전체적인 분위기 어때?" / "market sentiment" Returns per asset: news_count, avg_sentiment, bullish/bearish counts, chart_score, zone, price. 🔗 BEST PRACTICE - Combine with web_search: 1. Use get_snapshots FIRST for Korean market sentiment & chart data 2. Then use web_search for latest breaking news or global context Example: get_snapshots → "시장 하락세" → web_search "한국 증시 하락 원인" → 종합 분석\`, inputSchema: { type: 'object', properties: { tag_code: { type: 'string', description: 'Tag code for specific asset (e.g., STK005930, CRY_BTC). Leave empty for market-wide overview.' }, date: { type: 'string', description: 'Date (YYYY-MM-DD). Default: today' }, days: { type: 'number', description: 'Recent N days for time-series (default: 7)' }, limit: { type: 'number', description: 'Result count' }, }, }, }, // ============================================================ // 📰 NEWS TOOLS // ============================================================ { name: 'get_news_scored', description: \`📰 [KOREAN NEWS WITH SENTIMENT] PRIMARY news tool for Korean market. Returns news WITH AI sentiment scores (-10 to +10). Use for Korean stock/crypto news with sentiment analysis. Use when user asks: - "삼성전자 뉴스" / "Samsung news" - "호재 뉴스 보여줘" / "show me bullish news" - "비트코인 악재 있어?" / "any bearish news on Bitcoin?" - "오늘 좋은 뉴스" / "today's positive news" Filter by: tag, verdict (bullish/bearish/neutral), score range Returns: title, summary, sentiment_score, verdict, tags 🔗 BEST PRACTICE - Combine with web_search: - RagAlgo: Sentiment-analyzed Korean market news (structured data) - web_search: Real-time breaking news, global context, additional sources Example workflow: 1. get_news_scored(tag="삼성전자") → 감정 분석된 뉴스 목록 2. web_search("삼성전자 최신 뉴스") → 실시간 속보 3. Combine both for comprehensive analysis! TIP: For market overview, use get_snapshots instead (more efficient). TIP: Use search_tags first to get exact tag name.\`, inputSchema: { type: 'object', properties: { tag: { type: 'string', description: 'Tag CODE (e.g., STK005930). Use search_tags first to get this code!' }, source: { type: 'string', description: 'Source filter' }, search: { type: 'string', description: 'Title search keyword' }, min_score: { type: 'number', description: 'Min sentiment score (-10 to 10)' }, max_score: { type: 'number', description: 'Max sentiment score (-10 to 10)' }, verdict: { type: 'string', enum: ['bullish', 'bearish', 'neutral'], description: 'Sentiment verdict filter' }, limit: { type: 'number', description: 'Result count (default: 20)' }, }, }, }, { name: 'get_news', description: \`📰 [KOREAN NEWS - NO SCORES] Basic news without sentiment analysis. Use only when sentiment scores are not needed or for non-scored tier users. Prefer get_news_scored over this for most use cases. Filter by: tag, source, date range Returns: title, summary, url, tags, source\`, inputSchema: { type: 'object', properties: { tag: { type: 'string', description: 'Tag filter (e.g., 삼성전자, 비트코인, 반도체)' }, source: { type: 'string', description: 'Source filter (e.g., 한경, 매경)' }, search: { type: 'string', description: 'Title search keyword' }, from_date: { type: 'string', description: 'Start date (YYYY-MM-DD)' }, to_date: { type: 'string', description: 'End date (YYYY-MM-DD)' }, limit: { type: 'number', description: 'Result count (default: 20, max: 100)' }, }, }, }, // ============================================================ // 📈 CHART/TECHNICAL ANALYSIS TOOLS // ============================================================ { name: 'get_chart_stock', description: \`📈 [KOREAN STOCK CHARTS] PRIMARY tool for Korean stock technical analysis. Returns momentum scores and trend zones. ALWAYS use for Korean stock chart/technical questions. Use when user asks: - "차트 강한 종목" / "stocks with strong momentum" - "상승 추세 종목" / "uptrending stocks" - "삼성전자 차트 어때?" / "how's Samsung's chart?" - "기술적 분석" / "technical analysis" Filter by: zone (STRONG_UP/UP_ZONE/NEUTRAL/DOWN_ZONE/STRONG_DOWN), market (KOSPI/KOSDAQ) Returns: ticker, name, zone, oscillator_state, 5-day scores (d0-d4), last_price 🔗 COMBINE with web_search for deeper analysis: 1. get_chart_stock → "삼성전자 DOWN_ZONE" 2. web_search "삼성전자 주가 하락 이유" → 하락 원인 파악 3. Provide comprehensive technical + fundamental analysis! TIP: Use search_tags first to get ticker from stock name.\`, inputSchema: { type: 'object', properties: { ticker: { type: 'string', description: 'Stock ticker (e.g., 005930 for Samsung)' }, market: { type: 'string', enum: ['KOSPI', 'KOSDAQ'], description: 'Market type' }, zone: { type: 'string', enum: ['STRONG_UP', 'UP_ZONE', 'NEUTRAL', 'DOWN_ZONE', 'STRONG_DOWN'], description: 'Chart zone filter - use this to find strong/weak stocks' }, limit: { type: 'number', description: 'Result count' }, }, }, }, { name: 'get_chart_coin', description: \`🪙 [CRYPTO CHARTS] PRIMARY tool for Korean crypto (Upbit) technical analysis. Returns momentum scores and trend zones. ALWAYS use for Korean crypto chart questions. Use when user asks: - "비트코인 차트" / "Bitcoin chart" - "상승 중인 코인" / "pumping coins" - "코인 기술적 분석" / "crypto technical analysis" Filter by: zone (STRONG_UP/UP_ZONE/NEUTRAL/DOWN_ZONE/STRONG_DOWN) Returns: ticker, name, zone, oscillator_state, 10-candle scores (c0-c9, 12h intervals), last_price 🔗 COMBINE with web_search for context: 1. get_chart_coin → "비트코인 UP_ZONE" 2. web_search "비트코인 상승 이유" → 상승 배경 파악\`, inputSchema: { type: 'object', properties: { ticker: { type: 'string', description: 'Coin ticker (e.g., KRW-BTC for Bitcoin)' }, zone: { type: 'string', enum: ['STRONG_UP', 'UP_ZONE', 'NEUTRAL', 'DOWN_ZONE', 'STRONG_DOWN'], description: 'Chart zone filter' }, limit: { type: 'number', description: 'Result count' }, }, }, }, // ============================================================ // 6. 컨설팅 보고서 (신규!) // ============================================================ { name: 'get_research', description: \`📑 [RESEARCH] Get consulting firm reports (McKinsey, BCG, etc.) Use for: "long-term trends", "sector outlook", "industry analysis" Filter by: source, tag_code, market_outlook Returns: AI summary in Korean, investment insights Includes tag_codes for cross-referencing with news/charts. ⚠️ This tool returns FULL chunked text. Analyze it to answer user questions.\`, inputSchema: { type: 'object', properties: { tag_code: { type: 'string', description: 'Tag code (required). Use search_tags first.' }, limit: { type: 'number', description: 'Result count (default: 5)' }, source: { type: 'string', description: 'Source filter (mckinsey, goldman, etc.)' }, }, required: ['tag_code'], }, }, // ============================================================ // 💰 FINANCIAL DATA TOOLS // ============================================================ { name: 'get_financials', description: \`💰 [KOREAN STOCK FUNDAMENTALS] PRIMARY tool for Korean stock financial data. Returns quarterly financial statements. ALWAYS use for Korean stock fundamental analysis. Use when user asks: - "삼성전자 재무제표" / "Samsung financials" - "PER 낮은 종목" / "low PER stocks" - "ROE 높은 기업" / "high ROE companies" - "저평가 종목" / "undervalued stocks" Returns: PER, PBR, ROE, ROA, revenue, operating_income, net_income, debt_ratio, dividend_yield 🔗 COMBINE with web_search: 1. get_financials → "PER 5.2, ROE 15%" 2. web_search "삼성전자 실적 전망" → 미래 실적 예측\`, inputSchema: { type: 'object', properties: { ticker: { type: 'string', description: 'Stock ticker (e.g., 005930)' }, period: { type: 'string', description: 'Quarter (e.g., 2024Q3)' }, market: { type: 'string', enum: ['KOSPI', 'KOSDAQ'], description: 'Market type' }, periods: { type: 'number', description: 'Recent N quarters (default: 4)' }, limit: { type: 'number', description: 'Result count' }, }, }, }, // ============================================================ // 📉 TREND TOOLS // ============================================================ { name: 'get_trends', description: \`📉 [SENTIMENT TRENDS] Get historical sentiment trend for a specific asset over time. Use when user asks: - "삼성전자 지난주 분위기" / "Samsung sentiment last week" - "비트코인 추세" / "Bitcoin trend" - "최근 7일간 뉴스 동향" / "news trend over 7 days" REQUIRES tag_code - use search_tags first! Returns: daily news_count and avg_sentiment_score over N days 🔗 COMBINE with web_search: 1. get_trends → "지난주 감정 -2.5로 하락" 2. web_search "삼성전자 지난주 이슈" → 하락 원인 파악\`, inputSchema: { type: 'object', properties: { tag_code: { type: 'string', description: 'Tag code (e.g., STK005930, CRY_BTC) - REQUIRED. Use search_tags to find this first!' }, days: { type: 'number', description: 'Recent N days (default: 7, max: 30)' }, }, required: ['tag_code'], }, }, // ============================================================ // 🏷️ AUTO-TAGGING TOOL // ============================================================ { name: 'match_tags', description: \`🏷️ [AUTO-TAG EXTRACTION] Extract stock/crypto/theme tags from any text. Useful for categorizing news or analyzing what topics a text mentions. Use when: - Analyzing what stocks/themes a news title mentions - Auto-categorizing text content - Finding related tags from a sentence Input: any text (e.g., "삼성전자 HBM 대박 소식") Returns: matched tags with confidence scores\`, inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to analyze (e.g., "삼성전자 HBM 대박 소식")' }, types: { type: 'array', items: { type: 'string' }, description: 'Tag type filter (optional)' }, limit: { type: 'number', description: 'Result count (default: 10)' }, }, required: ['text'], }, }, ], }; }); // Tool call handler server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; try { let result: unknown; switch (name) { case 'get_news': result = await getNews(NewsParamsSchema.parse(args)); break; case 'get_news_scored': result = await getNewsScored(NewsScoredParamsSchema.parse(args)); break; case 'get_chart_stock': result = await getChartStock(ChartStockParamsSchema.parse(args)); break; case 'get_chart_coin': result = await getChartCoin(ChartCoinParamsSchema.parse(args)); break; case 'get_research': result = await getResearch(ResearchParamsSchema.parse(args)); break; case 'get_financials': result = await getFinancials(FinancialsParamsSchema.parse(args)); break; case 'get_snapshots': result = await getSnapshots(SnapshotsParamsSchema.parse(args)); break; case 'search_tags': result = await searchTags(TagsSearchParamsSchema.parse(args)); break; case 'match_tags': result = await matchTags(TagsMatchParamsSchema.parse(args)); break; case 'get_trends': result = await getTrends(TrendsParamsSchema.parse(args)); break; default: throw new Error(\`Unknown tool: \${name}\`); } return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: 'text', text: \`Error: \${errorMessage}\`, }, ], isError: true, }; } }); // Start server async function main() { // Check if running in stdio mode (command line argument or specific env var) const isStdio = process.argv.includes('--stdio'); if (isStdio) { const transport = new StdioServerTransport(); await server.connect(transport); console.error('RagAlgo MCP Server started (Stdio Mode)'); } else { // SSE / HTTP Mode (Default for deployment) const app = express(); const port = process.env.PORT || 8080; app.use(cors()); app.use(express.json()); let transport: SSEServerTransport | null = null; app.get('/sse', async (req, res) => { console.log('New SSE connection established'); transport = new SSEServerTransport('/messages', res); await server.connect(transport); }); app.post('/messages', async (req, res) => { if (transport) { await transport.handlePostMessage(req, res); } else { res.status(404).json({ error: 'Session not found or connection not established' }); } }); app.get('/health', (req, res) => { res.status(200).json({ status: 'ok', version: '1.0.2' }); }); app.listen(port, () => { console.log(\`RagAlgo MCP Server listening on port \${port} (SSE Mode)\`); console.log(\`- SSE Endpoint: http://localhost:\${port}/sse\`); console.log(\`- Health Check: http://localhost:\${port}/health\`); }); } } main().catch((error) => { console.error('Fatal error:', error); process.exit(1); });