stockmatrix-mcp 0.1.3 → 0.2.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.
+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.
 
-## Installation
+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.
 
-```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,106 @@ Add to `.vscode/mcp.json`:
 }
 ```
 
+## Try Asking
+
+After setup, just ask in natural language:
+
+| Prompt | What happens |
+|--------|-------------|
+| "요즘 한국 주식시장에서 뜨는 테마 뭐야?" | Top trending themes with scores |
+| "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 |
+| "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`
 
-한국 주식시장 테마 생명주기 랭킹을 조회합니다. Retrieves theme lifecycle rankings by stage.
+Get theme rankings by lifecycle stage.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `stage` | string | No | Filter by stage: `emerging`, `growth`, `peak`, `decline`, `reigniting` |
+| `stage` | string | No | `emerging` / `growth` / `peak` / `decline` / `reigniting` |
+
+### `search_themes`
+
+Search themes by keyword (Korean or English).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | e.g. `"AI"`, `"반도체"`, `"2차전지"`, `"삼성전자"` |
 
 ### `get_theme_detail`
 
-특정 테마의 상세 정보를 조회합니다. Gets detailed theme info including score, stage, related stocks, and news.
+Get detailed info: score breakdown (4 components), stage, prediction, stocks, news, comparisons.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `theme_id` | string (UUID) | Yes | Theme UUID |
+| `theme_id` | string (UUID) | Yes | Theme UUID from ranking or search |
 
 ### `get_theme_history`
 
-테마의 최근 30일 점수 이력을 조회합니다. Returns 30-day score history for a theme.
+Get 30-day score history for trend analysis.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `theme_id` | string (UUID) | Yes | Theme UUID |
 
-### `search_themes`
+### `get_stock_theme`
 
-테마를 검색합니다. Searches themes by name in Korean or English.
+Find themes a specific stock belongs to.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `query` | string | Yes | Search query (e.g. `"AI"`, `"반도체"`, `"삼성전자"`) |
+| `symbol` | string | Yes | 6-digit code, e.g. `"005930"` (Samsung), `"000660"` (SK Hynix) |
 
-### `get_stock_theme`
+### `get_methodology`
 
-특정 종목이 속한 테마를 조회합니다. Finds themes related to a specific stock code.
+Get TLI algorithm documentation — scoring, stages, stabilization, comparison, prediction.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `symbol` | string | Yes | 6-digit Korean stock code (e.g. `"005930"` for Samsung) |
+| `section` | string | No | `scoring` / `stabilization` / `stages` / `comparison` / `prediction` / `all` |
 
-## Environment Variables
+## Scoring Algorithm
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `STOCKMATRIX_API_URL` | `https://stockmatrix.co.kr` | API base URL |
+TLI scores (0-100) are a weighted sum of 4 components, optimized via Bayesian Optimization:
 
-## Examples
+| 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 |
 
-**"What are the hottest stock themes in Korea right now?"**
-→ `get_theme_ranking` with `stage: "growth"`
+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).
 
-**"Tell me about the semiconductor theme"**
-→ `search_themes` with `query: "반도체"` → `get_theme_detail` with the returned theme ID
+## Lifecycle Stages
 
-**"What themes is Samsung Electronics part of?"**
-→ `get_stock_theme` with `symbol: "005930"`
+```
+Dormant → Emerging → Growth → Peak → Decline → Dormant
+                                          ↓
+                                     Reigniting
+```
 
-## Data Sources
+Stage transitions require 2 consecutive days of the same candidate (hysteresis) and follow Markov transition constraints.
 
-- Naver DataLab search interest trends
-- Naver Finance theme stock data
-- Naver News article collection
-- KRX (Korea Exchange) market data
+## Data Coverage
+
+- **250+ themes** across KOSPI & KOSDAQ
+- **Daily updates** — scores, news, stock mappings
+- **Sources**: Naver DataLab, Naver Finance, Naver News
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STOCKMATRIX_API_URL` | `https://stockmatrix.co.kr` | Override API base URL |
 
 ## License
 

package/dist/fetch-helper.d.ts

