ideastatica-mcp

Claude (Claude Desktop / Claude Code) ile IDEA StatiCa Connection arasında çalışan bir MCP (Model Context Protocol) sunucusu. IDEA StatiCa ile birlikte kurulan yerel REST servisi (IdeaStatiCa.ConnectionRestApi.exe, API 4.0) üzerinden projeyi açar, bağlantıları, elemanları, parametreleri ve yükleri okur/değiştirir, CBFEM hesabı yapar, sonuçları özetler, rapor ve dışa aktarım üretir, projeyi kaydeder.

Resmi Python SDK'sı (ideastatica-connection-api, kurulu IDEA StatiCa sürümüyle eşleşen 26.0.x) kullanılır; hiçbir uç nokta elle uydurulmamıştır. Tasarım ve kapsam için PLAN.md.

Gereksinimler

• Windows, IDEA StatiCa 24.1 veya üstü (bu kurulum: 26.0, C:\Program Files\IDEA StatiCa\StatiCa 26.0)

• Geçerli IDEA StatiCa lisansı (Basic lisans API'yi desteklemez; servis lisans koltuğu ayırır)

• Python 3.11+ (bu makinede 3.14)

• git (depoyu klonlamak için) veya GitHub'dan ZIP indirme

Related MCP server: ETABS MCP Server

Depoda neler var, neler yok

Bu depo yalnızca kaynak kodu içerir (yaklaşık 2 MB). Aşağıdakiler depoda yoktur, her kullanıcı kendi makinesine indirir/kurar:

Bu yüzden .venv klasörünü GitHub'a yüklemeyin (.gitignore zaten dışlar). Yüklenen paketin büyük görünmesinin tek nedeni genellikle .venv'dir.

İndirme

git clone https://github.com/<kullanici>/ideastatica-mcp.git
cd ideastatica-mcp

git yoksa depo sayfasında Code → Download ZIP ile indirip klasöre çıkarın ve o klasörde PowerShell açın.

Kurulum

powershell -ExecutionPolicy Bypass -File scripts\setup.ps1

setup.ps1 sanal ortamı (.venv) oluşturur, paketi ve bağımlılıkları PyPI'dan indirip kurar (mcp, ideastatica-connection-api==26.0.* …) ve SDK sözleşme testini çalıştırır.

Betik kullanmadan elle kurulum:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"      # veya: pip install -r requirements.txt

Önemli – SDK sürümü kurulu IDEA StatiCa ile eşleşmeli. Bağımlılık ideastatica-connection-api>=26.0.5,<26.1 olarak sabitlenmiştir. Farklı bir IDEA StatiCa sürümü kullanıyorsanız eşleşen SDK'yı kurun (sürüm numarası IDEA StatiCa'nınkiyle aynı olmalı):

.\.venv\Scripts\python.exe -m pip install "ideastatica-connection-api==<IDEA sürümü>.*"

(Eşleşme service_status çıktısındaki sdk_matches_service alanından doğrulanır.)

Claude Desktop

powershell -ExecutionPolicy Bypass -File scripts\install_claude_desktop.ps1

Betik %APPDATA%\Claude\claude_desktop_config.json dosyasına (yedek alarak) şu girdiyi ekler:

{
  "mcpServers": {
    "ideastatica": {
      "command": "C:\\KLASOR\\ideastatica-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "ideastatica_mcp"],
      "env": { "IDEASTATICA_LOG_LEVEL": "INFO" }
    }
  }
}

(C:\KLASOR\ideastatica-mcp yerine depoyu klonladığınız klasörün tam yolunu yazın; betik bunu sizin yerinize doldurur.) Elle yazmak isterseniz örnek: claude_desktop_config.example.json.

Claude Desktop'ı yeniden başlatın. Sohbette "IDEA StatiCa servis durumunu göster" demek service_status aracını çağırır.

Claude Code

Proje klasöründeki .mcp.json sunucuyu otomatik tanımlar. Başka bir klasörden kullanmak için:

