# Construction Job Costing Agent — MCP Server + MCP Apps

A proof-of-concept MCP (Model Context Protocol) server that provides construction job costing data and interactive visualizations for **Pacific Northwest Builders Inc.**, a fictitious general contractor.

## What This POC Proves

1. **MCP as a data backend for Copilot** — An MCP server can serve structured financial data (jobs, cost codes, change orders, cash flow) to M365 Copilot via SSE transport.
2. **MCP Apps for rich UI** — Tool responses include `ui://` resources with self-contained HTML views (SVG charts, interactive tables) that render inline in the Copilot panel.
3. **Domain-specific agent** — A declarative agent manifest gives Copilot the persona and instructions of a construction finance analyst.
4. **No external dependencies for charts** — All visualizations use inline SVG — no Chart.js, D3, or other libraries.

## Architecture

```
┌─────────────────────────────────────┐
│         M365 Copilot / Chat         │
│  (Declarative Agent: Job Cost       │
│   Analyst)                          │
└──────────────┬──────────────────────┘
               │ SSE (port 3001)
               ▼
┌─────────────────────────────────────┐
│        MCP Server (Node.js)         │
│  ┌───────────┐  ┌────────────────┐  │
│  │  tools.ts  │  │   data.ts     │  │
│  │  7 tools   │  │  6 jobs       │  │
│  │            │  │  cost codes   │  │
│  │  Handlers  │  │  change orders│  │
│  │  + UI refs │  │  cash flow    │  │
│  └───────────┘  └────────────────┘  │
│  ┌──────────────────────────────┐   │
│  │  views/ (HTML+SVG)           │   │
│  │  • job-dashboard.html        │   │
│  │  • cost-breakdown.html       │   │
│  │  • budget-vs-actual.html     │   │
│  │  • cashflow-forecast.html    │   │
│  │  • change-orders.html        │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘
```

## Setup

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Start the server
npm start
```

The server starts on **http://localhost:3001** with SSE endpoint at `/sse`.

## Tools

| Tool | Description | UI |
|------|-------------|-----|
| `query_jobs` | List all projects with summary stats | Dashboard with sparkline bars |
| `get_job_detail` | Full detail for one job (cost codes, subs, COs) | — |
| `get_cost_breakdown` | Cost by category (Labor/Materials/Equipment/Subs/Overhead) | Donut chart |
| `get_cost_code_detail` | Budget vs actual by CSI cost code | Horizontal bar chart |
| `compare_budget_vs_actual` | Cross-job budget vs actual comparison | Grouped bar chart |
| `get_cashflow_forecast` | Monthly planned vs actual vs forecast | Line chart |
| `get_change_orders` | Change orders with status filtering | Interactive table |

## Register as M365 Copilot Declarative Agent

1. Start the MCP server (`npm start`)
2. In the M365 Copilot admin or Teams Developer Portal, create a new declarative agent
3. Point it to the `declarative-agent.json` manifest in this directory
4. The manifest references `http://localhost:3001/sse` as the MCP server endpoint
5. For production, deploy the server and update the URL accordingly

## Testing in Copilot

Once registered, try these prompts:

- **"Show me a dashboard of all active projects"** → Job dashboard with cards and budget bars
- **"Which jobs are over budget?"** → Filtered list highlighting Cascade Office Tower
- **"Show the cost breakdown for the Downtown Transit Hub"** → Donut chart of cost categories
- **"What's the cash flow forecast for Cascade Office Tower?"** → Line chart with planned/actual/forecast
- **"List all pending change orders across projects"** → Interactive table filtered to Pending
- **"Compare budget vs actual for all projects"** → Grouped bar chart
- **"Give me the cost code detail for the bridge retrofit"** → Budget vs actual bars by CSI code

## Sample Data

The server includes realistic data for 6 construction projects totaling ~$113.6M in contract value:

| Project | Contract Value | Status | % Complete |
|---------|---------------|--------|------------|
| Cascade Office Tower | $12.5M | In Progress | 67% |
| Riverfront Mixed-Use Complex | $28.3M | In Progress | 35% |
| Highway 101 Bridge Retrofit | $8.7M | In Progress | 82% |
| Summit Ridge Condos Phase 2 | $15.1M | In Progress | 12% |
| Downtown Transit Hub | $45.2M | In Progress | 55% |
| Lakewood Elementary Renovation | $3.8M | In Progress | 95% |

12 change orders, 8 subcontractors, monthly cash flow data, and CSI-format cost codes per job.

## License

Internal proof-of-concept — not for production use.