@daften/fireflyiii-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerAllTools } from './tools/index.js';
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export function createServer(client, filterOptions = {}) {
+    const server = new McpServer({
+        name: 'firefly-iii-mcp',
+        version: pkg.version,
+    });
+    registerAllTools(server, client, filterOptions);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,gBAAgB,EAA0B,MAAM,kBAAkB,CAAC;AAE5E,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAwB,CAAC;AAEjH,MAAM,UAAU,YAAY,CAAC,MAAqB,EAAE,gBAAmC,EAAE;IACvF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,GAAG,CAAC,OAAO;KACrB,CAAC,CAAC;IAEH,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;IAEhD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tools/_annotations.d.ts

@@ -0,0 +1,17 @@
+export declare const READ_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly openWorldHint: true;
+    readonly idempotentHint: true;
+};
+export declare const WRITE_ANNOTATIONS: {
+    readonly openWorldHint: true;
+};
+export declare const UPDATE_ANNOTATIONS: {
+    readonly openWorldHint: true;
+    readonly idempotentHint: true;
+};
+export declare const DELETE_ANNOTATIONS: {
+    readonly destructiveHint: true;
+    readonly openWorldHint: true;
+};
+//# sourceMappingURL=_annotations.d.ts.map

package/dist/tools/_annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_annotations.d.ts","sourceRoot":"","sources":["../../src/tools/_annotations.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AAEX,eAAO,MAAM,iBAAiB;;CAAmC,CAAC;AAClE,eAAO,MAAM,kBAAkB;;;CAAyD,CAAC;AACzF,eAAO,MAAM,kBAAkB;;;CAA0D,CAAC"}

package/dist/tools/_annotations.js

@@ -0,0 +1,9 @@
+export const READ_ANNOTATIONS = {
+    readOnlyHint: true,
+    openWorldHint: true,
+    idempotentHint: true,
+};
+export const WRITE_ANNOTATIONS = { openWorldHint: true };
+export const UPDATE_ANNOTATIONS = { openWorldHint: true, idempotentHint: true };
+export const DELETE_ANNOTATIONS = { destructiveHint: true, openWorldHint: true };
+//# sourceMappingURL=_annotations.js.map

package/dist/tools/_annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_annotations.js","sourceRoot":"","sources":["../../src/tools/_annotations.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,YAAY,EAAE,IAAI;IAClB,aAAa,EAAE,IAAI;IACnB,cAAc,EAAE,IAAI;CACZ,CAAC;AAEX,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,aAAa,EAAE,IAAI,EAAW,CAAC;AAClE,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAW,CAAC;AACzF,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAW,CAAC"}

package/dist/tools/_helpers.d.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+type ToolConfig = {
+    title?: string;
+    description?: string;
+    inputSchema?: Record<string, z.ZodTypeAny>;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+};
+export declare function defineTool(server: McpServer, name: string, config: ToolConfig, fetch: (args: Record<string, unknown>) => Promise<unknown>): void;
+export declare const dateSchema: z.ZodString;
+export {};
+//# sourceMappingURL=_helpers.d.ts.map

package/dist/tools/_helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_helpers.d.ts","sourceRoot":"","sources":["../../src/tools/_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,KAAK,UAAU,GAAG;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;IAC3C,WAAW,CAAC,EAAE;QACZ,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACH,CAAC;AAEF,wBAAgB,UAAU,CACxB,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GACzD,IAAI,CAkBN;AAED,eAAO,MAAM,UAAU,aAAqE,CAAC"}

package/dist/tools/_helpers.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { formatError } from '../client.js';
+export function defineTool(server, name, config, fetch) {
+    // registerTool is generic in the SDK; the cast avoids fighting its complex overload resolution
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    server.registerTool(name, config, async (args) => {
+        try {
+            const result = await fetch(args);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: formatError(err) }], isError: true };
+        }
+    });
+}
+export const dateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be YYYY-MM-DD');
+//# sourceMappingURL=_helpers.js.map