@@ -1,3 +1,4 @@
 export declare const fetchApi: <T = unknown>(path: string, params?: Record<string, string>) => Promise<T>;
-export declare const formatResult: (data: unknown) => string;
+/** JSON 직렬화 with optional context header for AI agents */
+export declare const formatResult: (data: unknown, context?: string) => string;
 export declare const formatError: (error: unknown) => string;

package/dist/fetch-helper.js

@@ -1,5 +1,8 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
 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);
@@ -78,7 +81,13 @@ 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}`;

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/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';
@@ -6,16 +7,20 @@ 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 { registerGetMethodology } from './tools/get-methodology.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);
+    registerGetMethodology(s);
     return s;
 };
 export const createSandboxServer = () => createServer();
@@ -23,7 +28,7 @@ const server = createServer();
 const main = async () => {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error('StockMatrix MCP server running on stdio');
+    console.error(`StockMatrix MCP server v${version} running on stdio`);
 };
 main().catch((error) => {
     console.error('Fatal error in main():', error);

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,109 @@
+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.',
+    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.' },
+        ],
+        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.',
+};
+const SECTIONS = ['scoring', 'stabilization', 'stages', 'comparison', 'prediction', 'all'];
+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?
+- TLI 알고리즘 설명, 점수 산출 방식, 단계 판정 기준
+- What data sources are used?
+
+Returns structured documentation of the scoring algorithm, 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)'),
+    }, async ({ section }) => {
+        const selected = section || 'all';
+        if (selected === 'all') {
+            return {
+                content: [{ type: 'text', text: JSON.stringify(METHODOLOGY, null, 2) }],
+            };
+        }
+        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-stock-theme.js

@@ -1,16 +1,24 @@
 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', '특정 종목이 속한 테마를 조회합니다. 종목 코드로 관련 테마 정보를 확인할 수 있습니다.', {
+    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('Korean stock code (e.g. "005930" for Samsung Electronics, "000660" for SK Hynix)'),
+            .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) }],
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
             };
         }
         catch (error) {

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

@@ -1,16 +1,29 @@
 import { z } from 'zod';
 import { fetchApi, formatResult, formatError } 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}`);
             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,27 @@
 import { z } from 'zod';
 import { fetchApi, formatResult, formatError } 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`);
             return {
-                content: [{ type: 'text', text: formatResult(data) }],
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
             };
         }
         catch (error) {

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

@@ -7,29 +7,49 @@ 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.`;
 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 (재점화)'),
+            .describe('Filter by lifecycle stage: emerging (초기 — early interest), growth (성장 — expanding), peak (정점 — maximum attention), decline (하락 — fading), reigniting (재점화 — comeback)'),
     }, async ({ stage }) => {
         try {
             const data = await fetchApi('/api/tli/scores/ranking');
             if (stage) {
                 const stageData = data[stage];
                 const summary = data.summary;
+                const stageContext = `${CONTEXT}\nFiltered: ${stage} — ${STAGE_DESCRIPTIONS[stage]}`;
                 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-themes.js

@@ -1,17 +1,27 @@
 import { z } from 'zod';
 import { fetchApi, formatResult, formatError } 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.
+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, or investment theme. Searches theme names and related stock names.
+
+Examples: "AI", "반도체" (semiconductor), "2차전지" (EV battery), "방산" (defense), "로봇" (robotics), "원자력" (nuclear), "삼성전자" (Samsung).
+
+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, or stock name (Korean or English)'),
     }, async ({ query }) => {
         try {
             const data = await fetchApi('/api/tli/themes', { q: query });
             return {
-                content: [{ type: 'text', text: formatResult(data) }],
+                content: [{ type: 'text', text: formatResult(data, CONTEXT) }],
             };
         }
         catch (error) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "stockmatrix-mcp",
   "mcpName": "io.github.MongLong0214/stockmatrix-mcp",
-  "version": "0.1.3",
-  "description": "StockMatrix MCP Server - Korean stock market theme lifecycle analysis for AI agents",
+  "version": "0.2.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": {