stockmatrix-mcp 0.2.0 → 0.4.0

package/README.md

@@ -1,8 +1,8 @@
 # stockmatrix-mcp
 
-MCP server for Korean stock market theme analysis. Track 250+ KOSPI/KOSDAQ investment themes with lifecycle scores, trend data, related stocks, and news — all through natural conversation with AI.
+Ask about Korean stock market themes in natural conversation with AI. Track 250+ KOSPI/KOSDAQ investment themes, get daily movers, compare themes side-by-side, and see predictions — all through Claude, Cursor, or any MCP-compatible AI agent.
 
-Scores are computed using **TLI (Theme Lifecycle Index)** — a Bayesian-optimized algorithm combining search interest, news momentum, market volatility, and stock activity into a 0-100 score with lifecycle stage classification.
+Powered by **TLI (Theme Lifecycle Index)** — a Bayesian-optimized scoring algorithm combining search interest, news momentum, market volatility, and stock activity into a 0-100 score with lifecycle stage classification.
 
 ## Quick Start
 
@@ -57,65 +57,89 @@ After setup, just ask in natural language:
 
 | Prompt | What happens |
 |--------|-------------|
-| "요즘 한국 주식시장에서 뜨는 테마 뭐야?" | Top trending themes with scores |
+| "요즘 뜨는 테마 TOP 5" | Top 5 themes ranked by TLI score |
+| "오늘 한국 테마 시장 요약해줘" | AI-optimized market overview |
+| "어제 대비 가장 많이 오른 테마는?" | Daily score movers and stage transitions |
 | "AI 관련 테마 찾아줘" | Search AI-related themes |
-| "반도체 테마 최근 한달 추세 어때?" | 30-day score history |
-| "삼성전자가 속한 테마 알려줘" | Themes linked to Samsung (005930) |
-| "성장 단계인 테마만 보여줘" | Growth-stage themes only |
-| "방산 테마 상세 정보" | Score, stocks, news for defense theme |
-| "TLI 점수는 어떻게 계산돼?" | Algorithm methodology |
+| "반도체 vs 2차전지 비교해줘" | Side-by-side theme comparison |
+| "앞으로 오를 테마 알려줘" | Rising predictions with analog evidence |
+| "삼성전자가 속한 테마" | Stock-to-theme lookup (auto-detects 6-digit codes) |
+| "방산 테마 상세 정보" | Score breakdown, stocks, news, comparisons |
+| "반도체 테마 최근 한달 추세" | 30-day score history |
+| "TLI 점수는 어떻게 계산돼?" | Algorithm methodology (tip: use `section=scoring` to save tokens) |
 | "What are the hottest stock themes in Korea?" | Works in English too |
-| "Which themes is SK Hynix (000660) part of?" | Stock-to-theme lookup |
 
 ## Available Tools
 
 ### `get_theme_ranking`
-
-Get theme rankings by lifecycle stage.
+Get theme rankings by lifecycle stage with limit and sort options.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `stage` | string | No | `emerging` / `growth` / `peak` / `decline` / `reigniting` |
+| `limit` | number | No | Results per stage (1-50, default: 10) |
+| `sort` | string | No | `score` / `change7d` / `newsCount7d` (default: score) |
 
-### `search_themes`
+### `get_market_summary`
+Get an AI-optimized market overview with top themes (includes themeId for chaining).
 
-Search themes by keyword (Korean or English).
+### `get_theme_changes`
+Get daily or weekly score movers, stage transitions, and newly emerging themes.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `query` | string | Yes | e.g. `"AI"`, `"반도체"`, `"2차전지"`, `"삼성전자"` |
+| `period` | string | No | `1d` (default) / `7d` |
 
-### `get_theme_detail`
+### `compare_themes`
+Compare 2-5 themes side-by-side with scores, stocks, sparklines, and similarity.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `theme_ids` | string[] | Yes | Array of 2-5 theme UUIDs |
 
-Get detailed info: score breakdown (4 components), stage, prediction, stocks, news, comparisons.
+### `get_predictions`
+Get themes predicted to rise, peak, or cool based on historical analog matching.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `theme_id` | string (UUID) | Yes | Theme UUID from ranking or search |
+| `phase` | string | No | `rising` / `hot` / `cooling` (default: all) |
 
-### `get_theme_history`
+### `search_themes`
+Search themes by keyword, stock name, or stock code.
 
-Get 30-day score history for trend analysis.
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | e.g. `"AI"`, `"반도체"`, `"삼성전자"`, `"005930"` |
+
+### `search_stocks`
+Search stocks by company name or 6-digit code, with related theme preview. Automatically performs stock-to-theme lookup for 6-digit codes.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `theme_id` | string (UUID) | Yes | Theme UUID |
+| `query` | string | Yes | e.g. `"삼성전자"`, `"SK하이닉스"`, `"005930"` |
+
+### `get_theme_detail`
+Get detailed analysis: score breakdown (4 components), stage, prediction, stocks, news, comparisons.
 
-### `get_stock_theme`
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `theme_id` | string (UUID) | Yes | Theme UUID from ranking or search |
 
