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.

Related MCP server: Kolmo Construction

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:

   git clone <repository_url>
   cd construction-supervision-mcp

2. Create and activate a Python 3.12 virtual environment:

   # 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:

   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:

python -m construction_supervision_mcp

Or via the installed entry-point script:

construction-supervision-mcp

Environment Configuration

Optionally configure the database path via an environment variable (see .env.example):

# 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:

{
  "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:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}

Response:

{"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:

{"jsonrpc":"2.0","method":"notifications/initialized"}

(No response emitted)

3. List Tools

Request:

{"jsonrpc":"2.0","id":2,"method":"tools/list"}

Response:

{"jsonrpc":"2.0","result":{"tools":[{"name":"get_stage_guidance",...}]},"id":2}

4. Call Tool (record_project_progress)

Request:

{"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:

{"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:

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