# Percentage Calculation Engine MCP

> Percentage Calculation Engine calculates exact percentages, discounts, and relative increases every time. Stop relying on LLMs for financial math; this server runs pure JavaScript logic at the edge. It lets your AI client perform deterministic calculations for VAT rates, invoice discounts, and interest accrual, giving you a reliable source of truth for complex quantitative reporting.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** arithmetic, financial-math, determinism, vat-calculation, discount-logic, precision-math

## Description

Listen up: when you're dealing with money, you can't trust a language model to do the math. LLMs are great for talking, but they guess at numbers; they don't calculate them. This Percentage Calculation Engine is your fix. It runs pure JavaScript logic directly through your AI client, making sure every number it spits out is deterministic—meaning the answer will be exactly the same time after time, no matter how you prompt it.

The engine gives your agent two specific tools: `calculate_increase_by` and `calculate_percent_of`. You just feed it raw numbers—the base amount and the percentage. The server runs the math using pure JavaScript, giving back an absolute number every single time. No approximations allowed here. Just accurate financials.

This tool set lets you calculate sales tax and VAT rates by passing a base price and the required tax rate to determine the final total including Value Added Tax (VAT) or standard sales tax. You can use `calculate_percent_of` to figure out exactly what specific portion—say, 7%—represents out of a larger base total; this is essential when you're summarizing financial reports for clients.

When it comes time to apply discounts and coupons, the server uses `calculate_increase_by`. You pass the original cost, and then use a negative percentage. This immediately tells you the reduced total by applying the discount, simulating how a coupon works at the checkout counter. It’s perfect for figuring out markdown values or tiered pricing structures.

If you need to compute relative increases—like calculating annual growth rates, depreciation, or investment gains—you call `calculate_increase_by`. You adjust a starting value up or down by a specified percentage. This gives you the precise new value, whether it's positive growth or negative decline.

What makes this powerful is that you can handle layered math. For instance, imagine an item has a coupon applied to it first; then the tax gets added to that discounted subtotal. You run multiple calculations sequentially: use `calculate_increase_by` to get the pre-tax discount price, and then feed *that* result into another calculation (or back into `calculate_percent_of`) to apply the final sales tax rate. This gives you a reliable source of truth for complex quantitative reporting.

You need certainty when dealing with invoices, payroll processing, or e-commerce checkouts. Instead of risking an AI hallucination on basic arithmetic, this engine provides your agent with a calculator that never guesses. It’s pure, raw math logic built into the toolset.

## Tools

### calculate_increase_by
Changes a starting value up or down by a specified percentage. Use a negative percent for discounts.

### calculate_percent_of
Computes exactly what X percent of a given base total is. Great for tax calculations and finding discount values.

## Prompt Examples

**Prompt:** 
```
What is exactly 15.5% of $2,500.00?
```

**Response:** 
```
✅ **Percentage Extracted:** `$387.50`
```

**Prompt:** 
```
Add a 20% VAT tax rate to the baseline price of $500.
```

**Response:** 
```
✅ **Increased Value:** The final price with VAT is `$600.00`.
```

**Prompt:** 
```
Apply a 10% coupon discount to the shopping cart total of $1000.
```

**Response:** 
```
✅ **Decreased Value:** The new cart total is `$900.00`.
```

## Capabilities

### Calculate Sales Tax and VAT
Pass a base price and tax rate to determine the final amount including Value Added Tax (VAT) or sales tax.

### Apply Discounts and Coupons
Determine the reduced total by applying a percentage discount to an original cost, simulating coupon use.

### Compute Relative Increases
Adjust a starting value up or down by a specified percentage, useful for calculating growth rates or depreciation.

### Determine Percentage of Total
Calculate what specific portion (X%) represents out of a larger base total. Essential for financial reporting summaries.

### Handle Layered Math
Run multiple calculations sequentially—for example, taking a discount off an item price and then applying tax to the discounted subtotal.

## Use Cases

### Processing an E-commerce Checkout
A customer's cart totals $1000. The agent needs to apply a 10% coupon discount and then calculate the 20% VAT on the reduced total. The agent calls `calculate_percent_of` twice in sequence, ensuring the tax is applied only to the discounted amount, resulting in a perfect final checkout price.

### Calculating Quarterly Sales Commission
A salesperson made $50,000 in revenue. Their commission is 12%. The agent uses `calculate_percent_of` to immediately determine the exact commission amount ($6,000) and can then calculate their yearly projected earnings by applying a growth rate increase.

### Writing Off Inventory Value
A warehouse needs to write down old stock valued at $15,000 due to obsolescence. The agent uses `calculate_increase_by` with a negative percentage (e.g., -25%) to determine the precise new book value of the inventory.

### Determining Payroll Tax Liabilities
The payroll system calculates gross wages ($8,000) and needs to know the exact withholding tax at 6.5%. The agent calls `calculate_percent_of` with this data, getting a precise number that must match legal requirements.

## Benefits

- Stop rounding errors. The engine guarantees precise, fractional calculations for VAT and taxes, removing guesswork from your final invoice total.
- Process layered discounts accurately. You can chain calls to calculate a discount off a price *before* applying tax, maintaining mathematical rigor.
- Ensure consistent growth metrics. Use `calculate_increase_by` to reliably determine year-over-year percentage changes for reporting without variance.
- Build accurate checkout logic. Determine the exact coupon value or proportional fee using `calculate_percent_of`, making your e-commerce platform reliable.
- Handle negative adjustments easily. Applying a discount is just another calculation; use a negative percent input in `calculate_increase_by` to find the new, lower total.

## How It Works

The bottom line is that you send raw numbers to the engine and get a mathematically proven final value back. No guessing involved.

1. Start by providing your AI client with two numbers: the base value (e.g., $500) and the percentage change (e.g., 20%).
2. The agent invokes a tool, like `calculate_percent_of`, which runs the math using deterministic JavaScript logic.
3. You get back one precise number representing the calculated result—the exact tax amount, discount, or new total.

## Frequently Asked Questions

**Can it calculate discounts?**
Yes, by passing a negative percentage.

**Is it deterministic?**
Absolutely. Pure math evaluation local.

**Does it support tax addition?**
Yes, simply use the increase_by function.

**When should I use `calculate_increase_by` versus `calculate_percent_of` with the Percentage Calculation Engine?**
Use `calculate_percent_of` when you need to find a percentage of a base number (e.g., 15% of $200). Use `calculate_increase_by` when the change is relative, like applying an adjustment or discount rate directly to an amount.

**How does the Percentage Calculation Engine handle invalid or missing financial inputs?**
The server validates all inputs using native JavaScript math logic. If a required value is missing or improperly formatted, the tool returns a specific error code instead of attempting to guess an answer. This keeps your data flow clean.

**Does running `calculate_percent_of` impact performance for complex financial reports?**
No. Because the math runs as pure JavaScript at the edge, it operates outside the LLM's main processing layer. This design keeps latency low, even when you run multiple successive percentage checks.

**Can the Percentage Calculation Engine accurately handle floating-point precision for currency?**
Yes, it handles financial precision correctly because it utilizes native JavaScript math standards. You get accurate results for currency calculations without the rounding errors that can plague general LLM processing.

**Is the Percentage Calculation Engine limited to US dollar or Euro calculations?**
The engine is designed around pure mathematical logic, not specific currencies. It works with any numerical input you provide (e.g., USD, EUR) as long as the values are structured correctly.