-Find themes a specific stock belongs to.
+### `get_theme_history`
+Get 30-day score history for trend analysis.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `symbol` | string | Yes | 6-digit code, e.g. `"005930"` (Samsung), `"000660"` (SK Hynix) |
+| `theme_id` | string (UUID) | Yes | Theme UUID |
 
 ### `get_methodology`
-
-Get TLI algorithm documentation — scoring, stages, stabilization, comparison, prediction.
+Get TLI algorithm documentation — scoring, stages, stabilization, comparison, prediction, data sources, and more.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `section` | string | No | `scoring` / `stabilization` / `stages` / `comparison` / `prediction` / `all` |
+| `section` | string | No | `scoring` / `stages` / `comparison` / `prediction` / `all` (default: all) |
+
+> Tip: Use `section=scoring` to get just the scoring algorithm and save context tokens.
 
 ## Scoring Algorithm
 
@@ -128,13 +152,13 @@ TLI scores (0-100) are a weighted sum of 4 components, optimized via Bayesian Op
 | Volatility | 10.4% | Interest time-series |
 | Stock Activity | 22.6% | Naver Finance |
 
-Scores are stabilized through **Cautious Decay** (3-signal majority vote prevents false drops), **Bollinger Band Clamp** (limits daily change), and **Age-adaptive EMA** (newer themes react faster).
+Scores are stabilized through **Cautious Decay** (3-signal majority vote), **Bollinger Band Clamp** (limits daily change), and **Age-adaptive EMA** (newer themes react faster).
 
 ## Lifecycle Stages
 
 ```
-Dormant → Emerging → Growth → Peak → Decline → Dormant
-                                          ↓
+Dormant -> Emerging -> Growth -> Peak -> Decline -> Dormant
+                                          |
                                      Reigniting
 ```
 
@@ -144,6 +168,9 @@ Stage transitions require 2 consecutive days of the same candidate (hysteresis)
 
 - **250+ themes** across KOSPI & KOSDAQ
 - **Daily updates** — scores, news, stock mappings
+- **Stock lookup** by company name or 6-digit code
+- **AI market summary** for first-call overview
+- **Predictions** with historical analog matching
 - **Sources**: Naver DataLab, Naver Finance, Naver News
 
 ## Configuration

package/dist/cache.d.ts

@@ -0,0 +1,7 @@
+interface Cache {
+    get: <T = unknown>(key: string) => T | undefined;
+    set: <T = unknown>(key: string, value: T, ttlMs: number) => void;
+    readonly size: number;
+}
+export declare const createCache: (maxSize?: number) => Cache;
+export {};

package/dist/cache.js

@@ -0,0 +1,36 @@
+export const createCache = (maxSize = 50) => {
+    const store = new Map();
+    const evictExpired = () => {
+        const now = Date.now();
+        for (const [key, entry] of store) {
+            if (entry.expiresAt <= now) {
+                store.delete(key);
+            }
+        }
+    };
+    return {
+        get(key) {
+            const entry = store.get(key);
+            if (!entry)
+                return undefined;
+            if (entry.expiresAt <= Date.now()) {
+                store.delete(key);
+                return undefined;
+            }
+            return entry.value;
+        },
+        set(key, value, ttlMs) {
+            if (store.size >= maxSize) {
+                evictExpired();
+            }
+            if (store.size >= maxSize) {
+                const oldest = store.keys().next().value;
+                store.delete(oldest);
+            }
+            store.set(key, { value, expiresAt: Date.now() + ttlMs });
+        },
+        get size() {
+            return store.size;
+        },
+    };
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createRequire } from 'node:module';
+import { registerGetThemeRanking } from './tools/get-theme-ranking.js';
+import { registerGetThemeDetail } from './tools/get-theme-detail.js';
+import { registerGetThemeHistory } from './tools/get-theme-history.js';
+import { registerSearchThemes } from './tools/search-themes.js';
+import { registerSearchStocks } from './tools/search-stocks.js';
+import { registerGetMarketSummary } from './tools/get-market-summary.js';
+import { registerGetMethodology } from './tools/get-methodology.js';
+import { registerGetThemeChanges } from './tools/get-theme-changes.js';
+import { registerCompareThemes } from './tools/compare-themes.js';
+import { registerGetPredictions } from './tools/get-predictions.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+const server = new McpServer({
+    name: 'stockmatrix-mcp',
+    version,
+});
+registerGetThemeRanking(server);
+registerGetThemeDetail(server);
+registerGetThemeHistory(server);
+registerSearchThemes(server);
+registerSearchStocks(server);
+registerGetMarketSummary(server);
+registerGetMethodology(server);
+registerGetThemeChanges(server);
+registerCompareThemes(server);
+registerGetPredictions(server);
+const main = async () => {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`StockMatrix MCP server v${version} running on stdio`);
+};
+main().catch((error) => {
+    console.error('Fatal error in main():', error);
+    process.exit(1);
+});

package/dist/fetch-helper.d.ts

@@ -1,4 +1,7 @@
-export declare const fetchApi: <T = unknown>(path: string, params?: Record<string, string>) => Promise<T>;
+import type { ZodType } from 'zod';
+export declare const fetchApi: <T = unknown>(path: string, params?: Record<string, string>, schema?: ZodType<T>) => Promise<T>;
 /** JSON 직렬화 with optional context header for AI agents */
 export declare const formatResult: (data: unknown, context?: string) => string;
 export declare const formatError: (error: unknown) => string;
