# Bracket analysis tools: MCP server (24-679 HW5)

An MCP server that exposes the four analytical tools from Homework 4 (second-order dynamics) and two new tools for early-stage bracket decisions. Built with the official MCP Python SDK (`mcp` 2.x).

| Tool | Origin | What it answers |
|---|---|---|
| `mass_spring_damper_params` | HW4 | What are ωn, ζ, ωd and the poles of this mass on this spring? |
| `step_response_metrics` | HW4 | How much does it overshoot, and how long until it settles? |
| `spec_to_poles` | HW4 | What ζ, ωn and poles meet an overshoot and settling spec? |
| `pd_gain_design` | HW4 | What PD gains place the poles there, and what does the real loop do? |
| `bracket_hand_check` | New | Does a closed-form check agree with the surrogate or FEA for this bracket arm? |
| `rank_design_candidates` | New | Which candidate designs meet the goal, which is best, and why? |

Every input carries its unit in its name (`arm_length_mm`, `load_N`) and has a valid range in its JSON schema, so out-of-range values are rejected before any code runs.

## Setup

Requires Python 3.10 or newer. Node.js is only needed for the MCP Inspector.

```bash
git clone https://github.com/jackstev-edu/hw5-mcp-server.git && cd hw5-mcp-server
python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

## Run

**Scripted client (reproduces the demo transcript):**

```bash
python demo_client.py      # writes demo_transcript.md and demo_transcript.json
```

**MCP Inspector, web UI:**

```bash
npx @modelcontextprotocol/inspector python server.py
```

Open the printed URL, click Connect, then Tools → List Tools.

**MCP Inspector, CLI (reproduces inspector_log.txt):**

```bash
./inspector_demo.sh
```

**Claude Desktop or another MCP client:** add this to the client's MCP config, with absolute paths.

```json
{ "mcpServers": { "bracket-analysis-tools": {
    "command": "/abs/path/.venv/bin/python", "args": ["/abs/path/server.py"] } } }
```

## Files

- `server.py`: the server and all six tools
- `demo_client.py`: scripted MCP client used for the demo record
- `inspector_demo.sh`: the same calls through MCP Inspector's CLI
- `demo_transcript.md`, `inspector_log.txt`: recorded outputs
- `research/ai_persona_interviews.md`: HW5 Q2 persona cards and full AI interview transcripts

## Limits

The bracket tools use Euler-Bernoulli beam theory and typical handbook material values. They are for screening and for catching setup mistakes, not for sign-off. Confirm material data and run a verified simulation before acting on a result.