stockmatrix-mcp 0.1.4 → 0.4.0

package/README.md

@@ -1,14 +1,10 @@
 # stockmatrix-mcp
 
-MCP server for Korean stock market theme lifecycle analysis. Provides real-time theme scores, lifecycle stages, related stocks, and news for 250+ KOSPI/KOSDAQ investment themes.
+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.
 
-## Installation
+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.
 
-```bash
-npx -y stockmatrix-mcp
-```
-
-## Configuration
+## Quick Start
 
 ### Claude Desktop
 
@@ -25,9 +21,9 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-### Cursor
+### Cursor / Windsurf
 
-Add to `.cursor/mcp.json`:
+Add to `.cursor/mcp.json` or `.windsurf/mcp.json`:
 
 ```json
 {
@@ -40,7 +36,7 @@ Add to `.cursor/mcp.json`:
 }
 ```
 
-### VS Code
+### VS Code / Claude Code
 
 Add to `.vscode/mcp.json`:
 
@@ -55,71 +51,133 @@ Add to `.vscode/mcp.json`:
 }
 ```
 
+## Try Asking
+
+After setup, just ask in natural language:
+
+| Prompt | What happens |
+|--------|-------------|
+| "요즘 뜨는 테마 TOP 5" | Top 5 themes ranked by TLI score |
+| "오늘 한국 테마 시장 요약해줘" | AI-optimized market overview |
+| "어제 대비 가장 많이 오른 테마는?" | Daily score movers and stage transitions |
+| "AI 관련 테마 찾아줘" | Search AI-related themes |
+| "반도체 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 |
+
 ## Available Tools
 
 ### `get_theme_ranking`
-
-한국 주식시장 테마 생명주기 랭킹을 조회합니다. Retrieves theme lifecycle rankings by stage.
+Get theme rankings by lifecycle stage with limit and sort options.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `stage` | string | No | Filter by stage: `emerging`, `growth`, `peak`, `decline`, `reigniting` |
+| `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) |
 
-### `get_theme_detail`
+### `get_market_summary`
+Get an AI-optimized market overview with top themes (includes themeId for chaining).
 
-특정 테마의 상세 정보를 조회합니다. Gets detailed theme info including score, stage, related stocks, and news.
+### `get_theme_changes`
+Get daily or weekly score movers, stage transitions, and newly emerging themes.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `theme_id` | string (UUID) | Yes | Theme UUID |
+| `period` | string | No | `1d` (default) / `7d` |
 
-### `get_theme_history`
+### `compare_themes`
+Compare 2-5 themes side-by-side with scores, stocks, sparklines, and similarity.
 
-테마의 최근 30일 점수 이력을 조회합니다. Returns 30-day score history for a theme.
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `theme_ids` | string[] | Yes | Array of 2-5 theme UUIDs |
+
+### `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 |
+| `phase` | string | No | `rising` / `hot` / `cooling` (default: all) |
 
 ### `search_themes`
+Search themes by keyword, stock name, or stock code.
+
+| 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 |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | e.g. `"삼성전자"`, `"SK하이닉스"`, `"005930"` |
 
-테마를 검색합니다. Searches themes by name in Korean or English.
+### `get_theme_detail`
+Get detailed analysis: score breakdown (4 components), stage, prediction, stocks, news, comparisons.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `query` | string | Yes | Search query (e.g. `"AI"`, `"반도체"`, `"삼성전자"`) |
+| `theme_id` | string (UUID) | Yes | Theme UUID from ranking or search |
+
+### `get_theme_history`
+Get 30-day score history for trend analysis.
 
-### `get_stock_theme`
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `theme_id` | string (UUID) | Yes | Theme UUID |
 
-특정 종목이 속한 테마를 조회합니다. Finds themes related to a specific stock code.
+### `get_methodology`
+Get TLI algorithm documentation — scoring, stages, stabilization, comparison, prediction, data sources, and more.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `symbol` | string | Yes | 6-digit Korean stock code (e.g. `"005930"` for Samsung) |
+| `section` | string | No | `scoring` / `stages` / `comparison` / `prediction` / `all` (default: all) |
 
-## Environment Variables
+> Tip: Use `section=scoring` to get just the scoring algorithm and save context tokens.
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `STOCKMATRIX_API_URL` | `https://stockmatrix.co.kr` | API base URL |
+## Scoring Algorithm
 
-## Examples
+TLI scores (0-100) are a weighted sum of 4 components, optimized via Bayesian Optimization:
 
-**"What are the hottest stock themes in Korea right now?"**
-→ `get_theme_ranking` with `stage: "growth"`
+| Component | Weight | Source |
+|-----------|--------|--------|
+| Search Interest | 30.4% | Naver DataLab |
+| News Momentum | 36.6% | Naver News |
+| Volatility | 10.4% | Interest time-series |
+| Stock Activity | 22.6% | Naver Finance |
 
