# Iron Bridge Construction — MCP Equipment Safety Server

## Company & Problem

**Iron Bridge Construction** manages heavy equipment (cranes, excavators, scaffolding) across multiple job sites.  
Before this system, site workers used paper checklists. Nothing stopped an uncertified operator from taking a crane, and nothing forced a human supervisor sign-off when the work was near power lines.

**The fix:** an MCP server that gives an LLM *scoped, safe* access to equipment data. The model never talks to the database directly. Every write that carries real risk is gated by capability checks, role changes, elicitation, and sampling.

## Protocol Concerns Mapping

| # | Concern | How it appears in this system |
|---|---------|-------------------------------|
| 1 | Capability negotiation | Server declares `elicitation` + `sampling`. Client checks before offering high-risk tools. |
| 2 | Notifications | Worker starts with read-only tools. After `authenticate_supervisor`, server pushes `tools/list_changed` and approval tools appear. |
| 3 | Elicitation | `request_equipment` for high-risk items (crane / near power lines) pauses mid-call and asks a human supervisor for explicit confirmation. |
| 4 | Resources | Safety policies (`lifting-safety`, `electrical-proximity`) are exposed as resources, not tools. |
| 5 | Prompts | Reusable template `prepare-equipment-receipt` that takes `{request_id}`. |
| 6 | Sampling | Before final approval of a high-risk request the server asks the *client's* model to draft a short risk summary; result is stored in audit log. |
| 7 | Progress tracking | `generate_site_compliance_report` walks every request and reports 25/50/75/100 %. |
| 8 | Defensive tool design | Strict JSON Schema (`additionalProperties: false`), server-side `jsonschema` validation, parameterized SQL, and handler-level authorization. |

## Transport

- **Development:** stdio (default).
- **Demo / multi-site:** Streamable HTTP (`MCP_TRANSPORT=streamable-http`).

Commit history shows the transition from stdio-only to HTTP support.

## Quick Start

```bash
python -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\Activate.ps1 on Windows
pip install -r requirements.txt
python db/init_db.py
python agent/client.py      # starts stdio server automatically
```

HTTP mode:

```bash
export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=8000
python -m mcp_server.server
# endpoint: http://127.0.0.1:8000/mcp
```

## Tool Comparison

| Tool | Read/Write | Needs elicitation? | Needs sampling? | Notes |
|------|------------|--------------------|-----------------|-------|
| `check_worker_certification` | read | no | no | always available |
| `get_equipment_status` | read | no | no | always available |
| `request_equipment` | write | **yes** if high-risk | **yes** if high-risk | creates PENDING request |
| `authenticate_supervisor` | write (session) | no | no | triggers `tools/list_changed` |
| `approve_equipment_request` | write | no | no | only after supervisor auth |
| `generate_site_compliance_report` | read (report) | no | no | progress updates |

If a client connects without `elicitation` or `sampling` capability, high-risk requests return `NOT_SUBMITTED` and nothing is written to the database.

## Folder Layout

```
db/                 schema, seed, ERD, init script
mcp_server/         server, schemas, service layer, database helpers
agent/              demo client that performs the full handshake
docs/               progressive code parts for team commits
issues/             ready-to-paste GitHub Issue bodies (one per concern)
```

## Team Workflow (4 sequential parts per concern)

See `docs/` and `issues/`. Each concern is an independent GitHub Issue.  
Code for each concern is delivered in 4 progressive commits so every teammate has a visible contribution.