# MCP PropTech — Property Maintenance Automation

A production-ready **Model Context Protocol (MCP) server** that lets a
Claude-powered agent orchestrate your full property maintenance workflow — built
on top of an existing **n8n + WhatsApp** automation system.

```
┌─────────────────────────────────────────────────────────┐
│                  Claude Agent / Desktop                  │
└────────────────────────┬────────────────────────────────┘
                         │  MCP (stdio / SSE)
┌────────────────────────▼────────────────────────────────┐
│             MCP PropTech Maintenance Server              │
│                                                         │
│  get_open_tickets   update_maintenance_status           │
│  notify_tenant      escalate_to_vendor                  │
└──────┬──────────────────────────────────┬───────────────┘
       │                                  │
┌──────▼──────┐                  ┌────────▼──────────┐
│  Ticket DB  │                  │   Integrations    │
│ (in-memory  │                  │  ┌─────────────┐  │
│  → Postgres │                  │  │  n8n        │  │
│  in prod)   │                  │  │  Webhooks   │  │
└─────────────┘                  │  ├─────────────┤  │
                                 │  │  Twilio     │  │
                                 │  │  WhatsApp   │  │
                                 │  └─────────────┘  │
                                 └───────────────────┘
```

## Tools

| Tool | Description |
|------|-------------|
| `get_open_tickets` | Query tickets filtered by status, priority, category, property |
| `update_maintenance_status` | Drive tickets through the lifecycle with audit notes |
| `notify_tenant` | Send WhatsApp messages via 5 templates (acknowledgement, scheduled, update, resolved, delay) |
| `escalate_to_vendor` | Assign vendor, trigger n8n workflow, notify tenant in one call |

## Quick start

```bash
# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Fill in ANTHROPIC_API_KEY, Twilio creds, n8n webhook URLs

# 3. Run the agent (single pass over the ticket queue)
npm run agent

# 4. Run as a daemon (checks every 5 minutes)
npm run agent:dev -- --daemon
```

## Claude Desktop integration

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "proptech-maintenance": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/MCPPropTech/src/mcp-server/index.ts"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "TWILIO_ACCOUNT_SID": "AC...",
        "TWILIO_AUTH_TOKEN": "...",
        "TWILIO_WHATSAPP_FROM": "whatsapp:+14155238886",
        "N8N_WEBHOOK_MAINTENANCE": "https://your-n8n.com/webhook/maintenance",
        "N8N_WEBHOOK_ESCALATE": "https://your-n8n.com/webhook/escalate"
      }
    }
  }
}
```

Then from Claude Desktop you can say things like:
- *"Show me all open emergency tickets"*
- *"Escalate the burst pipe in unit 3B to a plumber"*
- *"Send Marcus in 7A a WhatsApp update on his AC ticket"*

## Architecture

### MCP Server (`src/mcp-server/`)
The server runs over **stdio** (for Claude Desktop / agent SDK) and exposes the
four tools above. Swap `StdioServerTransport` for `SSEServerTransport` to serve
over HTTP for remote deployments.

### Ticket Store (`src/data/`)
An in-memory store with 6 seed tickets covering every status and priority.
Replace `TicketStore` internals with a Postgres/Supabase/Airtable adapter for
production — the tool handlers only call the store interface.

### n8n Integration (`src/integrations/n8n.ts`)
Fires webhooks to two n8n endpoints:
- **Maintenance webhook** — on every status change and tenant notification
- **Escalation webhook** — when a vendor is assigned

Your n8n workflows handle the rest: emailing vendors, updating spreadsheets,
creating calendar invites, sending owner reports.

### WhatsApp / Twilio (`src/integrations/whatsapp.ts`)
Uses the Twilio API to send WhatsApp messages. Gracefully falls back to
**simulation mode** (console logging) when credentials are not set — perfect
for demos and local development.

### Claude Agent (`src/agent/maintenance-agent.ts`)
A full agentic loop using `@anthropic-ai/sdk` that:
1. Connects to the MCP server via `StdioClientTransport`
2. Fetches available tools and converts them to the Anthropic tool format
3. Runs an agentic loop until Claude stops calling tools
4. Logs each tool call and result to the console

## Lifecycle state machine

```
open ──→ in_progress ──→ resolved ──→ closed
  │         │                ↑
  │         └──→ awaiting_tenant
  │                   │
  └──→ escalated ←────┘
           │
           └──→ in_progress / resolved
```

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | Agent only | Claude API key |
| `TWILIO_ACCOUNT_SID` | Optional | Twilio account SID for WhatsApp |
| `TWILIO_AUTH_TOKEN` | Optional | Twilio auth token |
| `TWILIO_WHATSAPP_FROM` | Optional | Sender WhatsApp number |
| `N8N_WEBHOOK_MAINTENANCE` | Optional | n8n status-change webhook URL |
| `N8N_WEBHOOK_ESCALATE` | Optional | n8n vendor escalation webhook URL |
| `N8N_API_KEY` | Optional | n8n API key (if required by your instance) |
| `VENDOR_CONTACTS` | Optional | JSON map overriding default vendor directory |
| `AGENT_INTERVAL_MS` | Optional | Daemon poll interval (default: 300000 = 5 min) |