Metadata-Version: 2.4
Name: ELF-mcp-server
Version: 1.43.0
Summary: MCP server for ELF600 electromagnetic analysis docs, workflow recipes, Cubit MEG export notes, and 586 verified public ELF/MAGIC .mai/.meg sample decks.
Project-URL: Homepage, https://github.com/ksugahar/ELF-mcp-server
Project-URL: Repository, https://github.com/ksugahar/ELF-mcp-server
Project-URL: Issues, https://github.com/ksugahar/ELF-mcp-server/issues
Project-URL: ELF600 Vendor, https://www.science-solutions.jp/elf/
Author-email: Kengo Sugahara <ksugahar@ele.kindai.ac.jp>
License: BSD-3-Clause
License-File: LICENSE
Keywords: bem,eddy-current,electromagnetic,elf,elf600,elfin,fem,magic,magnetostatic,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0
Description-Content-Type: text/markdown

# ELF-mcp-server

[![PyPI](https://img.shields.io/pypi/v/ELF-mcp-server.svg)](https://pypi.org/project/ELF-mcp-server/)
[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![Python: 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)

**MCP server providing ELF600 electromagnetic field analysis documentation** — file formats, solver options, element types, workflow recipes, and ELF-runnable public input decks for the [ELF600](https://www.science-solutions.jp/elf/) BEM-based electromagnetic analysis suite (MAGIC magnetostatic, ELFIN electrostatic, BEAM particle tracking).

This server does **not** execute ELF600 simulations — it provides curated documentation and public `.mai`/`.meg` input decks that AI coding assistants (Claude Code, Cursor, etc.) can consult while authoring ELF input files.

---

## Features

**24 tools + 1 prompt** providing curated docs, workflow recipes, ELF-runnable public sample decks, and raw access to ELF600 help HTM, example inputs, vendor wiki, and Python ctypes API:

| Tool family | Purpose | Files |
|---|---|---|
| `elf_usage(topic)` | 31 curated topics — high-level recipes | (knowledge.py) |
| `elf_help_*(...)` | Help HTM files from `C:/ELF600/help/` | 1141 files, 1.18M chars |
| `elf_examples_*(...)` | Example .mai/.mei/.txt plus 100-card playbook from `C:/ELF600/examples/` | 332 files, 533k chars |
| `elf_sample_decks_*(...)` | Lab-authored ELF-runnable public `.mai`/`.meg` sample decks | 586 cases, 1172 input files |
| `elf_recipe_*(...)` | Workflow decision cards for elements, PRE/SOL blocks, outputs, checks, and pitfalls | public-safe recipes |
| `elf_wiki_*(...)` | Vendor wiki pages from elf.co.jp PukiWiki | 146 pages, 211k chars |
| `elf_python_*(...)` | Python ctypes API + configs from `C:/ELF600/bin/` | 15 files, 246k chars |

Each `_*` family has 3 tools: `_index`, `_search(query)`, `_get(path)`.
The examples family also has `elf_examples_playbook(limit=100)`, which
summarizes 100 `.mai` examples as compact cards with detected SOL blocks,
element families, feature tags, companion `.mei/.model` files, and reuse hints.
The recipe family also has `elf_plan_workflow(goal)`, which chooses a short
public-safe recipe sequence from a natural-language analysis goal.
The sample deck family has `elf_sample_decks_index/search/get/playbook`
for ELF-runnable public `.mai`/`.meg` decks. The Python family also has
`elf_python_team28()`: a compact 28-case seed manifest from the public motor
cases for ELF Python-interface orchestration. `team28` is not a normal
ELF GUI/CLI deck-execution workflow. Solver outputs, comparison metrics,
executable orchestration state, and Python-interface runtime state are not
bundled.

### MCP quick start

For MCP clients, start with `elf_overview()` to discover the server surface and
public boundary. The most useful calls while authoring ELF/MAGIC inputs are:

- `elf_sample_decks_playbook(limit=20, family="pm_square")` for compact cards
  over the public PM motor decks
- `elf_sample_decks_playbook(limit=20, family="spm")` for surface-PM motor
  decks with stator coils, rotor/stator iron, and pickup coils
- `elf_sample_decks_playbook(limit=20, family="srm")` for switched-reluctance
  motor decks with salient iron and phase-pair excitation
- `elf_sample_decks_playbook(limit=20, family="induction_cage_10")` for induction
  motor cage decks with transient eddy-current pickup patterns
- `elf_sample_decks_playbook(limit=20, family="application")` for transformer
  MRI gradient-coil, WPT coupled-coil, induction-heating, and accelerator
  electromagnet application decks, plus actuator, maglev, separator, brake,
  NDT probe, magnetic-gear, voice-coil, relay/solenoid, Hall-sensor fixture,
  and electromagnetic-clutch decks
- `elf_sample_decks_playbook(limit=20, query="Loop10")` for the 10-cycle
  learning-loop decks across WPT, MRI, SR motor, SPM, IH, reluctance motor,
  hysteresis motor, transformer, and accelerator electromagnet families
- `elf_sample_decks_playbook(limit=20, query="Loop11")` for actuator,
  maglev bearing, magnetic separator, eddy-current brake, and NDT probe decks
- `elf_sample_decks_playbook(limit=20, query="Loop12")` for magnetic gear,
  voice-coil actuator, relay solenoid, Hall-sensor fixture, and
  electromagnetic-clutch decks
- `elf_sample_decks_search("HBCN FLUM", ext="mai")` to find reusable input
  patterns
- `elf_sample_decks_search("SPM HBRM FLUM", ext="mai")` to find surface-PM
  motor setup patterns
- `elf_sample_decks_search("SRM reluctance FLUM", ext="mai")` to find
  switched-reluctance motor setup patterns
- `elf_sample_decks_search("WPT MOMC FLUM", ext="mai")` to find wireless
  power-transfer AC coupling patterns
- `elf_sample_decks_search("MRI OHM2 FREQ", ext="mai")` to find AC shielding
  and eddy-current setup patterns
- `elf_sample_decks_search("induction motor cage OHM2 FLUM", ext="mai")` to find
  induction-motor cage and pickup setup patterns
- `elf_sample_decks_search("accelerator electromagnet FLUM", ext="mai")` to
  find coil/yoke electromagnet setup patterns
- `elf_sample_decks_search("IH induction-heating MOMC", ext="mai")` to find
  induction-heating AC conductor setup patterns
- `elf_sample_decks_search("Loop11 actuator plunger FLUM", ext="mai")` to find
  solenoid/plunger actuator setup patterns
- `elf_sample_decks_search("Loop11 NDT eddy-current probe OHM2", ext="mai")` to
  find eddy-current inspection probe setup patterns
- `elf_sample_decks_search("Loop12 magnetic gear HBCN FLUM", ext="mai")` to
  find PM magnetic-gear setup patterns
- `elf_sample_decks_search("Loop12 electromagnetic clutch OHM2", ext="mai")` to
  find AC clutch and conducting-plate setup patterns
- `elf_sample_decks_get("motor/pm_cosine_pickup_72/pm001/pm001.mai")` to open a
  concrete public deck
- `elf_python_team28()` to inspect the Python-interface seed manifest

This MCP server is documentation and input-deck retrieval only; it does not
launch ELF, run solvers, manage licenses, or publish validation outputs.

### ELF/MAGIC application input authoring

ELF/MAGIC is useful for magnetostatic and AC magnetic input authoring when the
model is expressed as `.mai` analysis control plus `.meg` mesh data. This server
turns that knowledge into MCP tools:

- 402 public motor input-deck pairs covering 2-pole, 4-pole, 6-pole, 8-pole,
  cosine-remanence PM pickup families, 10 explicit SPM motor examples, and
  10 SRM switched-reluctance examples, 10 induction cage examples, plus
  loop-reviewed SPM, SR motor, synchronous-reluctance motor, and hysteresis
  motor families
- 184 public application input-deck pairs covering transformer core/pickup
  coupling, MRI gradient-coil/eddy-current shield patterns, WPT coupled coils,
  IH induction-heating workpieces, accelerator electromagnets, actuator
  plungers, maglev bearings, magnetic separators, eddy-current brakes,
  NDT eddy-current probes, magnetic gears, voice-coil actuators,
  relay solenoids, Hall-sensor fixtures, and electromagnetic clutches
- playbook cards that expose each deck's SOL blocks, PRE keywords, element
  families, feature tags, and reuse hints
- curated motor topics for air-gap field, flux linkage/back-EMF pickup,
  polarity/angle conventions, force outputs, and eddy-current setup
- Python-interface `team28` seed manifest for higher-level orchestration,
  without bundling runtime state or solver outputs

Useful entry points are `elf_usage(topic="ipm_motor")`,
`elf_usage(topic="motor_radia_bridge")`,
`elf_recipe_search("motor pickup")`, and
`elf_sample_decks_playbook(limit=50, family="pm_square")`,
`elf_sample_decks_playbook(family="spm")`, or
`elf_sample_decks_playbook(family="srm")`, or
`elf_sample_decks_playbook(family="induction_cage_10")`. For non-motor applications,
start with `elf_sample_decks_playbook(family="application")`,
`elf_sample_decks_search("transformer FLUM")`,
`elf_sample_decks_search("WPT MOMC FLUM")`, or
`elf_sample_decks_search("MRI OHM2 FREQ")`,
`elf_sample_decks_search("IH induction-heating MOMC")`, or
`elf_sample_decks_search("accelerator electromagnet FLUM")`,
`elf_sample_decks_search("Loop11 actuator plunger FLUM")`, or
`elf_sample_decks_search("Loop11 NDT eddy-current probe OHM2")`,
`elf_sample_decks_search("Loop12 magnetic gear HBCN FLUM")`, or
`elf_sample_decks_search("Loop12 electromagnetic clutch OHM2")`.

### Public `.meg` mesh generation

For normal ELF/MAGIC authoring, the canonical mesh path is:

```text
.mei (mesh script) --> IEmesh / mesh750.exe --> .meg
```

For the bundled public sample corpus, the `.meg` files are generated as small
ASCII ELF/MAGIC mesh decks directly by lab-authored Python generators. The
writer emits `BOOK MEP 3.50`, `MGSC`, `MGR1` node records, and 8-node element
connectivity records such as `MMB8T`, `MCL8T`, `MAB8T`, and `MWL8T`. Cubit is
not used for these compact public examples.

For larger CAD/mesh workflows, Cubit-side `cubit_mesh_export` also supports
ELF-compatible `.meg` export through helper calls such as
`cubit_mesh_export.export_meg(cubit, "model.meg", DIM="T")` and
`cubit_mesh_export.export_3D_meg(cubit, "model")`. A command-style route such
as `radia_export meg "output.meg" threed labels "1:MMB,2:MWL"` is documented in
`elf_usage(topic="meg_export")`. The published examples keep the geometry
deliberately inspectable and dependency-free.

### Public lint

Before publishing, run:

```bash
python -m pytest
elf-mcp-server --selftest
elf-mcp-policy-lint
```

`elf-mcp-policy-lint` checks the public package boundary: no private validation
paths, no unrelated commercial-tool references, no bundled solver outputs
inside the public sample decks, and exact agreement with
`public_samples/VALIDATED_MANIFEST.json`. Only sample families marked
`validation: passed` in that manifest are intended for publication.

Bundled data (all generated from fresh ELF600 install via `scripts/crawl_*.py`):
- `help_dump.json` — Shift_JIS HTM decoded + HTML-stripped
- `examples_dump.json` — 228 MAGIC + 66 ELFIN + 38 BEAM input files
- `wiki_dump.json` — 146 curated pages from https://elf.co.jp/
- `python_dump.json` — `elftypes.py`/`magtypes.py` (83 ctypes API functions each), `*.cfg`, `ELFERR.def`/`MESERR.def`, etc.

### Curated topics (`elf_usage`)

Returns documentation on:

- **File formats**: `.mai` (analysis input), `.mei` (mesh script), `.meg` (compiled mesh)
- **Solvers**: MAGIC (magnetostatic, transient, AC), ELFIN (electrostatic), BEAM (particle tracking)
- **Eddy current**: MAB / MAT / MBB elements, time-stepping, sinusoidal AC (SOL MOMC)
- **Element types**: full catalog with DOF counts and symmetry restrictions (3D / 2D / Axisym)
- **B-H curves**: anisotropy (HBA1/HBA2), recoil, extrapolation
- **Motor workflows**: IPM Ld/Lq plus a radia-mcp/open-FEA concept bridge for air-gap field, torque, flux linkage/back-EMF, lamination, and eddy-current studies
- **Inductance**: Lsc (JIS) and Ll (IEEJ) with 6 samples
- **Magnetization / demagnetization** (MAGNE2)
- **Convergence** troubleshooting, error codes (160+ ELF-Q/E/W codes)
- **Force methods**: FORC vs FORT vs FIXB
- **Tools**: IEmesh, Wmap3, MagFilter2, MaiEditor3, ELF/Bench

Available topics:
```
all, overview, mai_format, mei_format, meg_format,
magic, elfin, beam, element_types, bh_curves,
sol_commands, mei_commands, ipm_motor, motor_radia_bridge, inductance,
magnetization, examples, meg_export, treasure_box,
sinusoidal, anisotropy, sted, meshing, convergence,
force_methods, errors, iemesh, tools, cln_extraction,
licensing, python_api, live_drive
```

The `cln_extraction` topic documents the 6-step ELF MAGIC -> Cauer Ladder
Network synthesis workflow (Foster fit + Cauer-I/II + 3-way validation
against step response / Joule loss / Lorentz force). Distilled from a
21-script rectangular-CLN reference analysis suite.

---

## Installation

```bash
pip install ELF-mcp-server
```

The current PyPI distribution name is `ELF-mcp-server`. The installed console
scripts remain lowercase: `elf-mcp-server` and `elf-mcp-policy-lint`.

Verify:
```bash
elf-mcp-server --selftest
```

---

## Usage

### Claude Code

```bash
claude mcp add elf "C:/Program Files/Python312/Scripts/elf-mcp-server.exe"
```

(Adjust path for your Python install. On Linux/macOS, the script is typically `~/.local/bin/elf-mcp-server` or similar.)

### Cursor / Other MCP clients

Add to your MCP config:
```json
{
  "mcpServers": {
    "elf": {
      "command": "elf-mcp-server"
    }
  }
}
```

### Self-test

```bash
elf-mcp-server --selftest
```
Iterates through all curated topics and asserts non-empty documentation.

---

## What is ELF600?

ELF600 is a commercial BEM (Boundary Element Method) electromagnetic analysis suite distributed by Science Solutions International Laboratory ([https://www.science-solutions.jp/elf/](https://www.science-solutions.jp/elf/)).

| Module | Purpose |
|--------|---------|
| **MAGIC** | Magnetostatic field (static, transient, AC). Eddy current via MAB/MAT/MBB. |
| **ELFIN** | Electrostatic field analysis (D-E curves) |
| **BEAM** | Charged particle beam tracking |

Workflow:
```
.mei (mesh script) --> IEmesh --> .meg (compiled mesh)
.mai (analysis) + .meg --> MAGIC/ELFIN/BEAM --> .mag/.mao results
```

---

## Why this server?

LLM coding agents authoring ELF input files (`.mai`/`.mei`) need access to:
- The ~60k character ELF reference manual content,
- Element naming conventions (T/K/R symmetry × element family),
- SOL block recipes (MOME / MOMC / FIEL / FORC / NONL),
- Frequency-sweep AC analysis structure,
- Common error code interpretation,

without polluting context with the entire vendor PDF. This MCP server returns just the relevant topical chunk on demand.

---

## License

BSD-3-Clause. See [LICENSE](./LICENSE).

ELF600 itself is a commercial product of Science Solutions International Laboratory and is not redistributed by this package — only documentation references.

---

## Author

Kengo Sugahara, Kindai University ([ksugahar@ele.kindai.ac.jp](mailto:ksugahar@ele.kindai.ac.jp))