claude mcp add ideastatica -- "C:\KLASOR\ideastatica-mcp\.venv\Scripts\python.exe" -m ideastatica_mcp

C:\KLASOR\ideastatica-mcp yerine kendi klasör yolunuzu yazın. .mcp.json içindeki yol da kendi klasörünüze göre düzenlenmelidir.

Nasıl çalışır

Claude ──stdio/MCP──▶ ideastatica_mcp ──HTTP──▶ IdeaStatiCa.ConnectionRestApi.exe (localhost)

• İlk araç çağrısında servis otomatik başlatılır (boş bir portta) ve /heartbeat beklenir. Lisans kontrolü uzun sürebildiğinden bir araç çağrısı en fazla IDEASTATICA_START_WAIT (40 sn) bekler; süre dolarsa "still starting" der, servis arka planda başlamaya devam eder, bir sonraki çağrı (ör. service_status) hazır olunca bağlanır.

• Çalışan servis %LOCALAPPDATA%\ideastatica-mcp\logs\service-state.json ile hatırlanır: MCP sunucusu yeniden başlarsa aynı servise yeniden bağlanır (adopt), lisans başlatması tekrar ödenmez. Servis yalnızca service_stop ile (veya IDEASTATICA_KILL_ON_EXIT=true ise MCP kapanınca) durur.

• Projeler servis belleğinde açık kalır; save_project çağrılana kadar diske yazılmaz.

• project_id verilmezse son açılan proje, connection_id verilmezse projedeki tek bağlantı kullanılır.

• Üretilen dosyalar (rapor, IFC/IOM/DWG, kaydedilen proje, ham sonuçlar) %USERPROFILE%\Documents\IdeaStatiCa-MCP altına yazılır; mevcut dosya overwrite=true olmadan ezilmez.

• Loglar: stderr ve %LOCALAPPDATA%\ideastatica-mcp\logs\ (servis çıktısı da orada).

Araçlar (118)

Yeni gruplar (07.10.2026)

get_raw_results artık path="plates[0].items" / "welds.*.name" gibi yol filtresi alır.

İkinci genişletme (08.10.2026)

Not: servisin result-mesh (gerilme ağı) uç noktası da bu derlemede kapalı; render_utilization_map kontrol sonuçlarını (kaynak oranı, plaka plastik şekil değiştirme, bulon oranı) parça bazında renklendirir.

Temel gruplar

Kaynaklar (resources): ideastatica://docs/parameter-reference (ifade parametre referansı), ideastatica://docs/parameters-getting-started, ideastatica://docs/api-reference, ideastatica://docs/api-concepts, ideastatica://status, ideastatica://projects.

İstemler (prompts): calculate_and_report, parametric_study, design_from_library.

