ragalgo-mcp-server 1.0.5 → 1.0.6

package/README.md

@@ -1,119 +1,192 @@
-# RagAlgo: Dynamic RAG Engine for AI Reliability
-
-> **Global Beta**: Currently specialized in **Korean Finance (Stocks & Crypto)**, but built on a universal "Tag & Score" protocol applicable to any domain.
-
-RagAlgo is not just a data API. It is a **"State-of-Truth" Provider** designed to prevent LLM hallucinations when dealing with **complex static knowledge** and **highly volatile dynamic data**.
-
-### Why RagAlgo?
-Traditional RAG (SQL/Vector DB) often fails to capture the "current context" of fast-changing reality. RagAlgo solves this by converting data into **Mathematical Scores** and **Standardized Tags**.
-
-### Core Philosophy
-1.  **Sanitized Data:** We filter out noise so AI only ingests high-quality signals.
-2.  **Mathematical Scoring:** We translate complex movements into simple scores (e.g., `Chart Score: 9.5`), giving AI a clear ground truth to reason upon.
-3.  **Universal Protocol:** Our "Tag & Score" architecture is designed to **systematize and standardize any data domain**—including Legal, Medical, and Tech—into a format that AI can flawlessly understand and judge.
-
-
-### Flexible Integration: Scored vs. Non-Scored
-We respect your freedom to build. Choose the mode that fits your pipeline:
-
-| Mode | Target User | Description |
-|------|-------------|-------------|
-| **Scored API** (AI-Ready) | Builders & Startups | RagAlgo's math engines sanitize and score everything. Zero hallucinations. |
-| **Non-Scored API** (Raw Mode) | Data Scientists & Engineers | Pure, sanitized data feeds for your custom pipelines. Perfect for fine-tuning, **n8n** automation, **LangChain** agents, or **Flowise** workflows. |
-
----
-
-# RagAlgo MCP Server (KOR)
-
-금융 뉴스 및 데이터 API를 MCP(Model Context Protocol)로 제공하는 서버입니다.
-
-## 설치
-
-```bash
-cd mcp-server
-npm install
-npm run build
-```
-
-## 환경변수 설정
-
-```bash
-# Windows (PowerShell)
-$env:RAGALGO_API_KEY="ragalgo_scored_test_a3ed9bd570436d46"
-
-# Windows (CMD)
-set RAGALGO_API_KEY=ragalgo_scored_test_a3ed9bd570436d46
-
-# Mac/Linux
-export RAGALGO_API_KEY="ragalgo_scored_test_a3ed9bd570436d46"
-```
-
-## Claude Desktop 설정
-
-`%APPDATA%\Claude\claude_desktop_config.json` 파일에 추가:
-
-```json
-{
-  "mcpServers": {
-    "ragalgo": {
-      "command": "node",
-      "args": ["C:\\coding\\RagAlgo\\mcp-server\\dist\\index.js"],
-      "env": {
-        "RAGALGO_API_KEY": "ragalgo_scored_test_a3ed9bd570436d46"
-      }
-    }
-  }
-}
-```
-
-## 제공 도구 (9개)
-
-| 도구 | 설명 |
-|------|------|
-| `get_news` | 금융 뉴스 조회 (점수 제외) |
-| `get_news_scored` | 금융 뉴스 조회 (점수 포함) |
-| `get_chart_stock` | 주식 차트 점수 조회 |
-| `get_chart_coin` | 코인 차트 점수 조회 |
-| `get_financials` | 재무제표 조회 |
-| `get_snapshots` | 일별 스냅샷 조회 |
-| `search_tags` | 태그 검색 |
-| `match_tags` | 텍스트→태그 매칭 |
-| `get_trends` | 태그별 트렌드 조회 |
-
-## 사용 예시
-
-### Claude Desktop에서
-
-```
-"삼성전자 최근 뉴스 5개 보여줘"
-→ get_news_scored(tag="삼성전자", limit=5)
-
-"반도체 관련 호재 뉴스만 찾아줘"
-→ get_news_scored(tag="반도체", verdict="bullish")
-
-"005930 재무제표 보여줘"
-→ get_financials(ticker="005930")
-
-"비트코인 차트 분석"
-→ get_chart_coin(ticker="KRW-BTC")
-```
-
-## API 키 종류
-
-| Tier | API Key | 접근 가능 도구 |
-|------|---------|---------------|
-| nonscored | `ragalgo_nonscored_test_...` | get_news, get_financials, get_chart_*, search_tags, match_tags, get_trends |
-| scored | `ragalgo_scored_test_...` | 위 전부 + get_news_scored, get_snapshots |
-
-## 개발
-
-```bash
-# 개발 모드 실행
-npm run dev
-
-# 빌드
-npm run build
-
-# 프로덕션 실행
-npm start
-```
+# RagAlgo: Dynamic RAG Engine for AI Reliability
+
+[![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)
+
+> **"Your AI is an Analyst, NOT a Day Trader."**
+
+
+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
+
+Our production system on Railway processes global financial data 24/7:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        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).
+
+---
+
+## 💡 Why "Daily Close"?
+
+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-mcp-server", "--stdio"],
+      "env": {
+        "RAGALGO_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+> **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
+
+> **⚠️ 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.
+
+| 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 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.*
+
+- **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.
+
+---
+
+## 💬 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 {};