finhay-mcp-server 1.0.2

package/README.md

@@ -0,0 +1,118 @@
+# finhay-mcp-server
+
+MCP Server cho Finhay Securities — xem gia co phieu, danh muc dau tu, vang, crypto qua Claude AI.
+
+## Cai dat
+
+### Buoc 1: Tao API Key
+
+Vao [https://www.finhay.com.vn/finhay-skills](https://www.finhay.com.vn/finhay-skills) → Dang nhap → Tao API Key.
+
+Ban se nhan duoc:
+- **API Key**: `ak_live_xxx`
+- **API Secret**: `sk_live_yyy`
+
+### Buoc 2: Ket noi voi Claude
+
+Chon **mot trong ba** cach sau:
+
+#### Cach 1: Cai dat tu dong (Khuyen dung)
+
+Chay lenh sau va nhap API Key/Secret theo huong dan:
+
+```bash
+npx -y finhay-mcp-server --install
+```
+
+Sau khi hoan tat, khoi dong lai Claude Desktop la xong.
+
+#### Cach 2: Claude Code CLI
+
+Neu ban da cai [Claude Code](https://docs.anthropic.com/en/docs/claude-code), chay:
+
+```bash
+claude mcp add finhay -- npx -y finhay-mcp-server
+```
+
+Config se tu dong dong bo sang Claude Desktop.
+
+#### Cach 3: Cau hinh thu cong
+
+**Buoc 3a.** Tao file credentials tai `~/.finhay/credentials/.env`:
+
+```
+FINHAY_API_KEY=ak_live_xxx
+FINHAY_API_SECRET=sk_live_yyy
+```
+
+**Buoc 3b.** Them vao file config Claude Desktop:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "finhay": {
+      "command": "npx",
+      "args": ["-y", "@finhay/mcp-server"]
+    }
+  }
+}
+```
+
+> API Key/Secret **khong nam** trong file config Claude — duoc luu rieng tai `~/.finhay/credentials/.env` (dung chung voi Finhay Skills).
+
+### Buoc 3: Su dung
+
+Mo Claude, hoi:
+
+- "Gia co phieu VNM hom nay?"
+- "Xem danh muc dau tu cua toi"
+- "So sanh FPT va VNM"
+- "Gia vang SJC hom nay bao nhieu?"
+- "Lai suat tiet kiem ngan hang nao cao nhat?"
+- "Chi so CPI Viet Nam gan day?"
+
+## Tools
+
+### Thi truong (18 tools)
+
+| Tool | Mo ta |
+|------|-------|
+| `get_stock_realtime` | Gia co phieu realtime (1 ma, nhieu ma, hoac theo san) |
+| `get_price_history_chart` | Lich su gia OHLCV |
+| `get_recommendation_reports` | Bao cao phan tich tu chuyen gia |
+| `get_funds` | Danh sach quy dau tu |
+| `get_fund_portfolio` | Danh muc cua quy |
+| `get_fund_months` | Cac thang co du lieu quy |
+| `get_gold_prices` | Gia vang (SJC, DOJI, PNJ, BTMC) |
+| `get_gold_chart` | Bieu do gia vang |
+| `get_gold_providers` | Gia vang theo nha cung cap |
+| `get_silver_prices` | Gia bac |
+| `get_silver_chart` | Bieu do gia bac |
+| `get_all_financial_data` | Tong hop: vang, bac, crypto, lai suat, ty gia |
+| `get_bank_interest_rates` | Lai suat tiet kiem ngan hang |
+| `get_crypto_top_trending` | Crypto xu huong |
+| `get_macro_data` | Chi so vi mo (CPI, PMI, IIP, FED rate...) |
+| `get_market_session` | Trang thai phien giao dich |
+
+### Tai khoan (11 tools)
+
+| Tool | Mo ta |
+|------|-------|
+| `get_owner_info` | Thong tin chu tai khoan |
+| `get_account_summary` | So du: tien mat, chung khoan, ky quy |
+| `get_asset_summary` | Tong tai san |
+| `get_portfolio` | Danh muc co phieu voi lai/lo |
+| `get_pnl_today` | Lai/lo hom nay |
+| `get_order_history` | Lich su lenh |
+| `get_order_book` | So lenh trong ngay |
+| `get_order_detail` | Chi tiet 1 lenh |
+| `get_user_rights` | Quyen co dong: co tuc, quyen mua... |
+| `get_trade_info` | Suc mua / so luong ban duoc |
+
+
+## Yeu cau
+
+- Node.js >= 18
+- Tai khoan Finhay Securities voi API Key

package/dist/client/AccountContext.d.ts

@@ -0,0 +1,25 @@
+import { FinhayClient } from './FinhayClient.js';
+export interface AccountInfo {
+    userId: string;
+    defaultSubAccountId: string;
+    subAccountIds: string[];
+}
+/**
+ * Fetches and caches account info (userId, subAccountIds) on startup.
+ * Tools use this as default when user does not provide subAccountId.
+ */
+export declare class AccountContext {
+    private readonly client;
+    private info;
+    constructor(client: FinhayClient);
+    init(): Promise<void>;
+    getUserId(): string | undefined;
+    getDefaultSubAccountId(): string | undefined;
+    getSubAccountIds(): string[];
+    /**
+     * Returns the given subAccountId if provided, otherwise falls back to default.
+     * Throws if neither is available.
+     */
+    resolveSubAccountId(subAccountId?: string): string;
+    resolveUserId(userId?: string): string;
+}

package/dist/client/AccountContext.js

@@ -0,0 +1,64 @@
+/**
+ * Fetches and caches account info (userId, subAccountIds) on startup.
+ * Tools use this as default when user does not provide subAccountId.
+ */
+export class AccountContext {
+    client;
+    info = null;
+    constructor(client) {
+        this.client = client;
+    }
+    async init() {
+        try {
+            // Step 1: get userId
+            const meData = await this.client.get('/users/v1/users/me');
+            const meResult = meData.result ?? meData.data;
+            const userId = meResult?.user_id ?? meResult?.userId ?? meResult?.id ?? '';
+            if (!userId) {
+                throw new Error('Could not extract userId from /users/v1/users/me');
+            }
+            // Step 2: get sub-accounts
+            const subData = await this.client.get(`/users/v1/users/${userId}/sub-accounts`);
+            const subResult = subData.result ?? subData.data ?? [];
+            const subAccounts = Array.isArray(subResult) ? subResult : subResult?.subAccounts ?? subResult?.sub_accounts ?? [];
+            const subAccountIds = subAccounts.map((sa) => sa.subAccountId ?? sa.sub_account_id ?? sa.id ?? '').filter(Boolean);
+            this.info = {
+                userId: String(userId),
+                defaultSubAccountId: subAccountIds[0] ?? '',
+                subAccountIds,
+            };
+            console.error(`[finhay-mcp] Account loaded: userId=${this.info.userId}, subAccounts=[${subAccountIds.join(', ')}]`);
+        }
+        catch (err) {
+            console.error(`[finhay-mcp] Warning: could not fetch account info: ${err.message}`);
+            console.error('[finhay-mcp] Tools requiring subAccountId will need it as a parameter.');
+        }
+    }
+    getUserId() {
+        return this.info?.userId || undefined;
+    }
+    getDefaultSubAccountId() {
+        return this.info?.defaultSubAccountId || undefined;
+    }
+    getSubAccountIds() {
+        return this.info?.subAccountIds ?? [];
+    }
+    /**
+     * Returns the given subAccountId if provided, otherwise falls back to default.
+     * Throws if neither is available.
+     */
+    resolveSubAccountId(subAccountId) {
+        const resolved = subAccountId || this.info?.defaultSubAccountId;
+        if (!resolved) {
+            throw new Error('subAccountId is required. Could not auto-detect — provide it explicitly or check your API credentials.');
+        }
+        return resolved;
+    }
+    resolveUserId(userId) {
+        const resolved = userId || this.info?.userId;
+        if (!resolved) {
+            throw new Error('userId is required. Could not auto-detect — provide it explicitly or check your API credentials.');
+        }
+        return resolved;
+    }
+}

package/dist/client/FinhayClient.d.ts

@@ -0,0 +1,23 @@
+export declare class FinhayClient {
+    private readonly http;
+    private readonly signer;
+    private readonly apiKey;
+    constructor(baseUrl: string, apiKey: string, apiSecret: string);
+    /**
+     * GET request with HMAC signing.
+     */
+    get(path: string, query?: Record<string, string>): Promise<any>;
+    /**
+     * POST request with HMAC signing + body hash.
+     */
+    post(path: string, body: Record<string, any>): Promise<any>;
+    /**
+     * PUT request with HMAC signing + body hash.
+     */
+    put(path: string, body: Record<string, any>): Promise<any>;
+    /**
+     * DELETE request with HMAC signing + body hash.
+     */
+    delete(path: string, body: Record<string, any>): Promise<any>;
+    private writeRequest;
+}

package/dist/client/FinhayClient.js

@@ -0,0 +1,85 @@
+import axios from 'axios';
+import { randomUUID } from 'crypto';
+import { HmacSigner } from './HmacSigner.js';
+export class FinhayClient {
+    http;
+    signer;
+    apiKey;
+    constructor(baseUrl, apiKey, apiSecret) {
+        this.apiKey = apiKey;
+        this.signer = new HmacSigner(apiSecret);
+        this.http = axios.create({
+            baseURL: baseUrl,
+            timeout: 15000,
+        });
+    }
+    /**
+     * GET request with HMAC signing.
+     */
+    async get(path, query) {
+        const queryString = query
+            ? Object.entries(query).map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&')
+            : null;
+        const fullPath = queryString ? `${path}?${queryString}` : path;
+        const timestamp = String(Date.now());
+        const nonce = randomUUID();
+        const bodyHash = '';
+        const payload = this.signer.buildPayload(timestamp, 'GET', path, queryString, null);
+        const signature = this.signer.sign(payload);
+        const headers = {
+            'X-FH-APIKEY': this.apiKey,
+            'X-FH-TIMESTAMP': timestamp,
+            'X-FH-NONCE': nonce,
+            'X-FH-SIGNATURE': signature,
+            'X-FH-BODYHASH': bodyHash,
+            'X-Origin-Method': 'GET',
+            'X-Origin-Path': path,
+            ...(queryString ? { 'X-Origin-Query': queryString } : {}),
+        };
+        const response = await this.http.get(fullPath, { headers });
+        return response.data;
+    }
+    /**
+     * POST request with HMAC signing + body hash.
+     */
+    async post(path, body) {
+        return this.writeRequest('POST', path, body);
+    }
+    /**
+     * PUT request with HMAC signing + body hash.
+     */
+    async put(path, body) {
+        return this.writeRequest('PUT', path, body);
+    }
+    /**
+     * DELETE request with HMAC signing + body hash.
+     */
+    async delete(path, body) {
+        return this.writeRequest('DELETE', path, body);
+    }
+    async writeRequest(method, path, body) {
+        const bodyStr = JSON.stringify(body);
+        const bodyHash = HmacSigner.sha256(bodyStr);
+        const timestamp = String(Date.now());
+        const nonce = randomUUID();
+        const payload = this.signer.buildPayload(timestamp, method, path, null, bodyHash);
+        const signature = this.signer.sign(payload);
+        const headers = {
+            'X-FH-APIKEY': this.apiKey,
+            'X-FH-TIMESTAMP': timestamp,
+            'X-FH-NONCE': nonce,
+            'X-FH-SIGNATURE': signature,
+            'X-FH-BODYHASH': bodyHash,
+            'X-Origin-Method': method.toUpperCase(),
+            'X-Origin-Path': path,
+            'Content-Type': 'application/json',
+        };
+        const response = await this.http.request({
+            method,
+            url: path,
+            data: body,
+            headers,
+        });
+        return response.data;
+    }
+}

package/dist/client/HmacSigner.d.ts

@@ -0,0 +1,13 @@
+export declare class HmacSigner {
+    private readonly secret;
+    constructor(secret: string);
+    /**
+     * Build HMAC payload.
+     * Format: {timestamp}\n{METHOD}\n{path}{?query}\n{bodyHash}
+     */
+    buildPayload(timestamp: string, method: string, path: string, queryString: string | null, bodyHash: string | null): string;
+    /** HMAC-SHA256 sign */
+    sign(payload: string): string;
+    /** SHA256 hash (for body) */
+    static sha256(input: string): string;
+}

package/dist/client/HmacSigner.js

@@ -0,0 +1,36 @@
+import crypto from 'crypto';
+export class HmacSigner {
+    secret;
+    constructor(secret) {
+        this.secret = secret;
+    }
+    /**
+     * Build HMAC payload.
+     * Format: {timestamp}\n{METHOD}\n{path}{?query}\n{bodyHash}
+     */
+    buildPayload(timestamp, method, path, queryString, bodyHash) {
+        let payload = `${timestamp}\n${method.toUpperCase()}\n${path}`;
+        if (queryString) {
+            payload += `?${queryString}`;
+        }
+        payload += '\n';
+        if (bodyHash) {
+            payload += bodyHash;
+        }
+        return payload;
+    }
+    /** HMAC-SHA256 sign */
+    sign(payload) {
+        return crypto
+            .createHmac('sha256', this.secret)
+            .update(payload, 'utf8')
+            .digest('hex');
+    }
+    /** SHA256 hash (for body) */
+    static sha256(input) {
+        return crypto
+            .createHash('sha256')
+            .update(input, 'utf8')
+            .digest('hex');
+    }
+}

package/dist/config/environment.d.ts

@@ -0,0 +1,8 @@
+export interface Config {
+    apiKey: string;
+    apiSecret: string;
+    baseUrl: string;
+}
+/** Shared credential path — same as finhay-skills-hub */
+export declare const CREDENTIALS_PATH: string;
+export declare function getConfig(): Config;

package/dist/config/environment.js

@@ -0,0 +1,34 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+/** Shared credential path — same as finhay-skills-hub */
+export const CREDENTIALS_PATH = path.join(os.homedir(), '.finhay', 'credentials', '.env');
+/**
+ * Load credentials from ~/.finhay/credentials/.env into process.env
+ * (only sets vars that are not already defined).
+ */
+function loadCredentialsFile() {
+    if (!fs.existsSync(CREDENTIALS_PATH))
+        return;
+    const content = fs.readFileSync(CREDENTIALS_PATH, 'utf-8');
+    for (const line of content.split('\n')) {
+        const match = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.+?)\s*$/);
+        if (match && !process.env[match[1]]) {
+            process.env[match[1]] = match[2];
+        }
+    }
+}
+export function getConfig() {
+    // Load from shared credentials file first, then env vars can override
+    loadCredentialsFile();
+    const apiKey = process.env.FINHAY_API_KEY;
+    const apiSecret = process.env.FINHAY_API_SECRET;
+    const baseUrl = process.env.FINHAY_BASE_URL || 'https://open-api.fhsc.com.vn';
+    if (!apiKey || !apiSecret) {
+        console.error(`Error: FINHAY_API_KEY and FINHAY_API_SECRET are required.`);
+        console.error(`Run "npx @finhay/mcp-server --install" to set up credentials.`);
+        console.error(`Or create ${CREDENTIALS_PATH} manually.`);
+        process.exit(1);
+    }
+    return { apiKey, apiSecret, baseUrl };
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Route to installer if --install flag is passed
+if (process.argv.includes('--install')) {
+    const { run } = await import('./install.js');
+    await run;
+    process.exit(0);
+}
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { getConfig } from './config/environment.js';
+import { FinhayClient } from './client/FinhayClient.js';
+import { AccountContext } from './client/AccountContext.js';
+import { registerAllTools } from './tools/index.js';
+const config = getConfig();
+const client = new FinhayClient(config.baseUrl, config.apiKey, config.apiSecret);
+const account = new AccountContext(client);
+await account.init();
+const server = new McpServer({
+    name: 'finhay-mcp-server',
+    version: '1.0.0',
+});
+registerAllTools(server, client, account);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[finhay-mcp] Server started, connected via stdio');

package/dist/install.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare const run: Promise<void>;

package/dist/install.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const CREDENTIALS_PATH = path.join(os.homedir(), '.finhay', 'credentials', '.env');
+function ask(question) {
+    process.stdout.write(question);
+    return new Promise((resolve) => {
+        let buf = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.resume();
+        const onData = (chunk) => {
+            buf += chunk;
+            if (buf.includes('\n')) {
+                process.stdin.pause();
+                process.stdin.removeListener('data', onData);
+                resolve(buf.replace('\n', '').trim());
+            }
+        };
+        process.stdin.on('data', onData);
+    });
+}
+function askMasked(question) {
+    process.stdout.write(question);
+    if (!process.stdin.isTTY)
+        return ask('');
+    return new Promise((resolve) => {
+        process.stdin.setRawMode(true);
+        process.stdin.setEncoding('utf8');
+        process.stdin.resume();
+        let input = '';
+        const onData = (ch) => {
+            if (ch === '\r' || ch === '\n') {
+                process.stdin.setRawMode(false);
+                process.stdin.pause();
+                process.stdin.removeListener('data', onData);
+                process.stdout.write('\n');
+                resolve(input.trim());
+            }
+            else if (ch === '\u007F' || ch === '\b') {
+                if (input.length > 0) {
+                    input = input.slice(0, -1);
+                    process.stdout.write('\b \b');
+                }
+            }
+            else if (ch === '\u0003') {
+                process.stdout.write('\n');
+                process.exit(0);
+            }
+            else {
+                input += ch;
+                process.stdout.write('*');
+            }
+        };
+        process.stdin.on('data', onData);
+    });
+}
+function getClaudeConfigPath() {
+    const platform = os.platform();
+    if (platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    }
+    else if (platform === 'win32') {
+        return path.join(process.env.APPDATA || '', 'Claude', 'claude_desktop_config.json');
+    }
+    else {
+        return path.join(os.homedir(), '.config', 'Claude', 'claude_desktop_config.json');
+    }
+}
+function upsertEnvFile(filePath, vars) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    let lines = [];
+    if (fs.existsSync(filePath)) {
+        lines = fs.readFileSync(filePath, 'utf-8').split('\n');
+    }
+    const written = new Set();
+    const updatedLines = lines.map((line) => {
+        const match = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=/);
+        if (match && match[1] in vars) {
+            written.add(match[1]);
+            return `${match[1]}=${vars[match[1]]}`;
+        }
+        return line;
+    });
+    for (const [key, value] of Object.entries(vars)) {
+        if (!written.has(key)) {
+            updatedLines.push(`${key}=${value}`);
+        }
+    }
+    const content = updatedLines.filter((l) => l !== '').join('\n') + '\n';
+    fs.writeFileSync(filePath, content, { mode: 0o600 });
+}
+function updateClaudeConfig() {
+    const configPath = getClaudeConfigPath();
+    const configDir = path.dirname(configPath);
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            console.log(`  Canh bao: Khong doc duoc ${configPath}, se tao file moi.`);
+        }
+    }
+    if (!config.mcpServers) {
+        config.mcpServers = {};
+    }
+    config.mcpServers.finhay = {
+        command: 'npx',
+        args: ['-y', 'finhay-mcp-server'],
+    };
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    console.log(`  Claude Desktop config: ${configPath}`);
+}
+async function main() {
+    console.log('\n  Finhay MCP Server — Cai dat cho Claude Desktop\n');
+    console.log('  Tao API Key tai: https://www.finhay.com.vn/finhay-skills\n');
+    let apiKey = '';
+    let apiSecret = '';
+    if (fs.existsSync(CREDENTIALS_PATH)) {
+        const content = fs.readFileSync(CREDENTIALS_PATH, 'utf-8');
+        const keyMatch = content.match(/FINHAY_API_KEY=(.+)/);
+        const secretMatch = content.match(/FINHAY_API_SECRET=(.+)/);
+        if (keyMatch && secretMatch) {
+            const maskedKey = keyMatch[1].trim().slice(0, 8) + '***';
+            console.log(`  Tim thay credentials tai ${CREDENTIALS_PATH}`);
+            console.log(`  API Key: ${maskedKey}\n`);
+            const reuse = await ask('  Su dung credentials nay? (Y/n): ');
+            if (reuse.toLowerCase() !== 'n') {
+                apiKey = keyMatch[1].trim();
+                apiSecret = secretMatch[1].trim();
+            }
+            console.log();
+        }
+    }
+    if (!apiKey) {
+        apiKey = await ask('  API Key: ');
+        if (!apiKey) {
+            console.error('\n  Loi: API Key khong duoc de trong.\n');
+            process.exit(1);
+        }
+        apiSecret = await askMasked('  API Secret: ');
+        if (!apiSecret) {
+            console.error('\n  Loi: API Secret khong duoc de trong.\n');
+            process.exit(1);
+        }
+        upsertEnvFile(CREDENTIALS_PATH, {
+            FINHAY_API_KEY: apiKey,
+            FINHAY_API_SECRET: apiSecret,
+            FINHAY_BASE_URL: 'https://open-api.fhsc.com.vn',
+        });
+        console.log(`\n  Credentials: ${CREDENTIALS_PATH} (permission: 600)\n`);
+    }
+    updateClaudeConfig();
+    console.log('\n  Da cai dat thanh cong!');
+    console.log('  Hay khoi dong lai Claude Desktop de su dung.\n');
+}
+export const run = main().catch((err) => {
+    console.error('Loi:', err.message);
+    process.exit(1);
+});

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FinhayClient } from '../client/FinhayClient.js';
+import { AccountContext } from '../client/AccountContext.js';
+export declare function registerAllTools(server: McpServer, client: FinhayClient, account: AccountContext): void;

package/dist/tools/index.js

@@ -0,0 +1,6 @@
+import { registerMarketTools } from './market.js';
+import { registerPortfolioTools } from './portfolio.js';
+export function registerAllTools(server, client, account) {
+    registerMarketTools(server, client); // 18 tools: stock, funds, gold, silver, crypto, macro, etc.
+    registerPortfolioTools(server, client, account); // 11 tools: account, portfolio, orders, pnl, rights, etc.
+}

package/dist/tools/market.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FinhayClient } from '../client/FinhayClient.js';
+export declare function registerMarketTools(server: McpServer, client: FinhayClient): void;

package/dist/tools/market.js

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import { safeHandler } from '../utils/safeTool.js';
+export function registerMarketTools(server, client) {
+    // --- Stock realtime ---
+    server.tool('get_stock_realtime', 'Get realtime stock price. Use ONE of: symbol (single), symbols (multiple, comma-separated), or exchange (HOSE/HNX/UPCOM)', {
+        symbol: z.string().optional().describe('Single stock symbol (e.g., VNM)'),
+        symbols: z.string().optional().describe('Comma-separated symbols (e.g., VNM,FPT,VIC)'),
+        exchange: z.string().optional().describe('Exchange code: HOSE, HNX, or UPCOM'),
+    }, safeHandler(async ({ symbol, symbols, exchange }) => {
+        const query = {};
+        if (symbol)
+            query.symbol = symbol.toUpperCase();
+        else if (symbols)
+            query.symbols = symbols.toUpperCase();
+        else if (exchange)
+            query.exchange = exchange.toUpperCase();
+        const data = await client.get('/market/stock-realtime', query);
+        return JSON.stringify(data.result, null, 2);
+    }));
+    // --- Price history chart ---
+    server.tool('get_price_history_chart', 'Get OHLCV price history chart for a stock. Timestamps must be Unix seconds (not milliseconds).', {
+        symbol: z.string().describe('Stock symbol (e.g., FPT)'),
+        resolution: z.string().optional().describe('Resolution, only "1D" supported').default('1D'),
+        from: z.number().describe('Start timestamp in Unix SECONDS'),
+        to: z.number().describe('End timestamp in Unix SECONDS'),
+    }, safeHandler(async ({ symbol, resolution, from, to }) => {
+        const data = await client.get('/market/price-histories-chart', {
+            symbol: symbol.toUpperCase(),
+            resolution: resolution || '1D',
+            from: String(from),
+            to: String(to),
+        });
+        return JSON.stringify(data.data, null, 2);
+    }));
+    // --- Recommendation reports ---
+    server.tool('get_recommendation_reports', 'Get analyst recommendation reports for a stock symbol', { symbol: z.string().describe('Stock symbol (e.g., VNM)') }, safeHandler(async ({ symbol }) => {
+        const data = await client.get(`/market/recommendation-reports/${symbol.toUpperCase()}`);
+        return JSON.stringify(data.data, null, 2);
+    }));
+    // --- Funds ---
+    server.tool('get_funds', 'Get list of all available investment funds with performance data', {}, safeHandler(async () => {
+        const data = await client.get('/market/funds');
+        return JSON.stringify(data.data, null, 2);
+    }));
+    server.tool('get_fund_portfolio', 'Get portfolio composition of a specific fund', {
+        fund: z.string().describe('Fund code (e.g., DCDS)'),
+        month: z.string().optional().describe('Month in YYYY-MM format (defaults to latest)'),
+    }, safeHandler(async ({ fund, month }) => {
+        const query = {};
+        if (month)
+            query.month = month;
+        const data = await client.get(`/market/funds/${fund}/portfolio`, query);
+        return JSON.stringify(data.data, null, 2);
+    }));
+    server.tool('get_fund_months', 'Get available months for a fund portfolio', { fund: z.string().describe('Fund code (e.g., DCDS)') }, safeHandler(async ({ fund }) => {
+        const data = await client.get(`/market/funds/${fund}/months`);
+        return JSON.stringify(data.data, null, 2);
+    }));
+    // --- Gold ---
+    server.tool('get_gold_prices', 'Get current gold prices from Vietnamese providers (SJC, DOJI, PNJ, BTMC)', {}, safeHandler(async () => {
+        const data = await client.get('/market/financial-data/gold');
+        return JSON.stringify(data.data, null, 2);
+    }));
+    server.tool('get_gold_chart', 'Get gold price chart data over a number of days', { days: z.number().optional().describe('Number of days (default: 30)').default(30) }, safeHandler(async ({ days }) => {
+        const data = await client.get('/market/financial-data/gold-chart', { days: String(days) });
+        return JSON.stringify(data.data, null, 2);
+    }));
+    server.tool('get_gold_providers', 'Get gold prices grouped by provider (PNJ, DOJI, BTMC, SJC)', {}, safeHandler(async () => {
+        const data = await client.get('/market/financial-data/gold-providers');
+        return JSON.stringify(data.data, null, 2);
+    }));
+    // --- Silver ---
+    server.tool('get_silver_prices', 'Get current silver prices', {}, safeHandler(async () => {
+        const data = await client.get('/market/financial-data/silver');
+        return JSON.stringify(data.data, null, 2);
+    }));
+    server.tool('get_silver_chart', 'Get silver price chart data over a number of days', { days: z.number().optional().describe('Number of days (default: 30)').default(30) }, safeHandler(async ({ days }) => {
+        const data = await client.get('/market/financial-data/silver-chart', { days: String(days) });
+        return JSON.stringify(data.data, null, 2);
+    }));
+    // --- Financial data ---
+    server.tool('get_all_financial_data', 'Get all financial data: gold, silver, crypto, bank rates, USD exchange rate', {}, safeHandler(async () => {
+        const data = await client.get('/market/financial-data');
+        return JSON.stringify(data.data, null, 2);
+    }));
+    server.tool('get_bank_interest_rates', 'Get bank deposit interest rates from Vietnamese banks', {}, safeHandler(async () => {
+        const data = await client.get('/market/financial-data/bank-interest-rates');
+        return JSON.stringify(data.data, null, 2);
+    }));
+    server.tool('get_crypto_top_trending', 'Get top trending cryptocurrencies with price, market cap, and 30-day chart', {}, safeHandler(async () => {
+        const data = await client.get('/market/financial-data/cryptos/top-trending');
+        return JSON.stringify(data.data, null, 2);
+    }));
+    // --- Macro ---
+    server.tool('get_macro_data', 'Get macroeconomic indicators for Vietnam or US (CPI, PMI, IIP, FED rate, etc.)', {
+        type: z.enum([
+            'IIP', 'CPI', 'PMI', 'PCE', 'CORE_PCE', 'NFP', 'GOODS_RETAIL', 'SERVICE_RETAIL',
+            'TOTAL_EXPORT', 'FDI_EXPORT', 'DOMESTIC_EXPORT', 'FED_FUNDS_RATE', 'INTERBANK_RATE',
+            'GOVERNMENT_10Y_BOND_YIELD', 'UNEMPLOYMENT_RATE',
+        ]).describe('Macro indicator type'),
+        country: z.enum(['VN', 'US']).describe('Country code'),
+        period: z.enum(['ONE_MONTH', 'ONE_YEAR', 'YTD']).optional().describe('Time period filter'),
+    }, safeHandler(async ({ type, country, period }) => {
+        const query = { type, country };
+        if (period)
+            query.period = period;
+        const data = await client.get('/market/financial-data/macro', query);
+        return JSON.stringify(data.data, null, 2);
+    }));
+    // --- Market session ---
+    server.tool('get_market_session', 'Get current market session status and available order types for an exchange', {
+        exchange: z.enum(['HOSE', 'HNX', 'UPCOM', 'HCX']).describe('Exchange code'),
+    }, safeHandler(async ({ exchange }) => {
+        const data = await client.get('/trading/market/session', { exchange });
+        return JSON.stringify(data.result, null, 2);
+    }));
+}

package/dist/tools/portfolio.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FinhayClient } from '../client/FinhayClient.js';
+import { AccountContext } from '../client/AccountContext.js';
+export declare function registerPortfolioTools(server: McpServer, client: FinhayClient, account: AccountContext): void;

package/dist/tools/portfolio.js

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { safeHandler } from '../utils/safeTool.js';
+export function registerPortfolioTools(server, client, account) {
+    // --- Owner ---
+    server.tool('get_owner_info', 'Get owner identity info (name, accounts, sub-account IDs, etc.)', {}, safeHandler(async () => {
+        const data = await client.get('/users/v1/users/me');
+        return JSON.stringify(data.result, null, 2);
+    }));
+    // --- Account summary ---
+    server.tool('get_account_summary', 'Get account balance summary: cash, securities value, margin, net asset value', {
+        subAccountId: z.string().optional().describe('Sub-account ID (auto-detected if omitted)'),
+    }, safeHandler(async ({ subAccountId }) => {
+        const id = account.resolveSubAccountId(subAccountId);
+        const data = await client.get(`/trading/accounts/${id}/summary`);
+        return JSON.stringify(data.result, null, 2);
+    }));
+    // --- Asset summary ---
+    server.tool('get_asset_summary', 'Get asset summary with total valuation', {
+        subAccountId: z.string().optional().describe('Sub-account ID (auto-detected if omitted)'),
+    }, safeHandler(async ({ subAccountId }) => {
+        const id = account.resolveSubAccountId(subAccountId);
+        const data = await client.get(`/trading/sub-accounts/${id}/asset-summary`);
+        return JSON.stringify(data.data, null, 2);
+    }));
+    // --- Portfolio ---
+    server.tool('get_portfolio', 'Get portfolio positions with P/L, cost basis, available quantity per stock', {
+        subAccountId: z.string().optional().describe('Sub-account ID (auto-detected if omitted)'),
+    }, safeHandler(async ({ subAccountId }) => {
+        const id = account.resolveSubAccountId(subAccountId);
+        const data = await client.get(`/trading/v2/sub-accounts/${id}/portfolio`);
+        return JSON.stringify(data.data, null, 2);
+    }));
+    // --- PnL today ---
+    server.tool('get_pnl_today', 'Get today profit/loss amount and rate', {
+        userId: z.string().optional().describe('User ID (auto-detected if omitted)'),
+        subAccountId: z.string().optional().describe('Sub-account ID (default: ALL)'),
+    }, safeHandler(async ({ userId, subAccountId }) => {
+        const uid = account.resolveUserId(userId);
+        const query = {};
+        if (subAccountId)
+            query['sub-account-id'] = subAccountId;
+        const data = await client.get(`/trading/pnl-today/${uid}`, query);
+        return JSON.stringify(data.data, null, 2);
+    }));
+    // --- Order history ---
+    server.tool('get_order_history', 'Get order history for a sub-account within a date range', {
+        subAccountId: z.string().optional().describe('Sub-account ID (auto-detected if omitted)'),
+        fromDate: z.string().describe('Start date (YYYY-MM-DD)'),
+        toDate: z.string().describe('End date (YYYY-MM-DD)'),
+        page: z.number().optional().describe('Page number (default: 1)'),
+        orderStatus: z.string().optional().describe('Filter by status (default: ALL)'),
+        symbol: z.string().optional().describe('Filter by symbol (default: ALL)'),
+    }, safeHandler(async ({ subAccountId, fromDate, toDate, page, orderStatus, symbol }) => {
+        const id = account.resolveSubAccountId(subAccountId);
+        const query = { fromDate, toDate };
+        if (page)
+            query.page = String(page);
+        if (orderStatus)
+            query.orderStatus = orderStatus;
+        if (symbol)
+            query.symbol = symbol.toUpperCase();
+        const data = await client.get(`/trading/sub-accounts/${id}/orders`, query);
+        return JSON.stringify(data.result, null, 2);
+    }));
+    // --- Order book (intraday) ---
+    server.tool('get_order_book', 'Get intraday order book (today pending/matched orders)', {
+        subAccountId: z.string().optional().describe('Sub-account ID (auto-detected if omitted)'),
+    }, safeHandler(async ({ subAccountId }) => {
+        const id = account.resolveSubAccountId(subAccountId);
+        const data = await client.get(`/trading/v1/accounts/${id}/order-book`);
+        return JSON.stringify(data.result, null, 2);
+    }));
+    // --- Order detail ---
+    server.tool('get_order_detail', 'Get detail of a specific order by ID', {
+        subAccountId: z.string().optional().describe('Sub-account ID (auto-detected if omitted)'),
+        orderId: z.string().describe('Order ID'),
+    }, safeHandler(async ({ subAccountId, orderId }) => {
+        const id = account.resolveSubAccountId(subAccountId);
+        const data = await client.get(`/trading/v1/accounts/${id}/order-book/${orderId}`);
+        return JSON.stringify(data.data, null, 2);
+    }));
+    // --- User rights (corporate actions) ---
+    server.tool('get_user_rights', 'Get corporate actions: dividends, stock rights, meetings, etc.', {
+        subAccountId: z.string().optional().describe('Sub-account ID (auto-detected if omitted)'),
+        fromDate: z.string().optional().describe('Start date (YYYY-MM-DD)'),
+        toDate: z.string().optional().describe('End date (YYYY-MM-DD)'),
+        catType: z.string().optional().describe('Category type, comma-separated or ALL (default: ALL)'),
+        symbol: z.string().optional().describe('Filter by symbol (default: ALL)'),
+        status: z.string().optional().describe('Status filter, comma-separated or ALL (default: ALL)'),
+    }, safeHandler(async ({ subAccountId, fromDate, toDate, catType, symbol, status }) => {
+        const id = account.resolveSubAccountId(subAccountId);
+        const query = {};
+        if (fromDate)
+            query.fromDate = fromDate;
+        if (toDate)
+            query.toDate = toDate;
+        if (catType)
+            query.catType = catType;
+        if (symbol)
+            query.symbol = symbol.toUpperCase();
+        if (status)
+            query.status = status;
+        const data = await client.get(`/trading/v5/account/${id}/user-rights`, query);
+        return JSON.stringify(data.result, null, 2);
+    }));
+    // --- Trade info (pre-order check) ---
+    server.tool('get_trade_info', 'Get buying power (BUY) or available quantity (SELL) before placing an order', {
+        subAccountId: z.string().optional().describe('Sub-account ID (auto-detected if omitted)'),
+        symbol: z.string().describe('Stock symbol'),
+        side: z.enum(['BUY', 'SELL']).describe('Order side'),
+        quotePrice: z.number().describe('Quote price in VND'),
+    }, safeHandler(async ({ subAccountId, symbol, side, quotePrice }) => {
+        const id = account.resolveSubAccountId(subAccountId);
+        const data = await client.get(`/trading/sub-accounts/${id}/trade-info`, {
+            symbol: symbol.toUpperCase(),
+            side,
+            quote_price: String(quotePrice),
+        });
+        return JSON.stringify(data.result, null, 2);
+    }));
+}

package/dist/utils/formatter.d.ts

@@ -0,0 +1,3 @@
+export declare function formatVND(amount: number): string;
+export declare function formatVolume(vol: number): string;
+export declare function formatPercent(pct: number): string;

package/dist/utils/formatter.js

@@ -0,0 +1,14 @@
+const vndFmt = new Intl.NumberFormat('vi-VN');
+export function formatVND(amount) {
+    return vndFmt.format(amount) + 'đ';
+}
+export function formatVolume(vol) {
+    if (vol >= 1_000_000)
+        return (vol / 1_000_000).toFixed(1) + 'M';
+    if (vol >= 1_000)
+        return (vol / 1_000).toFixed(0) + 'K';
+    return String(vol);
+}
+export function formatPercent(pct) {
+    return (pct > 0 ? '+' : '') + pct.toFixed(2) + '%';
+}

package/dist/utils/safeTool.d.ts

@@ -0,0 +1,13 @@
+type ToolResult = {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError?: true;
+};
+/**
+ * Wraps an async handler so that errors are caught and returned
+ * as MCP error responses instead of crashing the server.
+ */
+export declare function safeHandler<T>(fn: (args: T) => Promise<string>): (args: T) => Promise<ToolResult>;
+export {};

package/dist/utils/safeTool.js

@@ -0,0 +1,29 @@
+import axios from 'axios';
+/**
+ * Wraps an async handler so that errors are caught and returned
+ * as MCP error responses instead of crashing the server.
+ */
+export function safeHandler(fn) {
+    return async (args) => {
+        try {
+            const text = await fn(args);
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (err) {
+            const message = formatError(err);
+            return { content: [{ type: 'text', text: message }], isError: true };
+        }
+    };
+}
+function formatError(err) {
+    if (axios.isAxiosError(err)) {
+        const status = err.response?.status;
+        const body = err.response?.data;
+        const detail = typeof body === 'object' ? JSON.stringify(body, null, 2) : String(body ?? '');
+        return `API error ${status ?? 'NETWORK'}: ${err.message}${detail ? `\n${detail}` : ''}`;
+    }
+    if (err instanceof Error) {
+        return `Error: ${err.message}`;
+    }
+    return `Error: ${String(err)}`;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "finhay-mcp-server",
+  "version": "1.0.2",
+  "description": "Finhay MCP Server — xem gia co phieu, danh muc dau tu qua Claude AI",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/finhay/mcp-server.git"
+  },
+  "keywords": [
+    "mcp",
+    "finhay",
+    "stock",
+    "vietnam",
+    "claude",
+    "ai"
+  ],
+  "bin": {
+    "finhay-mcp-server": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "axios": "^1.7.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.19.130",
+    "typescript": "^5.5.0",
+    "vitest": "^1.6.1"
+  },
+  "files": [
+    "dist",
+    "!dist/__tests__",
+    "!dist/install.js.map"
+  ]
+}