MCP server

Since 1.12.0 the engine ships a local Model Context Protocol (MCP) server. It lets an AI assistant such as Claude or Cursor inspect a dataset and fit a PLS-SEM model by calling the engine directly on your machine.

Everything runs locally over stdio: the tools read datasets from local file paths and nothing is uploaded. No account, no cloud, no API key. That makes it a good fit for sensitive survey data that cannot leave your laptop.

Install

The server is an optional extra, so it only pulls in the MCP SDK when you ask for it:

pip install "openpls-engine[mcp]"

This adds the openpls-mcp console command.

Connect your assistant

Point your MCP client at the openpls-mcp command. In Claude Desktop or Claude Code:

{
  "mcpServers": {
    "openpls": { "command": "openpls-mcp" }
  }
}

Cursor, Zed and other MCP clients use the same shape (a server with command: "openpls-mcp"). If openpls-mcp is not on your PATH, give the absolute path to the binary inside your virtual environment, e.g. /path/to/.venv/bin/openpls-mcp.

Tools

The server exposes two tools.

describe_dataset(path)

Inspect a dataset before modelling. Returns the row count and, for every column, its name, whether it is numeric (so usable as an indicator), and its non-null count. Use it so the assistant can pick indicator columns.

{
  "path": "data/satisfaction.csv",
  "rows": 250,
  "columns": [
    { "name": "imag1", "type": "numeric", "non_null": 250 },
    { "name": "imag2", "type": "numeric", "non_null": 250 }
  ]
}

fit_pls_sem(...)

Fit a model and return the core results. Arguments:

• data_path — local path to the dataset (CSV, TSV or Excel).
• latent_variables — one entry per construct: { "name", "indicators": [...], "mode": "A" | "B" }. Mode A is reflective, B is formative (default A).
• structural_paths — the structural model as { "source", "target" } construct-name pairs.
• scheme — inner-weighting scheme: CENTROID (default), PATH, FACTORIAL, NEWTON or PCA.
• scaled — standardise indicators before fitting (default false).
• missing_codes — numeric sentinels (e.g. [-99, -999]) to treat as missing.

A minimal three-construct mediation model:

{
  "data_path": "data/survey.csv",
  "latent_variables": [
    { "name": "Trust", "indicators": ["tr1", "tr2", "tr3"] },
    { "name": "Satisfaction", "indicators": ["sat1", "sat2", "sat3"] },
    { "name": "Loyalty", "indicators": ["loy1", "loy2", "loy3"] }
  ],
  "structural_paths": [
    { "source": "Trust", "target": "Satisfaction" },
    { "source": "Satisfaction", "target": "Loyalty" },
    { "source": "Trust", "target": "Loyalty" }
  ]
}

It returns R² per construct, path coefficients (estimate, p-value, f²), reliability (Cronbach’s alpha, rho_A, rho_C, AVE), model fit (SRMR, d_ULS) and the goodness-of-fit index:

{
  "goodness_of_fit": 0.6194,
  "model_fit": { "srmr": 0.0755, "d_uls": 0.7762 },
  "r_squared": [
    { "lv": "Satisfaction", "type": "Endogenous", "r_squared": 0.697, "r_squared_adj": 0.692 }
  ],
  "path_coefficients": [
    { "source": "Trust", "target": "Satisfaction", "estimate": 0.45, "p_value": 0.0, "t": 8.0, "f_squared": 0.26 }
  ],
  "reliability": [
    { "lv": "Satisfaction", "cronbach_alpha": 0.889, "rho_a": 0.9, "rho_c": 0.931, "ave": 0.817 }
  ]
}

A typical session

A natural flow is to let the assistant discover the columns, map them to constructs, then fit:

1. “Here is survey.csv, what is in it?” — the assistant calls describe_dataset and sees the column names.
2. “Model trust and satisfaction driving loyalty.” — it maps indicators to constructs and calls fit_pls_sem.
3. “Which paths are significant and does the model fit?” — it reads the returned R², p-values and SRMR and explains them.

Privacy

The tools only ever read the local file path you pass. No dataset, model or result leaves your machine, so you can analyse confidential data without sending it to any server. The compute is identical to calling the engine directly (see the Quickstart).