@pothos-wealth/mcp 0.1.0

package/dist/client.js

@@ -0,0 +1,46 @@
+export class PothosApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "PothosApiError";
+    }
+}
+export async function apiFetch(path, options = {}) {
+    const BASE_URL = (process.env.POTHOS_URL ?? "").replace(/\/$/, "");
+    const API_KEY = process.env.POTHOS_API_KEY ?? "";
+    const url = `${BASE_URL}/api/v1${path}`;
+    const res = await fetch(url, {
+        ...options,
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${API_KEY}`,
+            ...options.headers,
+        },
+    });
+    if (!res.ok) {
+        let message = `Backend returned ${res.status}`;
+        try {
+            const body = (await res.json());
+            if (body?.error)
+                message = body.error;
+        }
+        catch {
+            // ignore parse error, use default message
+        }
+        throw new PothosApiError(res.status, message);
+    }
+    if (res.status === 204)
+        return undefined;
+    return res.json();
+}
+export function fmtAmount(minorUnits) {
+    return (minorUnits / 100).toFixed(2);
+}
+export function fmtDate(unixTs) {
+    return new Date(unixTs * 1000).toLocaleDateString("en-US", {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+    });
+}

package/dist/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { config } from "dotenv";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+config({ path: join(dirname(fileURLToPath(import.meta.url)), "../.env") });
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerAccountTools } from "./tools/accounts.js";
+import { registerTransactionTools } from "./tools/transactions.js";
+import { registerCategoryTools } from "./tools/categories.js";
+import { registerBudgetTools } from "./tools/budgets.js";
+import { registerReportTools } from "./tools/reports.js";
+import { registerParseQueueTools } from "./tools/parseQueue.js";
+if (!process.env.POTHOS_URL) {
+    process.stderr.write("Error: POTHOS_URL is required in .env\n");
+    process.exit(1);
+}
+if (!process.env.POTHOS_API_KEY) {
+    process.stderr.write("Error: POTHOS_API_KEY is required in .env\n");
+    process.exit(1);
+}
+const server = new McpServer({ name: "pothos", version: "0.1.0" }, {
+    instructions: `You are a personal finance assistant with full access to the user's Pothos financial data. Your job is to give clear, actionable financial insight — not just fetch data. Think like a financial advisor: interpret what you see, highlight what matters, and give the user something they can act on.
+
+## Data access
+- Accounts & balances: get_accounts (includes net worth)
+- Transactions: get_transactions (paginated, filterable by account/type/date)
+- Categories: get_categories (resolve IDs and names — always call this before filtering by category or adding a transaction)
+- Budgets: get_budgets (budget vs actual, with committed flag)
+- Reports: get_spending_overview, get_category_breakdown, get_spending_trends
+- Email inbox: get_pending_emails, submit_parsed_email, dismiss_email
+
+## How to answer questions
+Don't just return raw data — synthesize it. When someone asks how they're doing, pull spending + budgets + trends and give a real answer. Spot what's over budget, what's trending up, where they're doing well. Surface the things they should care about, not everything at once.
+
+Combine tools freely. A question like "am I on track this month?" warrants get_spending_overview + get_budgets. A question about a specific category warrants get_category_breakdown + get_transactions to show the actual items.
+
+Be specific. Instead of "you spent a lot on food", say "you're at 87% of your Food budget with 12 days left in the month."
+
+## Key facts
+- Committed budgets (marked [COMMITTED]) are hard obligations — rent, loan repayments, subscriptions. Even if the transaction hasn't posted yet, treat the full budgeted amount as a guaranteed upcoming expense. When assessing how much money the user has available, subtract any committed budget that hasn't been fully spent yet — that money is already spoken for.
+- Non-committed budgets are flexible targets. The user can underspend them. Treat remaining balance there as genuinely available.
+- Transfers are excluded from budgets and spending reports — they only move money between accounts.
+- Account balances are always current (derived from all transactions).
+- Category IDs are nanoids. Resolve them with get_categories whenever you need to match a name to an ID, or explain a category in a response.
+
+## Common flows
+- "How am I doing?" → get_spending_overview + get_budgets for current month → give a summary with highlights (over budget, on track, noteworthy trends)
+- Spending deep-dive → get_category_breakdown + get_transactions (filtered by category) → show what's driving spend
+- Trend question → get_spending_trends → note direction, compare to prior months
+- Log a transaction → get_accounts + get_categories (if needed) → add_transaction
+- Process inbox → get_pending_emails → parse each email yourself → submit_parsed_email for transactions, dismiss_email for non-transactions. Nothing is created automatically — submitted items go to the user's inbox for approval.`,
+});
+registerAccountTools(server);
+registerTransactionTools(server);
+registerCategoryTools(server);
+registerBudgetTools(server);
+registerReportTools(server);
+registerParseQueueTools(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/accounts.js

@@ -0,0 +1,22 @@
+import { apiFetch, fmtAmount, PothosApiError } from "../client.js";
+export function registerAccountTools(server) {
+    server.registerTool("get_accounts", {
+        description: "Get all accounts with their current balances and a net worth total. " +
+            "Closed accounts are included and marked [closed].",
+    }, async () => {
+        try {
+            const accounts = await apiFetch("/accounts?includeInactive=true");
+            const netWorth = accounts.reduce((sum, a) => sum + a.balance, 0);
+            const lines = accounts.map((a) => `- ${a.name} (${a.type}): ${fmtAmount(a.balance)}${a.isActive ? "" : " [closed]"} [id: ${a.id}]`);
+            lines.push(`\nNet worth: ${fmtAmount(netWorth)}`);
+            lines.push(`(${accounts.length} account${accounts.length !== 1 ? "s" : ""} total)`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (err) {
+            const msg = err instanceof PothosApiError ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Failed to fetch accounts: ${msg}` }],
+            };
+        }
+    });
+}

package/dist/tools/budgets.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { apiFetch, fmtAmount, PothosApiError } from "../client.js";
+const MONTHS = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+];
+export function registerBudgetTools(server) {
+    server.registerTool("get_budgets", {
+        description: "Get budget vs actual spending for a given month. " +
+            "Shows how much is budgeted, spent, and remaining per category. " +
+            "Defaults to the current month if not specified.",
+        inputSchema: {
+            month: z
+                .number()
+                .int()
+                .min(1)
+                .max(12)
+                .optional()
+                .describe("Month (1-12). Defaults to current month."),
+            year: z
+                .number()
+                .int()
+                .optional()
+                .describe("Year (e.g. 2026). Defaults to current year."),
+        },
+    }, async ({ month, year }) => {
+        try {
+            const now = new Date();
+            const m = month ?? now.getMonth() + 1;
+            const y = year ?? now.getFullYear();
+            const budgets = await apiFetch(`/budgets?month=${m}&year=${y}`);
+            if (budgets.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No budgets set for ${MONTHS[m - 1]} ${y}.`,
+                        },
+                    ],
+                };
+            }
+            const lines = [`Budgets for ${MONTHS[m - 1]} ${y}:`];
+            for (const b of budgets) {
+                const pct = b.amount > 0 ? Math.round((b.spent / b.amount) * 100) : 0;
+                const flags = [];
+                if (b.isCommitted)
+                    flags.push("COMMITTED");
+                if (b.remaining < 0)
+                    flags.push("OVER BUDGET");
+                else if (b.remaining === 0)
+                    flags.push("AT LIMIT");
+                const status = flags.length ? ` [${flags.join(", ")}]` : "";
+                lines.push(`- ${b.categoryId}: spent ${fmtAmount(b.spent)} / budget ${fmtAmount(b.amount)} (${pct}%) — ${b.remaining >= 0 ? fmtAmount(b.remaining) + " remaining" : fmtAmount(Math.abs(b.remaining)) + " over budget"}${status}`);
+            }
+            const committedUnpaid = budgets
+                .filter((b) => b.isCommitted && b.spent < b.amount)
+                .map((b) => ({
+                categoryId: b.categoryId,
+                unpaid: fmtAmount(b.amount - b.spent),
+            }));
+            const totalCommittedUnpaid = budgets
+                .filter((b) => b.isCommitted && b.spent < b.amount)
+                .reduce((s, b) => s + (b.amount - b.spent), 0);
+            const totalFlexibleRemaining = budgets
+                .filter((b) => !b.isCommitted && b.remaining > 0)
+                .reduce((s, b) => s + b.remaining, 0);
+            return {
+                content: [{ type: "text", text: lines.join("\n") }],
+                structuredContent: {
+                    committedUnpaid,
+                    totalCommittedUnpaid: fmtAmount(totalCommittedUnpaid),
+                    totalFlexibleRemaining: fmtAmount(totalFlexibleRemaining),
+                    note: "totalCommittedUnpaid is money that will definitely leave the account this month. Subtract it from available balance when assessing financial health.",
+                },
+            };
+        }
+        catch (err) {
+            const msg = err instanceof PothosApiError ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Failed to fetch budgets: ${msg}` }],
+            };
+        }
+    });
+}

package/dist/tools/categories.js

@@ -0,0 +1,37 @@
+import { apiFetch, PothosApiError } from "../client.js";
+export function registerCategoryTools(server) {
+    server.registerTool("get_categories", {
+        description: "List all available categories (global defaults and your custom ones), grouped by type. " +
+            "Use this to find valid category names when adding transactions.",
+    }, async () => {
+        try {
+            const categories = await apiFetch("/categories");
+            const grouped = { expense: [], income: [], neutral: [] };
+            for (const c of categories) {
+                grouped[c.type].push(c.icon ? `${c.name} ${c.icon} (id: ${c.id})` : `${c.name} (id: ${c.id})`);
+            }
+            const lines = [];
+            if (grouped.expense.length) {
+                lines.push("Expense categories:");
+                grouped.expense.forEach((c) => lines.push(`  ${c}`));
+            }
+            if (grouped.income.length) {
+                lines.push("Income categories:");
+                grouped.income.forEach((c) => lines.push(`  ${c}`));
+            }
+            if (grouped.neutral.length) {
+                lines.push("Neutral categories:");
+                grouped.neutral.forEach((c) => lines.push(`  ${c}`));
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (err) {
+            const msg = err instanceof PothosApiError ? err.message : String(err);
+            return {
+                content: [
+                    { type: "text", text: `Failed to fetch categories: ${msg}` },
+                ],
+            };
+        }
+    });
+}

package/dist/tools/parseQueue.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { apiFetch, fmtAmount, fmtDate, PothosApiError } from "../client.js";
+export function registerParseQueueTools(server) {
+    server.registerTool("get_pending_emails", {
+        description: "Fetch raw emails waiting to be parsed into transactions. " +
+            "Returns the email content for you to interpret and extract transaction details from. " +
+            "After parsing, call submit_parsed_email with the result for each email.",
+        inputSchema: {
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(10)
+                .describe("Max number of emails to return (default 10)"),
+        },
+    }, async ({ limit }) => {
+        try {
+            const pending = await apiFetch("/parse-queue?status=pending");
+            if (pending.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No pending emails." }],
+                };
+            }
+            const batch = pending.slice(0, limit ?? 10);
+            const remaining = pending.length - batch.length;
+            const lines = [
+                `${pending.length} pending email${pending.length !== 1 ? "s" : ""} (showing ${batch.length}):`,
+            ];
+            for (const msg of batch) {
+                lines.push(`\n--- Email ID: ${msg.id} ---`);
+                lines.push(`Subject: ${msg.subject ?? "(no subject)"}`);
+                lines.push(`Received: ${fmtDate(msg.createdAt)}`);
+                lines.push(`Body:\n${msg.rawContent}`);
+            }
+            if (remaining > 0) {
+                lines.push(`\n${remaining} more email${remaining !== 1 ? "s" : ""} not shown. Call again to get the next batch.`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (err) {
+            const msg = err instanceof PothosApiError ? err.message : String(err);
+            return {
+                content: [
+                    { type: "text", text: `Failed to fetch pending emails: ${msg}` },
+                ],
+            };
+        }
+    });
+    server.registerTool("submit_parsed_email", {
+        description: "Submit your parsed interpretation of a pending email. " +
+            "The result goes to your Pothos inbox for review before any transaction is created. " +
+            "Call get_accounts and get_categories first so you can supply accountId and categoryId. " +
+            "Use dismiss_email if the email is not a financial transaction.",
+        inputSchema: {
+            messageId: z.string().describe("ID of the pending email (from get_pending_emails)"),
+            type: z.enum(["income", "expense"]).describe("Transaction type"),
+            amount: z
+                .number()
+                .positive()
+                .describe("Transaction amount as a positive decimal (e.g. 45.50)"),
+            date: z.string().describe("Transaction date (YYYY-MM-DD)"),
+            description: z
+                .string()
+                .min(1)
+                .max(60)
+                .describe("Merchant name or transaction reference"),
+            accountId: z
+                .string()
+                .optional()
+                .describe("Account ID to associate with the transaction (from get_accounts)"),
+            categoryId: z
+                .string()
+                .optional()
+                .describe("Category ID to associate with the transaction (from get_categories)"),
+            notes: z.string().optional().describe("Optional notes"),
+        },
+    }, async ({ messageId, type, amount, date, description, accountId, categoryId, notes }) => {
+        try {
+            const minorUnits = Math.round(amount * 100);
+            const unixTs = Math.floor(new Date(date).getTime() / 1000);
+            await apiFetch(`/parse-queue/${messageId}/submit`, {
+                method: "POST",
+                body: JSON.stringify({
+                    type,
+                    amount: minorUnits,
+                    date: unixTs,
+                    description,
+                    accountId: accountId ?? null,
+                    categoryId: categoryId ?? null,
+                    notes: notes ?? null,
+                    bypassReview: false,
+                }),
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Submitted: ${type} of ${fmtAmount(minorUnits)} on ${fmtDate(unixTs)} — "${description}".\n` +
+                            `Review and approve it in your Pothos inbox.`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof PothosApiError ? err.message : String(err);
+            return {
+                content: [
+                    { type: "text", text: `Failed to submit parsed email: ${msg}` },
+                ],
+            };
+        }
+    });
+    server.registerTool("dismiss_email", {
+        description: "Dismiss a pending email that is not a financial transaction (e.g. newsletters, promotions). " +
+            "It will no longer appear in the pending queue.",
+        inputSchema: {
+            messageId: z.string().describe("ID of the pending email to dismiss"),
+        },
+    }, async ({ messageId }) => {
+        try {
+            await apiFetch(`/parse-queue/${messageId}/dismiss`, { method: "POST" });
+            return {
+                content: [{ type: "text", text: "Email dismissed." }],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof PothosApiError ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Failed to dismiss email: ${msg}` }],
+            };
+        }
+    });
+}

package/dist/tools/reports.js

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { apiFetch, fmtAmount, PothosApiError } from "../client.js";
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+export function registerReportTools(server) {
+    server.registerTool("get_spending_overview", {
+        description: "Get total income, expenses, net, and committed budget for a given month. " +
+            "Committed = unspent budget remaining (money set aside but not yet spent). " +
+            "Use this to assess true available funds. Defaults to the current month.",
+        inputSchema: {
+            month: z.number().int().min(1).max(12).optional().describe("Month (1-12)"),
+            year: z.number().int().optional().describe("Year (e.g. 2026)"),
+        },
+    }, async ({ month, year }) => {
+        try {
+            const now = new Date();
+            const m = month ?? now.getMonth() + 1;
+            const y = year ?? now.getFullYear();
+            const overview = await apiFetch(`/reports/overview?month=${m}&year=${y}`);
+            const monthName = new Date(y, m - 1).toLocaleDateString("en-US", {
+                month: "long",
+                year: "numeric",
+            });
+            const netSign = overview.net >= 0 ? "+" : "";
+            const text = `${monthName} Overview:\n` +
+                `  Income:    ${fmtAmount(overview.income)}\n` +
+                `  Expenses:  ${fmtAmount(Math.abs(overview.expenses))}\n` +
+                `  Net:       ${netSign}${fmtAmount(overview.net)}\n` +
+                `  Committed: ${fmtAmount(overview.committed)} (budgeted but not yet spent this month)`;
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            const msg = err instanceof PothosApiError ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Failed to fetch overview: ${msg}` }],
+            };
+        }
+    });
+    server.registerTool("get_category_breakdown", {
+        description: "Get expense breakdown by category for a given month, with percentages. " +
+            "Defaults to the current month.",
+        inputSchema: {
+            month: z.number().int().min(1).max(12).optional().describe("Month (1-12)"),
+            year: z.number().int().optional().describe("Year (e.g. 2026)"),
+        },
+    }, async ({ month, year }) => {
+        try {
+            const now = new Date();
+            const m = month ?? now.getMonth() + 1;
+            const y = year ?? now.getFullYear();
+            const breakdown = await apiFetch(`/reports/categories?month=${m}&year=${y}`);
+            const monthName = new Date(y, m - 1).toLocaleDateString("en-US", {
+                month: "long",
+                year: "numeric",
+            });
+            if (breakdown.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No expense data for ${monthName}.`,
+                        },
+                    ],
+                };
+            }
+            const totalExpenses = breakdown.reduce((sum, c) => sum + Math.abs(c.total), 0);
+            const lines = [`${monthName} — Expenses by Category:`];
+            for (const c of breakdown) {
+                const icon = c.categoryIcon ? ` ${c.categoryIcon}` : "";
+                const abs = Math.abs(c.total);
+                const pct = totalExpenses > 0 ? ((abs / totalExpenses) * 100).toFixed(1) : "0.0";
+                lines.push(`  ${c.categoryName}${icon}: ${fmtAmount(abs)} (${pct}%)`);
+            }
+            lines.push(`  Total expenses: ${fmtAmount(totalExpenses)}`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (err) {
+            const msg = err instanceof PothosApiError ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to fetch category breakdown: ${msg}`,
+                    },
+                ],
+            };
+        }
+    });
+    server.registerTool("get_spending_trends", {
+        description: "Get monthly income, expenses, and net over the last N months. Useful for spotting trends.",
+        inputSchema: {
+            months: z
+                .number()
+                .int()
+                .min(1)
+                .max(24)
+                .optional()
+                .default(6)
+                .describe("Number of months to look back (1-24, default 6)"),
+        },
+    }, async ({ months }) => {
+        try {
+            const n = months ?? 6;
+            const trends = await apiFetch(`/reports/trends?months=${n}`);
+            const lines = [`Spending trends (last ${n} months):`];
+            for (const t of trends) {
+                const netSign = t.net >= 0 ? "+" : "";
+                lines.push(`  ${MONTHS[t.month - 1]} ${t.year}: income ${fmtAmount(t.income)} | expenses ${fmtAmount(Math.abs(t.expenses))} | net ${netSign}${fmtAmount(t.net)}`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (err) {
+            const msg = err instanceof PothosApiError ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Failed to fetch trends: ${msg}` }],
+            };
+        }
+    });
+}

package/dist/tools/transactions.js

@@ -0,0 +1,162 @@
+import { z } from "zod";
+import { apiFetch, fmtAmount, fmtDate, PothosApiError } from "../client.js";
+export function registerTransactionTools(server) {
+    server.registerTool("get_transactions", {
+        description: "List transactions with optional filters. Returns paginated results with amounts, dates, and categories.",
+        inputSchema: {
+            accountId: z.string().optional().describe("Filter by account ID"),
+            type: z
+                .enum(["income", "expense", "transfer"])
+                .optional()
+                .describe("Filter by transaction type"),
+            startDate: z.string().optional().describe("Start date filter (YYYY-MM-DD)"),
+            endDate: z.string().optional().describe("End date filter (YYYY-MM-DD)"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(20)
+                .describe("Number of results to return (max 100)"),
+            page: z.number().int().min(1).optional().default(1).describe("Page number"),
+        },
+    }, async ({ accountId, type, startDate, endDate, limit, page }) => {
+        try {
+            const params = new URLSearchParams();
+            if (accountId)
+                params.set("accountId", accountId);
+            if (type)
+                params.set("type", type);
+            if (startDate)
+                params.set("startDate", String(Math.floor(new Date(startDate).getTime() / 1000)));
+            if (endDate)
+                params.set("endDate", String(Math.floor(new Date(endDate).getTime() / 1000)));
+            params.set("limit", String(limit ?? 20));
+            params.set("page", String(page ?? 1));
+            const [result, accounts] = await Promise.all([
+                apiFetch(`/transactions?${params}`),
+                apiFetch("/accounts?includeInactive=true"),
+            ]);
+            const accountMap = Object.fromEntries(accounts.map((a) => [a.id, a.name]));
+            if (result.data.length === 0) {
+                return { content: [{ type: "text", text: "No transactions found." }] };
+            }
+            const lines = [
+                `Found ${result.total} transaction${result.total !== 1 ? "s" : ""} (page ${result.page} of ${result.totalPages}):`,
+            ];
+            for (const t of result.data) {
+                const account = accountMap[t.accountId] ?? t.accountId;
+                const sign = t.amount > 0 ? "+" : "";
+                const parts = [
+                    fmtDate(t.date),
+                    t.description,
+                    `${t.type} ${sign}${fmtAmount(t.amount)}`,
+                    `[${account}]`,
+                ];
+                if (t.categoryId)
+                    parts.push(`[category: ${t.categoryId}]`);
+                lines.push(`- ${parts.join(" | ")}`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (err) {
+            const msg = err instanceof PothosApiError ? err.message : String(err);
+            return {
+                content: [
+                    { type: "text", text: `Failed to fetch transactions: ${msg}` },
+                ],
+            };
+        }
+    });
+    server.registerTool("add_transaction", {
+        description: "Create a new income or expense transaction. " +
+            "Use get_accounts to find account IDs and get_categories to find category IDs.",
+        inputSchema: {
+            accountId: z.string().describe("ID of the account"),
+            type: z.enum(["income", "expense"]).describe("Transaction type"),
+            amount: z.number().positive().describe("Amount as a positive decimal (e.g. 45.50)"),
+            date: z.string().describe("Transaction date (YYYY-MM-DD)"),
+            description: z.string().min(1).describe("Merchant name or description"),
+            categoryId: z.string().optional().describe("Category ID (optional)"),
+            notes: z.string().optional().describe("Additional notes (optional)"),
+        },
+    }, async ({ accountId, type, amount, date, description, categoryId, notes }) => {
+        try {
+            const minorUnits = Math.round(amount * 100);
+            const unixTs = Math.floor(new Date(date).getTime() / 1000);
+            const tx = await apiFetch("/transactions", {
+                method: "POST",
+                body: JSON.stringify({
+                    accountId,
+                    type,
+                    amount: minorUnits,
+                    date: unixTs,
+                    description,
+                    categoryId: categoryId ?? null,
+                    notes: notes ?? null,
+                }),
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Transaction created: "${tx.description}" — ${tx.type} — ${fmtAmount(Math.abs(tx.amount))} on ${fmtDate(tx.date)}.\n` +
+                            `Transaction ID: ${tx.id}`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof PothosApiError ? err.message : String(err);
+            return {
+                content: [
+                    { type: "text", text: `Failed to create transaction: ${msg}` },
+                ],
+            };
+        }
+    });
+    server.registerTool("add_transfer", {
+        description: "Transfer money between two accounts. Creates a linked pair of transactions. " +
+            "Use get_accounts to find account IDs.",
+        inputSchema: {
+            fromAccountId: z.string().describe("ID of the source account"),
+            toAccountId: z.string().describe("ID of the destination account"),
+            amount: z
+                .number()
+                .positive()
+                .describe("Amount to transfer as a positive decimal (e.g. 500.00)"),
+            date: z.string().describe("Transfer date (YYYY-MM-DD)"),
+            description: z.string().min(1).describe("Description or note for the transfer"),
+        },
+    }, async ({ fromAccountId, toAccountId, amount, date, description }) => {
+        try {
+            const minorUnits = Math.round(amount * 100);
+            const unixTs = Math.floor(new Date(date).getTime() / 1000);
+            await apiFetch("/transactions/transfer", {
+                method: "POST",
+                body: JSON.stringify({
+                    fromAccountId,
+                    toAccountId,
+                    amount: minorUnits,
+                    date: unixTs,
+                    description,
+                }),
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Transfer of ${fmtAmount(minorUnits)} on ${new Date(date).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" })} created successfully.`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof PothosApiError ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Failed to create transfer: ${msg}` }],
+            };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@pothos-wealth/mcp",
+	"version": "0.1.0",
+	"description": "MCP server for Pothos - natural language access to your budgets, transactions, and email parsing",
+	"type": "module",
+	"license": "AGPL-3.0",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/pothos-wealth/pothos.git",
+		"directory": "mcp"
+	},
+	"homepage": "https://github.com/pothos-wealth/pothos#mcp-server",
+	"keywords": [
+		"mcp",
+		"finance",
+		"budget",
+		"personal-finance",
+		"pothos"
+	],
+	"bin": {
+		"pothos-mcp": "dist/index.js"
+	},
+	"files": [
+		"dist/client.js",
+		"dist/index.js",
+		"dist/tools"
+	],
+	"scripts": {
+		"dev": "tsx watch src/index.ts",
+		"build": "tsc",
+		"start": "node dist/index.js",
+		"format": "npx prettier --write \"src/**/*.ts\""
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.0.0",
+		"dotenv": "^16.4.5",
+		"zod": "^3.23.8"
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"typescript-eslint": "^8.0.0",
+		"eslint": "^9.0.0",
+		"tsx": "^4.19.1",
+		"typescript": "^5.6.0"
+	}
+}