site-calc-investment 1.2.2__tar.gz → 1.2.3__tar.gz

{site_calc_investment-1.2.2 → site_calc_investment-1.2.3}/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to the Site-Calc Investment Client will be documented in thi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.3] - 2026-02-04
+
+### Added
+- **`save_data_file` MCP tool**: New tool (#15) that writes generated data (price arrays, demand
+  profiles) to CSV files on the local filesystem. Solves the problem where the LLM cannot write
+  files directly but the MCP server can.
+  - Supports named columns with automatic `.csv` extension
+  - Relative paths resolve against `INVESTMENT_DATA_DIR` environment variable
+  - Returned file path can be used directly in `add_device` via `{"file": "...", "column": "..."}`
+- **`INVESTMENT_DATA_DIR` environment variable**: Optional config for `save_data_file` base directory
+- **MCP Server specification**: Full docs at `docs/MCP_SERVER_SPEC.md`
+
+### Changed
+- MCP server instructions updated to inform the LLM about `save_data_file` capability
+- MCP tool count: 14 -> 15
+
+---
+
+
 ## [1.2.2] - 2026-02-04
 
 ### Added

{site_calc_investment-1.2.2 → site_calc_investment-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: site-calc-investment
-Version: 1.2.2
+Version: 1.2.3
 Summary: Python client for Site-Calc investment planning (capacity sizing, ROI analysis)
 Project-URL: Homepage, https://github.com/stranma/site-calc-investment
 Project-URL: Documentation, https://github.com/stranma/site-calc-investment#readme
@@ -212,6 +212,60 @@ comparison = compare_scenarios(
 print(comparison)  # DataFrame with NPV, IRR, costs, revenues
 ```
 
+## MCP Server (Claude Desktop Integration)
+
+The package includes an MCP server for use with Claude Desktop and other LLM tools.
+
+### Installation
+
+```bash
+pip install site-calc-investment[mcp]
+```
+
+### Claude Desktop Configuration
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "site-calc-investment": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/client-investment", "site-calc-investment-mcp"],
+      "env": {
+        "INVESTMENT_API_URL": "http://your-api-url",
+        "INVESTMENT_API_KEY": "inv_your_key_here",
+        "INVESTMENT_DATA_DIR": "/path/to/data/directory"
+      }
+    }
+  }
+}
+```
+
+### Tools (15)
+
+| Tool | Description |
+|------|-------------|
+| `create_scenario` | Create a new draft scenario |
+| `add_device` | Add a device (battery, CHP, PV, etc.) |
+| `set_timespan` | Set optimization time horizon |
+| `set_investment_params` | Set financial parameters (NPV, IRR) |
+| `review_scenario` | Review scenario before submission |
+| `remove_device` | Remove a device |
+| `delete_scenario` | Delete a scenario |
+| `list_scenarios` | List all draft scenarios |
+| `submit_scenario` | Submit for optimization |
+| `get_job_status` | Check job progress |
+| `get_job_result` | Get optimization results |
+| `cancel_job` | Cancel a job |
+| `list_jobs` | List all jobs |
+| `get_device_schema` | Get device property schema |
+| `save_data_file` | Save generated data as CSV |
+
+`save_data_file` lets the LLM write generated data (price arrays, demand profiles) to local CSV files, which can then be referenced in `add_device` properties.
+
+See [docs/MCP_SERVER_SPEC.md](docs/MCP_SERVER_SPEC.md) for full specification.
+
 ## Documentation
 
 Full documentation available at: https://github.com/stranma/site-calc-investment#readme

{site_calc_investment-1.2.2 → site_calc_investment-1.2.3}/README.md

@@ -172,6 +172,60 @@ comparison = compare_scenarios(
 print(comparison)  # DataFrame with NPV, IRR, costs, revenues
 ```
 
+## MCP Server (Claude Desktop Integration)
+
+The package includes an MCP server for use with Claude Desktop and other LLM tools.
+
+### Installation
+
+```bash
+pip install site-calc-investment[mcp]
+```
+
+### Claude Desktop Configuration
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "site-calc-investment": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/client-investment", "site-calc-investment-mcp"],
+      "env": {
+        "INVESTMENT_API_URL": "http://your-api-url",
+        "INVESTMENT_API_KEY": "inv_your_key_here",
+        "INVESTMENT_DATA_DIR": "/path/to/data/directory"
+      }
+    }
+  }
+}
+```
+
+### Tools (15)
+
+| Tool | Description |
+|------|-------------|
+| `create_scenario` | Create a new draft scenario |
+| `add_device` | Add a device (battery, CHP, PV, etc.) |
+| `set_timespan` | Set optimization time horizon |
+| `set_investment_params` | Set financial parameters (NPV, IRR) |
+| `review_scenario` | Review scenario before submission |
+| `remove_device` | Remove a device |
+| `delete_scenario` | Delete a scenario |
+| `list_scenarios` | List all draft scenarios |
+| `submit_scenario` | Submit for optimization |
+| `get_job_status` | Check job progress |
+| `get_job_result` | Get optimization results |
+| `cancel_job` | Cancel a job |
+| `list_jobs` | List all jobs |
+| `get_device_schema` | Get device property schema |
+| `save_data_file` | Save generated data as CSV |
+
+`save_data_file` lets the LLM write generated data (price arrays, demand profiles) to local CSV files, which can then be referenced in `add_device` properties.
+
+See [docs/MCP_SERVER_SPEC.md](docs/MCP_SERVER_SPEC.md) for full specification.
+
 ## Documentation
 
 Full documentation available at: https://github.com/stranma/site-calc-investment#readme

site_calc_investment-1.2.3/docs/MCP_SERVER_SPEC.md

@@ -0,0 +1,413 @@
+# MCP Server Specification
+
+**Package:** `site-calc-investment[mcp]`
+**Server name:** `site-calc-investment`
+**Protocol:** MCP (Model Context Protocol) via FastMCP
+**Tools:** 15
+
+---
+
+## 1. Overview
+
+The MCP server exposes the Site-Calc investment planning API as tools that LLMs (e.g., Claude Desktop) can call interactively. Users describe what they want to optimize in natural language, and the LLM assembles scenarios, submits jobs, and retrieves results through these tools.
+
+### 1.1 Architecture
+
+```
+Claude Desktop (LLM)
+    |
+    | MCP protocol (stdio)
+    v
+site-calc-investment-mcp (local process)
+    |
+    | HTTPS / REST
+    v
+Site-Calc API (remote server)
+```
+
+The MCP server runs **locally** on the user's machine. It has full filesystem access (for CSV data files) and network access (for the optimization API).
+
+### 1.2 Key Capabilities
+
+| Feature | Value |
+|---------|-------|
+| Tools | 15 |
+| Device types | 10 |
+| Max horizon | 100,000 intervals (~11 years) |
+| Resolution | 1-hour |
+| Local filesystem | Read + Write (CSV data files) |
+| API connection | HTTPS to Site-Calc server |
+
+---
+
+## 2. Configuration
+
+### 2.1 Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `INVESTMENT_API_URL` | Yes | Site-Calc API base URL |
+| `INVESTMENT_API_KEY` | Yes | API key (starts with `inv_`) |
+| `INVESTMENT_DATA_DIR` | No | Default directory for `save_data_file` relative paths |
+
+`INVESTMENT_API_URL` and `INVESTMENT_API_KEY` are required for job submission tools (`submit_scenario`, `get_job_status`, `get_job_result`, `cancel_job`). Scenario assembly tools work without them.
+
+`INVESTMENT_DATA_DIR` sets the base directory for resolving relative paths in `save_data_file`. If not set, relative paths resolve against the current working directory.
+
+### 2.2 Claude Desktop Configuration
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "site-calc-investment": {
+      "command": "C:\\Users\\Admin\\.local\\bin\\uv.exe",
+      "args": [
+        "run",
+        "--directory", "C:\\my_source\\site-calc\\client-investment",
+        "site-calc-investment-mcp"
+      ],
+      "env": {
+        "INVESTMENT_API_URL": "https://api.site-calc.example.com",
+        "INVESTMENT_API_KEY": "inv_your_api_key_here",
+        "INVESTMENT_DATA_DIR": "C:\\my_source\\BESS_Optimization_Tool"
+      }
+    }
+  }
+}
+```
+
+### 2.3 Installation
+
+```bash
+pip install site-calc-investment[mcp]
+```
+
+Or with uv (recommended for development):
+
+```bash
+cd client-investment
+uv sync --group dev
+```
+
+---
+
+## 3. Tool Reference
+
+### 3.1 Scenario Assembly Tools
+
+#### `create_scenario`
+
+Create a new draft optimization scenario.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Human-readable name |
+| `description` | string | No | Longer description |
+
+**Returns:** `{"scenario_id": "sc_...", "name": "..."}`
+
+---
+
+#### `add_device`
+
+Add a device to a draft scenario.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `scenario_id` | string | Yes | Target scenario |
+| `device_type` | string | Yes | One of 10 device types (see Section 4) |
+| `name` | string | Yes | Unique device name within scenario |
+| `properties` | object | Yes | Device-specific properties |
+| `schedule` | object | No | Runtime constraints |
+
+Properties support data shorthand:
+- A number (e.g., `50.0`) -- expanded to constant array matching the timespan
+- A list (e.g., `[30, 40, 80, 50]`) -- used directly
+- A file reference (e.g., `{"file": "prices.csv", "column": "price_eur"}`) -- loaded from local CSV
+
+**Returns:** Summary string.
+
+---
+
+#### `set_timespan`
+
+Set the optimization time horizon.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `scenario_id` | string | Yes | | Target scenario |
+| `start_year` | int | Yes | | Start year (e.g., 2025) |
+| `years` | int | No | 1 | Number of years |
+
+One year = 8,760 intervals. Maximum ~11 years (100,000 intervals).
+
+**Returns:** Confirmation string with interval count.
+
+---
+
+#### `set_investment_params`
+
+Set financial parameters for ROI calculation (NPV, IRR, payback).
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `scenario_id` | string | Yes | | Target scenario |
+| `discount_rate` | float | No | 0.05 | Annual discount rate (0-0.5) |
+| `project_lifetime_years` | int | No | timespan years | Project lifetime |
+| `device_capital_costs` | object | No | | CAPEX by device name (EUR) |
+| `device_annual_opex` | object | No | | Annual O&M by device name (EUR) |
+
+**Returns:** Confirmation string.
+
+---
+
+#### `review_scenario`
+
+Show a summary of the draft scenario before submitting.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `scenario_id` | string | Yes | Scenario to review |
+
+**Returns:** Dict with `name`, `devices`, `timespan`, `investment_params`, `validation`.
+
+---
+
+#### `remove_device`
+
+Remove a device from a draft scenario.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `scenario_id` | string | Yes | Target scenario |
+| `device_name` | string | Yes | Device to remove |
+
+**Returns:** Confirmation string.
+
+---
+
+#### `delete_scenario`
+
+Delete a draft scenario entirely.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `scenario_id` | string | Yes | Scenario to delete |
+
+**Returns:** Confirmation string.
+
+---
+
+#### `list_scenarios`
+
+List all active draft scenarios.
+
+**Returns:** List of `{"id", "name", "device_count", "has_timespan", "job_count"}`.
+
+---
+
+### 3.2 Job Submission and Management Tools
+
+#### `submit_scenario`
+
+Submit a draft scenario for server-side optimization.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `scenario_id` | string | Yes | | Scenario to submit |
+| `objective` | string | No | `maximize_profit` | Optimization objective |
+| `solver_timeout` | int | No | 300 | Time limit in seconds (max 900) |
+
+Objectives: `maximize_profit`, `minimize_cost`, `maximize_self_consumption`.
+
+**Returns:** `{"job_id": "...", "status": "pending"}`
+
+---
+
+#### `get_job_status`
+
+Check job status and progress.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `job_id` | string | Yes | Job identifier |
+
+**Returns:** Dict with `job_id`, `status`, and optionally `progress`, `message`, `estimated_completion_seconds`, `solver_time_seconds`, `error`.
+
+---
+
+#### `get_job_result`
+
+Retrieve completed optimization results.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `job_id` | string | Yes | | Job identifier |
+| `detail_level` | string | No | `summary` | `summary`, `monthly`, or `full` |
+
+Detail levels:
+- **summary** -- Aggregated totals (profit, cost, solve time, investment metrics). Compact.
+- **monthly** -- Summary + per-device monthly breakdowns.
+- **full** -- All data including hourly schedules. Can be very large.
+
+**Returns:** Result dict at requested detail level.
+
+---
+
+#### `cancel_job`
+
+Cancel a pending or running job.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `job_id` | string | Yes | Job to cancel |
+
+**Returns:** `{"job_id": "...", "status": "cancelled"}`
+
+---
+
+#### `list_jobs`
+
+List all scenarios and their associated jobs.
+
+**Returns:** List of `{"scenario_id", "scenario_name", "job_ids", "job_count"}`.
+
+---
+
+### 3.3 Data File Tools
+
+#### `save_data_file`
+
+Save generated data to a CSV file on the local filesystem.
+
+This tool exists because the LLM cannot write files directly, but this MCP server runs locally and can. Use it to persist generated data arrays (prices, demand profiles, etc.) so they can be referenced in `add_device` via `{"file": "<path>", "column": "<name>"}`.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file_path` | string | Yes | | Filename or path (e.g., `"prices_2025.csv"`) |
+| `columns` | object | Yes | | Named columns: `{"col_name": [float, ...]}` |
+| `overwrite` | bool | No | false | Allow overwriting existing files |
+
+Path resolution:
+- Absolute paths are used as-is
+- Relative paths resolve against `INVESTMENT_DATA_DIR` (or cwd if not set)
+- `.csv` extension is appended if missing
+- Non-`.csv` extensions are rejected
+
+**Returns:**
+```json
+{
+  "file_path": "C:\\Users\\Admin\\data\\prices.csv",
+  "columns": ["hour", "price_eur_mwh"],
+  "rows": 8760,
+  "message": "Saved 8760 rows to C:\\Users\\Admin\\data\\prices.csv"
+}
+```
+
+**Typical workflow:**
+```
+1. LLM generates price array (8760 values)
+2. LLM calls save_data_file(file_path="prices_2025.csv", columns={"price_eur": [...]})
+3. LLM calls add_device(properties={"price": {"file": "C:/.../prices_2025.csv", "column": "price_eur"}, ...})
+```
+
+---
+
+### 3.4 Helper Tools
+
+#### `get_device_schema`
+
+Get the properties schema for a device type.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `device_type` | string | Yes | Device type name |
+
+**Returns:** Schema dict with `properties`, `supports_schedule`, `example`.
+
+---
+
+## 4. Supported Device Types
+
+| Device Type | Description | Key Properties |
+|-------------|-------------|----------------|
+| `battery` | Battery energy storage | capacity, max_power, efficiency |
+| `chp` | Combined heat and power | gas_input, el_output, heat_output |
+| `heat_accumulator` | Thermal storage | capacity, max_power, efficiency |
+| `photovoltaic` | Solar PV | peak_power_mw, location, tilt, azimuth |
+| `electricity_import` | Buy from grid | price, max_import |
+| `electricity_export` | Sell to grid | price, max_export |
+| `gas_import` | Gas supply | price, max_import |
+| `heat_export` | Sell heat | price, max_export |
+| `electricity_demand` | Electricity load | max_demand_profile |
+| `heat_demand` | Heat load | max_demand_profile |
+
+Use `get_device_schema(device_type)` for full property documentation.
+
+---
+
+## 5. End-to-End Example
+
+A typical session for battery arbitrage analysis:
+
+```
+User: "Evaluate a 10 MWh battery with 2025 German electricity prices"
+
+LLM actions:
+1. Generate 8760 hourly prices for 2025
+2. save_data_file(file_path="de_prices_2025.csv",
+     columns={"hour": [0..8759], "price_eur_mwh": [32.1, 28.5, ...]})
+3. create_scenario(name="10 MWh Battery - DE 2025")
+4. set_timespan(scenario_id=sid, start_year=2025)
+5. add_device(scenario_id=sid, device_type="battery", name="BESS",
+     properties={"capacity": 10.0, "max_power": 5.0, "efficiency": 0.90})
+6. add_device(scenario_id=sid, device_type="electricity_import", name="GridBuy",
+     properties={"price": {"file": ".../de_prices_2025.csv", "column": "price_eur_mwh"},
+                 "max_import": 5.0})
+7. add_device(scenario_id=sid, device_type="electricity_export", name="GridSell",
+     properties={"price": {"file": ".../de_prices_2025.csv", "column": "price_eur_mwh"},
+                 "max_export": 5.0})
+8. set_investment_params(scenario_id=sid, discount_rate=0.05,
+     device_capital_costs={"BESS": 500000})
+9. review_scenario(scenario_id=sid)
+10. submit_scenario(scenario_id=sid)
+11. get_job_status(job_id=jid)  -- poll until complete
+12. get_job_result(job_id=jid, detail_level="summary")
+```
+
+LLM then presents the results: profit, NPV, IRR, payback period.
+
+---
+
+## 6. Error Handling
+
+Tools raise standard Python exceptions that FastMCP translates to MCP error responses:
+
+| Exception | Cause |
+|-----------|-------|
+| `ValueError` | Invalid parameters (wrong device type, missing properties, bad column data) |
+| `FileNotFoundError` | Referenced CSV/JSON file does not exist |
+| `FileExistsError` | `save_data_file` with `overwrite=False` on existing file |
+| `KeyError` | Nonexistent scenario_id or device_name |
+
+The LLM receives error messages and can retry with corrected parameters.
+
+---
+
+## 7. Testing
+
+```bash
+# Run MCP server tests
+cd client-investment && uv run pytest tests/test_mcp/ -v
+
+# Run full test suite
+cd client-investment && uv run pytest tests/ -v
+```
+
+Test coverage includes:
+- 11 tests for `save_csv` data layer
+- 2 tests for `save_data_file` tool integration
+- 7 MCP protocol integration tests (via FastMCP Client)
+- 77+ tests for scenario assembly and job management tools

{site_calc_investment-1.2.2 → site_calc_investment-1.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "site-calc-investment"
-version = "1.2.2"
+version = "1.2.3"
 description = "Python client for Site-Calc investment planning (capacity sizing, ROI analysis)"
 readme = "README.md"
 requires-python = ">=3.10"

{site_calc_investment-1.2.2 → site_calc_investment-1.2.3}/site_calc_investment/__init__.py

@@ -3,7 +3,7 @@
 Python client for long-term capacity planning and investment ROI analysis.
 """
 
-__version__ = "1.2.2"
+__version__ = "1.2.3"
 
 from site_calc_investment.analysis import (
     aggregate_annual,

{site_calc_investment-1.2.2 → site_calc_investment-1.2.3}/site_calc_investment/mcp/config.py

@@ -2,6 +2,12 @@
 
 import os
 from dataclasses import dataclass
+from typing import Optional
+
+
+def get_data_dir() -> Optional[str]:
+    """Get the configured data directory from INVESTMENT_DATA_DIR, or None."""
+    return os.environ.get("INVESTMENT_DATA_DIR") or None
 
 
 @dataclass(frozen=True)

{site_calc_investment-1.2.2 → site_calc_investment-1.2.3}/site_calc_investment/mcp/data_loaders.py

@@ -169,3 +169,73 @@ def _find_first_numeric_column(headers: list[str], file_path: str) -> int:
             if hint in h_lower:
                 return i
     return 0
+
+
+def _resolve_save_path(file_path: str, data_dir: Optional[str] = None) -> str:
+    """Resolve a file path for saving, applying data_dir for relative paths.
+
+    :param file_path: Filename or path (relative or absolute).
+    :param data_dir: Base directory for relative paths (or None for cwd).
+    :returns: Absolute path string.
+    :raises ValueError: If the extension is present but not '.csv'.
+    """
+    _, ext = os.path.splitext(file_path)
+    if ext and ext.lower() != ".csv":
+        raise ValueError(f"Only .csv files are supported, got '{ext}'. Use a .csv extension or omit the extension.")
+    if not ext:
+        file_path = file_path + ".csv"
+
+    if os.path.isabs(file_path):
+        return file_path
+
+    base = data_dir if data_dir else os.getcwd()
+    return os.path.abspath(os.path.join(base, file_path))
+
+
+def save_csv(
+    file_path: str,
+    columns: dict[str, list[float]],
+    data_dir: Optional[str] = None,
+    overwrite: bool = False,
+) -> str:
+    """Save column data as a CSV file.
+
+    :param file_path: Filename or path. Relative paths resolve against data_dir (or cwd).
+        Extension '.csv' is appended if missing.
+    :param columns: Named columns of numeric data. All must have the same length.
+    :param data_dir: Base directory for relative paths.
+    :param overwrite: Allow overwriting an existing file (default: False).
+    :returns: Absolute path to the saved file.
+    :raises ValueError: If columns are empty, have no rows, or have mismatched lengths.
+    :raises FileExistsError: If file exists and overwrite is False.
+    """
+    if not columns:
+        raise ValueError("columns must not be empty -- provide at least one named column.")
+
+    lengths = {name: len(vals) for name, vals in columns.items()}
+    unique_lengths = set(lengths.values())
+
+    if unique_lengths == {0}:
+        raise ValueError("All columns have 0 rows -- provide at least one row of data.")
+    if len(unique_lengths) > 1:
+        raise ValueError(f"All columns must have the same length, got: {lengths}")
+
+    resolved = _resolve_save_path(file_path, data_dir)
+
+    if not overwrite and os.path.exists(resolved):
+        raise FileExistsError(f"File already exists: {resolved}. Set overwrite=True to replace it.")
+
+    parent = os.path.dirname(resolved)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+
+    col_names = list(columns.keys())
+    row_count = len(next(iter(columns.values())))
+
+    with open(resolved, "w", encoding="utf-8", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(col_names)
+        for i in range(row_count):
+            writer.writerow([columns[name][i] for name in col_names])
+
+    return resolved