package/dist/tools/_helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_helpers.js","sourceRoot":"","sources":["../../src/tools/_helpers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAc3C,MAAM,UAAU,UAAU,CACxB,MAAiB,EACjB,IAAY,EACZ,MAAkB,EAClB,KAA0D;IAE1D,+FAA+F;IAC/F,8DAA8D;IAC7D,MAAc,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAA6B,EAAE,EAAE;QACjF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;qBAC5E;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACzF,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,EAAE,yBAAyB,CAAC,CAAC"}

package/dist/tools/accounts.d.ts

@@ -0,0 +1,48 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { FireflyClient } from '../client.js';
+import { type UnwrappedList, type UnwrappedSingle } from '../transform.js';
+export declare function fetchAccounts(client: FireflyClient, params: {
+    type?: string;
+    page?: number;
+    limit?: number;
+}): Promise<UnwrappedList>;
+export declare function fetchAccount(client: FireflyClient, id: string): Promise<UnwrappedSingle>;
+export declare function createAccount(client: FireflyClient, params: {
+    name: string;
+    type: 'asset' | 'expense' | 'revenue' | 'liability';
+    currency_code?: string;
+    iban?: string;
+    opening_balance?: string;
+    opening_balance_date?: string;
+    include_net_worth?: boolean;
+    notes?: string;
+}): Promise<UnwrappedSingle>;
+export declare function updateAccount(client: FireflyClient, id: string, params: {
+    name?: string;
+    currency_code?: string;
+    iban?: string;
+    opening_balance?: string;
+    opening_balance_date?: string;
+    include_net_worth?: boolean;
+    active?: boolean;
+    notes?: string;
+}): Promise<UnwrappedSingle>;
+export declare function deleteAccount(client: FireflyClient, id: string): Promise<{
+    deleted: true;
+    id: string;
+}>;
+export declare function fetchAccountTransactions(client: FireflyClient, id: string, params: {
+    start?: string;
+    end?: string;
+    type?: string;
+    page?: number;
+    limit?: number;
+}): Promise<UnwrappedList>;
+export declare function searchAccounts(client: FireflyClient, params: {
+    query: string;
+    field?: string;
+    page?: number;
+    limit?: number;
+}): Promise<UnwrappedList>;
+export declare function registerAccountTools(server: McpServer, client: FireflyClient): void;
+//# sourceMappingURL=accounts.d.ts.map

package/dist/tools/accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../../src/tools/accounts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,eAAe,EAGrB,MAAM,iBAAiB,CAAC;AAKzB,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD,OAAO,CAAC,aAAa,CAAC,CAKxB;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAG9F;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE;IACN,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACA,OAAO,CAAC,eAAe,CAAC,CAG1B;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,EACrB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE;IACN,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACA,OAAO,CAAC,eAAe,CAAC,CAG1B;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAG7G;AAED,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,aAAa,EACrB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACrF,OAAO,CAAC,aAAa,CAAC,CAOxB;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACvE,OAAO,CAAC,aAAa,CAAC,CAKxB;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAwJnF"}

