# Construction Supervision MCP Server

A specialized, local Model Context Protocol (MCP) server providing construction-supervision tools for small-to-medium building projects:
- Houses
- Small buildings
- Offices
- Commercial spaces

Built in **Python 3.12** following the standard MCP specifications and **JSON-RPC 2.0 directly over standard input and standard output (`stdio`)**, without using any third-party MCP SDK or server library.

---

## Features & Implemented Tools

The server implements all 5 core construction supervision tools required by the specification:

1. **`get_stage_guidance`**
   - Provides detailed guidance for any of the 9 supported construction stages and 4 project types.
   - Includes prerequisites, materials with typical quantities per m², main activities, critical supervision checkpoints, common mistakes, safety notes, and related stages.
2. **`generate_supervision_checklist`**
   - Generates actionable, prioritized (`critical`, `important`, `recommended`) inspection checklists for each stage across three project moments: `before`, `during`, and `after`.
3. **`record_project_progress`**
   - Records and updates stage progress (`not_started`, `in_progress`, `completed`, `blocked`) with notes in a local SQLite database (`project_progress.db`).
4. **`get_next_possible_stages`**
   - Evaluates recorded project status against strict domain dependency trees stored in structured JSON data (not hallucinated).
   - Identifies stages ready to start, missing prerequisites holding back progress, and suggested pre-stage verification points.
5. **`analyze_quotation`**
   - Analyzes construction material and labor line items against standard reference concepts and price ranges.
   - Detects recognized concepts, potentially missing items, duplicate entries, items priced below/within/above expected ranges, and unclassified entries.
   - Emits appropriate non-binding reference disclaimers.

---

## Supported Construction Stages

The server manages 9 defined construction stages with realistic sequence dependencies:
1. `site_preparation`
2. `foundations` (prerequisite: `site_preparation`)
3. `structural_elements` (prerequisite: `foundations`)
4. `masonry_walls` (prerequisite: `structural_elements`)
5. `electrical_installations` (prerequisite: `masonry_walls`)
6. `plumbing_installations` (prerequisite: `masonry_walls`)
7. `plastering_and_finishes` (prerequisites: `masonry_walls`, `electrical_installations`, `plumbing_installations`)
8. `flooring_and_cladding` (prerequisite: `plastering_and_finishes`)
9. `painting_and_handover` (prerequisite: `flooring_and_cladding`)

Supported project types:
- `house`
- `small_building`
- `office`
- `commercial_space`

---

## Installation & Prerequisites

### Prerequisites
- **Python 3.12+**
- Git

### Setup
1. Clone the repository and navigate into the folder:
   ```bash
   git clone <repository_url>
   cd construction-supervision-mcp
   ```

2. Create and activate a Python 3.12 virtual environment:
   ```bash
   # Windows PowerShell
   python -m venv .venv
   .venv\Scripts\Activate.ps1

   # Linux / macOS
   python3 -m venv .venv
   source .venv/bin/activate
   ```

3. Install the package in editable mode with development dependencies:
   ```bash
   pip install -e ".[dev]"
   ```

---

## Running the Server Locally

The server communicates via standard input (`stdin`) and standard output (`stdout`). Diagnostics are sent strictly to standard error (`stderr`).

Run directly:
```bash
python -m construction_supervision_mcp
```
Or via the installed entry-point script:
```bash
construction-supervision-mcp
```

### Environment Configuration
Optionally configure the database path via an environment variable (see `.env.example`):
```bash
# Windows PowerShell
$env:PROGRESS_DB_PATH = "my_custom_progress.db"

# Linux / macOS
export PROGRESS_DB_PATH="my_custom_progress.db"
```

---

## Configuring in an MCP Host

To use this server in an MCP host (such as Claude Desktop, Cursor, or custom terminal chatbot hosts), add the server definition to your client's MCP configuration JSON.

