loadbench-mcp 0.1.0__py3-none-any.whl

load_solver/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

load_solver/server.py

@@ -0,0 +1,338 @@
+"""
+Load solver — an MCP server that does the structural math LLMs get wrong.
+
+Three tools:
+  - check_tipping   : will a set of weights tip over its support footprint?
+  - solve_supports  : how much load does each leg / bracket carry?
+  - beam_check      : will this beam / shelf hold the load? (stress + deflection)
+
+Run locally:    uv run server.py
+Test the math:  python test_physics.py
+"""
+
+from typing import Literal
+import math
+import numpy as np
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("load-solver")
+
+
+# ----------------------------------------------------------------------------
+# Geometry / physics helpers  (plain functions, unit-tested in test_physics.py)
+# ----------------------------------------------------------------------------
+
+def _centroid(points):
+    """Mass-weighted centre of mass of [{x, y, mass}, ...]. Returns (cx, cy, total_mass)."""
+    total = sum(p["mass"] for p in points)
+    if total <= 0:
+        raise ValueError("total mass must be positive")
+    cx = sum(p["mass"] * p["x"] for p in points) / total
+    cy = sum(p["mass"] * p["y"] for p in points) / total
+    return cx, cy, total
+
+
+def _point_in_polygon(px, py, poly):
+    """Ray-casting test. poly = [{x, y}, ...] in order. Works for any simple polygon."""
+    inside = False
+    n = len(poly)
+    j = n - 1
+    for i in range(n):
+        xi, yi = poly[i]["x"], poly[i]["y"]
+        xj, yj = poly[j]["x"], poly[j]["y"]
+        if ((yi > py) != (yj > py)) and (px < (xj - xi) * (py - yi) / (yj - yi) + xi):
+            inside = not inside
+        j = i
+    return inside
+
+
+def _dist_point_segment(px, py, ax, ay, bx, by):
+    """Shortest distance from P to segment AB, plus the nearest point on AB."""
+    dx, dy = bx - ax, by - ay
+    if dx == 0 and dy == 0:
+        t = 0.0
+    else:
+        t = ((px - ax) * dx + (py - ay) * dy) / (dx * dx + dy * dy)
+        t = max(0.0, min(1.0, t))
+    nx, ny = ax + t * dx, ay + t * dy
+    return math.hypot(px - nx, py - ny), nx, ny
+
+
+def _nearest_boundary(px, py, poly):
+    """Min distance from P to the polygon boundary, and the nearest boundary point."""
+    best = (float("inf"), 0.0, 0.0)
+    n = len(poly)
+    for i in range(n):
+        a, b = poly[i], poly[(i + 1) % n]
+        d, nx, ny = _dist_point_segment(px, py, a["x"], a["y"], b["x"], b["y"])
+        if d < best[0]:
+            best = (d, nx, ny)
+    return best
+
+
+# ----------------------------------------------------------------------------
+# Tool 1 — tip-over check
+# ----------------------------------------------------------------------------
+
+@mcp.tool()
+def check_tipping(masses: list[dict], base_polygon: list[dict]) -> dict:
+    """Check whether a collection of weights will tip over its support footprint.
+
+    Computes the centre of mass and tests whether its vertical projection falls
+    inside the support base (the polygon where the object touches the ground).
+    If it falls outside, the object tips. Use this for shelving, stacked loads,
+    machinery on legs, vehicles, or anything that could topple.
+
+    Args:
+        masses: list of point masses, each {"x": metres, "y": metres, "mass": kg}.
+            x/y are top-down (plan-view) positions. Height does not affect whether
+            it tips on level ground, only the horizontal centre of mass does.
+        base_polygon: the support footprint as ordered vertices [{"x", "y"}, ...]
+            in metres (e.g. the four feet of a shelf, or the contact outline).
+
+    Returns:
+        center_of_mass, is_stable (bool), tipping_margin_m (positive = inside the
+        base with this much clearance; negative = already outside / tipping),
+        tipping_direction (unit vector toward the closest base edge), and a short
+        human-readable explanation.
+    """
+    if len(base_polygon) < 3:
+        raise ValueError("base_polygon needs at least 3 vertices")
+    cx, cy, total = _centroid(masses)
+    inside = _point_in_polygon(cx, cy, base_polygon)
+    dist, nx, ny = _nearest_boundary(cx, cy, base_polygon)
+    margin = dist if inside else -dist
+    # unit vector from CoM toward the nearest edge (the weak / tip direction)
+    vx, vy = nx - cx, ny - cy
+    norm = math.hypot(vx, vy) or 1.0
+    direction = {"x": round(vx / norm, 4), "y": round(vy / norm, 4)}
+    if inside:
+        explanation = (
+            f"Stable. Centre of mass is inside the support base with "
+            f"{margin:.3f} m of clearance to the nearest edge."
+        )
+    else:
+        explanation = (
+            f"Tips over. Centre of mass falls {abs(margin):.3f} m outside the "
+            f"support base; it will topple toward the indicated direction."
+        )
+    return {
+        "center_of_mass": {"x": round(cx, 4), "y": round(cy, 4)},
+        "total_mass_kg": round(total, 4),
+        "is_stable": inside,
+        "tipping_margin_m": round(margin, 4),
+        "tipping_direction": direction,
+        "explanation": explanation,
+    }
+
+
+# ----------------------------------------------------------------------------
+# Tool 2 — support reaction forces
+# ----------------------------------------------------------------------------
+
+@mcp.tool()
+def solve_supports(
+    supports: list[dict],
+    loads: list[dict],
+    self_weight_n: float = 0.0,
+) -> dict:
+    """Compute how much vertical force each support (leg, bracket, foot) carries.
+
+    Models a rigid object resting on point supports of equal stiffness and solves
+    static equilibrium so the reactions balance every applied load in force and
+    moment. Handles any number of supports. Flags supports that exceed their rated
+    capacity, and supports with a negative reaction (the object is lifting off /
+    would tip rather than rest evenly).
+
+    Args:
+        supports: [{"id": str, "x": m, "y": m, "capacity_n": N (optional)}].
+        loads: downward point loads [{"x": m, "y": m, "magnitude_n": N}].
+        self_weight_n: optional self-weight of the object (N), applied at the
+            centroid of the supports.
+
+    Returns:
+        per-support reaction forces, over-capacity / lift-off flags, total load,
+        max utilisation, any warnings, and a short explanation.
+    """
+    if len(supports) == 0:
+        raise ValueError("need at least one support")
+
+    warnings = []
+
+    # total load and its resultant position (centroid of the loads)
+    total = self_weight_n + sum(l["magnitude_n"] for l in loads)
+    if total <= 0:
+        raise ValueError("total load must be positive")
+
+    sx = sum(s["x"] for s in supports) / len(supports)
+    sy = sum(s["y"] for s in supports) / len(supports)
+    mx = self_weight_n * sx + sum(l["magnitude_n"] * l["x"] for l in loads)
+    my = self_weight_n * sy + sum(l["magnitude_n"] * l["y"] for l in loads)
+
+    xs = np.array([s["x"] for s in supports], dtype=float)
+    ys = np.array([s["y"] for s in supports], dtype=float)
+    n = len(supports)
+
+    # Reaction model: R_i = a + b*x_i + c*y_i  (deflection plane of a rigid body
+    # on equal-stiffness supports). Solve the 3 equilibrium equations for a,b,c.
+    A = np.array([
+        [n,            xs.sum(),        ys.sum()],
+        [xs.sum(),     (xs * xs).sum(), (xs * ys).sum()],
+        [ys.sum(),     (xs * ys).sum(), (ys * ys).sum()],
+    ])
+    rhs = np.array([total, mx, my])
+
+    if n < 3 or np.linalg.matrix_rank(A) < 3:
+        warnings.append(
+            "Supports are fewer than 3 or nearly collinear; the distribution is "
+            "approximate. Use 3+ non-collinear supports for a unique solution."
+        )
+        coeffs, *_ = np.linalg.lstsq(A, rhs, rcond=None)
+    else:
+        coeffs = np.linalg.solve(A, rhs)
+
+    a, b, c = coeffs
+    reactions = a + b * xs + c * ys
+
+    out = []
+    max_util = 0.0
+    for s, r in zip(supports, reactions):
+        force = float(r)
+        cap = s.get("capacity_n")
+        over = bool(cap is not None and force > cap)
+        util = (force / cap) if cap else None
+        if util is not None:
+            max_util = max(max_util, util)
+        if force < 0:
+            warnings.append(
+                f"Support '{s.get('id', '?')}' has a negative reaction "
+                f"({force:.1f} N) — it is lifting off; the object is unstable here."
+            )
+        out.append({
+            "id": s.get("id", "?"),
+            "force_n": round(force, 2),
+            "over_capacity": over,
+            "utilization": round(util, 3) if util is not None else None,
+        })
+
+    explanation = (
+        f"Total load {total:.1f} N distributed across {n} support(s). "
+        + ("Some supports are overloaded or lifting off — see flags." if warnings
+           else "All reactions are positive and within capacity.")
+    )
+    return {
+        "reactions": out,
+        "total_load_n": round(total, 2),
+        "max_utilization": round(max_util, 3) if max_util else None,
+        "warnings": warnings,
+        "explanation": explanation,
+    }
+
+
+# ----------------------------------------------------------------------------
+# Tool 3 — beam / shelf check
+# ----------------------------------------------------------------------------
+
+@mcp.tool()
+def beam_check(
+    span_m: float,
+    support_type: Literal["simply_supported", "cantilever"],
+    load_type: Literal["point", "udl"],
+    magnitude_n: float,
+    e_pa: float,
+    allowable_stress_pa: float,
+    section_modulus_m3: float | None = None,
+    inertia_m4: float | None = None,
+    width_m: float | None = None,
+    height_m: float | None = None,
+    deflection_limit_ratio: float | None = None,
+) -> dict:
+    """Check whether a beam or shelf holds a load: bending stress and deflection.
+
+    Closed-form Euler–Bernoulli check. "point" puts the whole load at the centre
+    (simply supported) or the free end (cantilever); "udl" spreads magnitude_n
+    evenly along the span. Give the section either directly (section_modulus_m3
+    and inertia_m4) OR as a solid rectangle (width_m and height_m).
+
+    Args:
+        span_m: clear span / length, metres.
+        support_type: "simply_supported" (held both ends) or "cantilever" (one end).
+        load_type: "point" or "udl" (uniformly distributed).
+        magnitude_n: total load in newtons (1 kg ≈ 9.81 N).
+        e_pa: Young's modulus of the material, pascals (steel ≈ 2.0e11, pine ≈ 9e9).
+        allowable_stress_pa: allowable bending stress of the material, pascals.
+        section_modulus_m3: Z, if known. Else give width_m and height_m.
+        inertia_m4: I, if known. Else give width_m and height_m.
+        width_m, height_m: for a solid rectangle, used to compute Z and I.
+        deflection_limit_ratio: optional, e.g. 250 means limit deflection to span/250.
+
+    Returns:
+        max_moment_nm, max_stress_pa, max_deflection_m, stress utilisation,
+        pass/fail, governing check, and a short explanation.
+    """
+    if width_m and height_m:
+        section_modulus_m3 = width_m * height_m ** 2 / 6.0
+        inertia_m4 = width_m * height_m ** 3 / 12.0
+    if not section_modulus_m3 or not inertia_m4:
+        raise ValueError("provide section_modulus_m3 + inertia_m4, or width_m + height_m")
+
+    L, P, E, I, Z = span_m, magnitude_n, e_pa, inertia_m4, section_modulus_m3
+
+    if support_type == "simply_supported":
+        if load_type == "point":
+            m_max = P * L / 4.0
+            defl = P * L ** 3 / (48.0 * E * I)
+        else:
+            m_max = P * L / 8.0
+            defl = 5.0 * P * L ** 3 / (384.0 * E * I)
+    else:  # cantilever
+        if load_type == "point":
+            m_max = P * L
+            defl = P * L ** 3 / (3.0 * E * I)
+        else:
+            m_max = P * L / 2.0
+            defl = P * L ** 3 / (8.0 * E * I)
+
+    stress = m_max / Z
+    stress_util = stress / allowable_stress_pa
+    stress_ok = stress <= allowable_stress_pa
+
+    defl_ok = True
+    defl_util = None
+    if deflection_limit_ratio:
+        limit = L / deflection_limit_ratio
+        defl_util = defl / limit
+        defl_ok = defl <= limit
+
+    passes = stress_ok and defl_ok
+    if not stress_ok:
+        governing = "bending stress"
+    elif not defl_ok:
+        governing = "deflection"
+    else:
+        governing = "stress" if (defl_util is None or stress_util >= defl_util) else "deflection"
+
+    explanation = (
+        f"{'PASS' if passes else 'FAIL'}: peak stress {stress/1e6:.1f} MPa vs "
+        f"{allowable_stress_pa/1e6:.1f} MPa allowable "
+        f"({stress_util*100:.0f}% used), deflection {defl*1000:.1f} mm."
+    )
+    return {
+        "max_moment_nm": round(m_max, 2),
+        "max_stress_pa": round(stress, 1),
+        "max_deflection_m": round(defl, 6),
+        "stress_utilization": round(stress_util, 3),
+        "deflection_utilization": round(defl_util, 3) if defl_util is not None else None,
+        "passes": passes,
+        "governing_check": governing,
+        "explanation": explanation,
+    }
+
+
+def main():
+    """Console entry point: run the MCP server over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

loadbench_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: loadbench-mcp
+Version: 0.1.0
+Summary: MCP server for structural load & stability math: tipping, support reactions, beam checks.
+Project-URL: Homepage, https://github.com/jeongho54/loadbench-mcp
+Project-URL: Repository, https://github.com/jeongho54/loadbench-mcp
+Author: jeongho54
+License-Expression: MIT
+Keywords: beam,engineering,mcp,model-context-protocol,statics,structural,tipping
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.27
+Requires-Dist: numpy>=1.26
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.jeongho54/loadbench -->
+
+# loadbench-mcp
+
+An MCP server that does the structural load & stability math language models get
+wrong. AI assistants call it instead of guessing.
+
+| Tool | Question it answers |
+|------|---------------------|
+| `check_tipping` | Will these weights topple over their footprint? |
+| `solve_supports` | How much load does each leg / bracket carry? |
+| `beam_check` | Will this beam or shelf hold the load? (stress + deflection) |
+
+All math is verified against hand-computed answers (`tests/test_physics.py`).
+
+## Install & run
+
+Once published to PyPI, any MCP client can launch it with no install step:
+
+```
+uvx loadbench-mcp
+```
+
+Or install it:
+
+```
+pip install loadbench-mcp
+loadbench-mcp
+```
+
+## Use it in Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "loadbench": {
+      "command": "uvx",
+      "args": ["loadbench-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop, then ask things like *"A 2 m pine shelf on two brackets
+0.3 m from each end — will it hold 40 kg in the middle?"*
+
+## Local development
+
+```
+uv run --with mcp --with numpy python -m load_solver.server   # run from source
+python -m pytest tests                                         # verify the math
+```
+
+Inputs are SI units (metres, kilograms, newtons; 1 kg ≈ 9.81 N). Tool docstrings
+carry the full argument details, which the model reads automatically.
+
+> Estimates for planning, not certified engineering. For loads where a failure
+> could cause injury or real damage, have a qualified engineer check the result.
+
+## License
+
+MIT

loadbench_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+load_solver/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+load_solver/server.py,sha256=rLHUur0ZJ2QftSHO1TwrR43xkhqY28IuqrPznZb4dlA,12922
+loadbench_mcp-0.1.0.dist-info/METADATA,sha256=0HTJgh3poeO4IzPyLV8yw-9G5heKMErgv7afGQ9Bzzc,2368
+loadbench_mcp-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+loadbench_mcp-0.1.0.dist-info/entry_points.txt,sha256=c7ADSkgt4pl4B9JBJOVb5A_9uZF7pM2SBfvi8z6PCD4,58
+loadbench_mcp-0.1.0.dist-info/RECORD,,

loadbench_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

loadbench_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+loadbench-mcp = load_solver.server:main