plotsim-mcp

Model Context Protocol server for plotsim — generate, validate, inspect, and trace synthetic multi-table datasets from any MCP client.

Status

0.1.0 — first public release. Eleven tools wired (discovery, templates, authoring, generation, inspection, trace), structured error contract, run-id sandbox, full stdout-discipline coverage.

Install

pip install plotsim-mcp

This pulls plotsim>=0.7.0 and the MCP Python SDK (mcp>=1.25,<2) as transitive dependencies.

Launch

The server speaks the MCP stdio transport:

python -m plotsim_mcp

It exits when the client closes the stream.

Claude Desktop configuration

Add an entry under the mcpServers key of your claude_desktop_config.json (location: %APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS):

{
  "mcpServers": {
    "plotsim": {
      "command": "python",
      "args": ["-m", "plotsim_mcp"]
    }
  }
}

Restart Claude Desktop. The plotsim server should appear in the MCP tool inspector.

Available tools

Discovery

Authoring

Generation and inspection

Trace

Run sandbox

create_dataset writes every dataset under a single sandbox root. The location is controlled by the PLOTSIM_MCP_RUN_ROOT environment variable; if unset, runs land at <system_temp>/plotsim-mcp-runs/<run_id>/. The run_id is a stable <UTC-timestamp>-<sha8> handle that round-trips through describe_run, get_validation_report, load_run, and trace_cell. Caller-supplied output_dir values are refused when they resolve outside the sandbox root (plotsim.run.path_forbidden).

Error contract

Every tool returns a CallToolResult. On structured failure the result carries isError=true and a JSON payload of shape:

{
  "code": "plotsim.template.unknown",
  "message": "human-readable summary",
  "details": {},
  "traceback_id": "optional server-side log key"
}

Codes are namespaced under plotsim.*. The current set is enumerated in plotsim_mcp/errors.py and plotsim_mcp/tools/trace_cell.py.

Contributing

See CONTRIBUTING.md for the tool conventions (dict-wrap, structured_output=False, stdout discipline, run-id sandbox, error contract) and the test layout. The Code of Conduct, Security policy, and Support docs round out the contributor surface.

License

Apache-2.0. See LICENSE.