# mcp-engineering-tools

[![CI](https://github.com/shahradzomorrodi/mcp-engineering-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/shahradzomorrodi/mcp-engineering-tools/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

An [MCP](https://modelcontextprotocol.io) server that gives an AI assistant a set of real mechanical-engineering tools. Instead of asking a model to recall a material property or do a beam calculation in its head (where it can quietly be wrong), the model calls a tool that returns a deterministic, checkable answer.

I'm a mechanical engineering student, and I built this to sit at the boundary I actually work at: hardware analysis on one side, AI tooling on the other. The Model Context Protocol is Anthropic's open standard for connecting models to external tools, so this is a small, complete example of exposing engineering domain logic through it.

![Live demo: calling beam_analysis on a cantilever rod through the MCP Inspector, showing it flag a factor of safety of 0.73 (the rod yields)](docs/demo.gif)

## Tools

| Tool | What it does |
|---|---|
| `material_properties` | Typical properties (density, modulus, yield/ultimate strength, thermal conductivity, CTE) for common materials. Accepts shorthand like `6061`, `Ti-6Al-4V`, `304`. |
| `beam_analysis` | Max deflection, moment, and bending stress for four standard beam cases, with an optional factor of safety against yield. |
| `convert_units` | Dimension-aware unit conversion. Refuses nonsense like force-to-length instead of returning a wrong number. |
| `list_units` | Lists every supported unit, grouped by dimension. |
| `fit_correlation` | Least-squares curve fit (linear or power law) of experimental data, returning coefficients, R^2, and a formula. |

The `fit_correlation` power-law mode is the form used to build dimensionless heat-transfer correlations like `Nu = C * Re^n`: it fits a straight line in log-log space and reads the exponent off the slope.

## See it work

`bun run demo` runs the server and calls each tool with a realistic question. A few of the answers:

**A loaded steel rod that actually fails.** The tool returns a factor of safety below 1, so it flags the failure with numbers instead of a guess:

```
beam_analysis  cantilever, 0.8 m, 20 mm dia, 500 N at the tip, steel
-> max_bending_stress_MPa: 509.3      (yield is 370 MPa)
   factor_of_safety: 0.73            // < 1: this rod yields
   max_deflection_m: 0.053
```

**Building a heat-transfer correlation from data.** Five (Re, Nu) points fit straight to the standard form:

```
fit_correlation  power-law on (Re, Nu) data
-> formula: "y = 0.1459 * x^0.6609"
   rSquaredLogSpace: 0.99999
```

**Refusing a meaningless request** instead of returning a wrong number:

```
convert_units  100 N -> m
-> Dimension mismatch: "N" is force, "m" is length. These are not convertible.
```

Every value above is computed by the server, which is the point: the model calls a tool and gets a checkable answer rather than recalling one that might be subtly wrong.

### Verified engineering walkthrough

`bun run showcase` is the compact version I use to demonstrate the project. It starts the actual MCP server, sends an AI-style beam request through MCP, compares the returned values against an independent Euler-Bernoulli calculation in the walkthrough script, and then runs the real automated test suite. The checked cantilever benchmark produces 0.400 mm deflection, 12.0 MPa bending stress, and a factor of safety of 23.0.

## Design notes

A few deliberate choices, since the point of this repo is the engineering, not the line count:

- **The curve fit is implemented from scratch** ([`src/regression.ts`](src/regression.ts)), not pulled from a numerics library. Ordinary least squares is short, and writing it keeps the behavior fully known and testable.
- **Units carry their dimension.** Conversion is only allowed within a dimension, and temperature is handled as an affine transform (offset, not just a scale) rather than being forced into the factor model.
- **Material values state their condition** (temper, processing). A strength number without a condition is not a real number, so each entry says what it corresponds to. These are first-pass handbook values, not certification data.
- **Every input is validated** with [zod](https://zod.dev) at the tool boundary, so bad calls fail with a clear message instead of a `NaN`.

## Running it

Requires [Bun](https://bun.sh) (dev) or Node 18+ (built output).

```bash
bun install
bun test          # 26 tests across the four modules
bun run typecheck
bun run build     # compiles to dist/
bun run demo      # starts the server and calls each tool with a real question
bun run showcase  # runs an MCP call, an independent hand check, and bun test
node scripts/smoke.mjs   # minimal end-to-end smoke check
```

## Using it with Claude

Add the built server to an MCP client. For **Claude Desktop**, edit its config file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "engineering-tools": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-engineering-tools/dist/server.js"]
    }
  }
}
```

For **Claude Code**:

```bash
claude mcp add engineering-tools -- node /absolute/path/to/mcp-engineering-tools/dist/server.js
```

Then ask, for example: "What's the factor of safety on a 1 m 6061 cantilever, 50 by 100 mm, carrying 1 kN at the tip?" and the model will call `material_properties` and `beam_analysis` and answer from the returned numbers.

## Roadmap

Possible future directions, not commitments. The point of listing them is to show where
the domain logic could grow:

- More beam cases (distributed loads, fixed-fixed, overhanging) and combined loading.
- Column buckling (Euler critical load) and a slenderness check.
- Fatigue screening against an endurance limit, with a stress-concentration factor input.
- A wider materials table (more alloys, polymers, and composites) with temperature-dependent values.
- Optional uncertainty on fitted correlations (confidence bounds on the coefficient and exponent).

## License

MIT, see [LICENSE](LICENSE).