tw-stock-mcp 0.1.1 → 0.1.2
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/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.2
|
|
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.2
|
|
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.2"]}'
|
|
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.2"]
|
|
41
41
|
}
|
|
42
42
|
}
|
|
43
43
|
}
|
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
|
}
|