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

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

@@ -5,6 +5,22 @@ 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.2] - 2026-02-04
+
+### Added
+- **MCP Server**: FastMCP-based MCP server exposing 14 tools for LLM-driven investment planning
+  - Stateful builder pattern: create scenario -> add devices -> set timespan -> review -> submit -> get results
+  - All 10 device types supported with data shorthand (scalar expansion, CSV/JSON file loading)
+  - 3 result detail levels: summary, monthly, full
+  - Install via `pip install site-calc-investment[mcp]`
+  - CLI entry point: `site-calc-investment-mcp`
+- **`get_device_schema` tool**: Returns property schemas for each device type with types, units, and examples
+
+### Changed
+- Package now has `[mcp]` optional dependency group (`fastmcp>=2.0`)
+
+---
+
 ## [1.2.1] - 2026-02-03
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: site-calc-investment
-Version: 1.2.1
+Version: 1.2.2
 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
@@ -25,6 +25,7 @@ Requires-Dist: numpy>=1.24
 Requires-Dist: pydantic>=2.0
 Requires-Dist: python-dateutil>=2.8
 Provides-Extra: dev
+Requires-Dist: fastmcp>=2.0; extra == 'dev'
 Requires-Dist: mypy>=1.0; extra == 'dev'
 Requires-Dist: pandas>=2.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
@@ -33,6 +34,8 @@ Requires-Dist: pytest-timeout>=2.2; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.1; extra == 'dev'
 Requires-Dist: tzdata>=2024.1; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # Site-Calc Investment Client

{site_calc_investment-1.2.1 → site_calc_investment-1.2.2}/examples/01_basic_capacity_planning.py

@@ -22,6 +22,7 @@ from site_calc_investment.models.requests import TimeSpanInvestment
 
 
 def main():
+    """Run basic capacity planning example with 1-week battery optimization."""
     # Get credentials from environment
     api_url = os.environ.get("INVESTMENT_API_URL_DEV") or os.environ.get("INVESTMENT_API_URL")
     api_key = os.environ.get("INVESTMENT_API_KEY_DEV") or os.environ.get("INVESTMENT_API_KEY")

{site_calc_investment-1.2.1 → site_calc_investment-1.2.2}/examples/02_scenario_comparison.py

