# PVsyst CLI MCP

Unofficial, local-only [Model Context Protocol](https://modelcontextprotocol.io/) server and dependency-free Python adapter for **PVsystCLI 8.0.6 on Windows**. It wraps the vendor's installed CLI; it does not bundle PVsyst, projects, weather data, license material, or simulation output.

## Requirements

- Windows, Python 3.10+, PVsystCLI 8.0.6 and a configured PVsyst workspace.
- A PVsystCLI license or an available evaluation quota. **The GUI and CLI have separate licensing states**; check `pvsyst_license_info` before running simulations.
- An existing `.PRJ` project and `.VC*` variant in the workspace. The CLI does not create projects.

The `run-simulation` and `convert-meteo` flags used here were checked against `PVsystCLI.exe help <command>` for 8.0.6. Newer CLI versions may differ. A compatible SFI is needed for numeric result columns; without one, the generated CSV can contain only dates.

## Install

```powershell
cd path\to\pvsyst-cli-mcp
py -m pip install -r requirements.txt
$env:PVSYST_CLI = 'C:\Program Files\PVsyst8.0.6\PVsystCLI.exe'
$env:PVSYST_WORKSPACE = 'C:\path\to\PVsyst8.0_Data'
py -m unittest discover -s tests -v
```

Configure a local stdio MCP client with absolute paths (substitute your real paths and Python executable):

```json
{
  "mcpServers": {
    "pvsyst": {
      "command": "C:\\path\\to\\python.exe",
      "args": ["C:\\path\\to\\pvsyst-cli-mcp\\pvsyst_mcp_server.py"],
      "env": {
        "PVSYST_CLI": "C:\\Program Files\\PVsyst8.0.6\\PVsystCLI.exe",
        "PVSYST_WORKSPACE": "C:\\path\\to\\PVsyst8.0_Data"
      }
    }
  }
}
```

Restart the MCP client after editing its configuration. This server uses the `mcp` Python SDK 2.x and exposes **seven typed tools**:

| Tool | Action |
|---|---|
| `pvsyst_license_info` | Read CLI status and remaining quota; no Host ID in the response |
| `pvsyst_list_projects` | List workspace projects |
| `pvsyst_list_variants` | List a project's variant IDs |
| `pvsyst_build_sfi` | Create a new hourly SFI in `workspace/Models` |
| `pvsyst_run_simulation` | Run an existing project/variant; write a new CSV/PDF in `workspace/Results` |
| `pvsyst_convert_meteo` | Convert staged CSV + MEF + SIT into a new MET file |
| `pvsyst_read_results` | Summarize numeric result columns from `workspace/Results` |

MCP file tools accept **filenames, not arbitrary filesystem paths**. Stage weather CSV and MEF files under `workspace/Meteo`, and SIT under `workspace/Sites`. Results go under `workspace/Results`, SFI definitions under `workspace/Models`. The MCP server does not expose an unrestricted shell or CLI escape hatch. It rejects existing output files rather than overwriting them.

## Example with Python

```python
from pathlib import Path
from pvsyst_cli import PVsystCLI, build_sfi, summarize

cli = PVsystCLI(cli_path=r"C:\Program Files\PVsyst8.0.6\PVsystCLI.exe",
                workspace=r"C:\path\to\PVsyst8.0_Data")
print(cli.license_info())
print(cli.list_projects())

# Replace project and variant with ones present in your own workspace.
sfi = build_sfi(cli.workspace / "Models" / "energy.sfi", "energy")
result = cli.run_simulation("MY_PROJECT.PRJ", "VC0", sfi=sfi,
                            out_csv=cli.workspace / "Results" / "run01.csv")
print(result)
print(summarize(result["csv"], "E_Grid"))
```

`sum` in the summary is the sum of samples. For an **hourly** CSV whose `E_Grid` unit is kW, it corresponds to kWh; check units and time step before interpreting other outputs. SFI output columns and variables vary by version and project. Predefined groups use identifiers observed in the official 8.0.6 example (`viGlobInc`, `viE_Grid`, `viPR`, etc.); custom `vi*` identifiers are accepted without implying that all are supported.

## Checks performed

On a local 8.0.6 installation, an existing demo project completed a full-year hourly run in roughly 8-11 seconds. Both the vendor's SFI and an SFI generated by this adapter yielded 8760 rows with numeric `GlobInc`, `E_Grid`, and `PR` columns. CSV parsing and license-status queries were exercised; the included tests use mocks and temporary files, so they do not consume simulation quota. Actual behavior of `convert-meteo`, PDF generation, or other PVsystCLI releases requires separate validation.

Official references: [PVsystCLI product](https://www.pvsyst.com/en/products/pvsyst-cli/), [command reference](https://www.pvsyst.com/help-cli/reference/index.html), [simulation use cases](https://www.pvsyst.com/help-cli/use-cases/simulation.html).

## License

The source code in this repository is licensed under MIT. PVsyst and PVsystCLI are separate proprietary products; this integration is not affiliated with or endorsed by PVsyst SA.