+/** 빈 결과에 가이던스 메시지를 포함하는 포맷터 */
+export declare const formatEmptyResult: (context: string, guidance: string) => string;

package/dist/fetch-helper.js

@@ -1,6 +1,9 @@
 import { createRequire } from 'node:module';
+import { createCache } from './cache.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
+const apiCache = createCache(50);
+const CACHE_TTL_MS = 3_600_000; // 1 hour
 const BASE_URL = process.env.STOCKMATRIX_API_URL || 'https://stockmatrix.co.kr';
 const MCP_USER_AGENT = `stockmatrix-mcp/${version}`;
 // 시작 시 URL 유효성 검증
@@ -26,13 +29,18 @@ const isRetryable = (error) => {
     return false;
 };
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-export const fetchApi = async (path, params) => {
+export const fetchApi = async (path, params, schema) => {
     const url = new URL(path, BASE_URL);
     if (params) {
         for (const [key, value] of Object.entries(params)) {
             url.searchParams.set(key, value);
         }
     }
+    const cacheKey = url.toString();
+    const cached = apiCache.get(cacheKey);
+    if (cached !== undefined) {
+        return schema ? schema.parse(cached) : cached;
+    }
     let lastError;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
         if (attempt > 0) {
@@ -67,9 +75,13 @@ export const fetchApi = async (path, params) => {
                 if (!wrapped.success) {
                     throw new Error(wrapped.error?.message || 'API returned unsuccessful response');
                 }
-                return wrapped.data;
+                const result = schema ? schema.parse(wrapped.data) : wrapped.data;
+                apiCache.set(cacheKey, result, CACHE_TTL_MS);
+                return result;
             }
-            return json;
+            const rawResult = schema ? schema.parse(json) : json;
+            apiCache.set(cacheKey, rawResult, CACHE_TTL_MS);
+            return rawResult;
         }
         catch (error) {
             lastError = error;
@@ -92,3 +104,7 @@ export const formatError = (error) => {
     const message = error instanceof Error ? error.message : String(error);
     return `Error: ${message}`;
 };
+/** 빈 결과에 가이던스 메시지를 포함하는 포맷터 */
+export const formatEmptyResult = (context, guidance) => {
+    return `${context}\n\n${JSON.stringify([], null, 2)}\n\n${guidance}`;
+};

package/dist/index.d.ts

@@ -1,3 +1,2 @@
-#!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare const createSandboxServer: () => McpServer;

package/dist/index.js

@@ -1,13 +1,15 @@
-#!/usr/bin/env node
 import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { registerGetThemeRanking } from './tools/get-theme-ranking.js';
 import { registerGetThemeDetail } from './tools/get-theme-detail.js';
 import { registerGetThemeHistory } from './tools/get-theme-history.js';
 import { registerSearchThemes } from './tools/search-themes.js';
-import { registerGetStockTheme } from './tools/get-stock-theme.js';
+import { registerSearchStocks } from './tools/search-stocks.js';
+import { registerGetMarketSummary } from './tools/get-market-summary.js';
 import { registerGetMethodology } from './tools/get-methodology.js';
+import { registerGetThemeChanges } from './tools/get-theme-changes.js';
+import { registerCompareThemes } from './tools/compare-themes.js';
+import { registerGetPredictions } from './tools/get-predictions.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
 const createServer = () => {
@@ -19,18 +21,12 @@ const createServer = () => {
     registerGetThemeDetail(s);
     registerGetThemeHistory(s);
     registerSearchThemes(s);
-    registerGetStockTheme(s);
+    registerSearchStocks(s);
+    registerGetMarketSummary(s);
     registerGetMethodology(s);
+    registerGetThemeChanges(s);
+    registerCompareThemes(s);
+    registerGetPredictions(s);
     return s;
 };
 export const createSandboxServer = () => createServer();
-const server = createServer();
-const main = async () => {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error(`StockMatrix MCP server v${version} running on stdio`);
-};
-main().catch((error) => {
-    console.error('Fatal error in main():', error);
-    process.exit(1);
-});

package/dist/tools/{get-stock-theme.d.ts → compare-themes.d.ts}

@@ -1,2 +1,2 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare const registerGetStockTheme: (server: McpServer) => void;
+export declare const registerCompareThemes: (server: McpServer) => void;

package/dist/tools/compare-themes.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
+const CONTEXT = `[StockMatrix Theme Comparison]
+Compare 2–5 Korean stock market themes side-by-side.
+Shows each theme's current TLI score, lifecycle stage, 7-day sparkline,
+pairwise similarity (from comparison algorithm), overlapping stocks, and any warnings.
+Use when the user asks to compare or contrast multiple themes.`;
+export const registerCompareThemes = (server) => {
+    server.tool('compare_themes', `Compare 2–5 Korean stock market themes side-by-side with lifecycle scores, similarity, and overlapping stocks.
+
+Use when the user asks:
+- Compare semiconductor and AI themes
+- How similar are these themes?
+- 반도체 vs AI 테마 비교, 테마 간 유사도
+- Which theme is stronger right now?
+- Do these themes share the same stocks?
+
+Returns each theme's score/stage/sparkline, pairwise similarity scores, and overlapping stocks.`, {
+        theme_ids: z
+            .array(z.string().uuid())
+            .min(2)
+            .max(5)
+            .describe('Array of 2–5 theme UUIDs to compare'),
+    }, async ({ theme_ids }) => {
+        try {
+            const data = await fetchApi('/api/tli/compare', {
+                ids: theme_ids.join(','),
+            });
+            return {
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatError(error) }],
+                isError: true,
+            };
+        }
+    });
+};

package/dist/tools/get-market-summary.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const registerGetMarketSummary: (server: McpServer) => void;

package/dist/tools/get-market-summary.js

@@ -0,0 +1,30 @@
+import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
+const CONTEXT = `[StockMatrix Market Summary]
+High-level Korean stock market theme briefing for AI agents.
+Use as a first call when the user asks what is hot, what the market looks like today, or wants a concise overview before drilling into a theme.
+Includes stage distribution, top themes, market coverage, endpoint references, and citation/disclaimer metadata.
+Each theme in the response includes themeId for chaining to get_theme_detail.`;
+export const registerGetMarketSummary = (server) => {
+    server.tool('get_market_summary', `Get an AI-optimized summary of the Korean stock theme market.
+
+Use when the user asks:
+- What's happening in Korean stock themes right now?
+- Give me a market overview before drilling down
+- 오늘 한국 테마 시장 요약
+- 현재 뜨는 테마와 시장 분포를 한 번에 보고 싶어
+
+Returns a concise market overview, stage distribution, top themes, endpoint references, citation metadata, and disclaimer text.`, {}, async () => {
+        try {
+            const data = await fetchApi('/api/ai/summary');
+            return {
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatError(error) }],
+                isError: true,
+            };
+        }
+    });
+};

