Construction Job Costing Agent

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

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