npm package: @rashidazarang/propertyware-mcp-server
Description: The Best PropertyWare MCP Server in Existence - Enterprise-grade Model Context Protocol server with advanced features, caching, security, and monitoring
Author: Rashid Azarang
Latest version: 2.0.1

# 🏢 Enhanced PropertyWare MCP Server v2.0.0

**The Best PropertyWare MCP Server in Existence** - An enterprise-grade Model Context Protocol (MCP) server for PropertyWare API integration with advanced features, performance optimization, and production-ready reliability.

[![npm version](https://img.shields.io/npm/v/@rashidazarang/propertyware-mcp-server.svg)](https://www.npmjs.com/package/@rashidazarang/propertyware-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io)

## 🌟 Enterprise Features

### 🔐 Advanced Authentication & Security
- **Multi-Authentication Support**: API Keys, JWT tokens, OAuth2 flows
- **Encrypted Credential Storage**: AES-256 encryption for sensitive data
- **Session Management**: Secure session handling with automatic token refresh
- **Input Validation**: Comprehensive validation using Joi schemas
- **XSS & SQL Injection Protection**: Advanced threat detection patterns
- **Security Audit Logging**: Detailed security event tracking

### ⚡ High-Performance Caching
- **Multi-tier Caching**: Memory + Redis with intelligent fallback
- **Cache Warmup**: Proactive data loading for optimal performance
- **Compression**: Automatic data compression for large responses
- **Smart Invalidation**: Pattern-based cache invalidation
- **Health Monitoring**: Real-time cache performance tracking

### 🛡️ Intelligent Rate Limiting
- **Multiple Algorithms**: Token bucket, sliding window, circuit breaker
- **Adaptive Rate Limiting**: Dynamic adjustment based on API performance
- **Per-client Limits**: Individual rate limits with burst handling
- **Circuit Breaker**: Automatic recovery from API failures
- **Global Rate Management**: System-wide rate limiting controls

### 📊 Comprehensive Health Monitoring
- **System Metrics**: CPU, memory, disk usage tracking
- **API Performance**: Response times, success rates, error tracking
- **Dependency Health**: External service monitoring
- **Alert System**: Configurable thresholds and notifications
- **Detailed Reporting**: Performance analytics and insights

### 🏗️ Enhanced PropertyWare Integration
- **10 Advanced Tools**: Complete PropertyWare API coverage
- **Smart Pagination**: Intelligent page size optimization
- **Request Retry Logic**: Exponential backoff with circuit breaking
- **XML Optimization**: High-performance SOAP processing
- **Analytics Integration**: Work order insights and forecasting

## 🚀 Quick Start

### Installation

```bash
# Install via npm (recommended)
npm install @rashidazarang/propertyware-mcp-server

# Or clone and install locally
git clone https://github.com/rashidazarang/propertyware-mcp
cd propertyware-mcp
npm install
```

### Basic Configuration

Create a `.env` file with your PropertyWare credentials:

```bash
# PropertyWare API Configuration
PROPERTYWARE_BASE_URL=https://api.propertyware.com/pw/api/rest/v1
PW_USERNAME=your_propertyware_username
PW_PASSWORD=your_propertyware_password

# Optional: Advanced Features
ENABLE_CACHING=true
ENABLE_RATE_LIMIT=true
ENABLE_SECURITY=true
ENABLE_HEALTH_MONITORING=true
LOG_LEVEL=info
```

### Advanced Configuration

For production deployments, configure additional enterprise features:

```bash
# Authentication & Security
JWT_SECRET=your_jwt_secret_key_here
ENCRYPTION_KEY=your_32_character_encryption_key
MAX_FAILED_ATTEMPTS=5
LOCKOUT_DURATION=900000

# Caching (Redis)
ENABLE_REDIS=true
REDIS_URL=redis://localhost:6379
CACHE_MEMORY_TTL=300
CACHE_REDIS_TTL=3600

# Rate Limiting
RATE_LIMIT_TOKENS_PER_INTERVAL=100
RATE_LIMIT_INTERVAL=60000
RATE_LIMIT_MAX_BURST_SIZE=150

# Health Monitoring
HEALTH_CHECK_INTERVAL=30000
HEALTH_ALERT_CPU_USAGE=80
HEALTH_ALERT_MEMORY_USAGE=85

# Security
SECURITY_MAX_INPUT_LENGTH=10000
SECURITY_ALLOWED_FILE_TYPES=pdf,doc,docx,txt,jpg,jpeg,png
SECURITY_MAX_FILE_SIZE=10485760
```

## 🔧 Usage

### Standalone Server

```bash
# Start the enhanced server
npm start

# Development mode with detailed logging
npm run dev

# Production mode with optimizations
NODE_ENV=production npm start
```

### Claude Desktop Integration

Add to your Claude Desktop MCP configuration (`~/.claude/mcp.json`):

```json
{
  "mcpServers": {
    "propertyware-enhanced": {
      "command": "node",
      "args": ["/path/to/propertyware-mcp-server/index.js"],
      "env": {
        "PW_USERNAME": "your_username",
        "PW_PASSWORD": "your_password",
        "ENABLE_CACHING": "true",
        "ENABLE_RATE_LIMIT": "true",
        "ENABLE_SECURITY": "true",
        "ENABLE_HEALTH_MONITORING": "true",
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

### Docker Support

```bash
# Build the image
docker build -t propertyware-mcp-server .

# Run with environment variables
docker run -d \
  --name propertyware-mcp \
  -e PW_USERNAME=your_username \
  -e PW_PASSWORD=your_password \
  -e ENABLE_CACHING=true \
  -e REDIS_URL=redis://redis:6379 \
  propertyware-mcp-server
```

### Kubernetes Deployment

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: propertyware-mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: propertyware-mcp-server
  template:
    metadata:
      labels:
        app: propertyware-mcp-server
    spec:
      containers:
      - name: propertyware-mcp-server
        image: rashidazarang/propertyware-mcp-server:latest
        env:
        - name: PW_USERNAME
          valueFrom:
            secretKeyRef:
              name: propertyware-secrets
              key: username
        - name: PW_PASSWORD
          valueFrom:
            secretKeyRef:
              name: propertyware-secrets
              key: password
        - name: ENABLE_CACHING
          value: "true"
        - name: REDIS_URL
          value: "redis://redis-service:6379"
```

## 🛠️ Enhanced Tools Suite

Our enterprise-grade MCP server provides 10 powerful tools with advanced features, caching, and comprehensive error handling.

### 🏢 `pw_get_portfolios`
**Get portfolios with advanced filtering and caching**

```json
{
  "filters": {
    "active": true,
    "search": "downtown"
  },
  "useCache": true,
  "forceRefresh": false
}
```

**Features:**
- Smart caching with TTL
- Advanced filtering options
- Real-time data validation
- Performance metrics tracking

---

### 🏬 `pw_get_buildings`
**Get buildings with advanced filtering and pagination**

```json
{
  "portfolioId": "12345",
  "filters": {
    "active": true,
    "search": "apartment",
    "propertyType": "Residential"
  },
  "pagination": {
    "page": 1,
    "limit": 25
  },
  "useCache": true
}
```

**Features:**
- Intelligent pagination optimization
- Property type filtering
- Geographic search capabilities
- Cache management with invalidation

---

### 🔧 `pw_get_work_orders`
**Get work orders with advanced filtering, search, and analytics**

```json
{
  "portfolioId": "12345",
  "buildingId": "67890",
  "filters": {
    "status": "Open",
    "priority": "High",
    "category": "Plumbing",
    "dateRange": {
      "startDate": "2024-01-01",
      "endDate": "2024-12-31"
    }
  },
  "search": "leak water damage",
  "includeAnalytics": true,
  "pagination": {
    "page": 1,
    "limit": 50
  }
}
```

**Features:**
- Real-time analytics and insights
- Multi-field search capabilities
- Status and priority filtering
- Performance trend analysis

---

### 📋 `pw_get_work_order`
**Get detailed work order information with history and attachments**

```json
{
  "workOrderId": "789456",
  "includeHistory": true,
  "includeAttachments": true,
  "includeComments": true
}
```

**Features:**
- Complete work order lifecycle tracking
- Attachment management
- Comment threading
- Audit trail access

---

### ✨ `pw_create_work_order`
**Create work orders with validation and automated workflows**

```json
{
  "portfolioId": "12345",
  "buildingId": "67890",
  "location": "Unit 4B - Kitchen",
  "description": "Tenant reports dripping kitchen faucet causing water damage",
  "category": "Plumbing",
  "priority": "High",
  "requestedBy": "Jane Smith",
  "scheduledDate": "2024-01-15",
  "estimatedCost": 150.00,
  "attachments": [
    {
      "filename": "water_damage.jpg",
      "content": "base64_encoded_image_data",
      "contentType": "image/jpeg"
    }
  ],
  "autoAssign": true,
  "sendNotifications": true
}
```

**Features:**
- Automated vendor assignment
- Intelligent cost estimation
- Multi-media attachments
- Notification workflows

---

### 🔄 `pw_update_work_order`
**Update work orders with change tracking and notifications**

```json
{
  "workOrderId": "789456",
  "updates": {
    "status": "Completed",
    "priority": "Normal",
    "completionNotes": "Faucet replaced, tested for leaks",
    "actualCost": 125.00,
    "completedDate": "2024-01-16"
  },
  "comment": "Work completed successfully, tenant satisfied",
  "sendNotifications": true,
  "trackChanges": true
}
```

**Features:**
- Comprehensive change tracking
- Automated notifications
- Cost variance analysis
- Completion documentation

---

### 🏠 `pw_get_leases`
**Get lease information with tenant details and payment history**

```json
{
  "portfolioId": "12345",
  "buildingId": "67890",
  "filters": {
    "status": "Active",
    "leaseType": "Residential",
    "dateRange": {
      "startDate": "2024-01-01",
      "endDate": "2024-12-31"
    }
  },
  "includeTenants": true,
  "includePaymentHistory": true,
  "pagination": {
    "page": 1,
    "limit": 30
  }
}
```

**Features:**
- Tenant relationship management
- Payment history tracking
- Lease performance analytics
- Renewal opportunity identification

---

### 🩺 `pw_test_connection`
**Test PropertyWare API connection with detailed diagnostics**

```json
{
  "includePerformanceTest": true,
  "testEndpoints": true,
  "generateReport": true
}
```

**Features:**
- Comprehensive connectivity testing
- Performance benchmarking
- Endpoint health verification
- Detailed diagnostic reporting

---

### 📊 `pw_get_analytics`
**Get PropertyWare analytics and insights**

```json
{
  "portfolioId": "12345",
  "metric": "work_orders",
  "timeframe": "month",
  "includeComparisons": true,
  "includeForecasts": true
}
```

**Metrics Available:**
- `work_orders`: Work order volume and trends
- `maintenance_costs`: Cost analysis and budgeting
- `response_times`: Service performance metrics
- `vendor_performance`: Contractor efficiency analysis
- `occupancy`: Property utilization rates

**Features:**
- Predictive analytics
- Comparative analysis
- Trend forecasting
- Performance KPIs

---

### 🏥 `pw_health_check`
**Get comprehensive health status of the MCP server**

```json
{
  "includeMetrics": true,
  "includeAlerts": true,
  "includeDependencies": true,
  "timeframe": 3600000
}
```

**Features:**
- Real-time system monitoring
- Performance metrics
- Alert management
- Dependency health tracking

## 🏗️ Architecture & Performance

### Enterprise Architecture
- **Microservices Ready**: Scalable, modular design
- **Cloud Native**: Docker and Kubernetes support
- **High Availability**: Circuit breakers and failover mechanisms
- **Observability**: Comprehensive monitoring and logging

### Performance Optimizations
- **Connection Pooling**: Efficient resource management
- **Request Batching**: Optimized API call patterns
- **Intelligent Caching**: Multi-tier caching strategy
- **Async Processing**: Non-blocking operations

### PropertyWare API Integration
- **Base URL**: `https://api.propertyware.com/pw/api/rest/v1`
- **Authentication**: Enhanced multi-method authentication
- **Format**: Optimized SOAP/XML processing
- **Retry Logic**: Exponential backoff with circuit breaking
- **Rate Limiting**: Intelligent API usage management

## 🛡️ Enterprise Security

### Security Features
- **Multi-factor Authentication**: Enhanced credential management
- **Encryption**: AES-256 for sensitive data storage
- **Input Validation**: Comprehensive Joi schema validation
- **Threat Protection**: XSS, SQL injection, and CSRF protection
- **Audit Logging**: Detailed security event tracking
- **Session Management**: Secure token handling with auto-refresh

### Compliance & Standards
- **SOC 2 Type II Ready**: Enterprise security controls
- **GDPR Compliant**: Privacy-first data handling
- **ISO 27001 Aligned**: Information security management
- **OWASP Top 10**: Protection against common vulnerabilities

## 📊 Monitoring & Analytics

### Health Monitoring
- **Real-time Metrics**: CPU, memory, disk, network usage
- **API Performance**: Response times, success rates, error tracking
- **Dependency Health**: External service monitoring
- **Alert System**: Configurable thresholds and notifications

### Performance Analytics
- **Request Tracking**: Detailed request lifecycle monitoring
- **Cache Performance**: Hit rates, miss analysis, optimization suggestions
- **Rate Limit Analytics**: Usage patterns and optimization recommendations
- **Security Events**: Threat detection and response metrics

## 🚀 Production Deployment

### Infrastructure Requirements
- **Node.js**: v18+ (LTS recommended)
- **Memory**: Minimum 512MB, recommended 2GB+
- **CPU**: 1+ cores, 2+ cores for high throughput
- **Redis**: Optional but recommended for caching
- **Monitoring**: Prometheus, Grafana, or similar

### Scaling Guidelines
- **Horizontal Scaling**: Multiple server instances with load balancing
- **Vertical Scaling**: Increase memory and CPU as needed
- **Cache Scaling**: Redis cluster for high-availability caching
- **Database Scaling**: Connection pooling and read replicas

### Environment Variables Reference

| Variable | Default | Description |
|----------|---------|-------------|
| `PROPERTYWARE_BASE_URL` | - | PropertyWare API base URL |
| `PW_USERNAME` | - | PropertyWare username (required) |
| `PW_PASSWORD` | - | PropertyWare password (required) |
| `ENABLE_CACHING` | `true` | Enable multi-tier caching |
| `ENABLE_RATE_LIMIT` | `true` | Enable intelligent rate limiting |
| `ENABLE_SECURITY` | `true` | Enable security features |
| `ENABLE_HEALTH_MONITORING` | `true` | Enable health monitoring |
| `LOG_LEVEL` | `info` | Logging level (error, warn, info, debug) |
| `JWT_SECRET` | - | JWT secret for token signing |
| `ENCRYPTION_KEY` | - | 32-character key for data encryption |
| `REDIS_URL` | - | Redis connection URL |
| `RATE_LIMIT_TOKENS_PER_INTERVAL` | `100` | Rate limit tokens per interval |
| `HEALTH_CHECK_INTERVAL` | `30000` | Health check interval (ms) |

## 📚 Examples & Use Cases

### Real Estate Portfolio Management
```javascript
// Get portfolio overview with analytics
const portfolios = await tools.pw_get_portfolios({
  filters: { active: true },
  useCache: true
});

// Get work orders with performance analytics
const workOrders = await tools.pw_get_work_orders({
  portfolioId: "12345",
  includeAnalytics: true,
  filters: {
    status: "Open",
    priority: "High"
  }
});
```

### Maintenance Management Workflow
```javascript
// Create emergency work order
const workOrder = await tools.pw_create_work_order({
  portfolioId: "12345",
  buildingId: "67890",
  location: "Unit 4B - Kitchen",
  description: "Emergency: Water leak causing damage",
  priority: "Emergency",
  autoAssign: true,
  sendNotifications: true
});

// Track completion
const update = await tools.pw_update_work_order({
  workOrderId: workOrder.workOrderId,
  updates: { status: "Completed" },
  comment: "Leak repaired, damage assessed"
});
```

### Analytics & Reporting
```javascript
// Get maintenance cost analytics
const analytics = await tools.pw_get_analytics({
  metric: "maintenance_costs",
  timeframe: "quarter",
  includeComparisons: true,
  includeForecasts: true
});

// Health check and performance monitoring
const health = await tools.pw_health_check({
  includeMetrics: true,
  includeAlerts: true,
  timeframe: 3600000
});
```

## 🤝 Contributing

We welcome contributions! Please read our [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).

### Development Setup
```bash
# Clone the repository
git clone https://github.com/rashidazarang/propertyware-mcp
cd propertyware-mcp

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with your credentials

# Run tests
npm test

# Start development server
npm run dev
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

Built on the proven PropertyWare integration from the GreenLight Property Management platform, successfully managing:
- 870+ work orders with advanced pagination
- Real-time property data synchronization
- Enterprise-grade error recovery
- Production-scale reliability

## 📞 Support

- **Documentation**: [Full API Documentation](https://docs.propertyware-mcp.com)
- **Issues**: [GitHub Issues](https://github.com/rashidazarang/propertyware-mcp/issues)
- **Community**: [Discord Server](https://discord.gg/propertyware-mcp)
- **Enterprise Support**: contact@rashidazarang.com

---

**Made with ❤️ by [Rashid Azarang](https://github.com/rashidazarang)**

*The Best PropertyWare MCP Server in Existence* 🏆