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 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.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.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.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.1"]
40
+ "args": ["-y", "npm:tw-stock-mcp@0.1.2"]
41
41
  }
42
42
  }
43
43
  }
@@ -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
- code = resolution.ok ? resolution.code : null;
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 = codes.flatMap((code) => {
240
+ const stocks = [];
241
+ for (const code of codes) {
239
242
  const entry = totals.get(code);
240
- if (entry)
241
- return [entry];
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: inputByCode.get(code) ?? code,
244
- reason: 'No institutional trading reported for this code in the period (not listed, suspended, or a warrant).',
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
- return [];
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
- codes.add(code);
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);
@@ -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: { type: 'string', enum: ['name_not_found', 'ambiguous_name', 'no_quote'] },
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
- unresolved.push({ input, reason: 'no_quote', suggestions: await suggest(input, market) });
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,
@@ -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
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tw-stock-mcp",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Zero-dependency MCP server for Taiwan stock market data (TWSE / TPEx)",
5
5
  "type": "module",
6
6
  "bin": {