@@ -125,6 +125,7 @@ def create_scenario(
 
 
 def main():
+    """Run scenario comparison example comparing three battery sizes."""
     print("=" * 60)
     print("BATTERY CAPACITY SIZING: SCENARIO COMPARISON")
     print("=" * 60)

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

@@ -1,6 +1,6 @@
 [project]
 name = "site-calc-investment"
-version = "1.2.1"
+version = "1.2.2"
 description = "Python client for Site-Calc investment planning (capacity sizing, ROI analysis)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -29,6 +29,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+mcp = ["fastmcp>=2.0"]
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
@@ -38,8 +39,12 @@ dev = [
     "mypy>=1.0",
     "pandas>=2.0",  # For scenario comparison
     "tzdata>=2024.1",  # Timezone data for Windows
+    "fastmcp>=2.0",  # For MCP server tests
 ]
 
+[project.scripts]
+site-calc-investment-mcp = "site_calc_investment.mcp:main"
+
 [project.urls]
 Homepage = "https://github.com/stranma/site-calc-investment"
 Documentation = "https://github.com/stranma/site-calc-investment#readme"

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

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

site_calc_investment-1.2.2/site_calc_investment/mcp/__init__.py

@@ -0,0 +1,15 @@
+"""MCP server for Site-Calc investment planning.
+
+Exposes investment optimization tools to LLM agents via FastMCP.
+Install with: pip install site-calc-investment[mcp]
+"""
+
+from site_calc_investment.mcp.server import mcp
+
+
+def main() -> None:
+    """Entry point for the MCP server."""
+    mcp.run()
+
+
+__all__ = ["main", "mcp"]

site_calc_investment-1.2.2/site_calc_investment/mcp/config.py

@@ -0,0 +1,34 @@
+"""Configuration for the MCP server, loaded from environment variables."""
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Config:
+    """MCP server configuration from environment variables."""
+
+    api_url: str
+    api_key: str
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        """Load configuration from environment variables.
+
+        :raises ValueError: If required environment variables are missing.
+        """
+        api_url = os.environ.get("INVESTMENT_API_URL", "")
+        api_key = os.environ.get("INVESTMENT_API_KEY", "")
+
+        if not api_url:
+            raise ValueError(
+                "INVESTMENT_API_URL environment variable is required. "
+                "Set it to the Site-Calc API URL (e.g., http://site-calc-prod-alb-xxx.elb.amazonaws.com)"
+            )
+        if not api_key:
+            raise ValueError(
+                "INVESTMENT_API_KEY environment variable is required. "
+                "Set it to your investment API key (starts with 'inv_')"
+            )
+
+        return cls(api_url=api_url, api_key=api_key)

site_calc_investment-1.2.2/site_calc_investment/mcp/data_loaders.py

@@ -0,0 +1,171 @@
+"""Data loading utilities for resolving price/profile shorthand to arrays."""
+
+import csv
+import json
+import os
+from typing import Any, Optional, Union
+
+
+def resolve_price_or_profile(
+    value: Union[float, int, list[float], dict[str, Any]],
+    expected_length: Optional[int],
+) -> list[float]:
+    """Resolve a price or profile value to a flat list of floats.
+
+    Accepts:
+    - float/int: expanded to constant array of expected_length
+    - list[float]: validated length (if expected_length set), returned as-is
+    - {"file": "path.csv"}: loaded from CSV (first numeric column)
+    - {"file": "path.csv", "column": "price_eur"}: specific column from CSV
+    - {"file": "path.json"}: loaded from JSON (flat array)
+
+    :param value: The value to resolve.
+    :param expected_length: Expected array length (from timespan). None skips length validation.
+    :returns: List of floats.
+    :raises ValueError: If the value cannot be resolved or has wrong length.
+    :raises FileNotFoundError: If a referenced file does not exist.
+    """
+    if isinstance(value, (int, float)):
+        if expected_length is None:
+            raise ValueError(
+                "Cannot expand scalar value without a timespan. Set the timespan first, or provide an explicit array."
+            )
+        return [float(value)] * expected_length
+
+    if isinstance(value, list):
+        result = [float(v) for v in value]
+        if expected_length is not None and len(result) != expected_length:
+            raise ValueError(
+                f"Array length {len(result)} does not match expected length {expected_length} "
+                f"(from timespan). Provide exactly {expected_length} values."
+            )
+        return result
+
+    if isinstance(value, dict):
+        return _load_from_file(value, expected_length)
+
+    raise ValueError(
+        f"Unsupported value type: {type(value).__name__}. "
+        "Expected a number (flat value), list of numbers, or "
+        '{"file": "path.csv"} for file loading.'
+    )
+
+
+def _load_from_file(spec: dict[str, Any], expected_length: Optional[int]) -> list[float]:
+    """Load data from a file reference.
+
+    :param spec: Dict with "file" key and optional "column" key.
+    :param expected_length: Expected array length.
+    :returns: List of floats loaded from file.
+    """
+    file_path = spec.get("file")
+    if not file_path:
+        raise ValueError('File reference must include a "file" key with the path.')
+
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(
+            f"Data file not found: {file_path}. Provide an absolute path to a CSV or JSON file on the local filesystem."
+        )
+
+    ext = os.path.splitext(file_path)[1].lower()
+    column = spec.get("column")
+
+    if ext == ".json":
+        result = _load_json(file_path)
+    elif ext in (".csv", ".tsv", ".txt"):
+        result = _load_csv(file_path, column)
+    else:
+        raise ValueError(f"Unsupported file format: '{ext}'. Supported formats: .csv, .tsv, .json")
+
+    if expected_length is not None and len(result) != expected_length:
+        raise ValueError(
+            f"File '{file_path}' has {len(result)} values, but expected {expected_length} "
+            f"(from timespan). The file must contain exactly {expected_length} values."
+        )
+
+    return result
+
+
+def _load_json(file_path: str) -> list[float]:
+    """Load a flat array from a JSON file."""
+    with open(file_path, encoding="utf-8") as f:
+        data = json.load(f)
+
+    if not isinstance(data, list):
+        raise ValueError(
+            f"JSON file '{file_path}' must contain a flat array of numbers, but got {type(data).__name__}."
+        )
+
+    try:
+        return [float(v) for v in data]
+    except (TypeError, ValueError) as e:
+        raise ValueError(f"JSON file '{file_path}' contains non-numeric values: {e}") from e
+
+
+def _load_csv(file_path: str, column: Optional[str] = None) -> list[float]:
+    """Load numeric data from a CSV file.
+
+    If column is specified, reads that column by header name.
+    Otherwise, reads the first numeric column.
+    """
+    with open(file_path, encoding="utf-8", newline="") as f:
+        sample = f.read(8192)
+        f.seek(0)
+
+        try:
+            dialect = csv.Sniffer().sniff(sample)
+        except csv.Error:
+            dialect = csv.excel  # type: ignore[assignment]
+
+        has_header = csv.Sniffer().has_header(sample)
+        f.seek(0)
+
+        reader = csv.reader(f, dialect)
+
+        if has_header:
+            headers = next(reader)
+            if column:
+                try:
+                    col_idx = headers.index(column)
+                except ValueError:
+                    raise ValueError(
+                        f"Column '{column}' not found in '{file_path}'. Available columns: {', '.join(headers)}"
+                    )
+            else:
+                col_idx = _find_first_numeric_column(headers, file_path)
+        else:
+            if column:
+                raise ValueError(f"Cannot use column='{column}' with '{file_path}': the file has no header row.")
+            col_idx = 0
+
+        values: list[float] = []
+        for row_num, row in enumerate(reader, start=2 if has_header else 1):
+            if not row or all(cell.strip() == "" for cell in row):
+                continue
+            if col_idx >= len(row):
+                raise ValueError(
+                    f"Row {row_num} in '{file_path}' has only {len(row)} columns, "
+                    f"but column index {col_idx} was expected."
+                )
+            try:
+                values.append(float(row[col_idx]))
+            except ValueError:
+                raise ValueError(
+                    f"Non-numeric value '{row[col_idx]}' at row {row_num}, column {col_idx} in '{file_path}'."
+                )
+
+    if not values:
+        raise ValueError(f"No data found in '{file_path}'.")
+
+    return values
+
+
+def _find_first_numeric_column(headers: list[str], file_path: str) -> int:
+    """Find the first column that looks numeric based on the header name."""
+    numeric_hints = ["price", "value", "cost", "demand", "power", "mw", "mwh", "eur", "profile"]
+    for i, h in enumerate(headers):
+        h_lower = h.lower().strip()
+        for hint in numeric_hints:
+            if hint in h_lower:
+                return i
+    return 0