site-calc-investment 1.2.2__py3-none-any.whl → 1.2.3__py3-none-any.whl

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/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/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

site_calc_investment/mcp/server.py

@@ -5,14 +5,21 @@ from typing import Any, Literal, Optional, cast
 from fastmcp import FastMCP
 
 from site_calc_investment.api.client import InvestmentClient
-from site_calc_investment.mcp.config import Config
+from site_calc_investment.mcp.config import Config, get_data_dir
+from site_calc_investment.mcp.data_loaders import save_csv
 from site_calc_investment.mcp.scenario import ScenarioStore
 
 mcp = FastMCP(
     "site-calc-investment",
-    instructions="Investment planning optimization tools for energy systems. "
-    "Build scenarios with batteries, CHP, PV, and market connections, "
-    "then submit for optimization to find optimal dispatch and ROI.",
+    instructions=(
+        "Investment planning optimization tools for energy systems. "
+        "Build scenarios with batteries, CHP, PV, and market connections, "
+        "then submit for optimization to find optimal dispatch and ROI.\n\n"
+        "IMPORTANT: Use save_data_file to write generated data (price arrays, "
+        "demand profiles) to the local filesystem BEFORE referencing them in "
+        "add_device. This MCP server runs locally and has filesystem access -- "
+        "you do not need to ask the user to save files manually."
+    ),
 )
 
 _store = ScenarioStore()
@@ -360,6 +367,52 @@ def list_jobs() -> list[dict[str, Any]]:
     return result
 
 
+# --- Data File Tools ---
+
+
+def save_data_file(
+    file_path: str,
+    columns: dict[str, list[float]],
+    overwrite: bool = False,
+) -> dict[str, Any]:
+    """Save generated data to a CSV file on the local filesystem.
+
+    This tool exists because you (the LLM) cannot write files directly --
+    but this MCP server runs on the user's local machine 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>"}.
+
+    Typical workflow:
+    1. Generate price/demand data as arrays
+    2. Call save_data_file to write them as CSV
+    3. Use the returned file_path in add_device properties
+
+    :param file_path: Filename or path (e.g., "prices_2025.csv").
+        Relative paths resolve against INVESTMENT_DATA_DIR env var (or cwd).
+        Extension '.csv' is appended if missing.
+    :param columns: Named columns of numeric data.
+        Example: {"hour": [0, 1, 2, ...], "price_eur_mwh": [30.5, 42.1, ...]}.
+        All columns must have the same length.
+    :param overwrite: Allow overwriting an existing file (default: False).
+    :returns: Dict with file_path (absolute), column names, and row count.
+    """
+    data_dir = get_data_dir()
+    saved_path = save_csv(
+        file_path=file_path,
+        columns=columns,
+        data_dir=data_dir,
+        overwrite=overwrite,
+    )
+    col_names = list(columns.keys())
+    row_count = len(next(iter(columns.values())))
+    return {
+        "file_path": saved_path,
+        "columns": col_names,
+        "rows": row_count,
+        "message": f"Saved {row_count} rows to {saved_path}",
+    }
+
+
 # --- Helper Tools ---
 
 
@@ -644,11 +697,11 @@ def get_device_schema(device_type: str) -> dict[str, Any]:
                     "description": "Maximum demand profile (MW, not MWh!)",
                 },
                 "min_demand_profile": {
-                    "type": "float | list[float]",
+                    "type": "float | list[float] | {file: str}",
                     "required": False,
                     "default": 0,
                     "unit": "MW",
-                    "description": "Minimum demand profile or constant",
+                    "description": "Minimum demand profile or constant. Supports file loading.",
                 },
             },
             "supports_schedule": False,
@@ -664,11 +717,11 @@ def get_device_schema(device_type: str) -> dict[str, Any]:
                     "description": "Maximum heat demand profile (MW)",
                 },
                 "min_demand_profile": {
-                    "type": "float | list[float]",
+                    "type": "float | list[float] | {file: str}",
                     "required": False,
                     "default": 0,
                     "unit": "MW",
-                    "description": "Minimum heat demand profile or constant",
+                    "description": "Minimum heat demand profile or constant. Supports file loading.",
                 },
             },
             "supports_schedule": False,
@@ -702,3 +755,4 @@ mcp.tool()(get_job_result)
 mcp.tool()(cancel_job)
 mcp.tool()(list_jobs)
 mcp.tool()(get_device_schema)
+mcp.tool()(save_data_file)

{site_calc_investment-1.2.2.dist-info → site_calc_investment-1.2.3.dist-info}/METADATA

