@cyanheads/finnhub-mcp-server 0.1.0
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/AGENTS.md +376 -0
- package/CLAUDE.md +376 -0
- package/Dockerfile +121 -0
- package/LICENSE +201 -0
- package/README.md +314 -0
- package/changelog/0.1.x/0.1.0.md +22 -0
- package/changelog/template.md +127 -0
- package/dist/config/server-config.d.ts +25 -0
- package/dist/config/server-config.d.ts.map +1 -0
- package/dist/config/server-config.js +37 -0
- package/dist/config/server-config.js.map +1 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +21 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp-server/resources/definitions/index.d.ts +12 -0
- package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -0
- package/dist/mcp-server/resources/definitions/index.js +8 -0
- package/dist/mcp-server/resources/definitions/index.js.map +1 -0
- package/dist/mcp-server/resources/definitions/news-categories.resource.d.ts +16 -0
- package/dist/mcp-server/resources/definitions/news-categories.resource.d.ts.map +1 -0
- package/dist/mcp-server/resources/definitions/news-categories.resource.js +45 -0
- package/dist/mcp-server/resources/definitions/news-categories.resource.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-company.tool.d.ts +51 -0
- package/dist/mcp-server/tools/definitions/get-company.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-company.tool.js +191 -0
- package/dist/mcp-server/tools/definitions/get-company.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-earnings.tool.d.ts +59 -0
- package/dist/mcp-server/tools/definitions/get-earnings.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-earnings.tool.js +201 -0
- package/dist/mcp-server/tools/definitions/get-earnings.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-news.tool.d.ts +55 -0
- package/dist/mcp-server/tools/definitions/get-news.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-news.tool.js +160 -0
- package/dist/mcp-server/tools/definitions/get-news.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-quote.tool.d.ts +35 -0
- package/dist/mcp-server/tools/definitions/get-quote.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-quote.tool.js +132 -0
- package/dist/mcp-server/tools/definitions/get-quote.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-recommendations.tool.d.ts +38 -0
- package/dist/mcp-server/tools/definitions/get-recommendations.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-recommendations.tool.js +110 -0
- package/dist/mcp-server/tools/definitions/get-recommendations.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/index.d.ts +209 -0
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/index.js +20 -0
- package/dist/mcp-server/tools/definitions/index.js.map +1 -0
- package/dist/mcp-server/tools/definitions/search-symbols.tool.d.ts +26 -0
- package/dist/mcp-server/tools/definitions/search-symbols.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/search-symbols.tool.js +101 -0
- package/dist/mcp-server/tools/definitions/search-symbols.tool.js.map +1 -0
- package/dist/services/finnhub/finnhub-service.d.ts +77 -0
- package/dist/services/finnhub/finnhub-service.d.ts.map +1 -0
- package/dist/services/finnhub/finnhub-service.js +148 -0
- package/dist/services/finnhub/finnhub-service.js.map +1 -0
- package/dist/services/finnhub/types.d.ts +147 -0
- package/dist/services/finnhub/types.d.ts.map +1 -0
- package/dist/services/finnhub/types.js +9 -0
- package/dist/services/finnhub/types.js.map +1 -0
- package/package.json +85 -0
- package/server.json +125 -0
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview finnhub_get_recommendations — analyst recommendation trends for
|
|
3
|
+
* one US symbol: strong-buy / buy / hold / sell / strong-sell counts per month,
|
|
4
|
+
* newest first. The consensus view to pair with the live quote and fundamentals.
|
|
5
|
+
* @module mcp-server/tools/definitions/get-recommendations.tool
|
|
6
|
+
*/
|
|
7
|
+
import { z } from '@cyanheads/mcp-ts-core';
|
|
8
|
+
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
9
|
+
export declare const getRecommendations: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
|
|
10
|
+
symbol: z.ZodString;
|
|
11
|
+
limit: z.ZodDefault<z.ZodNumber>;
|
|
12
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
13
|
+
symbol: z.ZodString;
|
|
14
|
+
trends: z.ZodArray<z.ZodObject<{
|
|
15
|
+
period: z.ZodString;
|
|
16
|
+
strongBuy: z.ZodNumber;
|
|
17
|
+
buy: z.ZodNumber;
|
|
18
|
+
hold: z.ZodNumber;
|
|
19
|
+
sell: z.ZodNumber;
|
|
20
|
+
strongSell: z.ZodNumber;
|
|
21
|
+
}, z.core.$strip>>;
|
|
22
|
+
}, z.core.$strip>, readonly [{
|
|
23
|
+
readonly reason: "no_coverage";
|
|
24
|
+
readonly code: JsonRpcErrorCode.NotFound;
|
|
25
|
+
readonly when: "Endpoint returned an empty array — no analyst coverage for the symbol.";
|
|
26
|
+
readonly recovery: "Verify the symbol is valid with finnhub_search_symbols; some thinly-traded or newly-listed stocks have no analyst coverage on Finnhub.";
|
|
27
|
+
}, {
|
|
28
|
+
readonly reason: "not_us_or_paid";
|
|
29
|
+
readonly code: JsonRpcErrorCode.Forbidden;
|
|
30
|
+
readonly when: "Upstream HTTP 403 — international or paid-only symbol.";
|
|
31
|
+
readonly recovery: "Free tier is US equities only; use a US symbol or a paid plan.";
|
|
32
|
+
}], {
|
|
33
|
+
readonly totalCount: z.ZodNumber;
|
|
34
|
+
readonly truncated: z.ZodOptional<z.ZodBoolean>;
|
|
35
|
+
readonly shown: z.ZodOptional<z.ZodNumber>;
|
|
36
|
+
readonly cap: z.ZodOptional<z.ZodNumber>;
|
|
37
|
+
}>;
|
|
38
|
+
//# sourceMappingURL=get-recommendations.tool.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"get-recommendations.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-recommendations.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAG3E,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsH7B,CAAC"}
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview finnhub_get_recommendations — analyst recommendation trends for
|
|
3
|
+
* one US symbol: strong-buy / buy / hold / sell / strong-sell counts per month,
|
|
4
|
+
* newest first. The consensus view to pair with the live quote and fundamentals.
|
|
5
|
+
* @module mcp-server/tools/definitions/get-recommendations.tool
|
|
6
|
+
*/
|
|
7
|
+
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
8
|
+
import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
|
|
9
|
+
import { getFinnhubService } from '../../../services/finnhub/finnhub-service.js';
|
|
10
|
+
export const getRecommendations = tool('finnhub_get_recommendations', {
|
|
11
|
+
description: 'Analyst recommendation trends for one US symbol: strong-buy / buy / hold / sell / strong-sell counts per month, newest first. The consensus view to pair with the live quote and fundamentals from finnhub_get_company. Resolve a company name with finnhub_search_symbols first.',
|
|
12
|
+
annotations: { readOnlyHint: true, openWorldHint: true },
|
|
13
|
+
input: z.object({
|
|
14
|
+
symbol: z
|
|
15
|
+
.string()
|
|
16
|
+
.min(1)
|
|
17
|
+
.describe('US stock ticker (e.g., "AAPL"). Resolve a name with finnhub_search_symbols first.'),
|
|
18
|
+
limit: z
|
|
19
|
+
.number()
|
|
20
|
+
.int()
|
|
21
|
+
.min(1)
|
|
22
|
+
.max(24)
|
|
23
|
+
.default(12)
|
|
24
|
+
.describe('Max months to return, newest first. Default 12 (one year of consensus history). The API typically returns 12–24 months; setting this higher surfaces older trend data.'),
|
|
25
|
+
}),
|
|
26
|
+
output: z.object({
|
|
27
|
+
symbol: z.string().describe('The symbol queried (echo of input).'),
|
|
28
|
+
trends: z
|
|
29
|
+
.array(z
|
|
30
|
+
.object({
|
|
31
|
+
period: z.string().describe('Month the consensus is for (YYYY-MM-DD, first of month).'),
|
|
32
|
+
strongBuy: z
|
|
33
|
+
.number()
|
|
34
|
+
.describe('Number of analysts with a Strong Buy rating this month.'),
|
|
35
|
+
buy: z.number().describe('Number of analysts with a Buy rating this month.'),
|
|
36
|
+
hold: z.number().describe('Number of analysts with a Hold rating this month.'),
|
|
37
|
+
sell: z.number().describe('Number of analysts with a Sell rating this month.'),
|
|
38
|
+
strongSell: z
|
|
39
|
+
.number()
|
|
40
|
+
.describe('Number of analysts with a Strong Sell rating this month.'),
|
|
41
|
+
})
|
|
42
|
+
.describe('One month of analyst recommendation counts.'))
|
|
43
|
+
.describe('Recommendation counts per month, newest first. Typically 12–24 months of history.'),
|
|
44
|
+
}),
|
|
45
|
+
enrichment: {
|
|
46
|
+
totalCount: z.number().describe('Total months available before the limit.'),
|
|
47
|
+
truncated: z.boolean().optional().describe('True when months were capped at the limit.'),
|
|
48
|
+
shown: z.number().optional().describe('Number of months returned.'),
|
|
49
|
+
cap: z.number().optional().describe('The limit that was applied.'),
|
|
50
|
+
},
|
|
51
|
+
errors: [
|
|
52
|
+
{
|
|
53
|
+
reason: 'no_coverage',
|
|
54
|
+
code: JsonRpcErrorCode.NotFound,
|
|
55
|
+
when: 'Endpoint returned an empty array — no analyst coverage for the symbol.',
|
|
56
|
+
recovery: 'Verify the symbol is valid with finnhub_search_symbols; some thinly-traded or newly-listed stocks have no analyst coverage on Finnhub.',
|
|
57
|
+
},
|
|
58
|
+
{
|
|
59
|
+
reason: 'not_us_or_paid',
|
|
60
|
+
code: JsonRpcErrorCode.Forbidden,
|
|
61
|
+
when: 'Upstream HTTP 403 — international or paid-only symbol.',
|
|
62
|
+
recovery: 'Free tier is US equities only; use a US symbol or a paid plan.',
|
|
63
|
+
},
|
|
64
|
+
],
|
|
65
|
+
async handler(input, ctx) {
|
|
66
|
+
const service = getFinnhubService();
|
|
67
|
+
let raw;
|
|
68
|
+
try {
|
|
69
|
+
raw = await service.recommendations(input.symbol, ctx);
|
|
70
|
+
}
|
|
71
|
+
catch (err) {
|
|
72
|
+
if (err instanceof McpError && err.code === JsonRpcErrorCode.Forbidden) {
|
|
73
|
+
throw ctx.fail('not_us_or_paid', undefined, {
|
|
74
|
+
symbol: input.symbol,
|
|
75
|
+
...ctx.recoveryFor('not_us_or_paid'),
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
throw err;
|
|
79
|
+
}
|
|
80
|
+
if (raw.length === 0) {
|
|
81
|
+
throw ctx.fail('no_coverage', `No analyst coverage for "${input.symbol}".`, {
|
|
82
|
+
symbol: input.symbol,
|
|
83
|
+
...ctx.recoveryFor('no_coverage'),
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
const sorted = [...raw].sort((a, b) => b.period.localeCompare(a.period));
|
|
87
|
+
const trends = sorted.map((r) => ({
|
|
88
|
+
period: r.period,
|
|
89
|
+
strongBuy: r.strongBuy,
|
|
90
|
+
buy: r.buy,
|
|
91
|
+
hold: r.hold,
|
|
92
|
+
sell: r.sell,
|
|
93
|
+
strongSell: r.strongSell,
|
|
94
|
+
}));
|
|
95
|
+
ctx.enrich.total(trends.length);
|
|
96
|
+
const sliced = trends.slice(0, input.limit);
|
|
97
|
+
if (trends.length > input.limit) {
|
|
98
|
+
ctx.enrich.truncated({ shown: sliced.length, cap: input.limit });
|
|
99
|
+
}
|
|
100
|
+
return { symbol: input.symbol, trends: sliced };
|
|
101
|
+
},
|
|
102
|
+
format: (result) => {
|
|
103
|
+
const lines = [`**${result.symbol}** analyst recommendations (newest first):`];
|
|
104
|
+
for (const t of result.trends) {
|
|
105
|
+
lines.push(`- ${t.period}: ${t.strongBuy} strong-buy / ${t.buy} buy / ${t.hold} hold / ${t.sell} sell / ${t.strongSell} strong-sell`);
|
|
106
|
+
}
|
|
107
|
+
return [{ type: 'text', text: lines.join('\n') }];
|
|
108
|
+
},
|
|
109
|
+
});
|
|
110
|
+
//# sourceMappingURL=get-recommendations.tool.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"get-recommendations.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-recommendations.tool.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Barrel collecting all tool definitions into `allToolDefinitions`
|
|
3
|
+
* for `createApp()`.
|
|
4
|
+
* @module mcp-server/tools/definitions/index
|
|
5
|
+
*/
|
|
6
|
+
export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
|
|
7
|
+
symbol: import("zod").ZodString;
|
|
8
|
+
}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
|
|
9
|
+
symbol: import("zod").ZodString;
|
|
10
|
+
profile: import("zod").ZodObject<{
|
|
11
|
+
name: import("zod").ZodString;
|
|
12
|
+
exchange: import("zod").ZodString;
|
|
13
|
+
industry: import("zod").ZodString;
|
|
14
|
+
country: import("zod").ZodString;
|
|
15
|
+
currency: import("zod").ZodString;
|
|
16
|
+
marketCapitalization: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
17
|
+
shareOutstanding: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
18
|
+
ipo: import("zod").ZodNullable<import("zod").ZodString>;
|
|
19
|
+
weburl: import("zod").ZodNullable<import("zod").ZodString>;
|
|
20
|
+
logo: import("zod").ZodNullable<import("zod").ZodString>;
|
|
21
|
+
}, import("zod/v4/core").$strip>;
|
|
22
|
+
fundamentals: import("zod").ZodObject<{
|
|
23
|
+
peTTM: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
24
|
+
epsTTM: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
25
|
+
week52High: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
26
|
+
week52Low: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
27
|
+
beta: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
28
|
+
dividendYieldTTM: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
29
|
+
netProfitMarginTTM: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
30
|
+
grossMarginTTM: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
31
|
+
revenueGrowthTTMYoy: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
32
|
+
roeTTM: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
33
|
+
}, import("zod/v4/core").$strip>;
|
|
34
|
+
peers: import("zod").ZodArray<import("zod").ZodString>;
|
|
35
|
+
partial: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
|
|
36
|
+
}, import("zod/v4/core").$strip>, readonly [{
|
|
37
|
+
readonly reason: "symbol_not_found";
|
|
38
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
|
|
39
|
+
readonly when: "/stock/profile2 returned an empty object for the symbol.";
|
|
40
|
+
readonly recovery: "Verify the ticker, or call finnhub_search_symbols to resolve the company name first.";
|
|
41
|
+
}, {
|
|
42
|
+
readonly reason: "not_us_or_paid";
|
|
43
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Forbidden;
|
|
44
|
+
readonly when: "Upstream HTTP 403 — international or paid-only symbol.";
|
|
45
|
+
readonly recovery: "Free tier is US equities only; international symbols need a paid Finnhub plan. Try the company's US listing.";
|
|
46
|
+
}], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
|
|
47
|
+
mode: import("zod").ZodEnum<{
|
|
48
|
+
history: "history";
|
|
49
|
+
calendar: "calendar";
|
|
50
|
+
}>;
|
|
51
|
+
symbol: import("zod").ZodOptional<import("zod").ZodString>;
|
|
52
|
+
from: import("zod").ZodOptional<import("zod").ZodString>;
|
|
53
|
+
to: import("zod").ZodOptional<import("zod").ZodString>;
|
|
54
|
+
limit: import("zod").ZodDefault<import("zod").ZodNumber>;
|
|
55
|
+
}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
|
|
56
|
+
mode: import("zod").ZodEnum<{
|
|
57
|
+
history: "history";
|
|
58
|
+
calendar: "calendar";
|
|
59
|
+
}>;
|
|
60
|
+
history: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
|
|
61
|
+
period: import("zod").ZodString;
|
|
62
|
+
year: import("zod").ZodNumber;
|
|
63
|
+
quarter: import("zod").ZodNumber;
|
|
64
|
+
actualEPS: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
65
|
+
estimateEPS: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
66
|
+
surprise: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
67
|
+
surprisePercent: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
68
|
+
}, import("zod/v4/core").$strip>>>;
|
|
69
|
+
calendar: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
|
|
70
|
+
symbol: import("zod").ZodString;
|
|
71
|
+
date: import("zod").ZodString;
|
|
72
|
+
hour: import("zod").ZodString;
|
|
73
|
+
epsEstimate: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
74
|
+
revenueEstimate: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
75
|
+
year: import("zod").ZodNumber;
|
|
76
|
+
quarter: import("zod").ZodNumber;
|
|
77
|
+
}, import("zod/v4/core").$strip>>>;
|
|
78
|
+
}, import("zod/v4/core").$strip>, readonly [{
|
|
79
|
+
readonly reason: "missing_symbol";
|
|
80
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
|
|
81
|
+
readonly when: "mode 'history' was requested without a symbol.";
|
|
82
|
+
readonly recovery: "Provide a `symbol` for history mode, or switch to mode: calendar for the market-wide upcoming-releases feed.";
|
|
83
|
+
}, {
|
|
84
|
+
readonly reason: "not_us_or_paid";
|
|
85
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Forbidden;
|
|
86
|
+
readonly when: "Upstream HTTP 403 on the symbol.";
|
|
87
|
+
readonly recovery: "Free tier is US equities only; use a US symbol or a paid plan.";
|
|
88
|
+
}], {
|
|
89
|
+
readonly totalCount: import("zod").ZodNumber;
|
|
90
|
+
readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
|
|
91
|
+
readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
92
|
+
readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
93
|
+
readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
|
|
94
|
+
}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
|
|
95
|
+
mode: import("zod").ZodEnum<{
|
|
96
|
+
company: "company";
|
|
97
|
+
market: "market";
|
|
98
|
+
}>;
|
|
99
|
+
symbol: import("zod").ZodOptional<import("zod").ZodString>;
|
|
100
|
+
from: import("zod").ZodOptional<import("zod").ZodString>;
|
|
101
|
+
to: import("zod").ZodOptional<import("zod").ZodString>;
|
|
102
|
+
category: import("zod").ZodDefault<import("zod").ZodEnum<{
|
|
103
|
+
general: "general";
|
|
104
|
+
forex: "forex";
|
|
105
|
+
crypto: "crypto";
|
|
106
|
+
merger: "merger";
|
|
107
|
+
}>>;
|
|
108
|
+
limit: import("zod").ZodDefault<import("zod").ZodNumber>;
|
|
109
|
+
}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
|
|
110
|
+
mode: import("zod").ZodEnum<{
|
|
111
|
+
company: "company";
|
|
112
|
+
market: "market";
|
|
113
|
+
}>;
|
|
114
|
+
articles: import("zod").ZodArray<import("zod").ZodObject<{
|
|
115
|
+
headline: import("zod").ZodString;
|
|
116
|
+
source: import("zod").ZodString;
|
|
117
|
+
datetime: import("zod").ZodString;
|
|
118
|
+
summary: import("zod").ZodString;
|
|
119
|
+
url: import("zod").ZodString;
|
|
120
|
+
category: import("zod").ZodOptional<import("zod").ZodString>;
|
|
121
|
+
related: import("zod").ZodOptional<import("zod").ZodString>;
|
|
122
|
+
}, import("zod/v4/core").$strip>>;
|
|
123
|
+
}, import("zod/v4/core").$strip>, readonly [{
|
|
124
|
+
readonly reason: "missing_symbol";
|
|
125
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
|
|
126
|
+
readonly when: "mode 'company' was requested without a symbol.";
|
|
127
|
+
readonly recovery: "Provide a `symbol` for company mode, or switch to mode: market with a category.";
|
|
128
|
+
}, {
|
|
129
|
+
readonly reason: "not_us_or_paid";
|
|
130
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Forbidden;
|
|
131
|
+
readonly when: "Upstream HTTP 403 on the symbol.";
|
|
132
|
+
readonly recovery: "Free tier is US equities only; use a US symbol or a paid plan.";
|
|
133
|
+
}], {
|
|
134
|
+
readonly totalCount: import("zod").ZodNumber;
|
|
135
|
+
readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
|
|
136
|
+
readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
137
|
+
readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
138
|
+
readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
|
|
139
|
+
}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
|
|
140
|
+
symbol: import("zod").ZodString;
|
|
141
|
+
}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
|
|
142
|
+
symbol: import("zod").ZodString;
|
|
143
|
+
current: import("zod").ZodNumber;
|
|
144
|
+
change: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
145
|
+
percentChange: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
146
|
+
high: import("zod").ZodNumber;
|
|
147
|
+
low: import("zod").ZodNumber;
|
|
148
|
+
open: import("zod").ZodNumber;
|
|
149
|
+
previousClose: import("zod").ZodNumber;
|
|
150
|
+
quoteTime: import("zod").ZodString;
|
|
151
|
+
marketOpen: import("zod").ZodNullable<import("zod").ZodBoolean>;
|
|
152
|
+
priceIsLive: import("zod").ZodBoolean;
|
|
153
|
+
}, import("zod/v4/core").$strip>, readonly [{
|
|
154
|
+
readonly reason: "symbol_not_found";
|
|
155
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
|
|
156
|
+
readonly when: "Quote sentinel detected (c=0, t=0, d=null, dp=null) — unknown US symbol at HTTP 200.";
|
|
157
|
+
readonly recovery: "Verify the ticker, or call finnhub_search_symbols to resolve the company name to a valid US symbol.";
|
|
158
|
+
}, {
|
|
159
|
+
readonly reason: "not_us_or_paid";
|
|
160
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Forbidden;
|
|
161
|
+
readonly when: "Upstream HTTP 403 — international or paid-only symbol.";
|
|
162
|
+
readonly recovery: "This free Finnhub tier covers US stocks only; international symbols require a paid plan. Try the US listing of the company.";
|
|
163
|
+
}], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
|
|
164
|
+
symbol: import("zod").ZodString;
|
|
165
|
+
limit: import("zod").ZodDefault<import("zod").ZodNumber>;
|
|
166
|
+
}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
|
|
167
|
+
symbol: import("zod").ZodString;
|
|
168
|
+
trends: import("zod").ZodArray<import("zod").ZodObject<{
|
|
169
|
+
period: import("zod").ZodString;
|
|
170
|
+
strongBuy: import("zod").ZodNumber;
|
|
171
|
+
buy: import("zod").ZodNumber;
|
|
172
|
+
hold: import("zod").ZodNumber;
|
|
173
|
+
sell: import("zod").ZodNumber;
|
|
174
|
+
strongSell: import("zod").ZodNumber;
|
|
175
|
+
}, import("zod/v4/core").$strip>>;
|
|
176
|
+
}, import("zod/v4/core").$strip>, readonly [{
|
|
177
|
+
readonly reason: "no_coverage";
|
|
178
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
|
|
179
|
+
readonly when: "Endpoint returned an empty array — no analyst coverage for the symbol.";
|
|
180
|
+
readonly recovery: "Verify the symbol is valid with finnhub_search_symbols; some thinly-traded or newly-listed stocks have no analyst coverage on Finnhub.";
|
|
181
|
+
}, {
|
|
182
|
+
readonly reason: "not_us_or_paid";
|
|
183
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Forbidden;
|
|
184
|
+
readonly when: "Upstream HTTP 403 — international or paid-only symbol.";
|
|
185
|
+
readonly recovery: "Free tier is US equities only; use a US symbol or a paid plan.";
|
|
186
|
+
}], {
|
|
187
|
+
readonly totalCount: import("zod").ZodNumber;
|
|
188
|
+
readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
|
|
189
|
+
readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
190
|
+
readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
191
|
+
}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
|
|
192
|
+
query: import("zod").ZodString;
|
|
193
|
+
limit: import("zod").ZodDefault<import("zod").ZodNumber>;
|
|
194
|
+
}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
|
|
195
|
+
results: import("zod").ZodArray<import("zod").ZodObject<{
|
|
196
|
+
symbol: import("zod").ZodString;
|
|
197
|
+
displaySymbol: import("zod").ZodString;
|
|
198
|
+
description: import("zod").ZodString;
|
|
199
|
+
type: import("zod").ZodString;
|
|
200
|
+
isLikelyUS: import("zod").ZodBoolean;
|
|
201
|
+
}, import("zod/v4/core").$strip>>;
|
|
202
|
+
}, import("zod/v4/core").$strip>, undefined, {
|
|
203
|
+
readonly totalCount: import("zod").ZodNumber;
|
|
204
|
+
readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
|
|
205
|
+
readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
206
|
+
readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
207
|
+
readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
|
|
208
|
+
}>)[];
|
|
209
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAO9B,CAAC"}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Barrel collecting all tool definitions into `allToolDefinitions`
|
|
3
|
+
* for `createApp()`.
|
|
4
|
+
* @module mcp-server/tools/definitions/index
|
|
5
|
+
*/
|
|
6
|
+
import { getCompany } from './get-company.tool.js';
|
|
7
|
+
import { getEarnings } from './get-earnings.tool.js';
|
|
8
|
+
import { getNews } from './get-news.tool.js';
|
|
9
|
+
import { getQuote } from './get-quote.tool.js';
|
|
10
|
+
import { getRecommendations } from './get-recommendations.tool.js';
|
|
11
|
+
import { searchSymbols } from './search-symbols.tool.js';
|
|
12
|
+
export const allToolDefinitions = [
|
|
13
|
+
searchSymbols,
|
|
14
|
+
getQuote,
|
|
15
|
+
getCompany,
|
|
16
|
+
getEarnings,
|
|
17
|
+
getNews,
|
|
18
|
+
getRecommendations,
|
|
19
|
+
];
|
|
20
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,aAAa;IACb,QAAQ;IACR,UAAU;IACV,WAAW;IACX,OAAO;IACP,kBAAkB;CACnB,CAAC"}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview finnhub_search_symbols — resolve a company name or partial
|
|
3
|
+
* ticker to Finnhub stock symbols. The entry point the rest of the surface
|
|
4
|
+
* depends on: users say "Microsoft", the other tools need "MSFT".
|
|
5
|
+
* @module mcp-server/tools/definitions/search-symbols.tool
|
|
6
|
+
*/
|
|
7
|
+
import { z } from '@cyanheads/mcp-ts-core';
|
|
8
|
+
export declare const searchSymbols: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
|
|
9
|
+
query: z.ZodString;
|
|
10
|
+
limit: z.ZodDefault<z.ZodNumber>;
|
|
11
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
12
|
+
results: z.ZodArray<z.ZodObject<{
|
|
13
|
+
symbol: z.ZodString;
|
|
14
|
+
displaySymbol: z.ZodString;
|
|
15
|
+
description: z.ZodString;
|
|
16
|
+
type: z.ZodString;
|
|
17
|
+
isLikelyUS: z.ZodBoolean;
|
|
18
|
+
}, z.core.$strip>>;
|
|
19
|
+
}, z.core.$strip>, undefined, {
|
|
20
|
+
readonly totalCount: z.ZodNumber;
|
|
21
|
+
readonly truncated: z.ZodOptional<z.ZodBoolean>;
|
|
22
|
+
readonly shown: z.ZodOptional<z.ZodNumber>;
|
|
23
|
+
readonly cap: z.ZodOptional<z.ZodNumber>;
|
|
24
|
+
readonly notice: z.ZodOptional<z.ZodString>;
|
|
25
|
+
}>;
|
|
26
|
+
//# sourceMappingURL=search-symbols.tool.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"search-symbols.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-symbols.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAGjD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;EAqHxB,CAAC"}
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview finnhub_search_symbols — resolve a company name or partial
|
|
3
|
+
* ticker to Finnhub stock symbols. The entry point the rest of the surface
|
|
4
|
+
* depends on: users say "Microsoft", the other tools need "MSFT".
|
|
5
|
+
* @module mcp-server/tools/definitions/search-symbols.tool
|
|
6
|
+
*/
|
|
7
|
+
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
8
|
+
import { getFinnhubService } from '../../../services/finnhub/finnhub-service.js';
|
|
9
|
+
export const searchSymbols = tool('finnhub_search_symbols', {
|
|
10
|
+
description: 'Resolve a company name or partial ticker to Finnhub stock symbols. The entry point for every other tool — users say "Microsoft", the rest of the surface needs "MSFT". Returns matched symbols with display symbol, description, and security type, best US match first. Each result carries isLikelyUS so an agent can avoid spending a call on an international symbol the free tier cannot reach.',
|
|
11
|
+
annotations: { readOnlyHint: true, openWorldHint: true },
|
|
12
|
+
input: z.object({
|
|
13
|
+
query: z
|
|
14
|
+
.string()
|
|
15
|
+
.min(1)
|
|
16
|
+
.describe('Company name (e.g., "Apple"), partial name ("micro"), or ticker fragment. Finnhub full-text matches across symbols and descriptions. Use this first when you have a company name, not a ticker — the rest of the tools need a symbol.'),
|
|
17
|
+
limit: z
|
|
18
|
+
.number()
|
|
19
|
+
.int()
|
|
20
|
+
.min(1)
|
|
21
|
+
.max(50)
|
|
22
|
+
.default(10)
|
|
23
|
+
.describe('Max symbols to return (Finnhub often returns 10–50 matches for a common word). Default 10. US Common Stock matches are surfaced first.'),
|
|
24
|
+
}),
|
|
25
|
+
output: z.object({
|
|
26
|
+
results: z
|
|
27
|
+
.array(z
|
|
28
|
+
.object({
|
|
29
|
+
symbol: z
|
|
30
|
+
.string()
|
|
31
|
+
.describe('Finnhub symbol — pass this to finnhub_get_quote / _company / _earnings / _news / _recommendations.'),
|
|
32
|
+
displaySymbol: z
|
|
33
|
+
.string()
|
|
34
|
+
.describe('Human-facing ticker as shown on its exchange (e.g., "AAPL", "603020.SS").'),
|
|
35
|
+
description: z.string().describe('Company / security name.'),
|
|
36
|
+
type: z
|
|
37
|
+
.string()
|
|
38
|
+
.describe('Security type (e.g., "Common Stock", "ETP", "ETF"). Empty string when Finnhub omits it.'),
|
|
39
|
+
isLikelyUS: z
|
|
40
|
+
.boolean()
|
|
41
|
+
.describe('Heuristic: symbol has no exchange suffix (no dot) — i.e., a plain US ticker reachable on the free tier. Suffixed symbols (".SS", ".T", ".L") are international and 403 on quote/profile.'),
|
|
42
|
+
})
|
|
43
|
+
.describe('A single matched symbol.'))
|
|
44
|
+
.describe('Matched symbols, US Common Stock first, then by Finnhub order.'),
|
|
45
|
+
}),
|
|
46
|
+
enrichment: {
|
|
47
|
+
totalCount: z
|
|
48
|
+
.number()
|
|
49
|
+
.describe('Total matches Finnhub reported (its `count`), before the limit.'),
|
|
50
|
+
truncated: z
|
|
51
|
+
.boolean()
|
|
52
|
+
.optional()
|
|
53
|
+
.describe('True when more matches existed than the limit returned.'),
|
|
54
|
+
shown: z.number().optional().describe('Number of symbols returned.'),
|
|
55
|
+
cap: z.number().optional().describe('The limit that was applied.'),
|
|
56
|
+
notice: z.string().optional().describe('Guidance when nothing matched the query.'),
|
|
57
|
+
},
|
|
58
|
+
async handler(input, ctx) {
|
|
59
|
+
const { count, result } = await getFinnhubService().search(input.query, ctx);
|
|
60
|
+
const mapped = result.map((match) => ({
|
|
61
|
+
symbol: match.symbol,
|
|
62
|
+
displaySymbol: match.displaySymbol,
|
|
63
|
+
description: match.description,
|
|
64
|
+
type: match.type,
|
|
65
|
+
isLikelyUS: !match.symbol.includes('.'),
|
|
66
|
+
}));
|
|
67
|
+
/**
|
|
68
|
+
* Stable sort: US Common Stock first, preserving Finnhub's order within
|
|
69
|
+
* each group. The dot-suffix → non-US mapping is how Finnhub namespaces
|
|
70
|
+
* exchanges (honest signal, not a fabricated score).
|
|
71
|
+
*/
|
|
72
|
+
const rank = (r) => r.isLikelyUS && r.type === 'Common Stock' ? 0 : 1;
|
|
73
|
+
const sorted = [...mapped].sort((a, b) => rank(a) - rank(b));
|
|
74
|
+
ctx.enrich.total(count);
|
|
75
|
+
if (count === 0) {
|
|
76
|
+
ctx.enrich.notice(`No symbols matched "${input.query}". Try the company's common name or a ticker fragment.`);
|
|
77
|
+
}
|
|
78
|
+
const results = sorted.slice(0, input.limit);
|
|
79
|
+
if (count > input.limit) {
|
|
80
|
+
ctx.enrich.truncated({ shown: results.length, cap: input.limit });
|
|
81
|
+
}
|
|
82
|
+
ctx.log.info('Symbol search complete', {
|
|
83
|
+
query: input.query,
|
|
84
|
+
count,
|
|
85
|
+
returned: results.length,
|
|
86
|
+
});
|
|
87
|
+
return { results };
|
|
88
|
+
},
|
|
89
|
+
format: (result) => {
|
|
90
|
+
if (result.results.length === 0) {
|
|
91
|
+
return [{ type: 'text', text: 'No matching symbols.' }];
|
|
92
|
+
}
|
|
93
|
+
const lines = result.results.map((r) => {
|
|
94
|
+
const region = r.isLikelyUS ? 'likely US (free tier)' : 'international';
|
|
95
|
+
const type = r.type || 'Unknown type';
|
|
96
|
+
return `**${r.symbol}** — ${r.description} (${type}, ${region}) · display: ${r.displaySymbol}`;
|
|
97
|
+
});
|
|
98
|
+
return [{ type: 'text', text: lines.join('\n') }];
|
|
99
|
+
},
|
|
100
|
+
});
|
|
101
|
+
//# sourceMappingURL=search-symbols.tool.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"search-symbols.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-symbols.tool.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview FinnhubService — the single authenticated, rate-aware,
|
|
3
|
+
* status-classifying HTTP client for the Finnhub REST API. One typed method per
|
|
4
|
+
* upstream endpoint the tool surface needs. Owns auth (the `token` query param),
|
|
5
|
+
* resilience (`withRetry` around the full fetch+parse pipeline via
|
|
6
|
+
* `fetchWithTimeout`), and the status classification that gives every tool
|
|
7
|
+
* identical, correct error semantics.
|
|
8
|
+
* @module services/finnhub/finnhub-service
|
|
9
|
+
*/
|
|
10
|
+
import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
|
|
11
|
+
import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
|
|
12
|
+
import type { RequestContextLike } from '@cyanheads/mcp-ts-core/utils';
|
|
13
|
+
import type { FinnhubEarning, FinnhubEarningsCalendar, FinnhubMarketStatus, FinnhubMetricResponse, FinnhubNewsArticle, FinnhubProfile, FinnhubQuote, FinnhubRecommendation, FinnhubSearchResponse } from './types.js';
|
|
14
|
+
/**
|
|
15
|
+
* Authenticated client for the Finnhub REST API. Initialized once in
|
|
16
|
+
* `createApp`'s `setup()` and accessed via {@link getFinnhubService}.
|
|
17
|
+
*/
|
|
18
|
+
export declare class FinnhubService {
|
|
19
|
+
private readonly baseUrl;
|
|
20
|
+
private readonly apiKey;
|
|
21
|
+
constructor();
|
|
22
|
+
/** `GET /search?q={query}` — resolve a name/ticker fragment to symbols. */
|
|
23
|
+
search(query: string, ctx: RequestContextLike): Promise<FinnhubSearchResponse>;
|
|
24
|
+
/** `GET /quote?symbol={symbol}` — real-time price snapshot. */
|
|
25
|
+
quote(symbol: string, ctx: RequestContextLike): Promise<FinnhubQuote>;
|
|
26
|
+
/** `GET /stock/market-status?exchange={exchange}` — live market-open flag. */
|
|
27
|
+
marketStatus(exchange: string, ctx: RequestContextLike): Promise<FinnhubMarketStatus>;
|
|
28
|
+
/** `GET /stock/profile2?symbol={symbol}` — company profile (`{}` if unknown). */
|
|
29
|
+
profile(symbol: string, ctx: RequestContextLike): Promise<FinnhubProfile>;
|
|
30
|
+
/** `GET /stock/metric?symbol={symbol}&metric=all` — fundamentals (~100 keys). */
|
|
31
|
+
metrics(symbol: string, ctx: RequestContextLike): Promise<FinnhubMetricResponse>;
|
|
32
|
+
/** `GET /stock/peers?symbol={symbol}` — sector peer symbols (includes the query). */
|
|
33
|
+
peers(symbol: string, ctx: RequestContextLike): Promise<string[]>;
|
|
34
|
+
/** `GET /stock/earnings?symbol={symbol}` — past quarters, newest first. */
|
|
35
|
+
earnings(symbol: string, ctx: RequestContextLike): Promise<FinnhubEarning[]>;
|
|
36
|
+
/** `GET /calendar/earnings?from={from}&to={to}` — upcoming releases window. */
|
|
37
|
+
earningsCalendar(from: string, to: string, ctx: RequestContextLike): Promise<FinnhubEarningsCalendar>;
|
|
38
|
+
/** `GET /company-news?symbol={symbol}&from={from}&to={to}`. */
|
|
39
|
+
companyNews(symbol: string, from: string, to: string, ctx: RequestContextLike): Promise<FinnhubNewsArticle[]>;
|
|
40
|
+
/** `GET /news?category={category}` — market-wide headlines. */
|
|
41
|
+
marketNews(category: string, ctx: RequestContextLike): Promise<FinnhubNewsArticle[]>;
|
|
42
|
+
/** `GET /stock/recommendation?symbol={symbol}` — analyst trends, empty if no coverage. */
|
|
43
|
+
recommendations(symbol: string, ctx: RequestContextLike): Promise<FinnhubRecommendation[]>;
|
|
44
|
+
/**
|
|
45
|
+
* Core request pipeline: build the authenticated URL, fetch, and parse — all
|
|
46
|
+
* wrapped in `withRetry` so transient failures (429/5xx/network) back off and
|
|
47
|
+
* retry while deterministic failures (401/403) fail fast.
|
|
48
|
+
*
|
|
49
|
+
* `fetchWithTimeout` throws a classified `McpError` on any non-OK status and
|
|
50
|
+
* reduces URLs in errors/logs to origin + pathname, so the `token` query
|
|
51
|
+
* param never reaches a client or a log line. Its default status mapping
|
|
52
|
+
* matches the design for 403 (→ `Forbidden`), 429 (→ `RateLimited`), and 5xx
|
|
53
|
+
* (→ `ServiceUnavailable`); only 401 is re-keyed below from `Unauthorized` to
|
|
54
|
+
* `ConfigurationError` so a bad/missing key fails loud as misconfiguration
|
|
55
|
+
* rather than "no data".
|
|
56
|
+
*/
|
|
57
|
+
private request;
|
|
58
|
+
/**
|
|
59
|
+
* Re-key a thrown `McpError` so a 401 (which `fetchWithTimeout` classifies as
|
|
60
|
+
* `Unauthorized`) becomes a `ConfigurationError` — a bad/missing Finnhub key
|
|
61
|
+
* is a misconfiguration that should fail loud, not a per-request auth failure.
|
|
62
|
+
* Every other error passes through unchanged: `Forbidden` (403),
|
|
63
|
+
* `RateLimited` (429), and `ServiceUnavailable` (5xx/network) already match
|
|
64
|
+
* the design's classification table.
|
|
65
|
+
*/
|
|
66
|
+
private reclassify;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Initialize the singleton. Called from `createApp`'s `setup()`. The
|
|
70
|
+
* `(config, storage)` signature matches the framework's `setup(core)` call
|
|
71
|
+
* convention; this service reads its own config via `getServerConfig()` and
|
|
72
|
+
* holds no tenant state, so neither is retained.
|
|
73
|
+
*/
|
|
74
|
+
export declare function initFinnhubService(_config: AppConfig, _storage: StorageService): void;
|
|
75
|
+
/** Access the singleton. Throws if `setup()` did not initialize it. */
|
|
76
|
+
export declare function getFinnhubService(): FinnhubService;
|
|
77
|
+
//# sourceMappingURL=finnhub-service.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"finnhub-service.d.ts","sourceRoot":"","sources":["../../../src/services/finnhub/finnhub-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,KAAK,EACV,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAYpB;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;;IAQhC,2EAA2E;IAC3E,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI9E,+DAA+D;IAC/D,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAIrE,8EAA8E;IAC9E,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASrF,iFAAiF;IACjF,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;IAIzE,iFAAiF;IACjF,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAShF,qFAAqF;IACrF,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAIjE,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAI5E,+EAA+E;IAC/E,gBAAgB,CACd,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC,uBAAuB,CAAC;IASnC,+DAA+D;IAC/D,WAAW,CACT,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAShC,+DAA+D;IAC/D,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAIpF,0FAA0F;IAC1F,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAS1F;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,OAAO;IAkCf;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;CAUnB;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI,CAErF;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,IAAI,cAAc,CAKlD"}
|