Skip to main content
Glama
I-SIMPA AI MCP Server

I-SIMPA AI MCP Server

by Ziad-Amr1
README.md
# I-SIMPA AI MCP Server (Room Acoustics Automation)

An AI Model Context Protocol (MCP) server and automation suite for **I-SIMPA 1.3.4** room acoustic simulation software. Connect AI assistants (such as Google Antigravity, Claude Desktop, Cursor, or OpenCode) directly to I-SIMPA to automate 3D tetrahedral meshing (TetGen), Classical Theory (Sabine & Eyring equations), SPPS energetic particle tracing, binary result parsing (.gabe / .recp), and ISO 3382 acoustic parameters calculation.

---

## Architecture Overview

```
+-------------------------------------------------------------+
| AI Agent / Client (Claude, Antigravity, Cursor)             |
+-------------------------------------------------------------+
                               |
                        MCP Protocol (JSON-RPC stdio)
                               v
+-------------------------------------------------------------+
| I-SIMPA FastMCP Server (mcp_server.py / isimpa-mcp)         |
| Exposes standard room acoustics MCP tools                   |
+-------------------------------------------------------------+
   |             |                 |                 |
   v             v                 v                 v
+-----------+ +---------------+ +-----------------+ +---------------+
| Solver    | | Config        | | Binary Parsers  | | Standards     |
| Client    | | Builder       | | GABE & RECP     | | ISO 3382 &    |
| SPPS/TC   | | XML generator | | libsimpa        | | DIN 18041     |
+-----------+ +---------------+ +-----------------+ +---------------+
```

---

## Key Features

- **Automated Solver Execution**: Run `spps.exe` (particle tracing) and `classicalTheory.exe` headlessly with timeout management and log capture.
- **Project Structure Validation**: Automatically scaffolds compliant project workspaces including the 5 mandatory subdirectories required by SPPS (`Intensity animation/`, `Punctual receivers/`, `Surface receiver/`, `Particles/`, `loudspeakers/`).
- **Dynamic Config Generation**: Programmatically build `config.xml` files with arbitrary sources (positions, power levels, directivity), punctual receivers, and material spectrums.
- **TetGen 3D Meshing**: Invokes TetGen (`-Qpq1.414An`) on boundary `.poly` models to create valid volumetric tetrahedral meshes (`tetramesh.mbin`).
- **Native Binary Parsers**: Parse I-SIMPA's proprietary `.gabe` tabular files and `.recp` punctual receiver impulse responses into clean Python dictionaries.
- **ISO 3382 Room Acoustic Metrics**:
  - $T_{30}$ and $T_{20}$ Reverberation Time via Schroeder backwards integration
  - $EDT$ (Early Decay Time)
  - $C_{50}$ (Speech Clarity) & $C_{80}$ (Music Clarity)
  - $D_{50}$ (Sound Definition) & $T_s$ (Center Time)
  - Relative Sound Pressure Level ($SPL$)
- **Architectural Material Database**: Standard octave-band absorption ($\alpha$) and scattering ($s$) coefficients (125 Hz to 4000 Hz) across 8 architectural categories.
- **Acoustic Standards Benchmarking**: Compare simulated metrics directly against international standards (ISO 3382, DIN 18041, BB93, ANSI S12.60) across educational, performance, commercial, and sacred spaces.

---

## Installation & Setup

### 1. Requirements
- I-SIMPA 1.3.4 installed (default: `C:\Program Files\I-SIMPA`)
- Python 3.10+
- Installation:
```bash
git clone https://github.com/Ziad-Amr1/isimpa-ai-mcp.git
cd isimpa-ai-mcp
pip install -e .
```

---

## MCP Server Configuration

Add the server to your MCP client configuration:

### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "isimpa": {
      "command": "isimpa-mcp",
      "env": {
        "ISIMPA_DIR": "C:\\Program Files\\I-SIMPA"
      }
    }
  }
}
```

### Antigravity (`agy` / `settings.json`)
```json
{
  "mcp": {
    "servers": {
      "isimpa": {
        "command": "isimpa-mcp"
      }
    }
  }
}
```

---

## Exposed MCP Tools

| Tool Name | Description |
| :--- | :--- |
| `isimpa_get_status` | Check I-SIMPA installation and solver binary availability. |
| `isimpa_create_project` | Scaffolds compliant project directory tree with all required subfolders. |
| `isimpa_build_config` | Build simulation XML configuration with sources, receivers, and materials. |
| `isimpa_run_tetgen` | Generates 3D tetrahedral volumetric mesh from boundary `.poly` mesh. |
| `isimpa_run_classical_theory` | Runs Classical Theory solver for Sabine and Eyring reverberation times. |
| `isimpa_run_spps` | Runs SPPS energetic particle tracing acoustic simulation. |
| `isimpa_parse_gabe` | Parses native `.gabe` binary simulation output into structured tabular data. |
| `isimpa_parse_recp` | Parses punctual receiver energy arrival history (`.recp`). |
| `isimpa_calculate_acoustic_parameters` | Computes ISO 3382 room acoustic metrics ($T_{30}, EDT, C_{50}, C_{80}, D_{50}$). |
| `isimpa_get_material_library` | Lists standard frequency-dependent absorption and scattering coefficients. |
| `isimpa_get_room_typologies` | Lists target acoustic ranges across room types (Classrooms, Concert Halls, etc.). |
| `isimpa_evaluate_room_performance` | Benchmarks metrics against international acoustic standards. |
| `isimpa_analytical_rt60` | Evaluates analytical Sabine and Eyring RT60 for quick feasibility checks. |

---

## License
Open source under the MIT License.