package/dist/tools/get-methodology.js

@@ -1,80 +1,34 @@
 import { z } from 'zod';
-const METHODOLOGY = {
-    name: 'TLI (Theme Lifecycle Index)',
-    version: '2.0 — Bayesian Optimized',
-    description: 'Quantitative index tracking Korean stock market theme lifecycles using public data sources.',
+import { fetchApi, formatResult } from '../fetch-helper.js';
+const SECTIONS = [
+    'scoring',
+    'stabilization',
+    'stages',
+    'comparison',
+    'prediction',
+    'data_sources',
+    'update_schedule',
+    'runtime',
+    'data_flow',
+    'database_tables',
+    'limitations',
+    'all',
+];
+const METHODOLOGY_FALLBACK = {
+    fallback: true,
     scoring: {
         range: '0-100',
         components: [
-            { name: 'interest', weight: '30.4%', source: 'Naver DataLab', method: '7-day search volume average vs 30-day baseline, sigmoid-normalized. Batch self-normalization applied (DataLab 5-keyword batch limit).' },
-            { name: 'newsMomentum', weight: '36.6%', source: 'Naver News', method: 'Log-scale news volume + weekly article count change rate.' },
-            { name: 'volatility', weight: '10.4%', source: 'Interest time-series', method: 'Standard deviation of interest values, sigmoid-normalized.' },
-            { name: 'activity', weight: '22.6%', source: 'Naver Finance', method: 'Related stock price change rates, trading volume intensity, and data coverage cross-signal.' },
+            { name: 'interest', weight: '30.4%' },
+            { name: 'newsMomentum', weight: '36.6%' },
+            { name: 'volatility', weight: '10.4%' },
+            { name: 'activity', weight: '22.6%' },
         ],
-        optimization: 'Weights derived via Bayesian Optimization (Optuna TPE sampler, 2-stage hierarchical search: 80 trials core params + 120 trials fine-tune). Validated with walk-forward train/val split with 7-day gap to prevent data leakage.',
-        accuracy: 'Growth/Decline Directional Accuracy (GDDA): ~66% on validation set.',
     },
-    stabilization: {
-        pipeline: 'Cautious Decay → Bollinger Band Clamp → EMA Smoothing (applied in this fixed order)',
-        cautiousDecay: {
-            description: 'Prevents false score drops from data gaps or temporary noise.',
-            mechanism: '3 independent binary signals checked on score decline: (1) interest slope < 0, (2) this week news < last week news, (3) directional volatility index < 0.4. Decline confirmed only if 2+ signals agree (majority vote). Otherwise, previous score × 0.947 used as floor.',
-        },
-        bollingerClamp: {
-            description: 'Limits daily score change to prevent spikes.',
-            mechanism: 'Max daily change = max(min_daily_change, 2 × σ of recent smoothed scores).',
-        },
-        emaScheduling: {
-            description: 'Theme age-adaptive smoothing.',
-            mechanism: 'EMA alpha linearly interpolated: new themes (0 days) α=0.6 (reactive) → mature themes (30+ days) α=0.3 (stable). Null first_spike_date uses default α=0.417.',
-        },
-    },
-    stages: {
-        order: 'Dormant → Emerging → Growth → Peak → Decline (→ Dormant or Reigniting)',
-        thresholds: {
-            dormant: { score: '< 10', condition: 'AND trend ≠ rising' },
-            emerging: { score: 'default', condition: 'Does not match other stage criteria' },
-            growth: { score: '≥ 40', condition: 'AND stable/rising trend' },
-            peak: { score: '≥ 71', condition: 'OR (≥ 50 AND stable/rising AND news > 30 articles)' },
-            decline: { condition: 'Falling trend AND score < 86% of level score AND news declining' },
-            reigniting: { condition: 'Transition from Decline to Emerging/Growth' },
-        },
-        hysteresis: '2 consecutive days of same candidate stage required for transition (prevents 1-day noise).',
-        markov: 'Only allowed transitions: Dormant→Emerging, Emerging→Growth/Dormant, Growth→Peak/Decline, Peak→Decline/Growth, Decline→Dormant/Emerging/Growth. Data gap ≥ 3 days relaxes constraints.',
-    },
-    comparison: {
-        method: '3-Pillar similarity analysis',
-        pillars: [
-            { name: 'Feature Similarity', weight: 'dynamic (0.40-1.00)', method: 'Mutual Rank (sqrt of bidirectional rank product) with z-score and cosine fallbacks.' },
-            { name: 'Curve Similarity', weight: 'dynamic (0.00-0.60)', method: 'Shape RMSE (35%) + Derivative Pearson correlation (30%) + DTW distance (35%). Minimum 14 days data required.' },
-            { name: 'Keyword Similarity', weight: 'display only', method: 'Jaccard coefficient of theme keywords.' },
-        ],
-        threshold: '≥ 0.40 to qualify as meaningful comparison. Auto-tuned via comparison_calibration feedback loop.',
-    },
-    prediction: {
-        horizon: '7-day directional outlook',
-        phases: 'Rising (Emerging + Growth), Hot (Peak), Cooling (Decline + Dormant)',
-        reliability: 'Rising signals are most accurate. Cooling signals are reference-level only.',
-    },
-    dataSources: [
-        { name: 'Naver DataLab', provides: 'Search interest trends (relative values, 30-day window)' },
-        { name: 'Naver News', provides: 'Article counts and headlines' },
-        { name: 'Naver Finance', provides: 'Theme stock listings, prices, trading volumes' },
-    ],
-    updateSchedule: {
-        themeDiscovery: 'Sunday and Wednesday',
-        scores: 'Daily (full pipeline after market close)',
-        news: 'Daily (morning + evening)',
-        stocks: 'Weekdays (full)',
-    },
-    limitations: [
-        'Naver DataLab 5-keyword batch limit requires self-normalization across batches — precision is limited.',
-        'News momentum is article-count-based; sentiment analysis is not included (removed due to low accuracy).',
-        'Data collection intervals mean latest market changes may not be immediately reflected.',
-    ],
-    disclaimer: 'This algorithm and its results are for informational purposes only, not investment advice. High scores indicate strong theme momentum, not necessarily investment opportunity — they may signal overheating.',
+    disclaimer: 'Full methodology unavailable — showing cached summary. Try again later.',
 };
-const SECTIONS = ['scoring', 'stabilization', 'stages', 'comparison', 'prediction', 'all'];
+const CONTEXT = `[StockMatrix TLI Methodology]
+Comprehensive documentation of the TLI (Theme Lifecycle Index) algorithm — scoring, stages, stabilization, comparison, prediction, data sources, pipeline, and database schema.`;
 export const registerGetMethodology = (server) => {
     server.tool('get_methodology', `Get the TLI (Theme Lifecycle Index) algorithm methodology — how scores, stages, and predictions work.
 
@@ -82,28 +36,28 @@ Use when the user asks:
 - How are theme scores calculated?
 - What do the lifecycle stages mean?
 - How does the prediction work?
+- What data sources, schedules, runtime pipeline, or database tables power TLI?
 - TLI 알고리즘 설명, 점수 산출 방식, 단계 판정 기준
 - What data sources are used?
+- TLI 수집 파이프라인, 업데이트 주기, 비교 파이프라인, 데이터 테이블
 
-Returns structured documentation of the scoring algorithm, stage determination, stabilization techniques, comparison analysis, and prediction methodology.`, {
+Returns structured documentation of the scoring algorithm, data collection pipeline, runtime orchestration, database tables, stage determination, stabilization techniques, comparison analysis, and prediction methodology.`, {
         section: z
             .enum(SECTIONS)
             .optional()
-            .describe('Specific section: scoring, stabilization, stages, comparison, prediction, or all (default: all)'),
+            .describe('Specific section: scoring, stabilization, stages, comparison, prediction, data_sources, update_schedule, runtime, data_flow, database_tables, limitations, or all (default: all)'),
     }, async ({ section }) => {
-        const selected = section || 'all';
-        if (selected === 'all') {
+        try {
+            const params = section ? { section } : undefined;
+            const data = await fetchApi('/api/tli/methodology', params);
+            return {
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
+            };
+        }
+        catch {
             return {
-                content: [{ type: 'text', text: JSON.stringify(METHODOLOGY, null, 2) }],
+                content: [{ type: 'text', text: formatResult(METHODOLOGY_FALLBACK, CONTEXT) }],
             };
         }
-        const sectionData = METHODOLOGY[selected];
-        const result = {
-            section: selected,
-            ...(typeof sectionData === 'object' ? sectionData : { value: sectionData }),
-        };
-        return {
-            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-        };
     });
 };

package/dist/tools/get-predictions.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const registerGetPredictions: (server: McpServer) => void;

package/dist/tools/get-predictions.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
+const CONTEXT = `[StockMatrix Theme Predictions]
+Lifecycle phase predictions for Korean stock themes based on analog comparison forecasting.
+Shows which themes are rising, hot, or cooling with confidence levels and analog evidence.
+Use to identify emerging opportunities (rising) or themes past peak (cooling).
+Chain with get_theme_detail(themeId) for deeper analysis of any predicted theme.`;
+export const registerGetPredictions = (server) => {
+    server.tool('get_predictions', `Get lifecycle phase predictions for Korean stock themes.
+
+Use when the user asks:
+- Which themes are rising / about to peak / cooling down?
+- Show me predicted hot themes
+- 상승세 테마 예측, 하락 전환 예상 테마
+- 테마 생명주기 예측 결과를 보고 싶어
+
+Returns themes with predicted phase (rising/hot/cooling), confidence, expected peak day, and top analog evidence.`, {
+        phase: z
+            .enum(['rising', 'hot', 'cooling'])
+            .optional()
+            .describe('Filter by predicted phase: rising (ascending), hot (at peak), cooling (declining)'),
+    }, async ({ phase }) => {
+        try {
+            const params = {};
+            if (phase)
+                params.phase = phase;
+            const data = await fetchApi('/api/tli/predictions', params);
+            if (!data.themes || data.themes.length === 0) {
+                const guidance = data.guidance || 'Prediction data not yet available.';
+                return {
+                    content: [{ type: 'text', text: formatResult({ ...data, guidance }, CONTEXT) }],
+                };
+            }
+            return {
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatError(error) }],
+                isError: true,
+            };
+        }
+    });
+};

package/dist/tools/get-theme-changes.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const registerGetThemeChanges: (server: McpServer) => void;

package/dist/tools/get-theme-changes.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { fetchApi, formatResult, formatError, formatEmptyResult } from '../fetch-helper.js';
+const CONTEXT = `[StockMatrix Theme Changes]
+Daily or weekly score changes. period=1d means vs previous day, 7d means vs 7 days ago.
+movers: rising (score increased) and falling (score decreased), sorted by magnitude.
+stageTransitions: themes that changed lifecycle stage.
+newlyEmerging: themes that entered Emerging stage.
+Use theme IDs with get_theme_detail for deeper analysis.`;
+const isEmpty = (data) => data.movers.rising.length === 0 &&
+    data.movers.falling.length === 0 &&
+    data.stageTransitions.length === 0 &&
+    data.newlyEmerging.length === 0;
+export const registerGetThemeChanges = (server) => {
+    server.tool('get_theme_changes', `Get recent score changes and stage transitions for Korean stock themes.
+
+Use when the user asks:
+- What themes changed the most today/this week?
+- Which themes are rising or falling?
+- Any stage transitions recently?
+- 오늘 테마 변동, 급등/급락 테마
+- 이번 주 생명주기 단계 변화한 테마
+- 새로 떠오르는 테마 있어?
+
+Returns movers (rising/falling by score change), stage transitions, and newly emerging themes.`, {
+        period: z
+            .enum(['1d', '7d'])
+            .optional()
+            .describe('Comparison period: 1d = vs yesterday (default), 7d = vs 7 days ago'),
+    }, async ({ period }) => {
+        try {
+            const data = await fetchApi('/api/tli/changes', {
+                period: period || '1d',
+            });
+            if (isEmpty(data)) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: formatEmptyResult(CONTEXT, 'No significant changes detected for this period. Try period=7d for a wider window, or use get_theme_ranking for current standings.'),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatError(error) }],
+                isError: true,
+            };
+        }
+    });
+};

package/dist/tools/get-theme-detail.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
+import { fetchApi, formatResult, formatError, formatEmptyResult } from '../fetch-helper.js';
 const CONTEXT = `[StockMatrix Theme Detail]
 Score components (Bayesian-optimized weights):
   - interest (30.4%): Naver DataLab search volume — 7-day avg vs 30-day baseline
@@ -22,6 +22,11 @@ Use after get_theme_ranking or search_themes to drill into a specific theme. Ans
     }, async ({ theme_id }) => {
         try {
             const data = await fetchApi(`/api/tli/themes/${theme_id}`);
+            if (!data) {
+                return {
+                    content: [{ type: 'text', text: formatEmptyResult(CONTEXT, `Theme not found for ID "${theme_id}". Use search_themes to find valid theme IDs.`) }],
+                };
+            }
             return {
                 content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
             };

package/dist/tools/get-theme-history.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
+import { fetchApi, formatResult, formatError, formatEmptyResult } from '../fetch-helper.js';
 const CONTEXT = `[StockMatrix Theme History — 30-day]
 Daily TLI scores with stage transitions. Use to identify:
 - Trend direction: rising scores = growing interest, falling = declining
@@ -20,6 +20,11 @@ Answers: "이 테마 추세가 어때?", "최근 한달 흐름", "is this theme
     }, async ({ theme_id }) => {
         try {
             const data = await fetchApi(`/api/tli/themes/${theme_id}/history`);
+            if (!data || (Array.isArray(data) && data.length === 0)) {
+                return {
+                    content: [{ type: 'text', text: formatEmptyResult(CONTEXT, `No history data found for theme "${theme_id}". The theme may be too new or inactive.`) }],
+                };
+            }
             return {
                 content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
             };

package/dist/tools/get-theme-ranking.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
+import { fetchApi, formatResult, formatError, formatEmptyResult } from '../fetch-helper.js';
 const VALID_STAGES = [
     'emerging',
     'growth',
@@ -17,7 +17,8 @@ const STAGE_DESCRIPTIONS = {
 const CONTEXT = `[StockMatrix TLI Ranking]
 Scores: 0-100 (Bayesian-optimized weighted sum of 4 components: interest 30%, news momentum 37%, volatility 10%, activity 23%).
 Stages: Emerging → Growth → Peak → Decline → Dormant (with possible Reigniting). Stage transitions require 2 consecutive days of same candidate (hysteresis).
-Higher score = stronger theme momentum. Stage indicates lifecycle position.`;
+Higher score = stronger theme momentum. Stage indicates lifecycle position.
+The \`summary\` object includes \`signals\` (market mood indicators), \`hottestTheme\` (single highest scorer with 3+ stocks), and \`surging\` (rapidly rising themes).`;
 export const registerGetThemeRanking = (server) => {
     server.tool('get_theme_ranking', `Get Korean stock market theme rankings with lifecycle scores (TLI: Theme Lifecycle Index).
 
@@ -32,13 +33,35 @@ Returns themes ranked by score (0-100) with lifecycle stage and related stocks.
             .enum(VALID_STAGES)
             .optional()
             .describe('Filter by lifecycle stage: emerging (초기 — early interest), growth (성장 — expanding), peak (정점 — maximum attention), decline (하락 — fading), reigniting (재점화 — comeback)'),
-    }, async ({ stage }) => {
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe('Max themes per stage (1-50, default 10)'),
+        sort: z
+            .enum(['score', 'change7d', 'newsCount7d'])
+            .optional()
+            .describe('Sort order within each stage: score (default), change7d, newsCount7d'),
+    }, async ({ stage, limit, sort }) => {
         try {
-            const data = await fetchApi('/api/tli/scores/ranking');
+            const params = {};
+            if (limit !== undefined)
+                params.limit = String(limit);
+            if (sort !== undefined)
+                params.sort = sort;
+            const fetchParams = Object.keys(params).length > 0 ? params : undefined;
+            const data = await fetchApi('/api/tli/scores/ranking', fetchParams);
             if (stage) {
                 const stageData = data[stage];
                 const summary = data.summary;
                 const stageContext = `${CONTEXT}\nFiltered: ${stage} — ${STAGE_DESCRIPTIONS[stage]}`;
+                if (!stageData || (Array.isArray(stageData) && stageData.length === 0)) {
+                    return {
+                        content: [{ type: 'text', text: formatEmptyResult(stageContext, `No ${stage} themes currently. Try other stages: ${VALID_STAGES.filter(s => s !== stage).join(', ')}.`) }],
+                    };
+                }
                 return {
                     content: [
                         {

package/dist/tools/search-stocks.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const registerSearchStocks: (server: McpServer) => void;

package/dist/tools/search-stocks.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { fetchApi, formatResult, formatError, formatEmptyResult } from '../fetch-helper.js';
+const CONTEXT = `[StockMatrix Stock Search]
+Search Korean stocks by company name or 6-digit code, then inspect which themes they belong to.
+For 6-digit codes, returns detailed stock-to-theme lookup. For text queries, returns matching stocks with themes.
+Results include stock identity plus top related themes with lifecycle score and stage.
+Common examples: 삼성전자, SK하이닉스, NAVER, 카카오, 005930, 000660.`;
+const IS_SIX_DIGIT = /^\d{6}$/;
+export const registerSearchStocks = (server) => {
+    server.tool('search_stocks', `Search Korean stocks by company name, symbol, or 6-digit stock code, and preview their related themes.
+
+Use when the user asks:
+- Find Samsung Electronics / 삼성전자
+- I only know the company name, not the stock code
+- 종목명으로 코드 찾고 관련 테마도 보고 싶어
+- 삼성전자가 속한 테마 알려줘 / what themes is Samsung in?
+- 005930 테마 알려줘 / which themes is this stock part of?
+
+For 6-digit stock codes, automatically performs a detailed stock-to-theme lookup (replaces get_stock_theme).
+For text queries, searches by company name and returns matching stocks with theme previews.`, {
+        query: z
+            .string()
+            .min(1)
+            .max(200)
+            .describe('Company name or 6-digit stock code, e.g. "삼성전자", "SK하이닉스", "005930"'),
+    }, async ({ query }) => {
+        try {
+            if (IS_SIX_DIGIT.test(query.trim())) {
+                const [themeData, searchData] = await Promise.all([
+                    fetchApi(`/api/tli/stocks/${query.trim()}/theme`).catch(() => null),
+                    fetchApi('/api/tli/stocks/search', { q: query.trim() }).catch(() => null),
+                ]);
+                if (!themeData && (!searchData || (Array.isArray(searchData) && searchData.length === 0))) {
+                    return {
+                        content: [{ type: 'text', text: formatEmptyResult(CONTEXT, `No stock found for code "${query}". Verify the 6-digit Korean stock code.`) }],
+                    };
+                }
+                const combined = { stockThemes: themeData, searchResults: searchData };
+                return {
+                    content: [{ type: 'text', text: formatResult(combined, CONTEXT) }],
+                };
+            }
+            const data = await fetchApi('/api/tli/stocks/search', { q: query });
+            if (Array.isArray(data) && data.length === 0) {
+                return {
+                    content: [{ type: 'text', text: formatEmptyResult(CONTEXT, `No stocks found for "${query}". Try a different company name or check the spelling.`) }],
+                };
+            }
+            return {
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatError(error) }],
+                isError: true,
+            };
+        }
+    });
+};

package/dist/tools/search-themes.js

@@ -1,25 +1,31 @@
 import { z } from 'zod';
-import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
+import { fetchApi, formatResult, formatError, formatEmptyResult } from '../fetch-helper.js';
 const CONTEXT = `[StockMatrix Theme Search]
 Results include TLI score (0-100), lifecycle stage, and theme ID for drill-down.
 Use theme_id with get_theme_detail for full analysis or get_theme_history for 30-day trend.
+Search also matches related stock names and 6-digit stock codes when available.
 Stages: Emerging (초기) → Growth (성장) → Peak (정점) → Decline (하락), with Reigniting (재점화) for comeback themes.`;
 export const registerSearchThemes = (server) => {
     server.tool('search_themes', `Search Korean stock market themes by keyword (Korean or English).
 
-Use when the user asks about a specific sector, industry, or investment theme. Searches theme names and related stock names.
+Use when the user asks about a specific sector, industry, investment theme, stock name, or stock code. Searches theme names, related stock names, and stock symbols.
 
-Examples: "AI", "반도체" (semiconductor), "2차전지" (EV battery), "방산" (defense), "로봇" (robotics), "원자력" (nuclear), "삼성전자" (Samsung).
+Examples: "AI", "반도체" (semiconductor), "2차전지" (EV battery), "방산" (defense), "로봇" (robotics), "원자력" (nuclear), "삼성전자" (Samsung), "005930".
 
 Returns matching themes with TLI scores and lifecycle stages. Use the returned theme_id with get_theme_detail or get_theme_history for deeper analysis.`, {
         query: z
             .string()
             .min(1)
             .max(200)
-            .describe('Search query — theme name, sector keyword, or stock name (Korean or English)'),
+            .describe('Search query — theme name, sector keyword, stock name, or 6-digit stock code'),
     }, async ({ query }) => {
         try {
             const data = await fetchApi('/api/tli/themes', { q: query });
+            if (Array.isArray(data) && data.length === 0) {
+                return {
+                    content: [{ type: 'text', text: formatEmptyResult(CONTEXT, `No themes found for "${query}". Try broader keywords like "AI", "반도체", "2차전지".`) }],
+                };
+            }
             return {
                 content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
             };

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "stockmatrix-mcp",
   "mcpName": "io.github.MongLong0214/stockmatrix-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "StockMatrix MCP Server — Korean stock market theme lifecycle analysis (TLI) with Bayesian-optimized scoring for AI agents",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "stockmatrix-mcp": "dist/index.js"
+    "stockmatrix-mcp": "dist/cli.js"
   },
   "files": [
     "dist"
   ],
   "scripts": {
     "build": "tsc",
-    "start": "node dist/index.js",
+    "start": "node dist/cli.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -26,6 +26,11 @@
     "kosdaq",
     "ai-agent"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MongLong0214/stock-ai-newsletter",
+    "directory": "mcp"
+  },
   "homepage": "https://stockmatrix.co.kr/developers",
   "license": "MIT",
   "author": "StockMatrix <aistockmatrix@gmail.com>",

package/dist/tools/get-stock-theme.js

@@ -1,31 +0,0 @@
-import { z } from 'zod';
-import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
-const CONTEXT = `[StockMatrix Stock-to-Theme Lookup]
-Shows all investment themes a specific Korean stock belongs to, with each theme's TLI score and lifecycle stage.
-A stock can belong to multiple themes simultaneously. Use the returned theme_id with get_theme_detail for full analysis.
-Common codes: 005930 (삼성전자), 000660 (SK하이닉스), 373220 (LG에너지솔루션), 035420 (NAVER), 035720 (카카오).`;
-export const registerGetStockTheme = (server) => {
-    server.tool('get_stock_theme', `Find which investment themes a Korean stock belongs to.
-
-Use when the user asks about a specific stock by its 6-digit code. Returns all associated themes with TLI scores and lifecycle stages.
-
-Answers: "삼성전자 무슨 테마야?", "what themes is this stock part of?", "이 종목 관련 테마", "005930 테마 알려줘".`, {
-        symbol: z
-            .string()
-            .regex(/^\d{6}$/, 'Korean stock code must be 6 digits')
-            .describe('6-digit Korean stock code (e.g. "005930" for Samsung, "000660" for SK Hynix)'),
-    }, async ({ symbol }) => {
-        try {
-            const data = await fetchApi(`/api/tli/stocks/${symbol}/theme`);
-            return {
-                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
-            };
-        }
-        catch (error) {
-            return {
-                content: [{ type: 'text', text: formatError(error) }],
-                isError: true,
-            };
-        }
-    });
-};