tw-stock-mcp 0.1.1 → 0.1.3
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.
- package/README.md +4 -4
- package/build/core/institutional.js +11 -5
- package/build/core/resolve.js +26 -0
- package/build/core/trading-day.js +5 -0
- package/build/tools/get-institutional.js +21 -13
- package/build/tools/get-market-events.js +8 -3
- package/build/tools/get-quote.js +15 -2
- package/build/tools/shared.js +10 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -15,19 +15,19 @@ Requires Node.js 22 or later. Pin a version so an upstream change can never reac
|
|
|
15
15
|
**Claude Code**
|
|
16
16
|
|
|
17
17
|
```bash
|
|
18
|
-
claude mcp add tw-stock -- npx -y npm:tw-stock-mcp@0.1.
|
|
18
|
+
claude mcp add tw-stock -- npx -y npm:tw-stock-mcp@0.1.3
|
|
19
19
|
```
|
|
20
20
|
|
|
21
21
|
**Codex CLI**
|
|
22
22
|
|
|
23
23
|
```bash
|
|
24
|
-
codex mcp add tw-stock -- npx -y npm:tw-stock-mcp@0.1.
|
|
24
|
+
codex mcp add tw-stock -- npx -y npm:tw-stock-mcp@0.1.3
|
|
25
25
|
```
|
|
26
26
|
|
|
27
27
|
**VS Code**
|
|
28
28
|
|
|
29
29
|
```bash
|
|
30
|
-
code --add-mcp '{"name":"tw-stock","command":"npx","args":["-y","npm:tw-stock-mcp@0.1.
|
|
30
|
+
code --add-mcp '{"name":"tw-stock","command":"npx","args":["-y","npm:tw-stock-mcp@0.1.3"]}'
|
|
31
31
|
```
|
|
32
32
|
|
|
33
33
|
**Claude Desktop, Cursor and other clients** — add to the client's MCP config (`claude_desktop_config.json`, `~/.cursor/mcp.json`, …):
|
|
@@ -37,7 +37,7 @@ code --add-mcp '{"name":"tw-stock","command":"npx","args":["-y","npm:tw-stock-mc
|
|
|
37
37
|
"mcpServers": {
|
|
38
38
|
"tw-stock": {
|
|
39
39
|
"command": "npx",
|
|
40
|
-
"args": ["-y", "npm:tw-stock-mcp@0.1.
|
|
40
|
+
"args": ["-y", "npm:tw-stock-mcp@0.1.3"]
|
|
41
41
|
}
|
|
42
42
|
}
|
|
43
43
|
}
|
|
@@ -21,16 +21,17 @@ export function institutionalUrl(date, market) {
|
|
|
21
21
|
return `https://www.twse.com.tw/rwd/zh/fund/T86?${query}`;
|
|
22
22
|
}
|
|
23
23
|
export function summaryUrl(date) {
|
|
24
|
-
|
|
24
|
+
// BFI82U ignores `date`: it needs type=day and dayDate, or it silently answers with the latest day.
|
|
25
|
+
const query = new URLSearchParams({ type: 'day', dayDate: date.replaceAll('-', ''), response: 'json' });
|
|
25
26
|
return `https://www.twse.com.tw/rwd/zh/fund/BFI82U?${query}`;
|
|
26
27
|
}
|
|
27
|
-
/** Data rows, or null when the exchange has nothing for that date. */
|
|
28
|
+
/** Data rows, or null when the exchange has nothing for that date (no trading, or not published yet). */
|
|
28
29
|
function rowsOf(data) {
|
|
29
30
|
if (!data || typeof data !== 'object')
|
|
30
31
|
throw new Error('Invalid institutional response');
|
|
31
32
|
const response = data;
|
|
32
33
|
if (typeof response.stat === 'string' && response.stat.toLowerCase() !== 'ok') {
|
|
33
|
-
if (response.stat.includes('沒有符合條件'))
|
|
34
|
+
if (response.stat.includes('沒有符合條件') || response.stat.includes('大於可查詢最大日期'))
|
|
34
35
|
return null;
|
|
35
36
|
throw new Error(`Institutional data unavailable: ${response.stat}`);
|
|
36
37
|
}
|
|
@@ -74,10 +75,15 @@ const SUMMARY_LABELS = {
|
|
|
74
75
|
外資自營商: 'foreign_dealer',
|
|
75
76
|
合計: 'total',
|
|
76
77
|
};
|
|
77
|
-
|
|
78
|
+
/** `date` (YYYY-MM-DD) is the day asked for: an answer for any other day is refused rather than mislabelled. */
|
|
79
|
+
export function parseSummary(data, date) {
|
|
78
80
|
const rows = rowsOf(data);
|
|
79
81
|
if (!rows)
|
|
80
82
|
return null;
|
|
83
|
+
const answered = data.date;
|
|
84
|
+
if (date && typeof answered === 'string' && answered !== date.replaceAll('-', '')) {
|
|
85
|
+
throw new Error(`TWSE answered with the summary for ${answered} instead of ${date}`);
|
|
86
|
+
}
|
|
81
87
|
const summary = { market: 'tse', unit: 'TWD' };
|
|
82
88
|
for (const row of rows) {
|
|
83
89
|
const key = SUMMARY_LABELS[String(row[0]).trim()];
|
|
@@ -99,5 +105,5 @@ export function loadInstitutional(date, market, signal) {
|
|
|
99
105
|
}
|
|
100
106
|
export function loadSummary(date, signal) {
|
|
101
107
|
const url = summaryUrl(date);
|
|
102
|
-
return cache.get(url, date, async () => parseSummary(await requestJson(url, { signal })));
|
|
108
|
+
return cache.get(url, date, async () => parseSummary(await requestJson(url, { signal }), date));
|
|
103
109
|
}
|
package/build/core/resolve.js
CHANGED
|
@@ -1,6 +1,26 @@
|
|
|
1
1
|
import { normaliseCode } from './market.js';
|
|
2
2
|
import { DEFAULT_SECURITY_TYPES, getSecurities, rankSecurities, } from './securities.js';
|
|
3
3
|
const MAX_SUGGESTIONS = 5;
|
|
4
|
+
/**
|
|
5
|
+
* Where a code or exact name is listed when it is not on `market`: the listings
|
|
6
|
+
* on the other market, or none if it is on `market` after all, unknown, or the
|
|
7
|
+
* directory is unreachable. Best effort, for explaining an empty result.
|
|
8
|
+
*/
|
|
9
|
+
export async function listedElsewhere(input, market) {
|
|
10
|
+
const text = input.trim();
|
|
11
|
+
const code = normaliseCode(text);
|
|
12
|
+
let securities;
|
|
13
|
+
try {
|
|
14
|
+
securities = await getSecurities();
|
|
15
|
+
}
|
|
16
|
+
catch {
|
|
17
|
+
return [];
|
|
18
|
+
}
|
|
19
|
+
const matches = securities.filter((security) => (code ? security.code === code : security.name === text));
|
|
20
|
+
if (matches.some((security) => security.market === market))
|
|
21
|
+
return [];
|
|
22
|
+
return matches.slice(0, MAX_SUGGESTIONS);
|
|
23
|
+
}
|
|
4
24
|
/**
|
|
5
25
|
* Resolves a code ("2330", "2330.TW") or exact name ("台積電") to one security.
|
|
6
26
|
* When the directory is unreachable a code still resolves, with `market: null`,
|
|
@@ -32,6 +52,12 @@ export async function resolveSecurity(input, market) {
|
|
|
32
52
|
}
|
|
33
53
|
return { ok: false, reason: 'ambiguous_name', suggestions: matches.slice(0, MAX_SUGGESTIONS) };
|
|
34
54
|
}
|
|
55
|
+
if (market) {
|
|
56
|
+
const elsewhere = securities.filter((security) => (code ? security.code === code : security.name === text));
|
|
57
|
+
if (elsewhere.length) {
|
|
58
|
+
return { ok: false, reason: 'other_market', requested: market, suggestions: elsewhere.slice(0, MAX_SUGGESTIONS) };
|
|
59
|
+
}
|
|
60
|
+
}
|
|
35
61
|
const suggestions = rankSecurities(securities, code ?? text, {
|
|
36
62
|
market,
|
|
37
63
|
types: DEFAULT_SECURITY_TYPES,
|
|
@@ -19,6 +19,11 @@ export async function findTradingDay(requested, load) {
|
|
|
19
19
|
if (!isIsoDate(requested)) {
|
|
20
20
|
throw new Error(`date must be a real date in YYYY-MM-DD form, got "${requested}"`);
|
|
21
21
|
}
|
|
22
|
+
const today = taipeiToday();
|
|
23
|
+
if (requested > today) {
|
|
24
|
+
// Exchanges answer a future date with their own untranslated error; say it plainly instead.
|
|
25
|
+
throw new Error(`date ${requested} is in the future (today is ${today} in Taipei). Use today or an earlier date, or omit date for the latest trading day.`);
|
|
26
|
+
}
|
|
22
27
|
const data = await load(requested);
|
|
23
28
|
return data === null ? { date: null, tried: requested } : { date: requested, data, fellBack: false };
|
|
24
29
|
}
|
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
import { setTimeout as delay } from 'node:timers/promises';
|
|
2
2
|
import { loadInstitutional, loadSummary, } from '../core/institutional.js';
|
|
3
3
|
import { isIsoDate, normaliseCode } from '../core/market.js';
|
|
4
|
-
import { resolveSecurity } from '../core/resolve.js';
|
|
4
|
+
import { listedElsewhere, resolveSecurity } from '../core/resolve.js';
|
|
5
5
|
import { classifySecurity, DEFAULT_SECURITY_TYPES } from '../core/securities.js';
|
|
6
6
|
import { findTradingDay, noTradingDataMessage, previousTradingDays } from '../core/trading-day.js';
|
|
7
7
|
import { ToolError } from '../mcp/server.js';
|
|
8
|
+
import { describeOtherMarket, describeUnresolved } from './shared.js';
|
|
8
9
|
const NET_FIELDS = [
|
|
9
10
|
'foreign_net',
|
|
10
11
|
'trust_net',
|
|
@@ -224,27 +225,34 @@ export const getInstitutionalTool = {
|
|
|
224
225
|
let code = normaliseCode(input);
|
|
225
226
|
if (!code) {
|
|
226
227
|
const resolution = await resolveSecurity(input, market);
|
|
227
|
-
|
|
228
|
+
if (!resolution.ok) {
|
|
229
|
+
unresolved.push({ input, reason: describeUnresolved(input, resolution) });
|
|
230
|
+
continue;
|
|
231
|
+
}
|
|
232
|
+
code = resolution.code;
|
|
228
233
|
}
|
|
229
|
-
if (!code) {
|
|
230
|
-
unresolved.push({ input, reason: 'Not a code or exact name; use search_security.' });
|
|
231
|
-
}
|
|
232
|
-
else if (!inputByCode.has(code)) {
|
|
234
|
+
if (!inputByCode.has(code)) {
|
|
233
235
|
inputByCode.set(code, input);
|
|
234
236
|
codes.push(code);
|
|
235
237
|
}
|
|
236
238
|
}
|
|
237
239
|
const totals = aggregate(loaded, loaded.length > 1, new Set(codes));
|
|
238
|
-
const stocks =
|
|
240
|
+
const stocks = [];
|
|
241
|
+
for (const code of codes) {
|
|
239
242
|
const entry = totals.get(code);
|
|
240
|
-
if (entry)
|
|
241
|
-
|
|
243
|
+
if (entry) {
|
|
244
|
+
stocks.push(entry);
|
|
245
|
+
continue;
|
|
246
|
+
}
|
|
247
|
+
const input = inputByCode.get(code) ?? code;
|
|
248
|
+
const elsewhere = market ? await listedElsewhere(code, market) : [];
|
|
242
249
|
unresolved.push({
|
|
243
|
-
input
|
|
244
|
-
reason:
|
|
250
|
+
input,
|
|
251
|
+
reason: elsewhere.length
|
|
252
|
+
? describeOtherMarket(input, market, elsewhere)
|
|
253
|
+
: 'No institutional trading reported for this code in the period (not listed, suspended, or a warrant).',
|
|
245
254
|
});
|
|
246
|
-
|
|
247
|
-
});
|
|
255
|
+
}
|
|
248
256
|
return { ...period, stocks, unresolved, notes };
|
|
249
257
|
}
|
|
250
258
|
const field = RANK_FIELD[rank_by];
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { EVENT_KINDS, loadEvents } from '../core/events.js';
|
|
2
2
|
import { isIsoDate, normaliseCode, taipeiToday } from '../core/market.js';
|
|
3
|
-
import { resolveSecurity } from '../core/resolve.js';
|
|
3
|
+
import { listedElsewhere, resolveSecurity } from '../core/resolve.js';
|
|
4
4
|
import { ToolError } from '../mcp/server.js';
|
|
5
|
-
import { describeUnresolved } from './shared.js';
|
|
5
|
+
import { describeOtherMarket, describeUnresolved } from './shared.js';
|
|
6
6
|
const DEFAULT_PAST_DAYS = 14;
|
|
7
7
|
const DEFAULT_FUTURE_DAYS = 45;
|
|
8
8
|
function shift(date, days) {
|
|
@@ -109,7 +109,12 @@ export const getMarketEventsTool = {
|
|
|
109
109
|
const input = raw.trim();
|
|
110
110
|
const code = normaliseCode(input);
|
|
111
111
|
if (code) {
|
|
112
|
-
|
|
112
|
+
// A code on the other market would otherwise look like "no events".
|
|
113
|
+
const elsewhere = market ? await listedElsewhere(code, market) : [];
|
|
114
|
+
if (elsewhere.length)
|
|
115
|
+
unresolved.push({ input, reason: describeOtherMarket(input, market, elsewhere) });
|
|
116
|
+
else
|
|
117
|
+
codes.add(code);
|
|
113
118
|
continue;
|
|
114
119
|
}
|
|
115
120
|
const resolution = await resolveSecurity(input, market);
|
package/build/tools/get-quote.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { normaliseCode } from '../core/market.js';
|
|
2
2
|
import { fetchQuotes } from '../core/quotes.js';
|
|
3
|
+
import { listedElsewhere } from '../core/resolve.js';
|
|
3
4
|
import { DEFAULT_SECURITY_TYPES, SECURITY_TYPES, searchSecurities, } from '../core/securities.js';
|
|
4
5
|
import { ToolError } from '../mcp/server.js';
|
|
5
6
|
import { securityOutputSchema } from './search-security.js';
|
|
@@ -94,7 +95,11 @@ export const getQuoteTool = {
|
|
|
94
95
|
type: 'object',
|
|
95
96
|
properties: {
|
|
96
97
|
input: { type: 'string' },
|
|
97
|
-
reason: {
|
|
98
|
+
reason: {
|
|
99
|
+
type: 'string',
|
|
100
|
+
enum: ['name_not_found', 'ambiguous_name', 'no_quote', 'other_market'],
|
|
101
|
+
description: 'other_market: not listed on the requested `market`; suggestions show where it is listed.',
|
|
102
|
+
},
|
|
98
103
|
suggestions: { type: 'array', items: securityOutputSchema },
|
|
99
104
|
},
|
|
100
105
|
required: ['input', 'reason', 'suggestions'],
|
|
@@ -123,10 +128,14 @@ export const getQuoteTool = {
|
|
|
123
128
|
throw new ToolError(`Could not look up name "${input}": ${error instanceof Error ? error.message : String(error)}. Retry with a security code instead.`);
|
|
124
129
|
});
|
|
125
130
|
const exact = matches.filter((security) => security.name === input);
|
|
131
|
+
const elsewhere = exact.length === 0 && market ? await listedElsewhere(input, market) : [];
|
|
126
132
|
if (exact.length === 1) {
|
|
127
133
|
if (!inputByCode.has(exact[0].code))
|
|
128
134
|
inputByCode.set(exact[0].code, input);
|
|
129
135
|
}
|
|
136
|
+
else if (elsewhere.length) {
|
|
137
|
+
unresolved.push({ input, reason: 'other_market', suggestions: elsewhere });
|
|
138
|
+
}
|
|
130
139
|
else {
|
|
131
140
|
const suggestions = exact.length > 1
|
|
132
141
|
? exact
|
|
@@ -143,7 +152,11 @@ export const getQuoteTool = {
|
|
|
143
152
|
: { quotes: [], missing: [], warnings: [] };
|
|
144
153
|
for (const code of result.missing) {
|
|
145
154
|
const input = inputByCode.get(code) ?? code;
|
|
146
|
-
|
|
155
|
+
const elsewhere = market ? await listedElsewhere(code, market) : [];
|
|
156
|
+
if (elsewhere.length)
|
|
157
|
+
unresolved.push({ input, reason: 'other_market', suggestions: elsewhere });
|
|
158
|
+
else
|
|
159
|
+
unresolved.push({ input, reason: 'no_quote', suggestions: await suggest(input, market) });
|
|
147
160
|
}
|
|
148
161
|
return {
|
|
149
162
|
quotes: result.quotes,
|
package/build/tools/shared.js
CHANGED
|
@@ -1,5 +1,14 @@
|
|
|
1
|
+
const describe = (security) => `${security.code} ${security.name} (${security.market}, ${security.type})`;
|
|
2
|
+
/** Says where a security is listed when the caller asked for the wrong market. */
|
|
3
|
+
export function describeOtherMarket(input, requested, listings) {
|
|
4
|
+
const listed = listings.map(describe).join('; ');
|
|
5
|
+
return `"${input}" is not listed on market "${requested}", but it is listed as ${listed}. Retry without market, or with that market.`;
|
|
6
|
+
}
|
|
1
7
|
/** A tool error message that tells the agent exactly how to retry. */
|
|
2
8
|
export function describeUnresolved(input, resolution) {
|
|
9
|
+
if (resolution.reason === 'other_market') {
|
|
10
|
+
return describeOtherMarket(input, resolution.requested, resolution.suggestions);
|
|
11
|
+
}
|
|
3
12
|
const reason = {
|
|
4
13
|
name_not_found: `"${input}" is not an exact security name.`,
|
|
5
14
|
ambiguous_name: `"${input}" matches more than one security.`,
|
|
@@ -8,8 +17,6 @@ export function describeUnresolved(input, resolution) {
|
|
|
8
17
|
if (!resolution.suggestions.length) {
|
|
9
18
|
return `${reason} Use search_security to find the right code.`;
|
|
10
19
|
}
|
|
11
|
-
const options = resolution.suggestions
|
|
12
|
-
.map((security) => `${security.code} ${security.name} (${security.market}, ${security.type})`)
|
|
13
|
-
.join('; ');
|
|
20
|
+
const options = resolution.suggestions.map(describe).join('; ');
|
|
14
21
|
return `${reason} Did you mean: ${options}? Retry with the code.`;
|
|
15
22
|
}
|