comsol-mcp: Instructions file for Codex

AGENTS.md — comsol-server-mcp

Project Overview

COMSOL MCP Server (comsol-mcp v0.1.9). An attach-first MCP bridge that connects to a running COMSOL Multiphysics Server, loads a main .mph model, locks it, and drives the same server-side model that a COMSOL Desktop client visualizes in real time.

Architecture

comsol_mcp/
  __init__.py              # from .mcp_server import main
  _server.py               # FastMCP instance, global state, constants, classification sets
  _state.py                # Workflow persistence, status/operations logging, path/port utils, _run_tool
  _connection.py           # Disconnect, client shell, _require_client
  _model.py                # Model adopt/prune, visible-main lock mechanism
  _model_ops.py            # Pure helpers: parameters, expressions, core metrics, tree, geometry
  _tools_connection.py     # server_info, check_server_port, server_start, server_connect, server_disconnect
  _tools_workflow.py       # Workflow tools, visible-main lifecycle, model_tree, run_study
  _tools_model.py          # model_create, model_load, prune_loaded_models
  _tools_params.py         # get_parameters, set_parameters, evaluate_expressions, get_core_metrics
  _tools_geometry.py       # ensure_component/geometry/mesh, create/update/delete/run_feature
  _tools_snapshot.py       # run_visible_main_iteration, save_main_model_snapshot, commit_current_main_model, save_model
  mcp_server.py            # Thin entrypoint: imports + register + main()

35 MCP tools registered via mcp.add_tool() in each module's register() function.

Build and Run

pip install -e .          # install in editable mode
pip install -e ".[dev]"   # with pytest
python -m comsol_mcp.mcp_server   # start MCP server
pytest                           # run tests (40 tests, all without COMSOL)

Module Dependency Graph

_server.py  (no deps)
  -> _state.py
    -> _connection.py
      -> _model.py
        -> _model_ops.py (no global state deps)

Tool modules depend on the above:
  _tools_connection -> _server, _state, _connection, _model
  _tools_workflow   -> _server, _state, _model, _tools_connection (cross-module call)
  _tools_model      -> _server, _state, _model
  _tools_params     -> _state, _model, _model_ops
  _tools_geometry   -> _state, _model, _model_ops
  _tools_snapshot   -> _server, _state, _model, _tools_params (cross-module call)