financy 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/LICENSE +190 -0
- package/README.md +139 -0
- package/dist/bin.js +750 -0
- package/dist/chunk-JZO2ARNB.js +492 -0
- package/dist/server-SIRWJMXP.js +199 -0
- package/package.json +65 -0
- package/skills/financy-setup/SKILL.md +177 -0
- package/skills/freshness-check/SKILL.md +139 -0
|
@@ -0,0 +1,492 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
// package.json
|
|
4
|
+
var package_default = {
|
|
5
|
+
name: "financy",
|
|
6
|
+
version: "0.1.0",
|
|
7
|
+
description: "Your Open-Finance accounts, balances and transactions in the terminal \u2014 with an embedded MCP server and agent skills",
|
|
8
|
+
type: "module",
|
|
9
|
+
bin: {
|
|
10
|
+
financy: "dist/bin.js"
|
|
11
|
+
},
|
|
12
|
+
license: "Apache-2.0",
|
|
13
|
+
author: "Open Finance AI <hello@open-finance.ai>",
|
|
14
|
+
homepage: "https://github.com/open-finance-ai/financy#readme",
|
|
15
|
+
bugs: {
|
|
16
|
+
url: "https://github.com/open-finance-ai/financy/issues"
|
|
17
|
+
},
|
|
18
|
+
keywords: [
|
|
19
|
+
"financy",
|
|
20
|
+
"open-finance",
|
|
21
|
+
"open-banking",
|
|
22
|
+
"cli",
|
|
23
|
+
"mcp",
|
|
24
|
+
"claude-code",
|
|
25
|
+
"agent-skills",
|
|
26
|
+
"fintech",
|
|
27
|
+
"israel"
|
|
28
|
+
],
|
|
29
|
+
repository: {
|
|
30
|
+
type: "git",
|
|
31
|
+
url: "git+https://github.com/open-finance-ai/financy.git"
|
|
32
|
+
},
|
|
33
|
+
publishConfig: {
|
|
34
|
+
access: "public",
|
|
35
|
+
provenance: true
|
|
36
|
+
},
|
|
37
|
+
files: [
|
|
38
|
+
"dist",
|
|
39
|
+
"skills"
|
|
40
|
+
],
|
|
41
|
+
engines: {
|
|
42
|
+
node: ">=20"
|
|
43
|
+
},
|
|
44
|
+
scripts: {
|
|
45
|
+
build: "tsup",
|
|
46
|
+
test: "vitest run",
|
|
47
|
+
"test:watch": "vitest",
|
|
48
|
+
typecheck: "tsc --noEmit",
|
|
49
|
+
lint: "eslint .",
|
|
50
|
+
smoke: "node scripts/smoke.mjs",
|
|
51
|
+
prepublishOnly: "npm run build"
|
|
52
|
+
},
|
|
53
|
+
dependencies: {
|
|
54
|
+
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
55
|
+
commander: "^12.1.0"
|
|
56
|
+
},
|
|
57
|
+
devDependencies: {
|
|
58
|
+
"@eslint/js": "^10.0.1",
|
|
59
|
+
"@types/node": "^20.14.0",
|
|
60
|
+
eslint: "^10.7.0",
|
|
61
|
+
globals: "^17.7.0",
|
|
62
|
+
tsup: "^8.2.4",
|
|
63
|
+
typescript: "^5.5.4",
|
|
64
|
+
"typescript-eslint": "^8.65.0",
|
|
65
|
+
undici: "^6.19.8",
|
|
66
|
+
vitest: "^2.0.5"
|
|
67
|
+
}
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
// src/version.ts
|
|
71
|
+
var VERSION = package_default.version;
|
|
72
|
+
var USER_AGENT = `financy-cli/${VERSION}`;
|
|
73
|
+
|
|
74
|
+
// src/config.ts
|
|
75
|
+
import { homedir } from "os";
|
|
76
|
+
import { join } from "path";
|
|
77
|
+
import { mkdir, readFile, writeFile } from "fs/promises";
|
|
78
|
+
var DEFAULT_AUTH_TOKEN_URL = "https://api.open-finance.ai/oauth/token";
|
|
79
|
+
var DEFAULT_API_BASE_URL = "https://api.open-finance.ai/v2";
|
|
80
|
+
var DEFAULT_CHAT_BASE_URL = "https://api.open-finance.ai/chat/chat";
|
|
81
|
+
function resolveConfigDir(env) {
|
|
82
|
+
if (env.FINANCY_CONFIG_DIR) return env.FINANCY_CONFIG_DIR;
|
|
83
|
+
const base = env.XDG_CONFIG_HOME || join(homedir(), ".config");
|
|
84
|
+
return join(base, "financy");
|
|
85
|
+
}
|
|
86
|
+
function resolveEndpoints(env) {
|
|
87
|
+
return {
|
|
88
|
+
authTokenUrl: env.FINANCY_AUTH_URL ?? DEFAULT_AUTH_TOKEN_URL,
|
|
89
|
+
apiBaseUrl: env.FINANCY_API_URL ?? DEFAULT_API_BASE_URL,
|
|
90
|
+
chatBaseUrl: env.FINANCY_CHAT_URL ?? DEFAULT_CHAT_BASE_URL,
|
|
91
|
+
configDir: resolveConfigDir(env)
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
function configFile(configDir) {
|
|
95
|
+
return join(configDir, "config.json");
|
|
96
|
+
}
|
|
97
|
+
async function readCredentialsFile(configDir) {
|
|
98
|
+
try {
|
|
99
|
+
const raw = await readFile(configFile(configDir), "utf8");
|
|
100
|
+
const parsed = JSON.parse(raw);
|
|
101
|
+
return parsed.profiles?.default ?? null;
|
|
102
|
+
} catch {
|
|
103
|
+
return null;
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
async function writeCredentialsFile(configDir, credentials) {
|
|
107
|
+
await mkdir(configDir, { recursive: true, mode: 448 });
|
|
108
|
+
await writeFile(
|
|
109
|
+
configFile(configDir),
|
|
110
|
+
JSON.stringify({ profiles: { default: credentials } }, null, 2),
|
|
111
|
+
{ mode: 384 }
|
|
112
|
+
);
|
|
113
|
+
}
|
|
114
|
+
async function loadConfig(env) {
|
|
115
|
+
const endpoints = resolveEndpoints(env);
|
|
116
|
+
const file = await readCredentialsFile(endpoints.configDir) ?? {};
|
|
117
|
+
const clientId = env.FINANCY_CLIENT_ID ?? file.clientId;
|
|
118
|
+
const clientSecret = env.FINANCY_CLIENT_SECRET ?? file.clientSecret;
|
|
119
|
+
const userId = env.FINANCY_USER_ID ?? file.userId;
|
|
120
|
+
const missing = [];
|
|
121
|
+
if (!clientId) missing.push("FINANCY_CLIENT_ID");
|
|
122
|
+
if (!clientSecret) missing.push("FINANCY_CLIENT_SECRET");
|
|
123
|
+
if (!userId) missing.push("FINANCY_USER_ID");
|
|
124
|
+
if (!clientId || !clientSecret || !userId) return { ok: false, missing };
|
|
125
|
+
return {
|
|
126
|
+
ok: true,
|
|
127
|
+
config: { clientId, clientSecret, userId, ...endpoints }
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
// src/exit-codes.ts
|
|
132
|
+
var EXIT = {
|
|
133
|
+
OK: 0,
|
|
134
|
+
UNEXPECTED: 1,
|
|
135
|
+
USAGE: 2,
|
|
136
|
+
AUTH: 3,
|
|
137
|
+
PLAN: 4,
|
|
138
|
+
CREDITS: 5,
|
|
139
|
+
NOT_FOUND: 6,
|
|
140
|
+
API: 7
|
|
141
|
+
};
|
|
142
|
+
|
|
143
|
+
// src/errors.ts
|
|
144
|
+
var CliError = class extends Error {
|
|
145
|
+
code;
|
|
146
|
+
exitCode;
|
|
147
|
+
extra;
|
|
148
|
+
constructor(exitCode, code, message, extra = {}) {
|
|
149
|
+
super(message);
|
|
150
|
+
this.name = "CliError";
|
|
151
|
+
this.code = code;
|
|
152
|
+
this.exitCode = exitCode;
|
|
153
|
+
this.extra = extra;
|
|
154
|
+
}
|
|
155
|
+
};
|
|
156
|
+
var authFailed = (message = "authentication failed \u2014 check your credentials or run financy setup") => new CliError(EXIT.AUTH, "AUTH_FAILED", message);
|
|
157
|
+
var planNotEligible = () => new CliError(
|
|
158
|
+
EXIT.PLAN,
|
|
159
|
+
"NOT_AVAILABLE_ON_PLAN",
|
|
160
|
+
"the API is available on Starter and Pro plans \u2014 upgrade in Financy \u2192 Settings \u2192 Plan"
|
|
161
|
+
);
|
|
162
|
+
var forbidden = (detail) => new CliError(EXIT.PLAN, "FORBIDDEN", `the API denied this request (403): ${detail}`);
|
|
163
|
+
var insufficientCredits = (cost, balance) => new CliError(
|
|
164
|
+
EXIT.CREDITS,
|
|
165
|
+
"INSUFFICIENT_CREDITS",
|
|
166
|
+
`an initiated refresh costs ${cost} credits; you have ${balance}`,
|
|
167
|
+
{ cost, balance }
|
|
168
|
+
);
|
|
169
|
+
var noRefreshableConnections = (message = "no connections are eligible for refresh") => new CliError(EXIT.UNEXPECTED, "NO_REFRESHABLE_CONNECTIONS", message);
|
|
170
|
+
var apiUnavailable = (message = "the Open-Finance API is unavailable \u2014 check your connection and try again") => new CliError(EXIT.API, "API_UNAVAILABLE", message);
|
|
171
|
+
|
|
172
|
+
// src/http.ts
|
|
173
|
+
async function httpFetch(url, init) {
|
|
174
|
+
try {
|
|
175
|
+
return await fetch(url, init);
|
|
176
|
+
} catch {
|
|
177
|
+
throw apiUnavailable();
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
// src/token-store.ts
|
|
182
|
+
import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
|
|
183
|
+
import { join as join2 } from "path";
|
|
184
|
+
function jwtExp(token) {
|
|
185
|
+
const payload = token.split(".")[1];
|
|
186
|
+
if (!payload) return null;
|
|
187
|
+
try {
|
|
188
|
+
const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
|
|
189
|
+
return typeof decoded.exp === "number" ? decoded.exp : null;
|
|
190
|
+
} catch {
|
|
191
|
+
return null;
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
function tokenFile(configDir) {
|
|
195
|
+
return join2(configDir, "token.json");
|
|
196
|
+
}
|
|
197
|
+
async function readCachedToken(configDir) {
|
|
198
|
+
try {
|
|
199
|
+
const raw = await readFile2(tokenFile(configDir), "utf8");
|
|
200
|
+
const parsed = JSON.parse(raw);
|
|
201
|
+
if (typeof parsed.accessToken === "string" && typeof parsed.exp === "number") {
|
|
202
|
+
return { accessToken: parsed.accessToken, exp: parsed.exp };
|
|
203
|
+
}
|
|
204
|
+
return null;
|
|
205
|
+
} catch {
|
|
206
|
+
return null;
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
async function writeCachedToken(configDir, token) {
|
|
210
|
+
await mkdir2(configDir, { recursive: true, mode: 448 });
|
|
211
|
+
await writeFile2(tokenFile(configDir), JSON.stringify(token), { mode: 384 });
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
// src/auth.ts
|
|
215
|
+
var EXPIRY_SKEW_SECONDS = 30;
|
|
216
|
+
async function mintToken(config) {
|
|
217
|
+
const res = await httpFetch(config.authTokenUrl, {
|
|
218
|
+
method: "POST",
|
|
219
|
+
headers: {
|
|
220
|
+
"content-type": "application/json",
|
|
221
|
+
"user-agent": USER_AGENT
|
|
222
|
+
},
|
|
223
|
+
body: JSON.stringify({
|
|
224
|
+
userId: config.userId,
|
|
225
|
+
clientId: config.clientId,
|
|
226
|
+
clientSecret: config.clientSecret
|
|
227
|
+
})
|
|
228
|
+
});
|
|
229
|
+
if (!res.ok) {
|
|
230
|
+
const detail = (await res.text().catch(() => "")).slice(0, 400);
|
|
231
|
+
throw authFailed(
|
|
232
|
+
`token endpoint ${config.authTokenUrl} returned HTTP ${res.status}` + (detail ? `: ${detail}` : "") + " \u2014 check credentials, or set FINANCY_AUTH_URL if the endpoint differs"
|
|
233
|
+
);
|
|
234
|
+
}
|
|
235
|
+
const body = await res.json().catch(() => ({}));
|
|
236
|
+
if (!body.accessToken) {
|
|
237
|
+
const keys = body && typeof body === "object" ? Object.keys(body) : [];
|
|
238
|
+
throw authFailed(
|
|
239
|
+
`token endpoint returned 200 but no "accessToken" field; response keys: [${keys.join(", ")}]`
|
|
240
|
+
);
|
|
241
|
+
}
|
|
242
|
+
return body.accessToken;
|
|
243
|
+
}
|
|
244
|
+
async function mintAndCache(config) {
|
|
245
|
+
const accessToken = await mintToken(config);
|
|
246
|
+
const exp = jwtExp(accessToken);
|
|
247
|
+
if (exp !== null) {
|
|
248
|
+
await writeCachedToken(config.configDir, { accessToken, exp });
|
|
249
|
+
}
|
|
250
|
+
return accessToken;
|
|
251
|
+
}
|
|
252
|
+
async function getAccessToken(config, now) {
|
|
253
|
+
const cached = await readCachedToken(config.configDir);
|
|
254
|
+
const nowSeconds = Math.floor(now.getTime() / 1e3);
|
|
255
|
+
if (cached && cached.exp - EXPIRY_SKEW_SECONDS > nowSeconds) {
|
|
256
|
+
return cached.accessToken;
|
|
257
|
+
}
|
|
258
|
+
return mintAndCache(config);
|
|
259
|
+
}
|
|
260
|
+
async function authorized(config, now, request) {
|
|
261
|
+
const token = await getAccessToken(config, now);
|
|
262
|
+
try {
|
|
263
|
+
return await request(token);
|
|
264
|
+
} catch (error) {
|
|
265
|
+
if (error instanceof CliError && error.code === "AUTH_FAILED") {
|
|
266
|
+
return await request(await mintAndCache(config));
|
|
267
|
+
}
|
|
268
|
+
throw error;
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
// src/api.ts
|
|
273
|
+
function authHeaders(token) {
|
|
274
|
+
return { authorization: `Bearer ${token}`, "user-agent": USER_AGENT };
|
|
275
|
+
}
|
|
276
|
+
async function ensureOk(res) {
|
|
277
|
+
if (res.ok) return;
|
|
278
|
+
if (res.status === 401) throw authFailed();
|
|
279
|
+
const detail = (await res.text().catch(() => "")).slice(0, 300);
|
|
280
|
+
if (res.status === 403) {
|
|
281
|
+
if (!detail || /NOT_AVAILABLE_ON_PLAN|plan/i.test(detail)) throw planNotEligible();
|
|
282
|
+
throw forbidden(detail);
|
|
283
|
+
}
|
|
284
|
+
throw apiUnavailable(
|
|
285
|
+
`the API returned HTTP ${res.status}${detail ? `: ${detail}` : ""}`
|
|
286
|
+
);
|
|
287
|
+
}
|
|
288
|
+
function debugBody(path, body) {
|
|
289
|
+
if (process.env.FINANCY_DEBUG) {
|
|
290
|
+
process.stderr.write(`[financy:debug] ${path} \u2192
|
|
291
|
+
${JSON.stringify(body, null, 2)}
|
|
292
|
+
`);
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
async function getPage(config, token, path, query = {}) {
|
|
296
|
+
const url = new URL(config.apiBaseUrl + path);
|
|
297
|
+
for (const [key, value] of Object.entries(query)) {
|
|
298
|
+
if (value !== void 0) url.searchParams.set(key, value);
|
|
299
|
+
}
|
|
300
|
+
const res = await httpFetch(url.toString(), { headers: authHeaders(token) });
|
|
301
|
+
await ensureOk(res);
|
|
302
|
+
const raw = await res.json().catch(() => ({}));
|
|
303
|
+
debugBody(path, raw);
|
|
304
|
+
return normalizePage(raw);
|
|
305
|
+
}
|
|
306
|
+
function normalizePage(raw) {
|
|
307
|
+
if (Array.isArray(raw)) return { items: raw, nextPage: null, count: raw.length };
|
|
308
|
+
const obj = raw ?? {};
|
|
309
|
+
const items = Array.isArray(obj.items) ? obj.items : [];
|
|
310
|
+
return { items, nextPage: obj.nextPage ?? null, count: obj.count ?? items.length };
|
|
311
|
+
}
|
|
312
|
+
async function getById(config, token, path) {
|
|
313
|
+
const res = await httpFetch(config.apiBaseUrl + path, { headers: authHeaders(token) });
|
|
314
|
+
if (res.status === 404) return null;
|
|
315
|
+
await ensureOk(res);
|
|
316
|
+
const body = await res.json();
|
|
317
|
+
debugBody(path, body);
|
|
318
|
+
if (body && typeof body === "object" && Object.keys(body).length === 0) return null;
|
|
319
|
+
return body;
|
|
320
|
+
}
|
|
321
|
+
async function postRefresh(config, token) {
|
|
322
|
+
const res = await httpFetch(config.chatBaseUrl + "/connections/refresh", {
|
|
323
|
+
method: "POST",
|
|
324
|
+
headers: authHeaders(token)
|
|
325
|
+
});
|
|
326
|
+
if (res.status === 401) throw authFailed();
|
|
327
|
+
if (res.status === 402) {
|
|
328
|
+
const body = await res.json().catch(() => ({}));
|
|
329
|
+
throw insufficientCredits(body.cost ?? 20, body.balance ?? 0);
|
|
330
|
+
}
|
|
331
|
+
if (res.status === 409) {
|
|
332
|
+
const body = await res.json().catch(() => ({}));
|
|
333
|
+
throw noRefreshableConnections(body.message);
|
|
334
|
+
}
|
|
335
|
+
await ensureOk(res);
|
|
336
|
+
return await res.json();
|
|
337
|
+
}
|
|
338
|
+
async function getConnections(config, token) {
|
|
339
|
+
return getPage(config, token, "/connections");
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
// src/core/status.ts
|
|
343
|
+
var STALE_THRESHOLD_DAYS = 2;
|
|
344
|
+
function toRow(c) {
|
|
345
|
+
return {
|
|
346
|
+
provider: c.providerId ?? null,
|
|
347
|
+
status: c.status,
|
|
348
|
+
fresh: c.lastFetchedDataDate ?? null,
|
|
349
|
+
expires: c.expiryDate ?? null,
|
|
350
|
+
accounts: (c.accounts ?? 0) + (c.cards ?? 0) + (c.savings ?? 0) + (c.loans ?? 0) + (c.securities ?? 0)
|
|
351
|
+
};
|
|
352
|
+
}
|
|
353
|
+
async function fetchStatus(config, now) {
|
|
354
|
+
const { items } = await authorized(config, now, (token) => getConnections(config, token));
|
|
355
|
+
return {
|
|
356
|
+
data: items.map(toRow),
|
|
357
|
+
staleThresholdDays: STALE_THRESHOLD_DAYS,
|
|
358
|
+
connections: items
|
|
359
|
+
};
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
// src/core/refresh.ts
|
|
363
|
+
async function fetchRefresh(config, now) {
|
|
364
|
+
const result = await authorized(config, now, (token) => postRefresh(config, token));
|
|
365
|
+
return { data: result };
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
// src/core/read.ts
|
|
369
|
+
var upper = (v) => v === void 0 ? void 0 : v.toUpperCase();
|
|
370
|
+
async function fetchPage(config, now, path, query) {
|
|
371
|
+
return authorized(config, now, (token) => getPage(config, token, path, query));
|
|
372
|
+
}
|
|
373
|
+
async function collectAll(config, now, path, query) {
|
|
374
|
+
const data = [];
|
|
375
|
+
let cursor = query.nextPage;
|
|
376
|
+
do {
|
|
377
|
+
const page = await fetchPage(config, now, path, { ...query, nextPage: cursor });
|
|
378
|
+
data.push(...page.items);
|
|
379
|
+
cursor = page.nextPage ?? void 0;
|
|
380
|
+
} while (cursor);
|
|
381
|
+
return { data, nextPage: null, count: data.length };
|
|
382
|
+
}
|
|
383
|
+
async function list(config, now, path, query, all) {
|
|
384
|
+
if (all) return collectAll(config, now, path, query);
|
|
385
|
+
const page = await fetchPage(config, now, path, query);
|
|
386
|
+
return { data: page.items, count: page.count, nextPage: page.nextPage };
|
|
387
|
+
}
|
|
388
|
+
async function getOne(config, now, path, notFound2) {
|
|
389
|
+
const resource = await authorized(
|
|
390
|
+
config,
|
|
391
|
+
now,
|
|
392
|
+
(token) => getById(config, token, path)
|
|
393
|
+
);
|
|
394
|
+
if (resource === null) throw notFound2;
|
|
395
|
+
return { data: resource };
|
|
396
|
+
}
|
|
397
|
+
var notFound = (code, message) => new CliError(EXIT.NOT_FOUND, code, message);
|
|
398
|
+
function fetchConnections(config, now, args) {
|
|
399
|
+
return list(config, now, "/connections", { limit: args.limit, nextPage: args.cursor }, !!args.all);
|
|
400
|
+
}
|
|
401
|
+
function fetchConnection(config, now, id) {
|
|
402
|
+
return getOne(
|
|
403
|
+
config,
|
|
404
|
+
now,
|
|
405
|
+
`/connections/${encodeURIComponent(id)}`,
|
|
406
|
+
notFound("CONNECTION_NOT_FOUND", `no connection ${id} in your scope`)
|
|
407
|
+
);
|
|
408
|
+
}
|
|
409
|
+
function fetchAccounts(config, now, args) {
|
|
410
|
+
return list(
|
|
411
|
+
config,
|
|
412
|
+
now,
|
|
413
|
+
"/data/accounts",
|
|
414
|
+
{
|
|
415
|
+
accountType: upper(args.type),
|
|
416
|
+
connectionId: args.connection,
|
|
417
|
+
limit: args.limit,
|
|
418
|
+
nextPage: args.cursor
|
|
419
|
+
},
|
|
420
|
+
!!args.all
|
|
421
|
+
);
|
|
422
|
+
}
|
|
423
|
+
function fetchAccount(config, now, id) {
|
|
424
|
+
return getOne(
|
|
425
|
+
config,
|
|
426
|
+
now,
|
|
427
|
+
`/data/accounts/${encodeURIComponent(id)}`,
|
|
428
|
+
notFound("ACCOUNT_NOT_FOUND", `no account ${id} in your scope`)
|
|
429
|
+
);
|
|
430
|
+
}
|
|
431
|
+
function fetchTransactions(config, now, args) {
|
|
432
|
+
return list(
|
|
433
|
+
config,
|
|
434
|
+
now,
|
|
435
|
+
"/data/transactions",
|
|
436
|
+
{
|
|
437
|
+
dateFrom: args.from,
|
|
438
|
+
dateTo: args.to,
|
|
439
|
+
accountId: args.account,
|
|
440
|
+
connectionId: args.connection,
|
|
441
|
+
type: upper(args.type),
|
|
442
|
+
limit: args.limit,
|
|
443
|
+
nextPage: args.cursor
|
|
444
|
+
},
|
|
445
|
+
!!args.all
|
|
446
|
+
);
|
|
447
|
+
}
|
|
448
|
+
function fetchTransaction(config, now, id) {
|
|
449
|
+
return getOne(
|
|
450
|
+
config,
|
|
451
|
+
now,
|
|
452
|
+
`/data/transactions/${encodeURIComponent(id)}`,
|
|
453
|
+
notFound("TRANSACTION_NOT_FOUND", `no transaction ${id} in your scope`)
|
|
454
|
+
);
|
|
455
|
+
}
|
|
456
|
+
function fetchCategories(config, now) {
|
|
457
|
+
return authorized(
|
|
458
|
+
config,
|
|
459
|
+
now,
|
|
460
|
+
(token) => getById(config, token, "/data/transaction-categories")
|
|
461
|
+
);
|
|
462
|
+
}
|
|
463
|
+
function fetchProviders(config, now) {
|
|
464
|
+
return list(config, now, "/providers", {}, false);
|
|
465
|
+
}
|
|
466
|
+
function fetchBranches(config, now) {
|
|
467
|
+
return list(config, now, "/bank-branches", {}, false);
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
export {
|
|
471
|
+
resolveEndpoints,
|
|
472
|
+
readCredentialsFile,
|
|
473
|
+
writeCredentialsFile,
|
|
474
|
+
loadConfig,
|
|
475
|
+
VERSION,
|
|
476
|
+
EXIT,
|
|
477
|
+
CliError,
|
|
478
|
+
getConnections,
|
|
479
|
+
mintToken,
|
|
480
|
+
STALE_THRESHOLD_DAYS,
|
|
481
|
+
fetchStatus,
|
|
482
|
+
fetchRefresh,
|
|
483
|
+
fetchConnections,
|
|
484
|
+
fetchConnection,
|
|
485
|
+
fetchAccounts,
|
|
486
|
+
fetchAccount,
|
|
487
|
+
fetchTransactions,
|
|
488
|
+
fetchTransaction,
|
|
489
|
+
fetchCategories,
|
|
490
|
+
fetchProviders,
|
|
491
|
+
fetchBranches
|
|
492
|
+
};
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import {
|
|
3
|
+
CliError,
|
|
4
|
+
EXIT,
|
|
5
|
+
VERSION,
|
|
6
|
+
fetchAccount,
|
|
7
|
+
fetchAccounts,
|
|
8
|
+
fetchBranches,
|
|
9
|
+
fetchCategories,
|
|
10
|
+
fetchConnection,
|
|
11
|
+
fetchConnections,
|
|
12
|
+
fetchProviders,
|
|
13
|
+
fetchRefresh,
|
|
14
|
+
fetchStatus,
|
|
15
|
+
fetchTransaction,
|
|
16
|
+
fetchTransactions,
|
|
17
|
+
loadConfig
|
|
18
|
+
} from "./chunk-JZO2ARNB.js";
|
|
19
|
+
|
|
20
|
+
// src/mcp/server.ts
|
|
21
|
+
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
|
|
22
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
23
|
+
import {
|
|
24
|
+
ListToolsRequestSchema,
|
|
25
|
+
CallToolRequestSchema
|
|
26
|
+
} from "@modelcontextprotocol/sdk/types.js";
|
|
27
|
+
|
|
28
|
+
// src/mcp/tools.ts
|
|
29
|
+
var str = (v) => v == null ? void 0 : String(v);
|
|
30
|
+
var bool = (v) => v === true;
|
|
31
|
+
function requireId(args) {
|
|
32
|
+
const id = args.id;
|
|
33
|
+
if (typeof id !== "string" || id.length === 0) {
|
|
34
|
+
throw new CliError(EXIT.USAGE, "MISSING_ARGUMENT", "the `id` argument is required");
|
|
35
|
+
}
|
|
36
|
+
return id;
|
|
37
|
+
}
|
|
38
|
+
var PAGING = {
|
|
39
|
+
limit: { type: "number", description: "page size (defaults to the API default)" },
|
|
40
|
+
cursor: { type: "string", description: "opaque nextPage cursor from a prior call" },
|
|
41
|
+
all: { type: "boolean", description: "auto-paginate to the end (ignores cursor/limit paging)" }
|
|
42
|
+
};
|
|
43
|
+
var NO_ARGS = { type: "object", properties: {} };
|
|
44
|
+
var idSchema = (noun) => ({
|
|
45
|
+
type: "object",
|
|
46
|
+
properties: { id: { type: "string", description: `the ${noun} id` } },
|
|
47
|
+
required: ["id"]
|
|
48
|
+
});
|
|
49
|
+
var listArgs = (a) => ({
|
|
50
|
+
limit: str(a.limit),
|
|
51
|
+
cursor: str(a.cursor),
|
|
52
|
+
all: bool(a.all)
|
|
53
|
+
});
|
|
54
|
+
var TOOLS = [
|
|
55
|
+
{
|
|
56
|
+
name: "list_connections",
|
|
57
|
+
description: "List the user's bank/card connections and their fetch state (status, data-through date, consent expiry, per-type counts). Start here to see what is connected. Supports limit/cursor paging and all.",
|
|
58
|
+
inputSchema: { type: "object", properties: { ...PAGING } },
|
|
59
|
+
run: (a, ctx) => fetchConnections(ctx.config, ctx.now, listArgs(a))
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
name: "get_connection",
|
|
63
|
+
description: "Read a single connection by id (from list_connections). Errors CONNECTION_NOT_FOUND if it is not in the user's scope.",
|
|
64
|
+
inputSchema: idSchema("connection"),
|
|
65
|
+
run: (a, ctx) => fetchConnection(ctx.config, ctx.now, requireId(a))
|
|
66
|
+
},
|
|
67
|
+
{
|
|
68
|
+
name: "list_accounts",
|
|
69
|
+
description: "List accounts with balances (securities embedded). Filter by type (CHECKING|CARD|LOAN|SAVINGS|SECURITY) or connection. Supports limit/cursor/all.",
|
|
70
|
+
inputSchema: {
|
|
71
|
+
type: "object",
|
|
72
|
+
properties: {
|
|
73
|
+
type: { type: "string", description: "CHECKING|CARD|LOAN|SAVINGS|SECURITY" },
|
|
74
|
+
connection: { type: "string", description: "filter to one connection id" },
|
|
75
|
+
...PAGING
|
|
76
|
+
}
|
|
77
|
+
},
|
|
78
|
+
run: (a, ctx) => fetchAccounts(ctx.config, ctx.now, {
|
|
79
|
+
...listArgs(a),
|
|
80
|
+
type: str(a.type),
|
|
81
|
+
connection: str(a.connection)
|
|
82
|
+
})
|
|
83
|
+
},
|
|
84
|
+
{
|
|
85
|
+
name: "get_account",
|
|
86
|
+
description: "Read a single account by id (from list_accounts). Errors ACCOUNT_NOT_FOUND if not in scope.",
|
|
87
|
+
inputSchema: idSchema("account"),
|
|
88
|
+
run: (a, ctx) => fetchAccount(ctx.config, ctx.now, requireId(a))
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
name: "list_transactions",
|
|
92
|
+
description: "List transactions, most useful with filters: from/to (YYYY-MM-DD), account, connection, type (BANK|CARD). Page with limit/cursor or fetch everything with all. Hebrew merchant names are returned as-is.",
|
|
93
|
+
inputSchema: {
|
|
94
|
+
type: "object",
|
|
95
|
+
properties: {
|
|
96
|
+
from: { type: "string", description: "earliest transaction date (YYYY-MM-DD)" },
|
|
97
|
+
to: { type: "string", description: "latest transaction date (YYYY-MM-DD)" },
|
|
98
|
+
account: { type: "string", description: "filter to one account id" },
|
|
99
|
+
connection: { type: "string", description: "filter to one connection id" },
|
|
100
|
+
type: { type: "string", description: "BANK|CARD" },
|
|
101
|
+
...PAGING
|
|
102
|
+
}
|
|
103
|
+
},
|
|
104
|
+
run: (a, ctx) => fetchTransactions(ctx.config, ctx.now, {
|
|
105
|
+
...listArgs(a),
|
|
106
|
+
from: str(a.from),
|
|
107
|
+
to: str(a.to),
|
|
108
|
+
account: str(a.account),
|
|
109
|
+
connection: str(a.connection),
|
|
110
|
+
type: str(a.type)
|
|
111
|
+
})
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
name: "get_transaction",
|
|
115
|
+
description: "Read a single transaction by id (from list_transactions). Errors TRANSACTION_NOT_FOUND if not in scope.",
|
|
116
|
+
inputSchema: idSchema("transaction"),
|
|
117
|
+
run: (a, ctx) => fetchTransaction(ctx.config, ctx.now, requireId(a))
|
|
118
|
+
},
|
|
119
|
+
{
|
|
120
|
+
name: "list_categories",
|
|
121
|
+
description: "The static transaction-category taxonomy (English + Hebrew). Use to interpret transaction category fields. No arguments.",
|
|
122
|
+
inputSchema: NO_ARGS,
|
|
123
|
+
run: async (_a, ctx) => ({ data: await fetchCategories(ctx.config, ctx.now) })
|
|
124
|
+
},
|
|
125
|
+
{
|
|
126
|
+
name: "list_providers",
|
|
127
|
+
description: "Reference data: the list of banks/providers, to resolve providerId values. No arguments.",
|
|
128
|
+
inputSchema: NO_ARGS,
|
|
129
|
+
run: (_a, ctx) => fetchProviders(ctx.config, ctx.now)
|
|
130
|
+
},
|
|
131
|
+
{
|
|
132
|
+
name: "list_bank_branches",
|
|
133
|
+
description: "Reference data: bank branches. No arguments (this route takes no paging).",
|
|
134
|
+
inputSchema: NO_ARGS,
|
|
135
|
+
run: (_a, ctx) => fetchBranches(ctx.config, ctx.now)
|
|
136
|
+
},
|
|
137
|
+
{
|
|
138
|
+
name: "get_status",
|
|
139
|
+
description: "Per-connection freshness rollup: for each connection its status, data-through date, consent expiry, and account count, plus staleThresholdDays. Call this first to decide whether data is fresh enough before answering questions about balances or transactions.",
|
|
140
|
+
inputSchema: NO_ARGS,
|
|
141
|
+
run: async (_a, ctx) => {
|
|
142
|
+
const { data, staleThresholdDays } = await fetchStatus(ctx.config, ctx.now);
|
|
143
|
+
return { data, staleThresholdDays };
|
|
144
|
+
}
|
|
145
|
+
},
|
|
146
|
+
{
|
|
147
|
+
name: "refresh_connections",
|
|
148
|
+
description: "Trigger an on-demand refresh of ALL connections (org-wide). This COSTS 20 credits \u2014 always confirm with the user before calling it. Data lands after a few minutes; poll get_status to watch progress. Returns the refresh outcome (accepted / already_running).",
|
|
149
|
+
inputSchema: NO_ARGS,
|
|
150
|
+
run: (_a, ctx) => fetchRefresh(ctx.config, ctx.now)
|
|
151
|
+
}
|
|
152
|
+
];
|
|
153
|
+
var BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
|
|
154
|
+
function errorEnvelope(error) {
|
|
155
|
+
const e = error instanceof CliError ? error : new CliError(EXIT.UNEXPECTED, "UNEXPECTED", String(error?.message ?? error));
|
|
156
|
+
return { error: { code: e.code, message: e.message, ...e.extra } };
|
|
157
|
+
}
|
|
158
|
+
async function callTool(name, args, io) {
|
|
159
|
+
try {
|
|
160
|
+
const tool = BY_NAME.get(name);
|
|
161
|
+
if (!tool) {
|
|
162
|
+
throw new CliError(EXIT.USAGE, "UNKNOWN_TOOL", `no tool named '${name}'`);
|
|
163
|
+
}
|
|
164
|
+
const result = await loadConfig(io.env);
|
|
165
|
+
if (!result.ok) {
|
|
166
|
+
throw new CliError(
|
|
167
|
+
EXIT.AUTH,
|
|
168
|
+
"NOT_CONFIGURED",
|
|
169
|
+
`missing ${result.missing.join(", ")} \u2014 run financy setup`
|
|
170
|
+
);
|
|
171
|
+
}
|
|
172
|
+
return await tool.run(args ?? {}, { config: result.config, now: io.now ?? /* @__PURE__ */ new Date() });
|
|
173
|
+
} catch (error) {
|
|
174
|
+
return errorEnvelope(error);
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
// src/mcp/server.ts
|
|
179
|
+
async function startMcpServer(env) {
|
|
180
|
+
const server = new Server(
|
|
181
|
+
{ name: "financy", version: VERSION },
|
|
182
|
+
{ capabilities: { tools: {} } }
|
|
183
|
+
);
|
|
184
|
+
server.setRequestHandler(ListToolsRequestSchema, () => ({
|
|
185
|
+
tools: TOOLS.map((t) => ({
|
|
186
|
+
name: t.name,
|
|
187
|
+
description: t.description,
|
|
188
|
+
inputSchema: t.inputSchema
|
|
189
|
+
}))
|
|
190
|
+
}));
|
|
191
|
+
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
192
|
+
const result = await callTool(request.params.name, request.params.arguments ?? {}, { env });
|
|
193
|
+
return { content: [{ type: "text", text: JSON.stringify(result) }] };
|
|
194
|
+
});
|
|
195
|
+
await server.connect(new StdioServerTransport());
|
|
196
|
+
}
|
|
197
|
+
export {
|
|
198
|
+
startMcpServer
|
|
199
|
+
};
|