Extend Engineer MCP

.github/workflows/ci.yml

@@ -38,3 +38,6 @@ jobs:
 
       - name: Verify the demo runs
         run: npm run demo
+
+      - name: Verify the package contents
+        run: npm pack --dry-run

.gitignore

@@ -2,6 +2,7 @@ node_modules/
 dist/
 coverage/
 *.tsbuildinfo
+*.tgz
 
 *.sqlite
 *.sqlite-journal

README.md

@@ -1,11 +1,12 @@
 # Engineer MCP
 
+[![CI](https://github.com/DanielCuevas1208/engineer-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/DanielCuevas1208/engineer-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
 [![Node](https://img.shields.io/badge/Node-%3E%3D22.13-brightgreen.svg)](package.json)
 
 Engineer MCP is a Model Context Protocol server for mechanical-engineering calculations.
-It gives coding agents verified answers for beams, bolts, shafts, bearings, stress, sections, and units.
+It gives coding agents verified answers for beams, bolts, springs, shafts, bearings, stress, sections, and units.
 Every result shows the formula, the method, and the source.
 
 ## What it provides
@@ -18,6 +19,7 @@ The release covers these domains:
 
 - Beam bending stress and deflection.
 - Bolt tensile design to ISO 898.
+- Helical compression spring design.
 - Shaft torsion and first critical speed.
 - Bearing rating life to ISO 281.
 - von Mises equivalent stress.
@@ -47,6 +49,7 @@ Warnings surface when a method uses an approximation.
 | `beam_bending` | Bending stress, deflection, and safety factor. |
 | `section_properties` | Area, inertia, and section modulus of a shape. |
 | `bolt_strength` | Stress area, preload, and capacity of a bolt. |
+| `spring_design` | Spring rate, shear stress, and safety factor of a compression spring. |
 | `shaft_analysis` | Torsion stress, twist, and critical speed. |
 | `bearing_life` | ISO 281 rating life in revolutions and hours. |
 | `von_mises` | Equivalent stress and yield safety factor. |
@@ -124,6 +127,26 @@ References:
   - Mechanics of Materials (Euler-Bernoulli beam theory)
 ```
 
+A call to `spring_design` for a steel spring under 2 kN with squared and ground ends:
+
+```text
+Spring index                              5
+Wahl factor                            1.31
+Total coils                               6
+Solid height                             48 mm
+Spring rate                           158.6 N/mm
+Deflection at load                    12.61 mm
+Working length                        77.39 mm
+Maximum shear stress                  521.4 MPa
+Spring safety factor                  1.342
+
+Method: Helical compression spring design
+Formula: C = D/d, K_w = (4C-1)/(4C-4) + 0.615/C, tau = K_w 8FD/(pi d^3), k = G d^4/(8 D^3 Na), delta = F/k, Ls = d Nt
+References:
+  - Shigley's Mechanical Engineering Design (Tenth edition, 2015)
+  - Machinery's Handbook (Thirty-first edition)
+```
+
 A call to `unit_convert` with a torque-to-energy request fails safely:
 
 ```text
@@ -146,9 +169,9 @@ Use a unit of the same quantity.
 The test suite is deterministic and offline.
 It covers the engines, the unit layer, the database, and the tools.
 
-- 73 tests across 9 files.
+- 98 tests across 10 files.
 - All tests pass on Node 22 and Node 24.
-- The CI workflow runs typecheck, tests, build, and demo.
+- The CI workflow runs typecheck, tests, build, demo, and a package check.
 
 Run `npm test` to reproduce the results.
 
@@ -159,6 +182,8 @@ Run `npm test` to reproduce the results.
 - The bolt tables cover coarse metric threads from M5 to M36.
 - The bearing factors are typical values for deep-groove ball bearings.
 - The critical speed is a first-mode approximation.
+- The spring design covers static round-wire springs only.
+  It does not estimate fatigue life for cyclic loads.
 - The built-in SQLite module of Node.js is still experimental.
 
 Check the cited sources for exact values.
@@ -168,10 +193,18 @@ Check the cited sources for exact values.
 The server grows in independent releases.
 Each release stays useful on its own.
 
+### Complete
+
+- Helical compression spring design.
+  The `spring_design` tool reports the spring rate, the shear stress, and the safety factor.
+
+### Remaining
+
 - Add fatigue analysis for cyclic loads.
-- Add press-fit and spring calculators.
-- Add more unit categories.
+- Add press-fit and interference-fit calculators.
+- Add more unit categories, including viscosity and thermal conductivity.
 - Add HTTP transport.
+- Add a catalog of ISO and DIN standard sections.
 
 See [docs/integration.md](docs/integration.md) for the EngineerKit plan.
 

docs/integration.md

@@ -38,9 +38,14 @@ This server follows semantic versioning. Breaking a tool signature or the result
 
 Engineer MCP grows in independent releases. Each release stays useful on its own.
 
+### Complete
+
+- Helical compression spring design. The `spring_design` tool computes the spring rate, the shear stress, and the safety factor.
+
+### Remaining
+
 - Add fatigue analysis for cyclic loads.
 - Add press-fit and interference-fit calculators.
-- Add a spring calculator for helical compression springs.
 - Add more unit categories, including viscosity and thermal conductivity.
 - Add HTTP transport in addition to stdio.
 - Add a catalog of ISO and DIN standard sections.

docs/mcp-tools.md

@@ -76,6 +76,40 @@ Inputs:
 - `preloadFraction`: preload as a fraction of proof load. The default is `0.75`.
 - `pitchMm`: thread pitch. The default comes from the database.
 
+## spring_design
+
+Compute the geometry, spring rate, shear stress, and safety factor of a helical compression spring.
+
+The tool uses the Wahl factor for the shear stress. It follows Shigley for the coil counts and the solid height.
+
+Inputs:
+
+- `wireDiameter`: wire diameter in metres.
+- `meanDiameter`: mean coil diameter in metres.
+- `activeCoils`: number of active coils.
+- `endType`: `plain`, `plain_ground`, `squared`, or `squared_ground`. The default is `squared_ground`.
+- `freeLength`: free length in metres.
+- `load`: applied axial load in newtons. Zero checks the geometry only.
+- `shearModulus`: shear modulus in pascals.
+- `shearYieldStrength`: torsional yield strength in pascals. Enables the safety factor.
+
+Example:
+
+```json
+{
+  "wireDiameter": 0.008,
+  "meanDiameter": 0.04,
+  "activeCoils": 4,
+  "endType": "squared_ground",
+  "freeLength": 0.09,
+  "load": 2000,
+  "shearModulus": 79300000000,
+  "shearYieldStrength": 700000000
+}
+```
+
+The tool warns on a spring index below 4 or above 12. It warns when the free-length ratio risks buckling. It warns when the load compresses the spring to solid height.
+
 ## shaft_analysis
 
 Compute the torsion stress, angle of twist, and first lateral critical speed of a shaft.

examples/demo.ts

@@ -70,6 +70,7 @@ type ToolHandlers = {
   beam_bending: Handler;
   section_properties: Handler;
   bolt_strength: Handler;
+  spring_design: Handler;
   shaft_analysis: Handler;
   bearing_life: Handler;
   von_mises: Handler;
@@ -83,6 +84,7 @@ const tools: NamedHandler[] = [
   ["beam_bending", toolHandlers.beam_bending],
   ["section_properties", toolHandlers.section_properties],
   ["bolt_strength", toolHandlers.bolt_strength],
+  ["spring_design", toolHandlers.spring_design],
   ["shaft_analysis", toolHandlers.shaft_analysis],
   ["bearing_life", toolHandlers.bearing_life],
   ["von_mises", toolHandlers.von_mises],
@@ -110,6 +112,17 @@ const inputs: Array<Record<string, unknown>> = [
     axialLoad: 30000,
     outputUnits: { recommendedPreload: "kN" },
   },
+  {
+    wireDiameter: 0.008,
+    meanDiameter: 0.04,
+    activeCoils: 4,
+    endType: "squared_ground",
+    freeLength: 0.09,
+    load: 2000,
+    shearModulus: 79.3e9,
+    shearYieldStrength: 700e6,
+    outputUnits: { maxShearStress: "MPa", springRate: "N/mm", deflection: "mm", solidHeight: "mm", workingLength: "mm" },
+  },
   {
     outerDiameter: 0.05,
     length: 1.2,

package.json

@@ -1,10 +1,18 @@
 {
   "name": "@engineerkit/engineer-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for verified mechanical-engineering calculations, references, and material data.",
   "type": "module",
   "license": "MIT",
   "author": "EngineerKit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DanielCuevas1208/engineer-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DanielCuevas1208/engineer-mcp/issues"
+  },
+  "homepage": "https://github.com/DanielCuevas1208/engineer-mcp#readme",
   "engines": {
     "node": ">=22.13.0"
   },

src/engine/index.ts

@@ -3,4 +3,13 @@ export { analyzeBearing, BEARING_METHOD, equivalentLoad, type BearingInput, type
 export { analyzeBolt, BOLT_METHOD, tensileStressArea, type BoltGradeData, type BoltInput } from "./bolt.js";
 export { computeSection, SECTION_METHOD, type SectionDef, type SectionProperties } from "./sections.js";
 export { analyzeShaft, SHAFT_METHOD, type ShaftInput } from "./shaft.js";
+export {
+  analyzeSpring,
+  solidHeight,
+  SPRING_METHOD,
+  totalCoils,
+  wahlFactor,
+  type SpringEndType,
+  type SpringInput,
+} from "./spring.js";
 export { vonMises, VON_MISES_METHOD, type StressInput, type StressMode } from "./stress.js";