MCP-Relational-Data/QUICKSTART.md

# Quickstart

Get from `git clone` to running calculations in under 2 minutes.

---

## 1. Install Rust

If you don't have Rust yet:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```

Verify:

```bash
rustc --version
```

## 2. Get the Code

```bash
git clone https://git.dcos.net/dcosnet/MCP-Relational-Data.git
cd MCP-Relational-Data
```

## 3. Build & Run the GUI

```bash
cargo run
```

A desktop window opens with 6 calculator panels in a two-column layout. Type into any input field and results update in real time. No "Calculate" button needed.

### Try It: Ohm's Law

1. Find the **Ohm's Law & Watts Law** panel (top-left).
2. Type `2` in the **Current (A)** field.
3. Type `4` in the **Resistance (Ω)** field.
4. Instantly see: Power = 16 Watts, Voltage = 8 Volts.

### Try It: AI Token Cost

1. Find the **AI Token Cost Estimator** panel.
2. Click **►** to cycle through models (GPT-4o, Claude 3.5 Sonnet, etc.).
3. Type `1000000` in **Input Tokens** and `500000` in **Output Tokens**.
4. See the total cost appear (e.g., $7.50 for GPT-4o).

### Try It: Break-Even

1. Find the **Break-Even Analysis** panel.
2. Enter Fixed Costs: `10000`, Price per Unit: `50`, Variable Cost: `20`.
3. Read: you need to sell 334 units, generating $16,666.67 in revenue, to break even.

## 4. Use the Daemon Instead

The daemon is a stdin/stdout JSON API — perfect for scripting, MCP servers, or piping into other programs.

### Start It

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

It waits for JSON on stdin. Status messages appear on stderr.

### In Another Terminal (or pipe)

```bash
# List tools
echo '{"tool":"list"}' | cargo run -- --daemon

# Calculate Ohm's Law
echo '{"tool":"ohm","current":2,"resistance":4}' | cargo run -- --daemon

# Calculate margin
echo '{"tool":"margin","cost":50,"sell":75}' | cargo run -- --daemon

# Get help for a specific tool
echo '{"tool":"help","name":"token_cost"}' | cargo run -- --daemon
```

### Build a Slim Binary (No GUI Dependencies)

If you only need the daemon and want a smaller, faster build:

```bash
cargo build --release --no-default-features --features daemon
./target/release/mcp-relational-data --daemon
```

This skips pulling in iced and its entire graphics stack.

## 5. Use It From Another Program

### Python Example

```python
import subprocess, json

def calculate(tool: str, **params) -> dict:
    params["tool"] = tool
    proc = subprocess.run(
        ["./target/release/mcp-relational-data", "--daemon"],
        input=json.dumps(params),
        capture_output=True, text=True
    )
    return json.loads(proc.stdout.strip())

# Ohm's Law: I=2A, R=4Ω → V=8V, P=16W
result = calculate("ohm", current=2, resistance=4)
print(result)
# {"tool":"ohm","power":"16 Watts(W)","current":"2 Amps(A)",
#  "resistance":"4 Ohms(Ω)","voltage":"8 Volts(V)"}

# How much does 1M tokens cost on Claude 3.5 Sonnet?
result = calculate("token_cost", model="claude 3.5 sonnet",
                   input_tokens=1_000_000, output_tokens=500_000)
print(result)
# {"tool":"token_cost","model":"Claude 3.5 Sonnet",
#  "input_cost":"$3.00","output_cost":"$7.50","total_cost":"$10.50"}
```

### Shell Script Example

```bash
#!/bin/bash
# gpu_power_cost.sh — estimate annual cost of running a GPU server

RESULT=$(echo '{"tool":"electricity","watts":700,"hours":24,"days":30,"rate":0.12}' \
  | ./target/release/mcp-relational-data --daemon)

YEARLY=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['yearly_cost'])")
echo "Annual electricity cost for 700W GPU: $YEARLY"
```

### Node.js Example

```javascript
const { spawn } = require('child_process');

function calculate(tool, params) {
  return new Promise((resolve, reject) => {
    const proc = spawn('./target/release/mcp-relational-data', ['--daemon']);
    let out = '';
    proc.stdout.on('data', d => out += d);
    proc.on('close', () => {
      try { resolve(JSON.parse(out)); }
      catch (e) { reject(e); }
    });
    proc.stdin.write(JSON.stringify({ tool, ...params }));
    proc.stdin.end();
  });
}

calculate('break_even', { fixed: 10000, price: 50, variable: 20 })
  .then(r => console.log(`Break even at ${r.units} units`));
```

## 6. Daemon Protocol Reference

Every interaction is one JSON line in, one JSON line out.

### Request Format

```json
{"tool": "<name>", ...params}
```

### Special Tools

| Tool | Purpose | Params |
|---|---|---|
| `list` | List all available calculators | *(none)* |
| `help` | Get description + param list for a tool | `name` |

### Calculation Tools

| Tool | Required Params |
|---|---|
| `ohm` | Any 2 of: `power`, `current`, `resistance`, `voltage` |
| `margin` | `cost`, `sell` |
| `roi` | `investment`, `revenue` |
| `token_cost` | `model` (optional, defaults to GPT-4o), `input_tokens`, `output_tokens` |
| `electricity` | `watts`, `hours`, `days` (default 30), `rate` |
| `break_even` | `fixed`, `price`, `variable` |
| `solar` | `panels`, `panel_watts`, `sun_hours`, `rate`, `system_cost`, `efficiency` (default 80) |
| `print3d` | `filament_cost_kg`, `print_weight_g`, `print_time_h`, `printer_watts`, `elec_rate`, `failure_rate`, `sell_price` |

### Error Handling

Invalid JSON or unknown tools return:

```json
{"error": "invalid JSON: expected value at line 1 column 2"}
```

```json
{"error": "unknown tool: \"bogus\". Send {\"tool\":\"list\"} for options."}
```

## 7. CLI Quick Reference

```bash
mcp-relational-data                  # Launch GUI
mcp-relational-data --daemon         # Start JSON daemon
mcp-relational-data --help           # Show help
mcp-relational-data --version        # Print version
```

---

That's it. You're up and running.