# Budget Engine MCP

> The Deterministic 50/30/20 Budget Engine enforces strict financial rules by offloading calculation to a V8 math engine. It takes your income and categorized expenses, mathematically enforcing the golden rule (50% Needs, 30% Wants, 20% Savings) to detect exact budget deviations.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** budgeting, financial-auditing, expense-tracking, math-engine, personal-finance, capital-management

## Description

When you feed raw transaction data into an AI client, it's risky business. General-purpose models often mess up decimal math or drop expenses from large arrays—you can't afford that kind of error when tracking capital. This MCP solves that problem by bypassing the LLM’s general processing layer and sending financial auditing tasks to a dedicated V8 mathematical engine.

It doesn't just give you an estimate; it calculates the precise target for every category based on your total income, guaranteeing deterministic accuracy. You map your expenses against the 50/30/20 framework, and the system instantly tells you if your 'Wants' category is $250.45 over budget. This level of precision stops AI math hallucinations before they happen, giving you actionable figures for immediate corrections. Because this MCP lives within the Vinkius catalog, your agent can access this guaranteed calculation engine from any compatible client, making financial auditing reliable no matter where you're working.

## Tools

### analyze_budget
Runs an income and expense list through the 50/30/20 rule, returning precise deviations and a structural budget health check.

## Prompt Examples

**Prompt:** 
```
Here is my mapped list of expenses and $5000 income. Am I over budget on wants?
```

**Response:** 
```
Using the analyze_budget tool: Yes, the diagnostic shows your 'Wants' category is $200 over budget (`isOverBudget: true`, `deviation: 200`), consuming 34% of your income instead of the required 30%.
```

**Prompt:** 
```
Calculate my monthly surplus and health status.
```

**Response:** 
```
Using the analyze_budget tool: Your total income is $4000, and expenses are $3200. You have a monthly surplus of $800, and your budget is structurally 'Healthy'.
```

**Prompt:** 
```
Based on my $6000 income, exactly how much is my 20% savings target?
```

**Response:** 
```
Using the analyze_budget tool: The mathematical 50/30/20 algorithm confirms your target for the 'saving' category is exactly $1200.00.
```

## Capabilities

### Enforce 50/30/20 Allocation
It calculates the specific target capital for Needs (50%), Wants (30%), and Savings (20%) based on a given monthly income.

### Detect Dollar Deviations
The engine provides exact dollar amounts showing how far an expense category is from its required budget target, down to the penny.

### Assess Budget Health Status
It automatically runs diagnostics to determine if your current spending pattern results in a surplus or deficit, assigning a structural 'Healthy' or 'Deficit' status.

## Use Cases

### Checking a personal budget before shopping
A user inputs their monthly salary and categorized spending (rent, groceries, entertainment) into the MCP. The agent runs analyze_budget and confirms they are $450 over budget on 'Wants,' telling them exactly how much they need to cut back immediately.

### Auditing a project's departmental spend
A finance analyst feeds the MCP three department expense reports. The agent runs analyze_budget, showing that while overall spending is acceptable, Department B's 'Needs' category only met 42% of its target, requiring immediate budget reallocation.

### Evaluating a new income stream
A freelancer inputs a projected increase in monthly revenue and their existing fixed costs. The MCP uses analyze_budget to confirm that the increased income is sufficient not only to cover expenses but also to maintain a 'Healthy' savings status.

## Benefits

- Stop guessing. Instead of relying on general AI models that might miscalculate decimals, the analyze_budget tool guarantees deterministic math by using a V8 engine to enforce every percentage and dollar amount.
- Immediate audit status: It tells you if your spending is 'Healthy' or in 'Deficit,' giving instant structural feedback on whether your budget plan will actually close out with money left over.
- Pinpoint accuracy: You don't just know you're over budget; the engine calculates exactly how much—like showing that 'Wants' cost $200.45 more than planned.
- Risk mitigation: By offloading this specific calculation to a dedicated MCP, your workflow avoids the biggest risk of LLMs when dealing with sensitive financial data and complex math arrays.
- Speed and reliability: Since it operates natively within V8, you get extreme speed for processing expense pipelines without having to wait on external API calls or slow computations.

## How It Works

The bottom line is that you get mathematically guaranteed financial audit results without any guesswork.

1. You provide the MCP with two key pieces of data: the total monthly income and a structured list (JSON array) of your categorized expenses.
2. The Deterministic 50/30/20 Budget Engine runs this input through its V8 mathematical core, enforcing the strict allocation rules against the provided figures.
3. You receive an immediate report detailing the exact deviation for each category, along with a final diagnosis of whether the budget is structurally healthy or facing a deficit.

## Frequently Asked Questions

**How does the analyze_budget tool handle currency?**
It handles standard decimal precision required for financial accounting. Since it runs on a V8 engine, it treats all input numbers with strict mathematical accuracy, preventing common rounding errors.

**Can I use the analyze_budget tool if my expenses aren't perfectly categorized?**
The tool requires you to provide an expense list that is already mapped and structured in a JSON array. If your data isn't pre-categorized, you need to fix the input data first.

**What does 'Deficit' mean when I run analyze_budget?**
A 'Deficit' status means that based on your current spending and income, your budget is structurally negative. You are spending more than the system determines you can afford under the 50/30/20 rule.

**Does analyze_budget calculate tax implications?**
No. The tool enforces the 50/30/20 rule based on your provided income and expense figures. It is a budget *auditing* engine, not a full tax compliance calculator.

**How do I correctly format the expense data when calling analyze_budget?**
You must provide a stringified JSON array where each expense object clearly defines its category and numerical amount. The engine requires structured input to map expenses accurately against the 50/30/20 rules.

**What happens if I pass invalid or missing data to analyze_budget?**
If the required inputs (like income or expense array) are malformed, the tool returns a specific error object. This structured failure report tells you exactly what input is wrong and how to correct it.

**Can analyze_budget handle very large lists of expenses?**
Yes, because this MCP runs on a native V8 mathematical engine, performance remains consistent even with extensive expense arrays. It's designed for deterministic speed and precision regardless of list size.

**Why should I use analyze_budget instead of just asking my AI agent to calculate the budget?**
You should use this MCP because it forces calculations into a dedicated V8 runtime environment. This bypasses any potential mathematical errors or rounding issues inherent in general-purpose LLM models.

**Does the engine automatically guess the category of an expense?**
No. The AI agent calling the tool is responsible for tagging each expense as 'need', 'want', or 'saving'. The MCP acts as an infallible mathematical referee, receiving the categorized list and computing the exact metrics and deviations.

**Why use an MCP instead of having the LLM do the math?**
Because LLMs hallucinate math. If you give an AI 45 different expenses to sum up, it will almost certainly miscalculate the total or botch the exact percentage deviation. The V8 engine calculates numbers deterministically with 100% precision.

**What happens if I spend more than my income?**
The engine perfectly calculates a negative surplus (deficit) and strictly alters the 'healthStatus' to 'Deficit', triggering a warning recommendation that instructs your agent to look at the deviations to cut costs.