MCP-Relational-Data/README.md

# MCP-Relational-Data

> Originally written in Visual Basic 6 (1999) by Jeremy Anderson. Modern port to Rust with iced GUI and a headless JSON daemon.

[![AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-edition_2021-orange.svg)](https://www.rust-lang.org/)
[![iced](https://img.shields.io/badge/iced-0.12-cyan.svg)](https://iced.rs/)

**Source:** [git.dcos.net/dcosnet/MCP-Relational-Data](https://git.dcos.net/dcosnet/MCP-Relational-Data)

---

## What Is This?

A desktop calculator suite that solves real-world problems across two domains:

- **Electronics engineering** — Ohm's Law & Watts Law with automatic pair-matching
- **Business & AI economics** — margin/markup, ROI, AI token cost, electricity cost, break-even analysis, solar revenue, 3D print cost

The project began in 1999 as a VB6 application called *Project for Electronics*, complete with `GoTo` statements, `Long` precision overflow bugs, and a 1 ms `Timer` hack for reactivity. Jeremy Anderson ported it to Rust — every VB6 bug is fixed, the architecture is decomposed into clean modules, and a daemon mode provides programmatic access.

## Calculators

| Calculator | Inputs | Outputs | Use Case |
|---|---|---|---|
| **Ohm's Law & Watts Law** | Any 2 of P, I, R, V | All 4 values | Circuit design, audio impedance matching, MOSFET PSU, LED drivers |
| **Margin & Markup** | Cost, Selling Price | Profit, Margin %, Markup % | Ecommerce pricing, wholesale vs retail |
| **Return on Investment** | Investment, Revenue | Profit, ROI % | Ad spend, marketing campaigns, capex |
| **AI Token Cost** | Model, Input/Output Tokens | Input/Output/Total Cost ($) | GPT-4o, Claude 3.5 Sonnet, and 4 more LLMs |
| **Electricity Cost** | Watts, Hours, Days, Rate | Daily/Monthly kWh, Monthly/Yearly Cost | GPU servers, datacenter racks, mining rigs |
| **Break-Even Analysis** | Fixed Costs, Price, Variable Cost | Units to Break Even, Revenue at Break Even | Product launch, pricing strategy |
| **Solar Panel Revenue** | Panels, Watts/Panel, Sun Hours, Rate, System Cost, Efficiency | System kW, kWh (daily/monthly/yearly), Revenue, Payback, 25-Year Earnings | Residential/commercial solar, net metering ROI |
| **3D Print Cost** | Filament Cost, Print Weight, Time, Printer Watts, Elec Rate, Failure %, Sell Price | Material Cost, Energy Cost, Cost/Print, Profit, Margin % | FDM/SLA print farming, Etsy shops, prototyping bids |

## Architecture

```
src/
  main.rs    — Entry point, CLI flag parsing (--gui / --daemon / --help / --version)
  calc.rs    — Pure calculation functions (zero I/O or GUI dependencies)
  gui.rs     — iced 0.12 desktop GUI (two-column layout, 8 panels)
  daemon.rs  — Stdin/stdout JSON API (MCP-friendly, one object per line)
```

- **`calc.rs`** contains every formula as a pure function: numbers in, numbers out. No side effects, no imports beyond `std`. Both the GUI and daemon call these same functions.
- **`gui.rs`** and **`daemon.rs`** are feature-gated behind `gui` and `daemon` Cargo features. Build only what you need.
- **`daemon.rs`** uses a data-driven tool registry (`TOOLS` constant array). Adding a calculator requires one entry in that array and one handler function — no dispatch match arms to maintain.

## Build & Run

### Prerequisites

- [Rust](https://rustup.rs/) (stable toolchain, edition 2021)

### GUI Mode (default)

```bash
cd MCP-Relational-Data
cargo run
```

### Daemon Mode

```bash
cargo run -- --daemon
```

### Slim Daemon-Only Binary

Skip the iced dependency entirely for a small, fast binary:

```bash
cargo run --no-default-features --features daemon -- --daemon
```

### Release Build

```bash
cargo build --release
# Binary at target/release/mcp-relational-data
```

## Daemon Protocol

The daemon reads one JSON object per line from stdin and writes one JSON object per line to stdout. Status messages go to stderr so they never pollute the JSON stream.

### List Available Tools

```bash
echo '{"tool":"list"}' | mcp-relational-data --daemon
```

```json
{"tools":["ohm","margin","roi","token_cost","electricity","break_even","solar","print3d"]}
```

### Get Tool Help

```bash
echo '{"tool":"help","name":"ohm"}' | mcp-relational-data --daemon
```

```json
{
  "name": "ohm",
  "description": "Ohm's Law & Watts Law — enter any 2 of 4 values...",
  "params": ["power", "current", "resistance", "voltage"]
}
```

### Run a Calculation

```bash
echo '{"tool":"ohm","current":2,"resistance":4}' | mcp-relational-data --daemon
```

```json
{
  "tool": "ohm",
  "power": "16 Watts(W)",
  "current": "2 Amps(A)",
  "resistance": "4 Ohms(\u03A9)",
  "voltage": "8 Volts(V)"
}
```

### More Examples

```bash
# Margin & Markup
echo '{"tool":"margin","cost":50,"sell":75}' | mcp-relational-data --daemon

# AI Token Cost (GPT-4o, 1M input + 500K output)
echo '{"tool":"token_cost","model":"gpt-4o","input_tokens":1000000,"output_tokens":500000}' | mcp-relational-data --daemon

# Electricity Cost (700W GPU, 24h/day, $0.12/kWh)
echo '{"tool":"electricity","watts":700,"hours":24,"days":30,"rate":0.12}' | mcp-relational-data --daemon

# Break-Even (fixed $10k, $50 price, $20 variable)
echo '{"tool":"break_even","fixed":10000,"price":50,"variable":20}' | mcp-relational-data --daemon

# Solar Panel Revenue (20 panels, 400W each, 5 sun hours, $0.12/kWh)
echo '{"tool":"solar","panels":20,"panel_watts":400,"sun_hours":5,"rate":0.12,"system_cost":12000,"efficiency":85}' | mcp-relational-data --daemon

# 3D Print Cost ($25/kg PLA, 50g print, 3h, 200W printer, 10% fail, sell $15)
echo '{"tool":"print3d","filament_cost_kg":25,"print_weight_g":50,"print_time_h":3,"printer_watts":200,"elec_rate":0.12,"failure_rate":10,"sell_price":15}' | mcp-relational-data --daemon
```

## CLI Flags

| Flag | Effect |
|---|---|
| *(none)* | Launch GUI |
| `--daemon` | Start stdin/stdout JSON daemon |
| `--help` / `-h` | Show usage info |
| `--version` / `-v` | Print version number |

## Cargo Feature Flags

| Feature | Dependencies | What It Enables |
|---|---|---|
| `gui` | iced 0.12 | Desktop GUI window |
| `daemon` | serde + serde_json | Stdin/stdout JSON API |
| *(default)* | both | `cargo run` builds everything |

## Ohm's Law Pair Matching

The solver uses a data-driven dispatch table. Each entry specifies a pair of non-zero checks and a solve function. Priority order:

| Priority | Known Values | Formulas |
|---|---|---|
| 1 | I, R | P = I² × R, V = I × R |
| 2 | I, V | R = V / I, P = I × V |
| 3 | I, P | V = P / I, R = V / I |
| 4 | R, V | I = V / R, P = I × V |
| 5 | V, P | I = P / V, R = V² / P |
| 6 | P, R | I = √(P/R), V = √(P×R) |

Enter any two non-zero values and the other two are computed instantly.

## VB6 Bugs Fixed

The original 1999 VB6 source had several defects that this port corrects:

1. **`Long` integer overflow** — VB6 used 16-bit `Long` for electrical values. Replaced with `f64` throughout.
2. **Brute-force square root** — Original used a `For` loop to approximate sqrt. Replaced with `(x).max(0.0).sqrt()`.
3. **1 ms Timer for reactivity** — Original polled inputs via a 1 ms `Timer` control. Replaced with iced's reactive `update()` pattern.
4. **No input validation** — Negative resistance or power was silently accepted. Now validated with error output.
5. **GoTo-based flow control** — Multiple `GoTo` labels. Replaced with structured match/data-driven dispatch.
6. **Formatting** — VB6 used `Format()` with fixed decimal places. Now uses 5-decimal precision with trailing-zero trimming.
7. **Unicode** — VB6 couldn't display the Ohm symbol (Ω). Now uses proper Unicode throughout.

## Supported AI Models (Token Cost)

| Model | Input ($/1M tokens) | Output ($/1M tokens) |
|---|---|---|
| GPT-4o | $2.50 | $10.00 |
| GPT-4 | $30.00 | $60.00 |
| GPT-3.5 Turbo | $0.50 | $1.50 |
| Claude 3.5 Sonnet | $3.00 | $15.00 |
| Claude 3 Opus | $15.00 | $75.00 |
| Claude 3 Haiku | $0.25 | $1.25 |

*Prices reflect commonly listed rates at time of writing. Update `calc.rs` if they change.*

## License

This project is licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0). See [LICENSE](LICENSE) for the full text.

Why AGPL? If you host this as a network service and modify it, you owe the world the source. Consider it a 25-year-later joke at the expense of the VB6 original that was locked in a `.frm` file on a floppy disk.

## Author

**Jeremy Anderson** — [dcos.net](https://dcos.net)

## Acknowledgments

- Original VB6 project: *Project for Electronics* by Jeremy Anderson (c. 1999)
- Ported to Rust with [iced](https://iced.rs/) 0.12
- Daemon protocol inspired by [MCP (Model Context Protocol)](https://modelcontextprotocol.io/)