@@ -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.dist-info → site_calc_investment-1.2.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-site_calc_investment/__init__.py,sha256=rtRAjNce13k5WT1S7WnL6tjnKXA6MdyzHeVggkI9jNc,2084
+site_calc_investment/__init__.py,sha256=5pzvQMGWiyaDU8ncrdevsRNvGHutVboe1C78BKqTMqA,2084
 site_calc_investment/exceptions.py,sha256=dz1wXM3Y4hHzK-PaQPY7sFPgLwUd6bZyWfJDVH9aBZk,2108
 site_calc_investment/analysis/__init__.py,sha256=u6nwlhY3gQnxn-nkUGc68ynmoBU7NUt3uoUuM9AfQIs,414
 site_calc_investment/analysis/comparison.py,sha256=3aqKpVcGy-2YfQZjS6qAzN12vuzvwDmE1JgZn6fuuIE,4487
@@ -6,17 +6,17 @@ site_calc_investment/analysis/financial.py,sha256=gzKYmylGDKZDqx1ZBefZwJMS9NuflH
 site_calc_investment/api/__init__.py,sha256=LmrMw5jO24beExGtcau7B34NnMkJUmDsHngEdzuCans,140
 site_calc_investment/api/client.py,sha256=Uh4yYPIC9oL1uiaaTe36xFeb5yfOsxkMetZojxRZoJs,15064
 site_calc_investment/mcp/__init__.py,sha256=jxRR08m6sGun1lOLQ5Z9X9uB26UqVyT90is7vvvW49w,326
-site_calc_investment/mcp/config.py,sha256=uZ_n4jdE_fO0MKsT8GoqQYrX9pUnKmUoRcIQujTIEms,1089
-site_calc_investment/mcp/data_loaders.py,sha256=6jvooKD4UoKIaeaU__fEc6t9viaf2FHDpTPh8WSRWYY,6308
+site_calc_investment/mcp/config.py,sha256=FuESohfC0yfk6g1R326DbAZoZN7V1YQ2Jbx7Vi6IN3M,1292
+site_calc_investment/mcp/data_loaders.py,sha256=Y1Ilk2YSh-qd3bDcN_MokxLevljPcDO3VGRnPYYdvvk,8995
 site_calc_investment/mcp/scenario.py,sha256=APLrYCXdl2VWMebk_kWfZu3Mvpbw9DIFHtnYGV9bH3Q,18774
-site_calc_investment/mcp/server.py,sha256=CEHCs4adr270CaSKZdk-xgaZ_SkjzWGL2nMOEI_Olkw,25445
+site_calc_investment/mcp/server.py,sha256=V1LFddWm6XPt1bdEZ4FZ_h7nYZxU7r_56JsitCki27M,27616
 site_calc_investment/models/__init__.py,sha256=aJsKxZGYe8AwsB7ZVrjRJs961iCd6KNKN5fpeYe52FY,1779
 site_calc_investment/models/common.py,sha256=r6Acg8uICJTETQ1FoVuBEdM8ThLQqwCVhclYO3kmCAY,5817
 site_calc_investment/models/devices.py,sha256=RmlbcxjavC3nFRyCJ6n8aUp2ZosVTpszmMmJfqpgd9c,9895
 site_calc_investment/models/requests.py,sha256=K3ESSgh3Qkq26jIL3TLTD6TRGmttVSiUUPTdbCmwRiw,5089
 site_calc_investment/models/responses.py,sha256=pmFfhSCAlCUZTxRDh0IdBn5znJiiFjF7U3LHZON_yQY,5482
-site_calc_investment-1.2.2.dist-info/METADATA,sha256=GlBIVQTTJQTFae5e-5SrO6fkRCyrrtDBw4a8puq-EiQ,7520
-site_calc_investment-1.2.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-site_calc_investment-1.2.2.dist-info/entry_points.txt,sha256=4q9JDR4ahtnx04H_wnMkl_td1Ki88099NbS7qRrOfg0,75
-site_calc_investment-1.2.2.dist-info/licenses/LICENSE,sha256=tmWogc4edAjn_ccDCKSLvMGW7asakJnAlQWuNqgApIs,1071
-site_calc_investment-1.2.2.dist-info/RECORD,,
+site_calc_investment-1.2.3.dist-info/METADATA,sha256=ZO-8638LBrDp9whS0TxFN3g1LaooAmGlEY_FCbT_YgM,9189
+site_calc_investment-1.2.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+site_calc_investment-1.2.3.dist-info/entry_points.txt,sha256=4q9JDR4ahtnx04H_wnMkl_td1Ki88099NbS7qRrOfg0,75
+site_calc_investment-1.2.3.dist-info/licenses/LICENSE,sha256=tmWogc4edAjn_ccDCKSLvMGW7asakJnAlQWuNqgApIs,1071
+site_calc_investment-1.2.3.dist-info/RECORD,,