-**"Tell me about the semiconductor theme"**
-→ `search_themes` with `query: "반도체"` → `get_theme_detail` with the returned theme ID
+Scores are stabilized through **Cautious Decay** (3-signal majority vote), **Bollinger Band Clamp** (limits daily change), and **Age-adaptive EMA** (newer themes react faster).
 
-**"What themes is Samsung Electronics part of?"**
-→ `get_stock_theme` with `symbol: "005930"`
+## Lifecycle Stages
 
-## Data Sources
+```
+Dormant -> Emerging -> Growth -> Peak -> Decline -> Dormant
+                                          |
+                                     Reigniting
+```
+
+Stage transitions require 2 consecutive days of the same candidate (hysteresis) and follow Markov transition constraints.
+
+## Data Coverage
+
+- **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
 
-- Naver DataLab search interest trends
-- Naver Finance theme stock data
-- Naver News article collection
-- KRX (Korea Exchange) market data
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STOCKMATRIX_API_URL` | `https://stockmatrix.co.kr` | Override API base URL |
 
 ## License
 

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,3 +1,7 @@
-export declare const fetchApi: <T = unknown>(path: string, params?: Record<string, string>) => Promise<T>;
-export declare const formatResult: (data: unknown) => string;
+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,5 +1,11 @@
+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/0.1.3`;
+const MCP_USER_AGENT = `stockmatrix-mcp/${version}`;
 // 시작 시 URL 유효성 검증
 try {
     new URL(BASE_URL);
@@ -23,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) {
@@ -64,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;
@@ -78,8 +93,18 @@ export const fetchApi = async (path, params) => {
     }
     throw lastError;
 };
-export const formatResult = (data) => JSON.stringify(data, null, 2);
+/** JSON 직렬화 with optional context header for AI agents */
+export const formatResult = (data, context) => {
+    if (context) {
+        return `${context}\n\n${JSON.stringify(data, null, 2)}`;
+    }
+    return JSON.stringify(data, null, 2);
+};
 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,31 +1,32 @@
-#!/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 = () => {
     const s = new McpServer({
         name: 'stockmatrix-mcp',
-        version: '0.1.3',
+        version,
     });
     registerGetThemeRanking(s);
     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 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.d.ts

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

package/dist/tools/get-methodology.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+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%' },
+            { name: 'newsMomentum', weight: '36.6%' },
+            { name: 'volatility', weight: '10.4%' },
+            { name: 'activity', weight: '22.6%' },
+        ],
+    },
+    disclaimer: 'Full methodology unavailable — showing cached summary. Try again later.',
+};
+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.
+
+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, 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, data_sources, update_schedule, runtime, data_flow, database_tables, limitations, or all (default: all)'),
+    }, async ({ section }) => {
+        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: formatResult(METHODOLOGY_FALLBACK, CONTEXT) }],
+            };
+        }
+    });
+};

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,16 +1,34 @@
 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
+  - newsMomentum (36.6%): Naver News article count — weekly change rate
+  - volatility (10.4%): Interest time-series standard deviation
+  - activity (22.6%): Related stock price changes, volume intensity, data coverage
+Score stabilization: Cautious Decay (3-signal majority vote prevents false drops) → Bollinger Clamp → Age-adaptive EMA smoothing.
+Stage transitions use Markov constraints + 2-day hysteresis.
+Comparisons: 3-Pillar similarity (feature + curve + keyword) with Mutual Rank, threshold ≥ 0.40.`;
 export const registerGetThemeDetail = (server) => {
-    server.tool('get_theme_detail', '특정 테마의 상세 정보를 조회합니다. 테마 점수, 생명주기 단계, 관련 종목, 뉴스 등을 포함합니다.', {
+    server.tool('get_theme_detail', `Get detailed analysis for a specific Korean stock theme.
+
+Returns: TLI score breakdown (4 components with weights), lifecycle stage, 24h/7d score changes, prediction outlook, top related stocks with price changes, latest news headlines, and similar theme comparisons.
+
+Use after get_theme_ranking or search_themes to drill into a specific theme. Answers: "tell me more about this theme", "what stocks are in this theme", "테마 상세 정보", "관련 종목 알려줘", "이 테마 전망".`, {
         theme_id: z
             .string()
             .uuid('Theme ID must be a valid UUID')
-            .describe('Theme UUID (e.g. "a1b2c3d4-e5f6-7890-abcd-ef1234567890")'),
+            .describe('Theme UUID from ranking or search results'),
     }, 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) }],
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
             };
         }
         catch (error) {

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

@@ -1,16 +1,32 @@
 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
+- Stage transitions: stage changes require 2 consecutive days (hysteresis)
+- Score stability: Cautious Decay prevents false drops from data gaps
+- Momentum: EMA smoothing adapts to theme age (newer themes react faster)
+Scores are 0-100, computed from interest + news + volatility + activity.`;
 export const registerGetThemeHistory = (server) => {
-    server.tool('get_theme_history', '테마의 최근 30일 점수 이력을 조회합니다. 생명주기 추이를 파악할 수 있습니다.', {
+    server.tool('get_theme_history', `Get 30-day score history for a Korean stock theme.
+
+Returns daily TLI scores and stage transitions for trend analysis. Use when the user asks about theme momentum over time, whether a theme is gaining or losing interest, or wants to see historical trajectory.
+
+Answers: "이 테마 추세가 어때?", "최근 한달 흐름", "is this theme gaining or losing momentum?", "show me the trend".`, {
         theme_id: z
             .string()
             .uuid('Theme ID must be a valid UUID')
-            .describe('Theme UUID (e.g. "a1b2c3d4-e5f6-7890-abcd-ef1234567890")'),
+            .describe('Theme UUID from ranking or search results'),
     }, 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) }],
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
             };
         }
         catch (error) {

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',
@@ -7,29 +7,72 @@ const VALID_STAGES = [
     'decline',
     'reigniting',
 ];
+const STAGE_DESCRIPTIONS = {
+    emerging: 'score < growth threshold, early interest signal',
+    growth: 'score ≥ 40 with stable/rising trend — expanding interest',
+    peak: 'score ≥ 71 or high score + news surge — maximum attention',
+    decline: 'falling trend + score drop + declining news coverage',
+    reigniting: 'previously declined theme showing renewed growth',
+};
+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.
+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', '한국 주식시장 테마 생명주기 랭킹을 조회합니다. 단계별(초기/성장/정점/쇠퇴/재점화) 테마 목록과 점수를 반환합니다.', {
+    server.tool('get_theme_ranking', `Get Korean stock market theme rankings with lifecycle scores (TLI: Theme Lifecycle Index).
+
+Use when the user asks about:
+- Trending stock themes, hot investment sectors, market momentum
+- What themes are rising/falling in Korea
+- 한국 주식 테마 랭킹, 요즘 뜨는 테마, 상승/하락 테마
+- KOSPI/KOSDAQ theme trends
+
+Returns themes ranked by score (0-100) with lifecycle stage and related stocks. Scores are computed from search interest (Naver DataLab), news momentum, market volatility, and stock activity — all optimized via Bayesian optimization.`, {
         stage: z
             .enum(VALID_STAGES)
             .optional()
-            .describe('Filter by lifecycle stage: emerging (초기), growth (성장), peak (정점), decline (쇠퇴), reigniting (재점화)'),
-    }, async ({ stage }) => {
+            .describe('Filter by lifecycle stage: emerging (초기 — early interest), growth (성장 — expanding), peak (정점 — maximum attention), decline (하락 — fading), reigniting (재점화 — comeback)'),
+        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: [
                         {
                             type: 'text',
-                            text: formatResult({ stage, themes: stageData, summary }),
+                            text: formatResult({ stage, themes: stageData, summary }, stageContext),
                         },
                     ],
                 };
             }
             return {
-                content: [{ type: 'text', text: formatResult(data) }],
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
             };
         }
         catch (error) {

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,17 +1,33 @@
 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', '테마를 검색합니다. 이름(한국어/영문)으로 필터링하여 일치하는 테마의 점수, 단계 정보를 반환합니다.', {
+    server.tool('search_themes', `Search Korean stock market themes by keyword (Korean or English).
+
+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), "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 or related stock name, e.g. "AI", "반도체", "삼성전자")'),
+            .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) }],
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
             };
         }
         catch (error) {

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "stockmatrix-mcp",
   "mcpName": "io.github.MongLong0214/stockmatrix-mcp",
-  "version": "0.1.4",
-  "description": "StockMatrix MCP Server - Korean stock market theme lifecycle analysis for AI agents",
+  "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,23 +0,0 @@
-import { z } from 'zod';
-import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
-export const registerGetStockTheme = (server) => {
-    server.tool('get_stock_theme', '특정 종목이 속한 테마를 조회합니다. 종목 코드로 관련 테마 정보를 확인할 수 있습니다.', {
-        symbol: z
-            .string()
-            .regex(/^\d{6}$/, 'Korean stock code must be 6 digits')
-            .describe('Korean stock code (e.g. "005930" for Samsung Electronics, "000660" for SK Hynix)'),
-    }, async ({ symbol }) => {
-        try {
-            const data = await fetchApi(`/api/tli/stocks/${symbol}/theme`);
-            return {
-                content: [{ type: 'text', text: formatResult(data) }],
-            };
-        }
-        catch (error) {
-            return {
-                content: [{ type: 'text', text: formatError(error) }],
-                isError: true,
-            };
-        }
-    });
-};