Örnek istekler (Claude'a)

• "C:\Projeler\kiris-kolon.ideaCon dosyasını aç, bağlantıları ve elemanları listele."

• "Parametreleri göster; plateThickness değerini 0.02 yap ve yeniden hesapla, sonuçları karşılaştır."

• "Tüm bağlantıları hesapla, %100'ü aşan kontrolleri vurgula ve PDF rapor üret."

• "Kütüphaneden bu bağlantıya uygun tasarım öner, en uygununu uygula ve kontrol et."

• "Projeyi AISC'ye dönüştür (S 355 → A992) ve yeni dosya olarak kaydet."

Birimler ve kurallar

• Parametre ifadeleri string ve SI birimlerinde (m, N, Pa, rad): 15 mm → "0.015"; metinler tek tırnak içinde ('M20 8.8'); diğer parametreye referans [anahtar]. Fonksiyonlar için parametre referansı kaynağına bakın (RoundWithOffset, GetValue, Bolts(...), IProfile(...) vb.).

• Yük etkileri de SI: kuvvetler N, momentler Nm (120 kN → 120000). Kontrol değerleri zaten yüzde (85.0 = %85); skipped=true olanlar atlanır.

• Plaka/bulon/kaynak tek tek API ile eklenemez: şablon uygula, kütüphaneden tasarım uygula veya IOM içe aktar; boyutları parametrelerle sür.

Yapılandırma (ortam değişkenleri)

Komut satırı: python -m ideastatica_mcp --help (--transport streamable-http --port 8765 ile HTTP taşıması da mümkündür).

Lisans

MIT. IDEA StatiCa programı ve lisansı bu lisansın kapsamında değildir; ayrıca edinilmelidir.

Testler

.\.venv\Scripts\python.exe -m pytest -q            # sahte SDK istemcisi + stdio el sıkışma
set IDEASTATICA_LIVE=1
.\.venv\Scripts\python.exe -m pytest -q tests\test_live.py -m live -s   # gerçek servis ile

• test_tools.py: 73 aracın davranışı, gerçek MCP istemcisiyle süreç içinde (fake SDK).

• test_sdk_contract.py: araçların çağırdığı her SDK metodu kurulu pakette var mı.

• test_stdio.py: sunucu Claude Desktop'ın başlattığı gibi alt süreçte başlatılır, el sıkışma + araç çağrısı.

• test_live.py: servisi başlatır, örnek projeyi açar, hesaplar, rapor üretir (lisans gerekir).

Durum / Doğrulama

• Birim, araç ve stdio testleri geçiyor (38 test).

• Canlı uçtan uca akış bu makinede doğrulandı (30.09.2026): servis ~130 sn'de hazır oldu, simple-project.ideaCon açıldı, elemanlar/operasyonlar/yükler okundu, CBFEM hesabı 4 sn sürdü (kaynaklar %79.5), PDF rapor ve kaydedilmiş proje üretildi.

• Servis başlatması lisans doğrulaması yüzünden 2-3 dakika sürebilir; araçlar "still starting" derse bir dakika sonra tekrar deneyin.

Performans

Ölçüm (07.10.2026, gerçek servis, simple-project.ideaCon):

Hız için yapılanlar: servis MCP açılır açılmaz arka planda başlatılır ve istemci kaydı yapılır (IDEASTATICA_PREWARM), çağrı başına heartbeat yok (hata olursa yeniden bağlanır), bağlantı listesi 60 sn önbelleklenir (değişikliklerde temizlenir), hesap işi 0,25 sn'den başlayan aralıkla yoklanır, büyük çıktılar kompakt döner (verbose=true ile tam hali). Kalan süreler IDEA StatiCa çözücüsü/rapor motorundan gelir ve MCP tarafında kısaltılamaz.

Sorun giderme

• "Sign in - IDEA StatiCa" penceresi: Servis ilk açılışta lisans girişi ister ve bu pencere yanıtlanana kadar bekler (giriş yapın ya da iptal edin; iptalde yerel tasarım setleriyle devam eder). Kalıcı çözüm: IDEA StatiCa uygulamasında bir kez oturum açmak. Birden fazla MCP örneği (Claude Desktop + Claude Code) aynı servisi durum dosyası üzerinden paylaşır; yine de ilk açılışta pencere bir kez çıkabilir.

• Servisi oturum açılışında hazır tutmak: scripts\register_autostart.ps1 görevi kaydeder (port 5055) ve IDEASTATICA_API_URL kullanıcı değişkenini ayarlar; MCP anında bağlanır.

• Servis başlamıyor / zaman aşımı: IDEA StatiCa'nın kendisi açılıp giriş yapılabiliyor mu? %LOCALAPPDATA%\ideastatica-mcp\logs\service-<port>.log ve %TEMP%\IdeaStatica\Logs\ConnectionRestApi.log dosyalarına bakın. IDEASTATICA_START_TIMEOUT ile bekleme süresini artırın veya servisi elle başlatıp IDEASTATICA_API_URL verin.

• HTTP 404 / proje bulunamadı: Servis yeniden başlamış olabilir; projeyi yeniden açın.

• SDK/servis sürüm uyuşmazlığı: service_status içindeki sdk_matches_service alanına bakın; pip install "ideastatica-connection-api==<kurulu sürüm>.*" ile eşleştirin.