# LaminateAnalyzerMCP

적층 복합재의 **중립면(neutral surface)·ABD 강성·평가 지표**를 결정론적으로 계산하는 MCP 서버.
LLM 에이전트가 계산을 직접 하지 않고 이 서버를 호출한다. 동일 입력 → 바이트 동일 응답(payload_hash 추적).

- 계획/사양: [docs/mcp_laminate_planning.md](docs/mcp_laminate_planning.md) (수학 사양·규약·오류코드의 단일 소스)
- 진행 상태: [checklist.md](checklist.md) · 결정 기록: [context-notes.md](context-notes.md)

## Tool 43종

**진입·검증·지표** — `analyze_laminate`(원샷 진입점) · `validate_laminate_input` ·
`compute_abd_matrix` · `compute_neutral_axis` · `evaluate_laminate` ·
`get_reference_cases`(폐형해 자가검증) · `get_server_info` · `generate_design_report`(ko/en) ·
`batch_evaluate_laminates`(≤32) · `run_sensitivity_analysis` · `check_design_rules`(적층 관례)

**하중·응력·파손** — `solve_load_response`(ε0/κ·유효 상수) · `recover_ply_stresses`(층별 응력·FPF) ·
`run_progressive_failure`(한계하중) · `compute_interlaminar_stresses`(박리) ·
`compute_failure_envelope`(72방향 포락선 — 최약 방향) · `assess_free_edge_delamination` ·
`assess_notched_strength`(원공 K_T + 조건부 σ_OH)

**안정성·진동·비선형** — `compute_buckling` · `compute_postbuckling`(좌굴 후 유효폭) ·
`solve_required_thickness_scale`(목표 여유의 최소 두께 배율) · `compute_natural_frequencies`(감쇠·횡전단) ·
`compute_large_deflection`(von Karman) · `solve_nonlinear_shear_response`(Hahn–Tsai) ·
`compute_bistable_shapes`(경화 후 쌍안정)

**환경·시간** — `compute_thermal_response`(유효 CTE·열/흡습 곡률·PCB 휨) ·
`compute_moisture_uptake`(Fickian — 포화·베이크 시간) · `estimate_fatigue_life`(반복 수명) ·
`estimate_spectrum_life`(Miner 누적손상) · `solve_stress_relaxation`(곡률 고정 이완)

**구조 세부·물성 유도** — `assess_sandwich_local_failure`(주름·딤플링·코어 전단) ·
`assess_bonded_lap_joint`(Volkersen — 겹침을 늘려도 피크가 안 준다) ·
`assess_partial_composite_bending`(순응층 — CLT 과대평가 배수) ·
`solve_prescribed_curvature`(변위 제어 — 곡률·굽힘반경 지정) ·
`derive_lamina_from_constituents`(섬유+수지 → lamina) · `homogenize_layer`(동박률) ·
`homogenize_patterned_layer`(방향성 패턴 → 직교이방) · `assess_crack_shielding`(문턱·차폐·이완)

**파괴역학** (§20 — A/B 등급 분리) — `assess_crack_tip_field`(K·Williams·소성역·CTOD·J·HRR) ·
`assess_brittle_fracture`(임계 결함크기·Weibull·응력부식) · `assess_interface_crack`(직교이방·진동 특이성) ·
`assess_crack_growth_rate`(Paris·문턱·Walker — **전부 B등급**, `confidence` 표시)

**형상 연계** (§21) — `build_laminate_from_geometry`(StepForge 형상 → laminate, 받거나 거절)

핵심 규약. `laminae[0]` = 최하단 ply, 각도 deg(CCW), `unit_system` 필수(`SI` | `SI_mm`), 하중은 단위 폭당.
에이전트용 상세 절차는 [docs/agent_guide.md](docs/agent_guide.md), 수식 유도는 [docs/math_spec.md](docs/math_spec.md),
두 MCP 협동 실 세션 기록은 [docs/s5_scenario_log.md](docs/s5_scenario_log.md).

## 두 표면 — MCP와 REST

같은 계산·검증·응답 envelope를 두 경로로 노출한다.

| 소비자 | 경로 | 발견 방법 |
|---|---|---|
| LLM 에이전트 (Claude 등) | `POST /mcp` (streamable HTTP) 또는 stdio | `tools/list` · `laminate://guide` 리소스 · `get_reference_cases` few-shot |
| 스크립트·서비스·사람 | `GET/POST /api/v1/tools[/{name}]` | `GET /api/v1/tools`(목록+JSON Schema) · `GET /api/v1/guide` · `/docs`(OpenAPI) |

```bash
curl -s localhost:8000/api/v1/tools | jq '.tools[].name'        # 도구 43종
curl -s -X POST localhost:8000/api/v1/tools/analyze_laminate \
     -H 'Content-Type: application/json' \
     -d '{"laminate":{"unit_system":"SI_mm","laminae":[...]}}'   # 실행
```

## 실행

```bash
# 로컬 stdio (Claude Code는 .mcp.json으로 자동 연결 — materialtwin과 함께 등록됨)
.venv/bin/laminate-mcp

# HTTP (HEAXHub fastapi 스택과 동일 형태)
.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --root-path /apps/laminate_analyzer_mcp
# → GET /health · REST /api/v1/* · OpenAPI /docs · MCP POST /mcp
```

## hwax portal(HEAXHub) 등록 — 완료

`HEAXHub/integrations/laminate-analyzer-mcp`가 이 리포지토리의 **심볼릭 링크**(in-tree 통합)이고,
`.portal/manifest.yaml`(schema v2)이 정본이다. 카탈로그 등록·빌드·서비스 기동·Caddy 라우트까지
실증 완료(2026-07-16). Caddy 라우트는 `forward_auth(/api/v1/authz) → prefix strip → 127.0.0.1:<port>`
구조라 포털 경유 접속에는 **포털 인증**이 필요하다(visibility: team).

```bash
# 에이전트 연결 (포털 경유 — 인증 토큰 필요)
claude mcp add --transport http laminate-analyzer \
  <포털베이스>/apps/laminate_analyzer_mcp/mcp --header "Authorization: Bearer <token>"
```

## 개발

```bash
python3.12 -m venv .venv && .venv/bin/pip install -e ".[test]"
.venv/bin/pytest            # 전체 회귀 (도구·광고 표면 일치까지 본다)
```