package/dist/tools/accounts.js

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+import { unwrapList, unwrapSingle, } from '../transform.js';
+import { DELETE_ANNOTATIONS, READ_ANNOTATIONS, UPDATE_ANNOTATIONS, WRITE_ANNOTATIONS } from './_annotations.js';
+import { dateSchema, defineTool } from './_helpers.js';
+export async function fetchAccounts(client, params) {
+    const query = { page: params.page, limit: params.limit };
+    if (params.type && params.type !== 'all')
+        query.type = params.type;
+    const response = await client.get('/accounts', query);
+    return unwrapList(response);
+}
+export async function fetchAccount(client, id) {
+    const response = await client.get(`/accounts/${id}`);
+    return unwrapSingle(response);
+}
+export async function createAccount(client, params) {
+    const response = await client.post('/accounts', params);
+    return unwrapSingle(response);
+}
+export async function updateAccount(client, id, params) {
+    const response = await client.put(`/accounts/${id}`, params);
+    return unwrapSingle(response);
+}
+export async function deleteAccount(client, id) {
+    await client.delete(`/accounts/${id}`);
+    return { deleted: true, id };
+}
+export async function fetchAccountTransactions(client, id, params) {
+    const query = { page: params.page, limit: params.limit };
+    if (params.start)
+        query.start = params.start;
+    if (params.end)
+        query.end = params.end;
+    if (params.type)
+        query.type = params.type;
+    const response = await client.get(`/accounts/${id}/transactions`, query);
+    return unwrapList(response);
+}
+export async function searchAccounts(client, params) {
+    const query = { query: params.query, page: params.page, limit: params.limit };
+    if (params.field)
+        query.field = params.field;
+    const response = await client.get('/search/accounts', query);
+    return unwrapList(response);
+}
+export function registerAccountTools(server, client) {
+    defineTool(server, 'get_accounts', {
+        title: 'Get Accounts',
+        description: 'Get all accounts from Firefly III. Filter by type: asset (bank/cash accounts), expense (merchants), revenue (income sources), liability (loans/debts), or all. Use get_account to fetch a single account by ID.',
+        inputSchema: {
+            type: z
+                .enum(['asset', 'expense', 'revenue', 'liability', 'all'])
+                .optional()
+                .default('all')
+                .describe('Account type filter'),
+            page: z.number().int().positive().optional().default(1).describe('Page number'),
+            limit: z.number().int().positive().max(100).optional().default(50).describe('Results per page (max 100)'),
+        },
+        annotations: READ_ANNOTATIONS,
+    }, ({ type, page, limit }) => fetchAccounts(client, {
+        type: type,
+        page: page,
+        limit: limit,
+    }));
+    defineTool(server, 'get_account', {
+        title: 'Get Account',
+        description: 'Get a single Firefly III account by its numeric ID, including the current balance. Use get_accounts to find valid account IDs.',
+        inputSchema: { id: z.string().describe('Account ID') },
+        annotations: READ_ANNOTATIONS,
+    }, ({ id }) => fetchAccount(client, id));
+    defineTool(server, 'create_account', {
+        title: 'Create Account',
+        description: 'Create a new account in Firefly III.',
+        inputSchema: {
+            name: z.string().describe('Account name'),
+            type: z.enum(['asset', 'expense', 'revenue', 'liability']).describe('Account type'),
+            currency_code: z.string().optional().describe('Currency code (e.g. EUR, USD)'),
+            iban: z.string().optional().describe('IBAN number'),
+            opening_balance: z.string().optional().describe('Opening balance as a number string'),
+            opening_balance_date: dateSchema.optional().describe('Opening balance date (YYYY-MM-DD)'),
+            include_net_worth: z.boolean().optional().describe('Include in net worth calculations'),
+            notes: z.string().optional().describe('Notes'),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, (params) => createAccount(client, params));
+    defineTool(server, 'update_account', {
+        title: 'Update Account',
+        description: 'Update an existing account in Firefly III. Only fields provided will be changed. Use get_account to confirm the ID.',
+        inputSchema: {
+            id: z.string().describe('Account ID — use get_accounts to find valid IDs'),
+            name: z.string().optional().describe('Account name'),
+            currency_code: z.string().optional().describe('Currency code (e.g. EUR, USD)'),
+            iban: z.string().optional().describe('IBAN number'),
+            opening_balance: z.string().optional().describe('Opening balance as a number string'),
+            opening_balance_date: dateSchema.optional().describe('Opening balance date (YYYY-MM-DD)'),
+            include_net_worth: z.boolean().optional().describe('Include in net worth calculations'),
+            active: z.boolean().optional().describe('Whether the account is active'),
+            notes: z.string().optional().describe('Notes'),
+        },
+        annotations: UPDATE_ANNOTATIONS,
+    }, ({ id, ...params }) => updateAccount(client, id, params));
+    defineTool(server, 'delete_account', {
+        title: 'Delete Account',
+        description: 'Permanently delete an account from Firefly III. **This action cannot be undone.** Accounts with linked transactions cannot be deleted. Use get_account to confirm before deleting.',
+        inputSchema: { id: z.string().describe('Account ID — use get_accounts to find valid IDs') },
+        annotations: DELETE_ANNOTATIONS,
+    }, ({ id }) => deleteAccount(client, id));
+    defineTool(server, 'get_account_transactions', {
+        title: 'Get Account Transactions',
+        description: 'Get all transactions for a specific account. Use get_accounts to find valid account IDs.',
+        inputSchema: {
+            id: z.string().describe('Account ID'),
+            start: dateSchema.optional().describe('Start date (YYYY-MM-DD)'),
+            end: dateSchema.optional().describe('End date (YYYY-MM-DD)'),
+            type: z
+                .enum(['all', 'withdrawal', 'deposit', 'transfer', 'opening_balance', 'reconciliation', 'special', 'default'])
+                .optional()
+                .describe('Filter by transaction type'),
+            page: z.number().int().positive().optional().default(1).describe('Page number'),
+            limit: z.number().int().positive().max(100).optional().default(50).describe('Results per page (max 100)'),
+        },
+        annotations: READ_ANNOTATIONS,
+    }, ({ id, start, end, type, page, limit }) => fetchAccountTransactions(client, id, {
+        start: start,
+        end: end,
+        type: type,
+        page: page,
+        limit: limit,
+    }));
+    defineTool(server, 'search_accounts', {
+        title: 'Search Accounts',
+        description: 'Search for accounts by name, IBAN, account number, or ID.',
+        inputSchema: {
+            query: z.string().describe('Search query'),
+            field: z
+                .enum(['all', 'id', 'name', 'iban', 'number', 'account_number'])
+                .optional()
+                .default('all')
+                .describe('Field to search in'),
+            page: z.number().int().positive().optional().default(1).describe('Page number'),
+            limit: z.number().int().positive().max(100).optional().default(50).describe('Results per page (max 100)'),
+        },
+        annotations: READ_ANNOTATIONS,
+    }, ({ query, field, page, limit }) => searchAccounts(client, {
+        query: query,
+        field: field,
+        page: page,
+        limit: limit,
+    }));
+}
+//# sourceMappingURL=accounts.js.map

package/dist/tools/accounts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.js","sourceRoot":"","sources":["../../src/tools/accounts.ts"],"names":[],"mappings":"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"}

package/dist/tools/attachments.d.ts

@@ -0,0 +1,31 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { FireflyClient } from '../client.js';
+import { type UnwrappedList, type UnwrappedSingle } from '../transform.js';
+export declare function fetchAttachments(client: FireflyClient, params: {
+    page?: number;
+    limit?: number;
+}): Promise<UnwrappedList>;
+export declare function fetchAttachment(client: FireflyClient, id: string): Promise<UnwrappedSingle>;
+export declare function createAttachment(client: FireflyClient, params: {
+    filename: string;
+    attachable_type: string;
+    attachable_id: string;
+    title?: string;
+    notes?: string;
+}): Promise<UnwrappedSingle>;
+export declare function updateAttachment(client: FireflyClient, id: string, params: {
+    filename?: string;
+    title?: string;
+    notes?: string;
+}): Promise<UnwrappedSingle>;
+export declare function deleteAttachment(client: FireflyClient, id: string): Promise<{
+    deleted: true;
+    id: string;
+}>;
+export declare function uploadAttachment(client: FireflyClient, id: string, content: Uint8Array): Promise<{
+    uploaded: true;
+    id: string;
+}>;
+export declare function downloadAttachment(client: FireflyClient, id: string): Promise<string>;
+export declare function registerAttachmentTools(server: McpServer, client: FireflyClient): void;
+//# sourceMappingURL=attachments.d.ts.map

package/dist/tools/attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../src/tools/attachments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,eAAe,EAGrB,MAAM,iBAAiB,CAAC;AAMzB,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC,OAAO,CAAC,aAAa,CAAC,CAGxB;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAGjG;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3G,OAAO,CAAC,eAAe,CAAC,CAG1B;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,aAAa,EACrB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,OAAO,CAAC,eAAe,CAAC,CAG1B;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAGhH;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,aAAa,EACrB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAGzC;AAED,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE3F;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CA+HtF"}

package/dist/tools/attachments.js

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { unwrapList, unwrapSingle, } from '../transform.js';
+import { DELETE_ANNOTATIONS, READ_ANNOTATIONS, UPDATE_ANNOTATIONS, WRITE_ANNOTATIONS } from './_annotations.js';
+import { defineTool } from './_helpers.js';
+// ---- Attachment fetch + CRUD ----
+export async function fetchAttachments(client, params) {
+    const response = await client.get('/attachments', { page: params.page, limit: params.limit });
+    return unwrapList(response);
+}
+export async function fetchAttachment(client, id) {
+    const response = await client.get(`/attachments/${id}`);
+    return unwrapSingle(response);
+}
+export async function createAttachment(client, params) {
+    const response = await client.post('/attachments', params);
+    return unwrapSingle(response);
+}
+export async function updateAttachment(client, id, params) {
+    const response = await client.put(`/attachments/${id}`, params);
+    return unwrapSingle(response);
+}
+export async function deleteAttachment(client, id) {
+    await client.delete(`/attachments/${id}`);
+    return { deleted: true, id };
+}
+export async function uploadAttachment(client, id, content) {
+    await client.postBinary(`/attachments/${id}/upload`, content);
+    return { uploaded: true, id };
+}
+export async function downloadAttachment(client, id) {
+    return client.getText(`/attachments/${id}/download`);
+}
+export function registerAttachmentTools(server, client) {
+    defineTool(server, 'get_attachments', {
+        title: 'Get Attachments',
+        description: 'Get all file attachments from Firefly III.',
+        inputSchema: {
+            page: z.number().int().positive().optional().default(1).describe('Page number'),
+            limit: z.number().int().positive().max(100).optional().default(50).describe('Results per page (max 100)'),
+        },
+        annotations: READ_ANNOTATIONS,
+    }, ({ page, limit }) => fetchAttachments(client, { page: page, limit: limit }));
+    defineTool(server, 'get_attachment', {
+        title: 'Get Attachment',
+        description: 'Get a single file attachment by its numeric ID. Use get_attachments to find valid IDs.',
+        inputSchema: {
+            id: z.string().describe('Attachment ID'),
+        },
+        annotations: READ_ANNOTATIONS,
+    }, ({ id }) => fetchAttachment(client, id));
+    defineTool(server, 'create_attachment', {
+        title: 'Create Attachment',
+        description: 'Create attachment metadata in Firefly III. This creates the metadata record only — use upload_attachment to send the actual file content. The returned ID is needed for the upload step.',
+        inputSchema: {
+            filename: z.string().describe('Filename including extension, e.g. receipt.pdf'),
+            attachable_type: z
+                .enum(['Account', 'Budget', 'Bill', 'TransactionJournal', 'PiggyBank', 'Tag'])
+                .describe('Type of object this attachment belongs to'),
+            attachable_id: z.string().describe('ID of the object this attachment belongs to'),
+            title: z.string().optional().describe('Human-readable title'),
+            notes: z.string().optional().describe('Notes'),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, ({ filename, attachable_type, attachable_id, title, notes }) => createAttachment(client, {
+        filename: filename,
+        attachable_type: attachable_type,
+        attachable_id: attachable_id,
+        title: title,
+        notes: notes,
+    }));
+    defineTool(server, 'update_attachment', {
+        title: 'Update Attachment',
+        description: 'Update attachment metadata. Only fields provided will be changed. Use get_attachment to confirm the ID before updating.',
+        inputSchema: {
+            id: z.string().describe('Attachment ID — use get_attachments to find valid IDs'),
+            filename: z.string().optional().describe('Filename including extension'),
+            title: z.string().optional().describe('Human-readable title'),
+            notes: z.string().optional().describe('Notes'),
+        },
+        annotations: UPDATE_ANNOTATIONS,
+    }, ({ id, filename, title, notes }) => updateAttachment(client, id, {
+        filename: filename,
+        title: title,
+        notes: notes,
+    }));
+    defineTool(server, 'delete_attachment', {
+        title: 'Delete Attachment',
+        description: 'Permanently delete an attachment and its file data from Firefly III. **This action cannot be undone.** Use get_attachment to confirm before deleting.',
+        inputSchema: {
+            id: z.string().describe('Attachment ID — use get_attachments to find valid IDs'),
+        },
+        annotations: DELETE_ANNOTATIONS,
+    }, ({ id }) => deleteAttachment(client, id));
+    defineTool(server, 'upload_attachment', {
+        title: 'Upload Attachment File',
+        description: 'Upload the binary content for an existing attachment record. Call create_attachment first to get the attachment ID, then call this tool with the base64-encoded file content. The two-step workflow: (1) create_attachment → get ID, (2) upload_attachment with that ID and content_base64.',
+        inputSchema: {
+            id: z.string().describe('Attachment ID from create_attachment'),
+            content_base64: z.string().describe('File content encoded as base64'),
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, ({ id, content_base64 }) => uploadAttachment(client, id, Buffer.from(content_base64, 'base64')));
+    defineTool(server, 'download_attachment', {
+        title: 'Download Attachment',
+        description: 'Download the raw content of an attachment as text. Useful for reading receipts or notes. Use get_attachments to find valid IDs.',
+        inputSchema: {
+            id: z.string().describe('Attachment ID'),
+        },
+        annotations: READ_ANNOTATIONS,
+    }, ({ id }) => downloadAttachment(client, id));
+}
+//# sourceMappingURL=attachments.js.map

package/dist/tools/attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../../src/tools/attachments.ts"],"names":[],"mappings":"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"}

package/dist/tools/bills.d.ts

@@ -0,0 +1,43 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { FireflyClient } from '../client.js';
+import { type UnwrappedList, type UnwrappedSingle } from '../transform.js';
+export declare function fetchBills(client: FireflyClient, params: {
+    start?: string;
+    end?: string;
+    page?: number;
+    limit?: number;
+}): Promise<UnwrappedList>;
+export declare function createBill(client: FireflyClient, params: {
+    name: string;
+    amount_min: string;
+    amount_max: string;
+    date: string;
+    repeat_freq: 'weekly' | 'monthly' | 'quarterly' | 'half-year' | 'yearly';
+    currency_code?: string;
+    end_date?: string;
+    active?: boolean;
+    notes?: string;
+}): Promise<UnwrappedSingle>;
+export declare function updateBill(client: FireflyClient, id: string, params: {
+    name?: string;
+    amount_min?: string;
+    amount_max?: string;
+    date?: string;
+    repeat_freq?: 'weekly' | 'monthly' | 'quarterly' | 'half-year' | 'yearly';
+    currency_code?: string;
+    end_date?: string;
+    active?: boolean;
+    notes?: string;
+}): Promise<UnwrappedSingle>;
+export declare function deleteBill(client: FireflyClient, id: string): Promise<{
+    deleted: true;
+    id: string;
+}>;
+export declare function fetchBillTransactions(client: FireflyClient, id: string, params: {
+    start?: string;
+    end?: string;
+    page?: number;
+    limit?: number;
+}): Promise<UnwrappedList>;
+export declare function registerBillTools(server: McpServer, client: FireflyClient): void;
+//# sourceMappingURL=bills.d.ts.map

package/dist/tools/bills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bills.d.ts","sourceRoot":"","sources":["../../src/tools/bills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,eAAe,EAGrB,MAAM,iBAAiB,CAAC;AAKzB,wBAAsB,UAAU,CAC9B,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACtE,OAAO,CAAC,aAAa,CAAC,CAMxB;AAED,wBAAsB,UAAU,CAC9B,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE;IACN,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACA,OAAO,CAAC,eAAe,CAAC,CAG1B;AAED,wBAAsB,UAAU,CAC9B,MAAM,EAAE,aAAa,EACrB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE;IACN,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACA,OAAO,CAAC,eAAe,CAAC,CAG1B;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAG1G;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACtE,OAAO,CAAC,aAAa,CAAC,CAMxB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CA8GhF"}