finhay-mcp-server 1.0.7 → 1.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.en.md +131 -0
  2. package/README.md +67 -73
  3. package/dist/tools/index.js +2 -2
  4. package/package.json +2 -1
package/README.en.md ADDED
@@ -0,0 +1,131 @@
1
+ # finhay-mcp-server
2
+
3
+ <!-- mcp-name: io.github.finhay/mcp-server -->
4
+
5
+ [Tiếng Việt](README.md) | [English](README.en.md)
6
+
7
+ MCP Server for Finhay Securities — view stock prices, portfolio, gold, crypto via Claude AI.
8
+
9
+ ## Installation
10
+
11
+ ### Step 1: Create API Key
12
+
13
+ Go to [https://www.finhay.com.vn/finhay-skills](https://www.finhay.com.vn/finhay-skills) → Login → Create API Key.
14
+
15
+ You will receive:
16
+ - **API Key**: `ak_live_xxx`
17
+ - **API Secret**: `sk_live_yyy`
18
+
19
+ ### Step 2: Connect to Claude
20
+
21
+ Choose **one of three** methods below:
22
+
23
+ #### Method 1: Automatic install (no Node.js required — Recommended)
24
+
25
+ Open Terminal (macOS) or PowerShell (Windows), paste this command and press Enter:
26
+
27
+ **macOS:**
28
+ ```bash
29
+ curl -fsSL https://raw.githubusercontent.com/finhay/mcp-server/main/install.sh | bash
30
+ ```
31
+
32
+ **Windows (PowerShell):**
33
+ ```powershell
34
+ irm https://raw.githubusercontent.com/finhay/mcp-server/main/install.ps1 | iex
35
+ ```
36
+
37
+ The script will auto-install Node.js (if needed), prompt for API Key/Secret, and configure Claude Desktop.
38
+
39
+ #### Method 2: Quick install (Node.js required)
40
+
41
+ If you already have Node.js (>= 18), run:
42
+
43
+ ```bash
44
+ npx -y finhay-mcp-server --install
45
+ ```
46
+
47
+ The script will prompt for API Key/Secret (Secret is masked with `*`), then automatically write the config to Claude Desktop.
48
+
49
+ #### Method 3: Manual configuration
50
+
51
+ **Step 3a.** Create credentials file at `~/.finhay/credentials/.env`:
52
+
53
+ ```
54
+ FINHAY_API_KEY=ak_live_xxx
55
+ FINHAY_API_SECRET=sk_live_yyy
56
+ ```
57
+
58
+ **Step 3b.** Add to Claude Desktop config:
59
+ - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
60
+ - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
61
+ - Windows (Microsoft Store): `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`
62
+
63
+ ```json
64
+ {
65
+ "mcpServers": {
66
+ "finhay": {
67
+ "command": "npx",
68
+ "args": ["-y", "finhay-mcp-server"]
69
+ }
70
+ }
71
+ }
72
+ ```
73
+
74
+ > API Key/Secret are **not stored** in Claude config — they live separately at `~/.finhay/credentials/.env` (shared with Finhay Skills).
75
+
76
+ Restart Claude Desktop after setup.
77
+
78
+ ### Step 3: Usage
79
+
80
+ Open Claude and ask:
81
+
82
+ - "What's VNM stock price today?"
83
+ - "Show my investment portfolio"
84
+ - "Compare FPT and VNM"
85
+ - "What's SJC gold price today?"
86
+ - "Which bank has the highest savings rate?"
87
+ - "Recent Vietnam CPI index?"
88
+
89
+ ## Tools
90
+
91
+ ### Market data (16 tools)
92
+
93
+ | Tool | Description |
94
+ |------|-------------|
95
+ | `get_stock_realtime` | Realtime stock prices (single, multiple, or by exchange) |
96
+ | `get_price_history_chart` | OHLCV price history |
97
+ | `get_recommendation_reports` | Analyst recommendation reports |
98
+ | `get_funds` | List of investment funds |
99
+ | `get_fund_portfolio` | Fund portfolio composition |
100
+ | `get_fund_months` | Available months for fund data |
101
+ | `get_gold_prices` | Gold prices (SJC, DOJI, PNJ, BTMC) |
102
+ | `get_gold_chart` | Gold price chart |
103
+ | `get_gold_providers` | Gold prices by provider |
104
+ | `get_silver_prices` | Silver prices |
105
+ | `get_silver_chart` | Silver price chart |
106
+ | `get_all_financial_data` | All-in-one: gold, silver, crypto, rates, FX |
107
+ | `get_bank_interest_rates` | Bank savings interest rates |
108
+ | `get_crypto_top_trending` | Top trending cryptocurrencies |
109
+ | `get_macro_data` | Macro indicators (CPI, PMI, IIP, FED rate...) |
110
+ | `get_market_session` | Trading session status |
111
+
112
+ ### Account (10 tools)
113
+
114
+ | Tool | Description |
115
+ |------|-------------|
116
+ | `get_owner_info` | Account owner info |
117
+ | `get_account_summary` | Balance: cash, securities, margin |
118
+ | `get_asset_summary` | Total assets |
119
+ | `get_portfolio` | Stock portfolio with P/L |
120
+ | `get_pnl_today` | Today's profit/loss |
121
+ | `get_order_history` | Order history |
122
+ | `get_order_book` | Today's order book |
123
+ | `get_order_detail` | Single order detail |
124
+ | `get_user_rights` | Shareholder rights: dividends, rights issues... |
125
+ | `get_trade_info` | Buying power / sellable quantity |
126
+
127
+
128
+ ## Requirements
129
+
130
+ - Node.js >= 18
131
+ - Finhay Securities account with API Key
package/README.md CHANGED
@@ -1,67 +1,61 @@
1
1
  # finhay-mcp-server
2
2
 
3
- MCP Server cho Finhay Securities — xem gia co phieu, danh muc dau tu, vang, crypto qua Claude AI.
3
+ <!-- mcp-name: io.github.finhay/mcp-server -->
4
4
 
5
- ## Cai dat
5
+ [Tiếng Việt](README.md) | [English](README.en.md)
6
6
 
7
- ### Buoc 1: Tao API Key
7
+ MCP Server cho Finhay Securities — xem giá cổ phiếu, danh mục đầu tư, vàng, crypto qua Claude AI.
8
8
 
9
- Vao [https://www.finhay.com.vn/finhay-skills](https://www.finhay.com.vn/finhay-skills) → Dang nhap → Tao API Key.
9
+ ## Cài đặt
10
10
 
11
- Ban se nhan duoc:
12
- - **API Key**: `ak_live_xxx`
13
- - **API Secret**: `sk_live_yyy`
14
-
15
- ### Buoc 2: Ket noi voi Claude
11
+ ### Bước 1: Tạo API Key
16
12
 
17
- Chon **mot trong bon** cach sau:
13
+ Vào [https://www.finhay.com.vn/finhay-skills](https://www.finhay.com.vn/finhay-skills) → Đăng nhập → Tạo API Key.
18
14
 
19
- #### Cach 1: Cai dat nhanh (can Node.js)
20
-
21
- Neu ban da co Node.js (>= 18), chay lenh sau:
15
+ Bạn sẽ nhận được:
16
+ - **API Key**: `ak_live_xxx`
17
+ - **API Secret**: `sk_live_yyy`
22
18
 
23
- ```bash
24
- npx -y finhay-mcp-server --install
25
- ```
19
+ ### Bước 2: Kết nối với Claude
26
20
 
27
- Script se hoi API Key/Secret (Secret duoc an bang dau `*`), tu dong ghi config vao Claude Desktop.
21
+ Chọn **một trong ba** cách sau:
28
22
 
29
- #### Cach 2: Cai dat tu dong (khong can Node.js)
23
+ #### Cách 1: Cài đặt tự động (không cần Node.js — khuyên dùng)
30
24
 
31
- Mo Terminal (macOS) hoac PowerShell (Windows), dan lenh sau va nhan Enter:
25
+ Mở Terminal (macOS) hoặc PowerShell (Windows), dán lệnh sau và nhấn Enter:
32
26
 
33
27
  **macOS:**
34
28
  ```bash
35
- curl -fsSL https://raw.githubusercontent.com/finhay-pro/finhay-skills-hub/main/skills/_shared/scripts/mcp/install.sh | bash
29
+ curl -fsSL https://raw.githubusercontent.com/finhay/mcp-server/main/install.sh | bash
36
30
  ```
37
31
 
38
32
  **Windows (PowerShell):**
39
33
  ```powershell
40
- irm https://raw.githubusercontent.com/finhay-pro/finhay-skills-hub/main/skills/_shared/scripts/mcp/install.ps1 | iex
34
+ irm https://raw.githubusercontent.com/finhay/mcp-server/main/install.ps1 | iex
41
35
  ```
42
36
 
43
- Script se tu dong cai Node.js (neu chua co), hoi API Key/Secret, va cau hinh Claude Desktop.
37
+ Script sẽ tự động cài Node.js (nếu chưa có), hỏi API Key/Secret, và cấu hình Claude Desktop.
44
38
 
45
- #### Cach 3: Claude Code CLI
39
+ #### Cách 2: Cài đặt nhanh (cần Node.js)
46
40
 
47
- Neu ban da cai [Claude Code](https://docs.anthropic.com/en/docs/claude-code) va muon su dung trong terminal:
41
+ Nếu bạn đã có Node.js (>= 18), chạy lệnh sau:
48
42
 
49
43
  ```bash
50
- claude mcp add finhay -- npx -y finhay-mcp-server
44
+ npx -y finhay-mcp-server --install
51
45
  ```
52
46
 
53
- > Luu y: Cach nay chi them MCP server vao Claude Code CLI, **khong dong bo** sang Claude Desktop. Neu muon dung tren Claude Desktop, hay dung Cach 1, 2 hoac 4.
47
+ Script sẽ hỏi API Key/Secret (Secret được ẩn bằng dấu `*`), tự động ghi config vào Claude Desktop.
54
48
 
55
- #### Cach 4: Cau hinh thu cong
49
+ #### Cách 3: Cấu hình thủ công
56
50
 
57
- **Buoc 3a.** Tao file credentials tai `~/.finhay/credentials/.env`:
51
+ **Bước 3a.** Tạo file credentials tại `~/.finhay/credentials/.env`:
58
52
 
59
53
  ```
60
54
  FINHAY_API_KEY=ak_live_xxx
61
55
  FINHAY_API_SECRET=sk_live_yyy
62
56
  ```
63
57
 
64
- **Buoc 3b.** Them vao file config Claude Desktop:
58
+ **Bước 3b.** Thêm vào file config Claude Desktop:
65
59
  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
66
60
  - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
67
61
  - Windows (Microsoft Store): `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`
@@ -77,61 +71,61 @@ FINHAY_API_SECRET=sk_live_yyy
77
71
  }
78
72
  ```
79
73
 
80
- > API Key/Secret **khong nam** trong file config Claude — duoc luu rieng tai `~/.finhay/credentials/.env` (dung chung voi Finhay Skills).
74
+ > API Key/Secret **không nằm** trong file config Claude — được lưu riêng tại `~/.finhay/credentials/.env` (dùng chung với Finhay Skills).
81
75
 
82
- Sau khi hoan tat, khoi dong lai Claude Desktop la xong.
76
+ Sau khi hoàn tất, khởi động lại Claude Desktop là xong.
83
77
 
84
- ### Buoc 3: Su dung
78
+ ### Bước 3: Sử dụng
85
79
 
86
- Mo Claude, hoi:
80
+ Mở Claude, hỏi:
87
81
 
88
- - "Gia co phieu VNM hom nay?"
89
- - "Xem danh muc dau tu cua toi"
90
- - "So sanh FPT va VNM"
91
- - "Gia vang SJC hom nay bao nhieu?"
92
- - "Lai suat tiet kiem ngan hang nao cao nhat?"
93
- - "Chi so CPI Viet Nam gan day?"
82
+ - "Giá cổ phiếu VNM hôm nay?"
83
+ - "Xem danh mục đầu tư của tôi"
84
+ - "So sánh FPT và VNM"
85
+ - "Giá vàng SJC hôm nay bao nhiêu?"
86
+ - "Lãi suất tiết kiệm ngân hàng nào cao nhất?"
87
+ - "Chỉ số CPI Việt Nam gần đây?"
94
88
 
95
89
  ## Tools
96
90
 
97
- ### Thi truong (18 tools)
91
+ ### Thị trường (16 tools)
98
92
 
99
- | Tool | Mo ta |
93
+ | Tool | Mô tả |
100
94
  |------|-------|
101
- | `get_stock_realtime` | Gia co phieu realtime (1 ma, nhieu ma, hoac theo san) |
102
- | `get_price_history_chart` | Lich su gia OHLCV |
103
- | `get_recommendation_reports` | Bao cao phan tich tu chuyen gia |
104
- | `get_funds` | Danh sach quy dau tu |
105
- | `get_fund_portfolio` | Danh muc cua quy |
106
- | `get_fund_months` | Cac thang co du lieu quy |
107
- | `get_gold_prices` | Gia vang (SJC, DOJI, PNJ, BTMC) |
108
- | `get_gold_chart` | Bieu do gia vang |
109
- | `get_gold_providers` | Gia vang theo nha cung cap |
110
- | `get_silver_prices` | Gia bac |
111
- | `get_silver_chart` | Bieu do gia bac |
112
- | `get_all_financial_data` | Tong hop: vang, bac, crypto, lai suat, ty gia |
113
- | `get_bank_interest_rates` | Lai suat tiet kiem ngan hang |
114
- | `get_crypto_top_trending` | Crypto xu huong |
115
- | `get_macro_data` | Chi so vi mo (CPI, PMI, IIP, FED rate...) |
116
- | `get_market_session` | Trang thai phien giao dich |
117
-
118
- ### Tai khoan (11 tools)
119
-
120
- | Tool | Mo ta |
95
+ | `get_stock_realtime` | Giá cổ phiếu realtime (1 mã, nhiều mã, hoặc theo sàn) |
96
+ | `get_price_history_chart` | Lịch sử giá OHLCV |
97
+ | `get_recommendation_reports` | Báo cáo phân tích từ chuyên gia |
98
+ | `get_funds` | Danh sách quỹ đầu tư |
99
+ | `get_fund_portfolio` | Danh mục của quỹ |
100
+ | `get_fund_months` | Các tháng có dữ liệu quỹ |
101
+ | `get_gold_prices` | Giá vàng (SJC, DOJI, PNJ, BTMC) |
102
+ | `get_gold_chart` | Biểu đồ giá vàng |
103
+ | `get_gold_providers` | Giá vàng theo nhà cung cấp |
104
+ | `get_silver_prices` | Giá bạc |
105
+ | `get_silver_chart` | Biểu đồ giá bạc |
106
+ | `get_all_financial_data` | Tổng hợp: vàng, bạc, crypto, lãi suất, tỷ giá |
107
+ | `get_bank_interest_rates` | Lãi suất tiết kiệm ngân hàng |
108
+ | `get_crypto_top_trending` | Crypto xu hướng |
109
+ | `get_macro_data` | Chỉ số vĩ mô (CPI, PMI, IIP, FED rate...) |
110
+ | `get_market_session` | Trạng thái phiên giao dịch |
111
+
112
+ ### Tài khoản (10 tools)
113
+
114
+ | Tool | Mô tả |
121
115
  |------|-------|
122
- | `get_owner_info` | Thong tin chu tai khoan |
123
- | `get_account_summary` | So du: tien mat, chung khoan, ky quy |
124
- | `get_asset_summary` | Tong tai san |
125
- | `get_portfolio` | Danh muc co phieu voi lai/lo |
126
- | `get_pnl_today` | Lai/lo hom nay |
127
- | `get_order_history` | Lich su lenh |
128
- | `get_order_book` | So lenh trong ngay |
129
- | `get_order_detail` | Chi tiet 1 lenh |
130
- | `get_user_rights` | Quyen co dong: co tuc, quyen mua... |
131
- | `get_trade_info` | Suc mua / so luong ban duoc |
116
+ | `get_owner_info` | Thông tin chủ tài khoản |
117
+ | `get_account_summary` | Số dư: tiền mặt, chứng khoán, ký quỹ |
118
+ | `get_asset_summary` | Tổng tài sản |
119
+ | `get_portfolio` | Danh mục cổ phiếu với lãi/lỗ |
120
+ | `get_pnl_today` | Lãi/lỗ hôm nay |
121
+ | `get_order_history` | Lịch sử lệnh |
122
+ | `get_order_book` | Sổ lệnh trong ngày |
123
+ | `get_order_detail` | Chi tiết 1 lệnh |
124
+ | `get_user_rights` | Quyền cổ đông: cổ tức, quyền mua... |
125
+ | `get_trade_info` | Sức mua / số lượng bán được |
132
126
 
133
127
 
134
- ## Yeu cau
128
+ ## Yêu cầu
135
129
 
136
130
  - Node.js >= 18
137
- - Tai khoan Finhay Securities voi API Key
131
+ - Tài khoản Finhay Securities với API Key
package/dist/tools/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { registerMarketTools } from './market.js';
2
2
  import { registerPortfolioTools } from './portfolio.js';
3
3
  export function registerAllTools(server, client, account) {
4
- registerMarketTools(server, client); // 18 tools: stock, funds, gold, silver, crypto, macro, etc.
5
- registerPortfolioTools(server, client, account); // 11 tools: account, portfolio, orders, pnl, rights, etc.
4
+ registerMarketTools(server, client); // 16 tools: stock, funds, gold, silver, crypto, macro, etc.
5
+ registerPortfolioTools(server, client, account); // 10 tools: account, portfolio, orders, pnl, rights, etc.
6
6
  }
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "finhay-mcp-server",
3
- "version": "1.0.7",
3
+ "version": "1.0.8",
4
+ "mcpName": "io.github.finhay/mcp-server",
4
5
  "description": "Finhay MCP Server — xem gia co phieu, danh muc dau tu qua Claude AI",
5
6
  "type": "module",
6
7
  "license": "MIT",