ragalgo-mcp-server 1.0.4 → 1.0.6

package/README.md

@@ -1,73 +1,192 @@
 # RagAlgo: Dynamic RAG Engine for AI Reliability
 
-> **AI 신뢰성을 위한 다이내믹 RAG 엔진**
+[![npm version](https://img.shields.io/npm/v/ragalgo-mcp-server.svg)](https://www.npmjs.com/package/ragalgo-mcp-server)
+[![npm downloads](https://img.shields.io/npm/dm/ragalgo-mcp-server.svg)](https://www.npmjs.com/package/ragalgo-mcp-server)
+[![GitHub stars](https://img.shields.io/github/stars/kokogo100/ragalgo-mcp-server?style=social)](https://github.com/kokogo100/ragalgo-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
 
-RagAlgo는 변동성이 큰 한국 금융(주식/코인) 데이터를 **'태그(Tag)'**와 **'점수(Score)'**로 표준화하여 제공하는 **AI 전용 MCP 서버**입니다.
-여러분의 AI 에이전트가 인터넷을 헤매지 않고, 가장 효율적으로 시장의 "진실(State-of-Truth)"을 파악할 수 있도록 돕습니다.
+> **"Your AI is an Analyst, NOT a Day Trader."**
 
-- **핵심 기능:** KOSPI/KOSDAQ 및 업비트(Upbit) 기반의 실시간 차트 점수, 뉴스 감정 분석
-- **무료 테스트:** 지금 바로 설치하여 **1,000회 무료 호출**로 충분히 테스트해보세요.
-- **상세 문서:** 웹소켓 연동 및 비즈니스 플랜 등 자세한 내용은 [공식 웹사이트(ragalgo.com)](https://www.ragalgo.com)에서 확인하실 수 있습니다.
+
+RagAlgo is an **MCP Server** that provides **mathematically scored financial context** (Korean Stocks/Crypto) to AI agents.
+We focus on **"State-of-Truth"** (Daily Closed Data) to prevent AI hallucinations caused by real-time market noise.
+
+- **Analyst, Not Broker:** We provide "Daily Analysis Reports" (Post-Market), not real-time tick data.
+- **Scored Context:** Instead of raw prices, we give you "Scores" (0~100) and "Zones" (Forest vs Tree).
+- **Global Market Specialist:** Optimized for US, UK, JP, KR, and Crypto.
+
+👉 **[Official Website (ragalgo.com)](https://www.ragalgo.com)**
 
 ---
 
-## 🚀 설치 및 실행
+## 📖 Architecture & Whitepaper
+
+Discover why RagAlgo is the **"Hippocampus"** for Agentic AI, not just another RAG.
+
+### 🏗️ Data Pipeline Architecture
 
-### 1. 직접 실행 (npx)
+Our production system on Railway processes global financial data 24/7:
 
-```bash
-# 별도 설치 없이 바로 실행 (API Key 필요)
-npx -y @ragalgo/server
 ```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        RagAlgo Data Pipeline (Railway)                      │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  📥 COLLECT              🔍 FILTER              🏷️ TAG           📊 SCORE  │
+│  ─────────────          ──────────────         ─────────        ──────────  │
+│  • KR-News-Collector    • filter-worker-1      • tag-worker     • Gemini-1  │
+│  • US-News-Collector    • filter-worker-2      • Meta-Hierarchy • Gemini-2  │
+│  • UK-News-Collector    • filter-worker-3      •   Worker       • ...       │
+│  • JP-News-Collector    • ibkr_filter_worker3  │                • Gemini-7  │
+│  • research-collector   │                      │                │           │
+│                         │                      │                │           │
+│  ════════════════════════════════════════════════════════════════════════  │
+│                                    ↓                                        │
+│                      📦 SNAPSHOT (Daily 18:00 KST)                          │
+│                      ──────────────────────────────                         │
+│                      • KR-Snapshot  • US-Snapshot                           │
+│                      • UK-Snapshot  • JP-Snapshot                           │
+│                      • CRY-Snapshot • Unified-Snapshot                      │
+│                                    ↓                                        │
+│                          🚀 SERVE (MCP Server)                              │
+│                          ─────────────────────                              │
+│                          • RagAlgo-Service (SSE/stdio)                      │
+│                          • ragalgo-relay-server (WebSocket)                 │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+![RagAlgo Architecture](./architecture.png)
+
+*   **[Vision Whitepaper (The Hook)](./docs/RagAlgo_Report_EN.md)**
+    *   **Concept**: Why RagAlgo is a "Semantic Digital Twin" (SDT) using the Hippocampus analogy.
+    *   **Value**: Explains the "Self-Growing Taxonomy" and "Data Flywheel" effect.
+*   **[Technical Report (The Proof)](./docs/CKN_Architecture_EN.md)**
+    *   **Deep Dive**: Detailed anatomy of the Contextual Knowledge Network (CKN).
+    *   **2025 Trend**: How RagAlgo serves as the memory layer for **Agentic AI** (e.g., PepsiCo/Salesforce Agentforce).
+
+---
 
-### 2. Claude Desktop 설정
+## 💡 Why "Daily Close"?
 
-`%APPDATA%\Claude\claude_desktop_config.json` (Windows) 또는 `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) 파일에 추가하세요.
+Users often ask: *"Why isn't the chart data real-time?"*
 
+**Because AI performs better with clarity.**
+Real-time tick data is full of noise and volatility. If you feed an LLM raw live prices, it often hallucinates patterns that don't exist.
+
+RagAlgo acts like a **Professional Technical Analyst** who works after the market closes:
+1.  **Wait for the dust to settle** (Market Close).
+2.  **Analyze the day's battle** (Daily Candle & Aux Indicators).
+3.  **Deliver a "Confirmed Strategy"** to your AI.
+
+Use RagAlgo to build **"Investment Advisors"**, not "High-Frequency Trading Bots".
+
+---
+
+## 🚀 Quick Start
+
+### Claude Desktop Configuration
+
+Add this to your config file:
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+#### ☁️ Cloud Mode (Recommended - No installation required)
+```json
+{
+  "mcpServers": {
+    "ragalgo": {
+      "url": "https://ragalgo-service-production.up.railway.app/sse",
+      "env": {
+        "RAGALGO_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+#### 📦 Local Mode (Requires Node.js)
 ```json
 {
   "mcpServers": {
     "ragalgo": {
       "command": "npx",
-      "args": ["-y", "@ragalgo/server", "--stdio"],
+      "args": ["-y", "ragalgo-mcp-server", "--stdio"],
       "env": {
-        "RAGALGO_API_KEY": "비즈니스_또는_테스트_키_입력"
+        "RAGALGO_API_KEY": "YOUR_API_KEY_HERE"
       }
     }
   }
 }
 ```
 
-> **Tip:** 테스트용 API Key는 [RagAlgo 대시보드](https://www.ragalgo.com/dashboard)에서 즉시 발급 가능합니다.
+> **Tip:** You can get a **Free 1,000 Call Key** instantly at [RagAlgo Dashboard](https://www.ragalgo.com/dashboard).
 
 ---
 
+## 📚 Usage Examples (Cookbook)
+
+We have a **dedicated repository** for practical examples to help you get started quickly.
+Please visit the **[RagAlgo Examples Repository](https://github.com/kokogo100/ragalgo-examples)**.
+
+### What's Inside?
+- **8 Step-by-Step Recipes:** From basic data fetching to advanced AI agents.
+- **Skeleton Code + Prompts:** Copy-paste ready resources.
+- **Scenarios:**
+  - 🐣 **Basic:** Get stock scores in 5 minutes.
+  - 🧪 **Intermediate:** Verify technical signals with AI.
+  - 🚀 **Advanced:** Build an autonomous reasoning agent (Mock Trading Audit).
+  - ☕ **Morning Briefing:** Create a bot that emails you a daily market summary.
+
+> **"Skeleton + Prompt" Approach:** We provide the ingredients. You ask ChatGPT/Claude to cook!
+
+---
+
+## 🌍 Supported Markets & Roadmap
+
+RagAlgo is expanding its CKN coverage globally. Currently, **US, UK, Japan, Korea, and Crypto** markets are fully supported.
+
+| Market | Asset Class | Status |
+| :--- | :--- | :--- |
+| **🇰🇷 Korea** | KOSPI / KOSDAQ | **🟢 Live** (Real-time Sentiment & Charts) |
+| **🇺🇸 USA** | NYSE / NASDAQ | **🟢 Live** (Daily Scored Context) |
+| **🇯🇵 Japan** | Nikkei 225 | **🟢 Live** (Daily Scored Context) |
+| **🇬🇧 UK** | LSE | **🟢 Live** (Daily Scored Context) |
+| **🪙 Crypto** | Global (Upbit/Binance) | **🟢 Live** (Real-time Sentiment & Charts) |
+
+---
 
+## 🛠 Tools
 
-## 🛠️ 제공 도구 (Tools)
+> **⚠️ CORE CONCEPT: Scored vs Raw**
+> - **`get_news_scored` (Default):** Returns only significant news (Scores ≠ 0). Best for AI decision making.
+> - **`get_news` (Raw):** Returns ALL news including noise. Use this ONLY if you need raw data feed.
 
-| 도구 | 설명 |
-|------|------|
-| `get_news_scored` | **[핵심]** 감정 점수(Sentiment Score)가 포함된 금융 뉴스 조회 |
-| `get_chart_stock` | **[핵심]** 한국 주식(KOSPI/KOSDAQ) 기술적 분석 점수 조회 |
-| `get_chart_coin` | **[핵심]** 한국 가상화폐(Upbit) 기술적 분석 점수 조회 |
-| `get_snapshots` | 시장 전체 요약 스냅샷 (뉴스 + 차트 + 트렌드) |
-| `get_financials` | 기업 재무제표 (분기/연간 실적) |
-| `search_tags` | 텍스트(종목명)를 RagAlgo 고유 태그로 변환 |
+| Tool | Description |
+|------|-------------|
+| `get_news_scored` | **[RECOMMENDED]** News **WITH** AI Sentiment Scores (-10 ~ +10). Filters out noise. |
+| `get_news` | **[Advanced]** Raw News **WITHOUT** scores. Includes 0-score noise. Use only if you build your own scorer. |
+| `get_chart_stock` | **[Core]** Global Stock (US/UK/JP/KR) Technical Analysis (Daily Close). |
+| `get_chart_coin` | **[Core]** Global Crypto Technical Analysis (Daily Close). |
+| `get_snapshots` | **[Best]** Market Overview (News + Chart + Trend) in one call. |
+| `get_financials` | Corporate Financials (Quarterly/Yearly). |
+| `search_tags` | Convert names (e.g., "Samsung") to RagAlgo Tags. |
 
 ---
 
-## 📡 Real-time WebSocket (Business Only)
+## 📡 Real-time WebSocket (Business Tier)
 
-실시간 주가/코인 점수 데이터를 웹소켓으로 수신할 수 있습니다.
+For users who *really* need live data (e.g., for monitoring dashboards), we offer a WebSocket stream.
+*Note: This is strictly for monitoring, not for LLM inference context.*
 
-- **대상:** Business Plan 사용자 (월 30개 연결 포함)
-- **주소:** `wss://ragalgo-relay-server-1-production.up.railway.app`
-- **구현 방법:** `socket.io-client` 라이브러리 사용 (자세한 코드는 [공식 문서](https://www.ragalgo.com/docs) 참조)
+- **Access:** Business Plan subscribers (Includes 30 connections).
+- **Address:** `wss://ragalgo-relay-server-1-production.up.railway.app`
+- **Guide:** See [Developer Docs](https://www.ragalgo.com/docs) for implementation details.
 
 ---
 
-## 💬 Community & Support
+## 💬 Support
 
 - **Website:** [ragalgo.com](https://www.ragalgo.com)
 - **Email:** support@ragalgo.com

package/dist/check_sdk.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/check_sdk.js

@@ -0,0 +1,11 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+const server = new Server({ name: 'test', version: '1.0' }, { capabilities: {} });
+if (typeof server.close === 'function') {
+    console.log('Server has close method');
+}
+else {
+    console.log('Server DOES NOT have close method');
+}
+// Check other properties
+console.log('Server keys:', Object.keys(server));
+console.log('Server proto keys:', Object.getOwnPropertyNames(Object.getPrototypeOf(server)));

package/dist/check_sse.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/check_sse.js

@@ -0,0 +1,10 @@
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { IncomingMessage, ServerResponse } from 'http';
+import { Socket } from 'net';
+// Mock objects to satisfy the constructor
+const req = new IncomingMessage(new Socket());
+const res = new ServerResponse(req);
+const transport = new SSEServerTransport('/messages', res);
+console.log('Has sessionId:', 'sessionId' in transport);
+// @ts-ignore
+console.log('SessionId value:', transport.sessionId);

package/dist/index.d.ts

@@ -1,9 +1,2 @@
 #!/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
- */
 export {};