Appraisal Firewall MCP Server

A Model Context Protocol (MCP) server that provides access to the Appraisal Firewall API for appraisal ordering and management.

Features

• Order Creation: Create residential and commercial appraisal orders
• Messaging: Send messages to appraisers through the platform
• Order Management: Retrieve order details and status
• Webhook Support: Receive real-time updates from Appraisal Firewall
• Demo Mode: Test endpoints with mock responses

Installation

1. Clone or download the server files
2. Install dependencies:

   npm install

3. Configure environment variables (see Configuration section)
4. Start the server:

   npm start

Configuration

Set up your environment variables. You can either:

1. Use environment variables:

   export AF_API_KEY="your_api_key"
   export AF_API_SECRET="your_api_secret"
   export AF_BASE_URL="https://uat.appraisalfirewall.com/api"
   export AF_ENVIRONMENT="UAT"

2. Use a .env file:

   AF_API_KEY=your_api_key
   AF_API_SECRET=your_api_secret
   AF_BASE_URL=https://uat.appraisalfirewall.com/api
   AF_ENVIRONMENT=UAT

API Endpoints

Core Functionality

• POST /api/create-residential - Create residential appraisal order
• POST /api/create-commercial - Create commercial appraisal order
• POST /api/message - Send message to appraiser
• GET /api/order/:losuniqueid - Get order details
• POST /api/webhook - Receive updates from Appraisal Firewall

Management

• GET / - Server info and available endpoints
• GET /health - Health check
• GET /api/info - Configuration and status info

Demo/Testing

• GET /test - Demo endpoints overview
• POST /test/create-residential - Demo residential order creation
• POST /test/create-commercial - Demo commercial order creation
• POST /test/message - Demo message sending
• GET /test/order/:losuniqueid - Demo order details

Usage Examples

Create Residential Appraisal Order

curl -X POST https://your-server.railway.app/api/create-residential \
  -H "Content-Type: application/json" \
  -d '{
    "originatoremail": "originator@company.com",
    "webhookurl": "https://your-server.railway.app/api/webhook",
    "losuniqueid": "LOS123456",
    "property": {
      "street": "123 Main St",
      "city": "Post Falls",
      "zip": "83854",
      "state": "ID",
      "county": "Kootenai"
    },
    "borrower": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "john@doe.com"
    },
    "saleprice": 555555,
    "loannumber": "12341234",
    "loantype": "Purchase",
    "daterequired": "04/28/2024"
  }'

Create Commercial Appraisal Order

curl -X POST https://your-server.railway.app/api/create-commercial \
  -H "Content-Type: application/json" \
  -d '{
    "originatoremail": "originator@company.com",
    "webhookurl": "https://your-server.railway.app/api/webhook",
    "losuniqueid": "LOS789012",
    "borrower": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "john@doe.com"
    },
    "loannumber": "1234",
    "salesprice": "1250000",
    "property": {
      "street": "1234 W. Main St.",
      "city": "Spokane",
      "state": "WA",
      "zip": "99016",
      "county": "Spokane"
    },
    "commercialdata": {
      "propertytype": "Office Building",
      "size": "25000 sq ft",
      "reporttype": "Summary",
      "valueapproachcost": true,
      "valueapproachincome": false,
      "valueapproachsales": true,
      "propertyinterest": "Fee Simple"
    }
  }'

Send Message to Appraiser

curl -X POST https://your-server.railway.app/api/message \
  -H "Content-Type: application/json" \
  -d '{
    "losuniqueid": "LOS123456",
    "message": "Please expedite this appraisal order"
  }'

Get Order Details

curl https://your-server.railway.app/api/order/LOS123456

Demo Mode

Test the functionality without real API credentials:

# Demo residential order
curl -X POST https://your-server.railway.app/test/create-residential \
  -H "Content-Type: application/json" \
  -d '{
    "property": {
      "street": "123 Demo St",
      "city": "Test City",
      "state": "ID",
      "zip": "83854"
    },
    "borrower": {
      "firstname": "Demo",
      "lastname": "User"
    },
    "saleprice": 350000
  }'

Webhook Handling

The server includes a webhook endpoint at /api/webhook that receives updates from Appraisal Firewall. Webhook payloads include:

• Order status updates (statusset)
• Messages from appraisers (message)
• Attachments and documents (attachment)
• Billing information (billing)

Example webhook payload:

{
  "losuniqueid": "LOS123456",
  "kind": "statusset",
  "logdate": "12/14/2021 21:00:32",
  "comment": "Accepted by the appraiser",
  "datedelivered": "12/14/2021 21:00:32",
  "fromkind": "Appraiser",
  "attachments": [
    {
      "kind": "appraisal",
      "filename": "appraisal_report.pdf",
      "url": "https://download-url.com/file"
    }
  ]
}

Data Structures

Residential Order Classification

The residential order supports various property classifications:

• waterfront - Waterfront property
• manufactured - Manufactured home
• singlefamily - Single family home
• condo - Condominium
• twofour - 2-4 unit property
• fha - FHA loan
• va - VA loan
• usda - USDA loan
• jumbo - Jumbo loan
• rush - Rush order
• complex - Complex property

Commercial Data

For commercial appraisals:

• propertytype - Type of commercial property
• size - Property size
• reporttype - Type of appraisal report
• valueapproachcost - Include cost approach
• valueapproachincome - Include income approach
• valueapproachsales - Include sales approach
• propertyinterest - Property interest type

Environment Configuration

UAT (Testing) Environment

AF_ENVIRONMENT=UAT
AF_BASE_URL=https://uat.appraisalfirewall.com/api
AF_API_KEY=your_uat_api_key
AF_API_SECRET=your_uat_api_secret

Production Environment

AF_ENVIRONMENT=Production
AF_BASE_URL=https://api.appraisalfirewall.com
AF_API_KEY=your_prod_api_key
AF_API_SECRET=your_prod_api_secret

Error Handling

The server handles common API errors:

• Authentication errors - Invalid API key/secret
• Validation errors - Missing required fields
• Network errors - Connection issues with Appraisal Firewall

All errors are returned with descriptive messages to help with debugging.

Deployment

Railway Deployment

1. Create new Railway project
2. Connect your repository
3. Set environment variables in Railway dashboard
4. Deploy

Environment Variables for Production

NODE_ENV=production
AF_ENVIRONMENT=Production
AF_API_KEY=your_production_api_key
AF_API_SECRET=your_production_api_secret
AF_BASE_URL=https://api.appraisalfirewall.com
PORT=3000

Support

For Appraisal Firewall API issues, contact their support team.

For server issues:

• Check environment variables are set correctly
• Verify API credentials are valid
• Check network connectivity to Appraisal Firewall API
• Review server logs for detailed error information

Security Notes

• Never commit API credentials to version control
• Use environment variables for all sensitive configuration
• Validate webhook payloads in production
• Consider implementing additional authentication for public deployments
• Monitor API usage to prevent abuse

Integration Workflows

Basic Workflow

1. Create appraisal order (residential or commercial)
2. Monitor webhook for status updates
3. Send messages to appraiser as needed
4. Receive completed appraisal via webhook

Advanced Workflow

1. Create order with specific requirements
2. Upload additional documents
3. Track order progress via webhooks
4. Handle appraiser communications
5. Process completed deliverables
6. Handle billing notifications