kratos-mcp-server 0.1.1__tar.gz

kratos_mcp_server-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    name: Unit tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync
+      - name: Run unit tests (Kratos integration tests are skipped without a build)
+        run: uv run pytest -m "not kratos" -q
+
+  build-package:
+    name: Build Python package
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package
+          path: dist/*
+
+  build-docs:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run docs:build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: docs-site
+          path: docs/.vitepress/dist

kratos_mcp_server-0.1.1/.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - name: Build with VitePress
+        run: npm run docs:build
+        env:
+          # Serve from https://<user>.github.io/<repo>/
+          DOCS_BASE: /${{ github.event.repository.name }}/
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

kratos_mcp_server-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Run unit tests
+        run: uv sync && uv run pytest -m "not kratos" -q
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Create GitHub release with artifacts
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  publish-pypi:
+    # Publishes via PyPI trusted publishing; configure the 'pypi' environment
+    # and a trusted publisher on pypi.org before the first release.
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

kratos_mcp_server-0.1.1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+node_modules/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+.cache/

kratos_mcp_server-0.1.1/CLAUDE.md

@@ -0,0 +1,115 @@
+# Kratos MCP Server
+
+MCP (Model Context Protocol) server exposing Kratos Multiphysics to AI
+assistants: installation introspection, case scaffolding (ProjectParameters /
+Materials / MDPA meshes), simulation execution as background jobs, and VTK
+post-processing. Python, `mcp` SDK (FastMCP), stdio transport.
+
+## Environment
+
+A local compiled build is optional: `src/kratos_mcp/kratos_env.py` resolves
+Kratos from, in order, an explicit `KRATOS_PYTHONPATH`/`KRATOS_LIBS`, a
+`KRATOS_ROOT` build tree, or a pip-installed `KratosMultiphysics` importable
+by the server's own interpreter.
+
+- `KRATOS_ROOT` (default `/home/vicente/src/Kratos`) → uses
+  `$KRATOS_ROOT/bin/Release` as `PYTHONPATH` and `$KRATOS_ROOT/bin/Release/libs`
+  as `LD_LIBRARY_PATH`.
+- Overrides: `KRATOS_PYTHONPATH`, `KRATOS_LIBS`, `KRATOS_SOURCE` (source tree
+  for macro parsing), `KRATOS_EXTRA_LIBS` (extra lib dirs; MKL under
+  `/opt/intel/oneapi/mkl/latest/lib` is auto-detected — LinearSolversApplication
+  needs `libmkl_rt.so.2`).
+- **Pip fallback**: if no build tree resolves, `kratos_env.resolve()` probes
+  `python -c "import KratosMultiphysics"` in a subprocess. The `kratos_install`
+  tool (`tools/environment.py`) populates this by running `pip install` —
+  official wheels are `KratosMultiphysics` (core), `Kratos<AppName>` per
+  application (e.g. `KratosStructuralMechanicsApplication`), or
+  `KratosMultiphysics-all` (everything) — Linux/Windows x86_64 only, no macOS
+  wheels. `kratos_env.pip_install()`/`pypi_package_name()` do the mapping and
+  subprocess call; running pip itself is fine in the server process (it never
+  imports Kratos), unlike everything else Kratos-related.
+- Manual incantation for ad-hoc Kratos scripts against a build tree:
+  `PYTHONPATH=$KRATOS_ROOT/bin/Release LD_LIBRARY_PATH=$KRATOS_ROOT/bin/Release/libs:/opt/intel/oneapi/mkl/latest/lib python3 ...`
+- Server state (jobs, bridge cache) lives in `~/.kratos-mcp/`
+  (`KRATOS_MCP_HOME` overrides; tests set it to a tmp dir).
+
+## The one hard rule
+
+**Never import KratosMultiphysics in the server process.** It prints an ASCII
+banner on import (corrupts the stdio JSON-RPC stream) and its C++ core can
+abort the process. All Kratos access goes through subprocesses:
+
+- `bridge.py` → spawns `worker.py` for short ops (introspection, validation,
+  deep mdpa read). Results travel via a `--result-file` JSON file, never
+  stdout. Cacheable ops are cached on disk keyed by build fingerprint.
+- `jobs.py` → spawns `runner.py` detached for simulations. Job state persists
+  in `~/.kratos-mcp/jobs/<id>/` (`meta.json` + `stdout.log`) and survives
+  server restarts; orphaned jobs are re-evaluated from pid liveness + log tail.
+
+`worker.py` and `runner.py` are the ONLY modules that import Kratos, and they
+only run inside subprocesses with the env vars injected.
+
+## Commands
+
+- `uv sync` — install deps (`mcp`, `meshio`, `numpy`; dev: pytest)
+- `uv run kratos-mcp` — run the server (stdio)
+- `uv run pytest -m "not kratos"` — unit tests, no Kratos needed
+- `uv run pytest -m kratos` — integration tests against the real build
+  (cantilever + thermal bar end-to-end with physics assertions)
+- `uv run python tests/smoke_client.py` — scripted stdio MCP client smoke test
+- `npm run docs:dev` / `npm run docs:build` — VitePress docs
+
+## Layout
+
+- `src/kratos_mcp/server.py` — FastMCP instance + main()
+- `src/kratos_mcp/tools/` — one module per tool category (`environment`,
+  `scaffold`, `mesh`, `simulation`, `postprocess`, `resources`, `prompts`),
+  each exposing `register(mcp)`; `register_all` in `__init__.py`
+- `src/kratos_mcp/mdpa.py` — pure-Python MDPA parse/write/inspect/validate +
+  structured mesh generators (line/rectangle/box with named boundary parts)
+- `src/kratos_mcp/source_catalog.py` — parses `KRATOS_REGISTER_ELEMENT/
+  CONDITION/CONSTITUTIVE_LAW` macros from the Kratos C++ sources (there is no
+  runtime registry for these)
+- `src/kratos_mcp/templates/` — case templates as data: `registry.json`
+  (metadata + placeholder defaults) + `<name>/ProjectParameters.json.tpl` +
+  `Materials.json.tpl`. Substitution: quoted `"{{key}}"` → JSON-typed value,
+  bare `{{key}}` → text.
+- `src/kratos_mcp/logparse.py` — step/convergence extraction from job logs
+
+## Kratos gotchas learned the hard way
+
+- Load-bearing conditions must be the `*LoadCondition*` types
+  (`LineLoadCondition2D2N`, `SurfaceLoadCondition3D4N`); the generic
+  `LineCondition2D2N`/`SurfaceCondition3D4N` are geometric dummies that
+  silently contribute nothing (zero RHS, zero displacement).
+- The convection-diffusion solver REPLACES mesh elements at import
+  (`element_replace_settings`); thermal meshes use generic `Element2D3N` +
+  `ThermalFace2D2N`. It must be a simplex mesh (triangles/tets) — its
+  `TetrahedralMeshOrientationCheck` fails on quads with "condition without
+  any corresponding element".
+- `solver_type: stationary` still defaults to the transient EulerianConvDiff
+  element; true steady state needs `element_replace_settings: {"element_name":
+  "LaplacianElement", ...}` (our `thermal_stationary` template does this).
+- Static analyses run exactly one step via `time_step: 1.1 > end_time: 1.0`
+  (standard Kratos test convention).
+- `Kernel.Get*VariableNames()` return one newline-separated string, not lists.
+- `KM.Parameters` tolerates `//` comments; plain `json.loads` on Kratos test
+  files may fail.
+- Kratos resolves mdpa/materials paths relative to the CWD → `runner.py`
+  chdirs into the case directory.
+
+## Conventions
+
+- All server logging to stderr (stdout is the MCP transport).
+- Tools return plain dicts; errors as `{"error": ...}` rather than raising
+  (bridge failures include worker stdout/stderr tails for diagnosis).
+- Blocking work inside async tools goes through `anyio.to_thread.run_sync`.
+- Tool inputs/outputs use absolute paths.
+- Reference cases used for templates/tests:
+  `applications/StructuralMechanicsApplication/tests/LinearTruss2D/2D2N/` and
+  `applications/ConvectionDiffusionApplication/tests/basic_conv_diffusion_test/`
+  in the Kratos tree.
+
+## Keep docs in sync
+
+Every time you change code in this repo, check whether doc/, README.md, and this file need updating too — and update them if they do. Treat doc drift as part of the change, not a follow-up.

kratos_mcp_server-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vicente Mataix Ferrándiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kratos_mcp_server-0.1.1/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: kratos-mcp-server
+Version: 0.1.1
+Summary: MCP server for Kratos Multiphysics: scaffold, run and post-process finite element simulations
+Author: Vicente Mataix Ferrándiz
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.2
+Requires-Dist: meshio>=5.3
+Requires-Dist: numpy>=1.26
+Description-Content-Type: text/markdown
+
+# Kratos MCP Server
+
+[![CI](https://github.com/loumalouomega/Kratos-MCP-Server/actions/workflows/ci.yml/badge.svg)](https://github.com/loumalouomega/Kratos-MCP-Server/actions/workflows/ci.yml)
+[![Deploy docs](https://github.com/loumalouomega/Kratos-MCP-Server/actions/workflows/docs.yml/badge.svg)](https://loumalouomega.github.io/Kratos-MCP-Server/)
+[![Release](https://github.com/loumalouomega/Kratos-MCP-Server/actions/workflows/release.yml/badge.svg)](https://github.com/loumalouomega/Kratos-MCP-Server/releases)
+[![PyPI](https://img.shields.io/pypi/v/kratos-mcp-server.svg)](https://pypi.org/project/kratos-mcp-server/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/github/license/loumalouomega/Kratos-MCP-Server)](LICENSE)
+
+An [MCP](https://modelcontextprotocol.io) server that lets AI assistants drive
+[Kratos Multiphysics](https://github.com/KratosMultiphysics/Kratos) finite
+element simulations end to end:
+
+- **Introspect** the installation: applications, elements, conditions,
+  constitutive laws, variables, solvers and their default parameters.
+- **Scaffold** simulation cases from templates: structural
+  (static/dynamic/modal), thermal (transient/stationary) and fluid
+  (transient incompressible) — ProjectParameters.json, Materials.json and
+  structured MDPA meshes with named boundary regions.
+- **Run** simulations as managed background jobs (status, live logs,
+  progress, cancel) that survive server restarts.
+- **Post-process** VTK results: summaries, point probes, convergence
+  analysis.
+
+31 tools, 7 resources and 4 guided prompts. See the full documentation in
+[`docs/`](docs/) (VitePress).
+
+## Quick start
+
+A local Kratos build is **not required** — the server can pip-install
+Kratos itself on first use.
+
+**Once published to PyPI**, no clone needed — `uvx` fetches and runs it:
+
+```bash
+claude mcp add kratos -- uvx kratos-mcp-server
+```
+
+**From a local checkout** (current state, before the first PyPI release):
+
+```bash
+git clone https://github.com/loumalouomega/Kratos-MCP-Server
+cd Kratos-MCP-Server
+uv sync
+claude mcp add kratos -- uv --directory "$PWD" run kratos-mcp
+```
+
+Then ask your assistant something like:
+
+> Check the Kratos installation — install it if it's missing — then set up
+> a cantilever plate 1 m × 0.2 m fixed on the left with a 1 MN/m downward
+> load on the right edge, run it, and report the tip deflection.
+
+The assistant calls `kratos_install` the first time and reuses it afterwards.
+If you already have a compiled Kratos checkout, skip that and point
+`KRATOS_ROOT` at it instead (`-e KRATOS_ROOT=/path/to/Kratos` on the `claude
+mcp add` line) — see [Installation](docs/guide/installation.md).
+
+## Requirements
+
+- Python ≥ 3.10, [uv](https://docs.astral.sh/uv/)
+- Kratos Multiphysics, either pip-installed via `kratos_install`
+  (Linux/Windows x86_64 only — no macOS wheels) or a compiled build (tested
+  with 10.4, StructuralMechanics / ConvectionDiffusion / FluidDynamics /
+  LinearSolvers applications)
+
+## Architecture in one paragraph
+
+Kratos is never imported in the server process — it prints a banner on import
+(which would corrupt the stdio JSON-RPC stream) and can abort the process on
+solver errors. Short operations run in a **worker** subprocess that returns
+JSON through a result file; simulations run **detached** with per-job
+directories under `~/.kratos-mcp/jobs/`. See
+[docs/guide/architecture.md](docs/guide/architecture.md).
+
+## Development
+
+```bash
+uv run pytest -m "not kratos"   # unit tests (no Kratos needed)
+uv run pytest -m kratos          # integration tests against the real build
+npm install && npm run docs:dev  # documentation site
+```
+
+## License
+
+[MIT](LICENSE)

kratos_mcp_server-0.1.1/README.md

@@ -0,0 +1,86 @@
+# Kratos MCP Server
+
+[![CI](https://github.com/loumalouomega/Kratos-MCP-Server/actions/workflows/ci.yml/badge.svg)](https://github.com/loumalouomega/Kratos-MCP-Server/actions/workflows/ci.yml)
+[![Deploy docs](https://github.com/loumalouomega/Kratos-MCP-Server/actions/workflows/docs.yml/badge.svg)](https://loumalouomega.github.io/Kratos-MCP-Server/)
+[![Release](https://github.com/loumalouomega/Kratos-MCP-Server/actions/workflows/release.yml/badge.svg)](https://github.com/loumalouomega/Kratos-MCP-Server/releases)
+[![PyPI](https://img.shields.io/pypi/v/kratos-mcp-server.svg)](https://pypi.org/project/kratos-mcp-server/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/github/license/loumalouomega/Kratos-MCP-Server)](LICENSE)
+
+An [MCP](https://modelcontextprotocol.io) server that lets AI assistants drive
+[Kratos Multiphysics](https://github.com/KratosMultiphysics/Kratos) finite
+element simulations end to end:
+
+- **Introspect** the installation: applications, elements, conditions,
+  constitutive laws, variables, solvers and their default parameters.
+- **Scaffold** simulation cases from templates: structural
+  (static/dynamic/modal), thermal (transient/stationary) and fluid
+  (transient incompressible) — ProjectParameters.json, Materials.json and
+  structured MDPA meshes with named boundary regions.
+- **Run** simulations as managed background jobs (status, live logs,
+  progress, cancel) that survive server restarts.
+- **Post-process** VTK results: summaries, point probes, convergence
+  analysis.
+
+31 tools, 7 resources and 4 guided prompts. See the full documentation in
+[`docs/`](docs/) (VitePress).
+
+## Quick start
+
+A local Kratos build is **not required** — the server can pip-install
+Kratos itself on first use.
+
+**Once published to PyPI**, no clone needed — `uvx` fetches and runs it:
+
+```bash
+claude mcp add kratos -- uvx kratos-mcp-server
+```
+
+**From a local checkout** (current state, before the first PyPI release):
+
+```bash
+git clone https://github.com/loumalouomega/Kratos-MCP-Server
+cd Kratos-MCP-Server
+uv sync
+claude mcp add kratos -- uv --directory "$PWD" run kratos-mcp
+```
+
+Then ask your assistant something like:
+
+> Check the Kratos installation — install it if it's missing — then set up
+> a cantilever plate 1 m × 0.2 m fixed on the left with a 1 MN/m downward
+> load on the right edge, run it, and report the tip deflection.
+
+The assistant calls `kratos_install` the first time and reuses it afterwards.
+If you already have a compiled Kratos checkout, skip that and point
+`KRATOS_ROOT` at it instead (`-e KRATOS_ROOT=/path/to/Kratos` on the `claude
+mcp add` line) — see [Installation](docs/guide/installation.md).
+
+## Requirements
+
+- Python ≥ 3.10, [uv](https://docs.astral.sh/uv/)
+- Kratos Multiphysics, either pip-installed via `kratos_install`
+  (Linux/Windows x86_64 only — no macOS wheels) or a compiled build (tested
+  with 10.4, StructuralMechanics / ConvectionDiffusion / FluidDynamics /
+  LinearSolvers applications)
+
+## Architecture in one paragraph
+
+Kratos is never imported in the server process — it prints a banner on import
+(which would corrupt the stdio JSON-RPC stream) and can abort the process on
+solver errors. Short operations run in a **worker** subprocess that returns
+JSON through a result file; simulations run **detached** with per-job
+directories under `~/.kratos-mcp/jobs/`. See
+[docs/guide/architecture.md](docs/guide/architecture.md).
+
+## Development
+
+```bash
+uv run pytest -m "not kratos"   # unit tests (no Kratos needed)
+uv run pytest -m kratos          # integration tests against the real build
+npm install && npm run docs:dev  # documentation site
+```
+
+## License
+
+[MIT](LICENSE)

kratos_mcp_server-0.1.1/docs/.vitepress/config.ts

@@ -0,0 +1,59 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'Kratos MCP Server',
+  description:
+    'MCP server for Kratos Multiphysics: scaffold, run and post-process finite element simulations from AI assistants',
+  base: process.env.DOCS_BASE ?? '/',
+  themeConfig: {
+    nav: [
+      { text: 'Guide', link: '/guide/getting-started' },
+      { text: 'Tools', link: '/tools/' },
+      { text: 'Tutorials', link: '/tutorials/cantilever-beam' },
+    ],
+    sidebar: {
+      '/guide/': [
+        {
+          text: 'Guide',
+          items: [
+            { text: 'Getting started', link: '/guide/getting-started' },
+            { text: 'Installation', link: '/guide/installation' },
+            { text: 'Connecting a client', link: '/guide/connecting' },
+            { text: 'Architecture', link: '/guide/architecture' },
+            { text: 'The MDPA mesh format', link: '/guide/mdpa-format' },
+            { text: 'Troubleshooting', link: '/guide/troubleshooting' },
+          ],
+        },
+      ],
+      '/tools/': [
+        {
+          text: 'Tool reference',
+          items: [
+            { text: 'Overview', link: '/tools/' },
+            { text: 'Environment & introspection', link: '/tools/environment' },
+            { text: 'Project scaffolding', link: '/tools/scaffolding' },
+            { text: 'Meshes (MDPA)', link: '/tools/mesh' },
+            { text: 'Simulation & jobs', link: '/tools/simulation' },
+            { text: 'Post-processing', link: '/tools/postprocessing' },
+            { text: 'Resources', link: '/tools/resources' },
+            { text: 'Prompts', link: '/tools/prompts' },
+          ],
+        },
+      ],
+      '/tutorials/': [
+        {
+          text: 'Tutorials',
+          items: [
+            { text: 'Cantilever beam', link: '/tutorials/cantilever-beam' },
+            { text: 'Thermal bar', link: '/tutorials/thermal-bar' },
+          ],
+        },
+      ],
+    },
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/KratosMultiphysics/Kratos' },
+    ],
+    search: { provider: 'local' },
+    outline: [2, 3],
+  },
+})

kratos_mcp_server-0.1.1/docs/guide/architecture.md

@@ -0,0 +1,117 @@
+# Architecture
+
+## The core constraint
+
+Kratos cannot run inside the MCP server process, for three reasons:
+
+1. **stdout is sacred.** MCP over stdio uses stdout for JSON-RPC framing, and
+   `import KratosMultiphysics` prints a multi-line ASCII banner to stdout.
+   One import would corrupt the protocol stream.
+2. **Crashes.** Kratos is a C++ core; a solver bug or bad input can abort the
+   whole process (segfault). The server must survive that.
+3. **Environment.** A build-tree Kratos needs `PYTHONPATH` and
+   `LD_LIBRARY_PATH` set *before* the interpreter starts — too late for a
+   process that is already running.
+
+So the server process never imports Kratos. Two subprocess mechanisms cover
+all Kratos access:
+
+```
+┌──────────────────────────────┐
+│  MCP client (Claude, ...)    │
+└──────────────┬───────────────┘
+               │ stdio JSON-RPC
+┌──────────────▼───────────────┐
+│  kratos-mcp server (FastMCP) │   never imports Kratos
+│  tools/ · mdpa.py · jobs.py  │
+└─────┬───────────────────┬────┘
+      │ bridge.run_op()   │ jobs.start()
+      │ (sync, seconds)   │ (detached, minutes-hours)
+┌─────▼─────────┐   ┌─────▼─────────┐
+│  worker.py    │   │  runner.py    │   both import Kratos,
+│  introspection│   │  AnalysisStage│   env vars injected
+│  validation   │   │  .Run()       │
+└───────────────┘   └───────────────┘
+```
+
+## Getting Kratos itself
+
+`kratos_env.resolve()` finds Kratos in one of three ways, in order: an
+explicit `KRATOS_PYTHONPATH`/`KRATOS_LIBS` override, a `KRATOS_ROOT`
+checkout with a compiled `bin/Release`, or a **pip-installed**
+`KratosMultiphysics` importable by the server's own interpreter — probed in
+a subprocess so a missing package fails safely instead of raising in the
+server process. That third path is what `kratos_env.pip_install()` and the
+`kratos_install` tool populate: they run `pip install` (never Kratos itself)
+directly in the server process — safe, since pip does not import
+Kratos — installing the official `KratosMultiphysics` / `Kratos<AppName>` /
+`KratosMultiphysics-all` wheels (Linux/Windows x86_64 only). Once installed,
+the very next `resolve()` call picks it up automatically; no restart needed.
+A local build always takes priority when both are present.
+
+## The bridge (short operations)
+
+`bridge.run_op(op, args)` spawns `python -m kratos_mcp.worker` with the Kratos
+environment injected and a JSON request file. The worker writes its result to
+a **result file** — never stdout — so banners and solver chatter cannot
+corrupt it; stdout/stderr are captured and attached to error messages.
+
+Ops: `check`, `list_applications`, `list_variables`, `has_constitutive_laws`,
+`get_solver_defaults`, `validate_parameters`, `read_mdpa_deep`.
+
+Because each spawn costs one to a few seconds, results of build-dependent ops
+are cached in `~/.kratos-mcp/cache/`, keyed by `(op, args, build
+fingerprint)` — editing or rebuilding Kratos invalidates the cache
+automatically.
+
+## Jobs (simulations)
+
+`jobs.start()` launches `python -m kratos_mcp.runner --case-dir ...` fully
+detached (own session), with everything persisted under
+`~/.kratos-mcp/jobs/<job_id>/`:
+
+```
+20260712-101530-a1b2c3/
+├── meta.json     # state machine: queued → running → succeeded|failed|cancelled
+└── stdout.log    # combined solver output
+```
+
+- **Status** is recomputed from the process return code, or — after a server
+  restart, when the child handle is gone — from pid liveness plus the
+  AnalysisStage end banner in the log.
+- **Progress** (`current_step`, `current_time`) is parsed from the
+  `STEP:`/`TIME:` lines AnalysisStage prints each step.
+- **Cancel** sends SIGTERM to the job's process group and escalates to
+  SIGKILL after a grace period.
+
+The runner picks the analysis class from the `analysis_stage` key in
+ProjectParameters.json (the convention used by Kratos itself and by all our
+templates), from an explicit `analysis_type`/`analysis_class` argument, or by
+inferring it from `solver_type`.
+
+## Hybrid introspection
+
+What the tools report comes from two sources:
+
+- **Runtime** (authoritative for *your build*): version, compiled
+  applications, variables, constitutive-law existence, solver default
+  parameters — via the bridge.
+- **Source parsing**: element/condition/constitutive-law catalogs are parsed
+  from `KRATOS_REGISTER_*` macros in the C++ sources, because Kratos has no
+  runtime listing for them. Entries are flagged `compiled: true/false` by
+  cross-referencing the compiled application list.
+
+## Pure-Python MDPA layer
+
+`mdpa.py` parses, writes, validates and generates `.mdpa` meshes without
+Kratos, so mesh tools work even where no build is available and unit tests
+run anywhere. `mdpa_validate(deep=true)` additionally round-trips the file
+through the real `ModelPartIO` in a worker.
+
+## Templates as data
+
+Case templates live in `src/kratos_mcp/templates/` as JSON files with
+`{{placeholder}}` markers plus a `registry.json` describing defaults,
+required applications and solver modules. Substitution is typed: a quoted
+`"{{key}}"` becomes the JSON encoding of the value (numbers stay numbers,
+arrays stay arrays); a bare `{{key}}` inside a longer string is textual.