stockmatrix-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StockMatrix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# 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.
+
+## Installation
+
+```bash
+npx -y stockmatrix-mcp
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "stockmatrix": {
+      "command": "npx",
+      "args": ["-y", "stockmatrix-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "stockmatrix": {
+      "command": "npx",
+      "args": ["-y", "stockmatrix-mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "stockmatrix": {
+      "command": "npx",
+      "args": ["-y", "stockmatrix-mcp"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `get_theme_ranking`
+
+한국 주식시장 테마 생명주기 랭킹을 조회합니다. Retrieves theme lifecycle rankings by stage.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `stage` | string | No | Filter by stage: `emerging`, `growth`, `peak`, `decline`, `reigniting` |
+
+### `get_theme_detail`
+
+특정 테마의 상세 정보를 조회합니다. Gets detailed theme info including score, stage, related stocks, and news.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `theme_id` | string (UUID) | Yes | Theme UUID |
+
+### `get_theme_history`
+
+테마의 최근 30일 점수 이력을 조회합니다. Returns 30-day score history for a theme.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `theme_id` | string (UUID) | Yes | Theme UUID |
+
+### `search_themes`
+
+테마를 검색합니다. Searches themes by name in Korean or English.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | Search query (e.g. `"AI"`, `"반도체"`, `"삼성전자"`) |
+
+### `get_stock_theme`
+
+특정 종목이 속한 테마를 조회합니다. Finds themes related to a specific stock code.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `symbol` | string | Yes | 6-digit Korean stock code (e.g. `"005930"` for Samsung) |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STOCKMATRIX_API_URL` | `https://stockmatrix.co.kr` | API base URL |
+
+## Examples
+
+**"What are the hottest stock themes in Korea right now?"**
+→ `get_theme_ranking` with `stage: "growth"`
+
+**"Tell me about the semiconductor theme"**
+→ `search_themes` with `query: "반도체"` → `get_theme_detail` with the returned theme ID
+
+**"What themes is Samsung Electronics part of?"**
+→ `get_stock_theme` with `symbol: "005930"`
+
+## Data Sources
+
+- Naver DataLab search interest trends
+- Naver Finance theme stock data
+- Naver News article collection
+- KRX (Korea Exchange) market data
+
+## License
+
+MIT
+
+## Links
+
+- [Website](https://stockmatrix.co.kr)
+- [Developer Guide](https://stockmatrix.co.kr/developers)
+- [GitHub](https://github.com/MongLong0214/stock-ai-newsletter)
+- [llms.txt](https://stockmatrix.co.kr/llms.txt)

package/dist/fetch-helper.d.ts

@@ -0,0 +1,3 @@
+export declare const fetchApi: <T = unknown>(path: string, params?: Record<string, string>) => Promise<T>;
+export declare const formatResult: (data: unknown) => string;
+export declare const formatError: (error: unknown) => string;

package/dist/fetch-helper.js

@@ -0,0 +1,45 @@
+const BASE_URL = process.env.STOCKMATRIX_API_URL || 'https://stockmatrix.co.kr';
+// 시작 시 URL 유효성 검증
+try {
+    new URL(BASE_URL);
+}
+catch {
+    throw new Error(`Invalid STOCKMATRIX_API_URL: "${BASE_URL}" is not a valid URL`);
+}
+export const fetchApi = async (path, params) => {
+    const url = new URL(path, BASE_URL);
+    if (params) {
+        for (const [key, value] of Object.entries(params)) {
+            url.searchParams.set(key, value);
+        }
+    }
+    const response = await fetch(url.toString(), {
+        headers: { Accept: 'application/json' },
+    });
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => 'Unknown error');
+        throw new Error(`API request failed: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+    const contentType = response.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) {
+        const preview = await response.text().catch(() => '');
+        throw new Error(`Expected JSON response but got ${contentType || 'unknown'}: ${preview.slice(0, 200)}`);
+    }
+    const json = (await response.json());
+    if (json !== null &&
+        typeof json === 'object' &&
+        'success' in json &&
+        'data' in json) {
+        const wrapped = json;
+        if (!wrapped.success) {
+            throw new Error(wrapped.error?.message || 'API returned unsuccessful response');
+        }
+        return wrapped.data;
+    }
+    return json;
+};
+export const formatResult = (data) => JSON.stringify(data, null, 2);
+export const formatError = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    return `Error: ${message}`;
+};

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+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';
+const server = new McpServer({
+    name: 'stockmatrix-mcp',
+    version: '0.1.0',
+});
+registerGetThemeRanking(server);
+registerGetThemeDetail(server);
+registerGetThemeHistory(server);
+registerSearchThemes(server);
+registerGetStockTheme(server);
+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

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

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

@@ -0,0 +1,23 @@
+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,
+            };
+        }
+    });
+};

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

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

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

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
+export const registerGetThemeDetail = (server) => {
+    server.tool('get_theme_detail', '특정 테마의 상세 정보를 조회합니다. 테마 점수, 생명주기 단계, 관련 종목, 뉴스 등을 포함합니다.', {
+        theme_id: z
+            .string()
+            .uuid('Theme ID must be a valid UUID')
+            .describe('Theme UUID (e.g. "a1b2c3d4-e5f6-7890-abcd-ef1234567890")'),
+    }, async ({ theme_id }) => {
+        try {
+            const data = await fetchApi(`/api/tli/themes/${theme_id}`);
+            return {
+                content: [{ type: 'text', text: formatResult(data) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatError(error) }],
+                isError: true,
+            };
+        }
+    });
+};

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

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

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

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
+export const registerGetThemeHistory = (server) => {
+    server.tool('get_theme_history', '테마의 최근 30일 점수 이력을 조회합니다. 생명주기 추이를 파악할 수 있습니다.', {
+        theme_id: z
+            .string()
+            .uuid('Theme ID must be a valid UUID')
+            .describe('Theme UUID (e.g. "a1b2c3d4-e5f6-7890-abcd-ef1234567890")'),
+    }, async ({ theme_id }) => {
+        try {
+            const data = await fetchApi(`/api/tli/themes/${theme_id}/history`);
+            return {
+                content: [{ type: 'text', text: formatResult(data) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatError(error) }],
+                isError: true,
+            };
+        }
+    });
+};

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

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

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

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
+const VALID_STAGES = [
+    'emerging',
+    'growth',
+    'peak',
+    'decline',
+    'reigniting',
+];
+export const registerGetThemeRanking = (server) => {
+    server.tool('get_theme_ranking', '한국 주식시장 테마 생명주기 랭킹을 조회합니다. 단계별(초기/성장/정점/쇠퇴/재점화) 테마 목록과 점수를 반환합니다.', {
+        stage: z
+            .enum(VALID_STAGES)
+            .optional()
+            .describe('Filter by lifecycle stage: emerging (초기), growth (성장), peak (정점), decline (쇠퇴), reigniting (재점화)'),
+    }, async ({ stage }) => {
+        try {
+            const data = await fetchApi('/api/tli/scores/ranking');
+            if (stage) {
+                const stageData = data[stage];
+                const summary = data.summary;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: formatResult({ stage, themes: stageData, summary }),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [{ type: 'text', text: formatResult(data) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatError(error) }],
+                isError: true,
+            };
+        }
+    });
+};

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

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

package/dist/tools/search-themes.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { fetchApi, formatResult, formatError } from '../fetch-helper.js';
+export const registerSearchThemes = (server) => {
+    server.tool('search_themes', '테마를 검색합니다. 이름(한국어/영문)으로 필터링하여 일치하는 테마의 점수, 단계 정보를 반환합니다.', {
+        query: z
+            .string()
+            .min(1)
+            .describe('Search query (theme name or related stock name, e.g. "AI", "반도체", "삼성전자")'),
+    }, async ({ query }) => {
+        try {
+            const data = await fetchApi('/api/tli/themes', { q: query });
+            return {
+                content: [{ type: 'text', text: formatResult(data) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatError(error) }],
+                isError: true,
+            };
+        }
+    });
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "stockmatrix-mcp",
+  "version": "0.1.0",
+  "description": "StockMatrix MCP Server - Korean stock market theme lifecycle analysis for AI agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "stockmatrix-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "korean-stocks",
+    "theme-lifecycle",
+    "finance",
+    "kospi",
+    "kosdaq",
+    "ai-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MongLong0214/stock-ai-newsletter.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://stockmatrix.co.kr/developers",
+  "bugs": {
+    "url": "https://github.com/MongLong0214/stock-ai-newsletter/issues"
+  },
+  "license": "MIT",
+  "author": "StockMatrix <aistockmatrix@gmail.com>",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}