### Claude Desktop Configuration Example
Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "construction-supervision": {
      "command": "C:\\path\\to\\construction-supervision-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "construction_supervision_mcp"
      ],
      "env": {
        "PROGRESS_DB_PATH": "C:\\path\\to\\construction-supervision-mcp\\project_progress.db"
      }
    }
  }
}
```

---

## Tool Specifications & Parameters

### 1. `get_stage_guidance`
Returns domain knowledge and specifications for a construction stage.

- **Parameters:**
  - `stage_id` (string, required): One of the 9 supported stage identifiers.
  - `project_type` (string, required): One of `house`, `small_building`, `office`, `commercial_space`.
- **Result Schema:**
  - Object containing `id`, `name`, `description`, `project_types`, `prerequisites`, `materials`, `activities`, `supervision_points`, `common_mistakes`, `safety_notes`, and `related_stages`.

### 2. `generate_supervision_checklist`
Generates a checklist for site inspection.

- **Parameters:**
  - `stage_id` (string, required): Stage identifier.
  - `moment` (string, required): `"before"`, `"during"`, or `"after"`.
- **Result Schema:**
  - Object containing `stage_id`, `stage_name`, `moment`, and `items` (array of objects with `item`, `priority`, and `explanation`).

### 3. `record_project_progress`
Saves or updates the progress state for a stage in SQLite.

- **Parameters:**
  - `project_id` (string, required): Unique project identifier.
  - `stage_id` (string, required): Stage identifier.
  - `status` (string, required): `"not_started"`, `"in_progress"`, `"completed"`, or `"blocked"`.
  - `notes` (string, optional): Notes on progress or inspection findings.
- **Result Schema:**
  - Object confirming `project_id`, `stage_id`, `status`, `notes`, and `updated_at` (ISO 8601 UTC timestamp).

### 4. `get_next_possible_stages`
Evaluates database stage statuses against defined dependency rules.

- **Parameters:**
  - `project_id` (string, required): Project identifier.
- **Result Schema:**
  - Object containing:
    - `completed_stages`: List of completed stage records.
    - `in_progress_stages`: List of currently in-progress stages.
    - `blocked_stages`: List of blocked stages.
    - `possible_next_stages`: Stages whose prerequisites are fully met.
    - `stages_with_missing_prerequisites`: Stages blocked by uncompleted prerequisites.
    - `suggested_verifications`: Checkpoints to verify before beginning upcoming stages.

### 5. `analyze_quotation`
Analyzes quotation line items against reference concepts and price brackets.

- **Parameters:**
  - `project_type` (string, required): Project type.
  - `work_category` (string, required): Category matching one of the construction stages.
  - `items` (array, required): Array of item objects, each containing:
    - `description` (string)
    - `unit` (string)
    - `quantity` (number)
    - `unit_price` (number, in Guatemalan Quetzales [GTQ])
- **Result Schema:**
  - Object containing:
    - `project_type`: Project type identifier.
    - `work_category`: Work category identifier.
    - `reference_currency`: Reference currency code (`"GTQ"`).
    - `recognized_items`: Matched items with `reference_range` (in GTQ) and `price_status` (`below_range`, `within_range`, `above_range`).
    - `potentially_missing_concepts`: Standard concepts not found in quotation.
    - `potentially_duplicated_concepts`: Reference concepts matched by multiple items.
    - `unclassified_items`: Items that could not be matched with reference keywords.
    - `observations`: Summary findings.
    - `disclaimer`: Reference pricing notice.

---

## Example JSON-RPC Exchanges

### 1. Initialize Handshake
**Request:**
```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}
```
**Response:**
```json
{"jsonrpc":"2.0","result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"construction-supervision-mcp","version":"0.1.0"}},"id":1}
```

### 2. Initialized Notification
**Notification:**
```json
{"jsonrpc":"2.0","method":"notifications/initialized"}
```
*(No response emitted)*

### 3. List Tools
**Request:**
```json
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
```
**Response:**
```json
{"jsonrpc":"2.0","result":{"tools":[{"name":"get_stage_guidance",...}]},"id":2}
```

### 4. Call Tool (`record_project_progress`)
**Request:**
```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"record_project_progress","arguments":{"project_id":"house-01","stage_id":"site_preparation","status":"completed","notes":"Clearing finished"}}}
```
**Response:**
```json
{"jsonrpc":"2.0","result":{"content":[{"type":"text","text":"{\"project_id\":\"house-01\",\"stage_id\":\"site_preparation\",\"status\":\"completed\",\"notes\":\"Clearing finished\",\"updated_at\":\"...\"}"}]},"id":3}
```

---

## Testing

Run the automated test suite using `pytest`:
```bash
pytest -v
```

The test suite covers:
- JSON-RPC 2.0 protocol message validation, parsing, errors, and serialization (`test_protocol.py`).
- MCP lifecycle methods: `initialize`, `notifications/initialized`, `tools/list`, and unknown method handling (`test_server_lifecycle.py`).
- All five tools with valid inputs, invalid parameters, unknown stages, and quotation edge cases (`test_tools.py`).
- SQLite persistence validation and prerequisite sequence dependency verification.
- End-to-end `stdio` streaming test ensuring `stdout` contains strictly valid JSON-RPC lines without diagnostic pollution (`test_stdio_e2e.py`).

---

## Price-Reference Disclaimer & Limitations

> [!WARNING]
> Reference price ranges and standard concepts provided by this server are based on typical construction estimates in Guatemalan Quetzales (GTQ) for academic course demonstration purposes only. They do not represent real-time market prices or vendor quotes. Actual construction costs vary substantially depending on local labor rates, material quality, geographical location, site topography, supplier relationships, inflation, and seasonal conditions.
>
> This tool does not provide legal, financial, architectural, or structural engineering certification or warranty.