npm package: @rashidazarang/aptly-property-management-mcp
Description: Advanced Model Context Protocol server for Aptly Property Management with bulk operations, real-time webhooks, workflow automation, and intelligent search capabilities
Author: Rashid Azarang
Latest version: 2.0.0

# Aptly Property Management MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Aptly Property Management platform for comprehensive property workflow management.

## Features

🏠 **Property Management Integration** - Complete integration with Aptly's property management platform  
📋 **Work Order Management** - Create, update, search, and manage work orders (cards)  
💬 **Comments & Communication** - Add comments and notes to work orders  
📎 **File Attachments** - Upload and manage files attached to work orders  
🔄 **System Integrations** - Sync with property management systems like Propertyware, Yardi, RealPage  
📊 **Analytics & Reporting** - Generate comprehensive property management reports  
🛡️ **Enterprise Security** - Secure API authentication and data validation  

## Installation

```bash
npm install @rashidazarang/aptly-property-management-mcp
```

## Quick Start

### Environment Setup

Set your Aptly API token:

```bash
export APTLY_API_TOKEN="your-aptly-api-token"
export APTLY_BASE_URL="https://api.getaptly.com"  # Optional
```

### Using with Claude Desktop

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "aptly-property-management": {
      "command": "npx",
      "args": ["@rashidazarang/aptly-property-management-mcp"],
      "env": {
        "APTLY_API_TOKEN": "your-aptly-api-token"
      }
    }
  }
}
```

### Using with MCP Client

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['@rashidazarang/aptly-property-management-mcp'],
  env: {
    APTLY_API_TOKEN: 'your-aptly-api-token'
  }
});

const client = new Client(
  {
    name: 'aptly-client',
    version: '1.0.0',
  },
  {
    capabilities: {},
  }
);

await client.connect(transport);
```

## Available Tools

### Connection & Setup
- `aptly_test_connection` - Test API connection
- `aptly_get_boards` - Get all accessible boards

### Work Order Management
- `aptly_get_cards` - Get cards from a board with filters
- `aptly_create_card` - Create new work order
- `aptly_update_card` - Update existing work order
- `aptly_delete_card` - Delete work order
- `aptly_search_cards` - Search across all work orders

### Communication
- `aptly_get_comments` - Get comments for a work order
- `aptly_add_comment` - Add comment to work order

### File Management
- `aptly_get_files` - Get file attachments
- `aptly_upload_file` - Upload file to work order

### System Integration
- `aptly_get_integrations` - List available integrations
- `aptly_sync_integration` - Trigger sync with PM systems

### Analytics
- `aptly_generate_report` - Generate property management reports

## Available Resources

### Boards
- `aptly://boards` - List all boards
- `aptly://board/{id}` - Specific board details
- `aptly://board/{id}/cards` - Cards in a board

### Cards (Work Orders)
- `aptly://card/{id}` - Specific card details
- `aptly://card/{id}/comments` - Card comments
- `aptly://card/{id}/files` - Card file attachments

### System Resources
- `aptly://integrations` - Available integrations
- `aptly://reports` - Analytics reports

## Usage Examples

### Creating Work Orders

```bash
# Using Claude Desktop with MCP
"Create a work order for broken faucet at 123 Main St, Unit 4B"
"New urgent work order: HVAC not working in Building A"
"Create maintenance request for tenant John Doe - leaky pipe in bathroom"
```

### Managing Work Orders

```bash
"Update work order WO-123 status to completed"
"Assign work order WO-456 to Mike Rodriguez" 
"Set work order WO-789 priority to urgent"
"Add comment to WO-123: Parts ordered, will repair tomorrow"
```

### Searching and Reporting

```bash
"Show me all high priority work orders"
"Find work orders for Oak Street Apartments"
"Generate monthly work order summary report"
"List all open plumbing work orders"
```

### Integration Management

```bash
"Sync data from Propertyware"
"Show available property management integrations"
"Get status of last sync operation"
```

## Tool Schemas

### Create Work Order

```json
{
  "name": "aptly_create_card",
  "arguments": {
    "boardId": "board-123",
    "title": "HVAC Repair - Unit 5B", 
    "description": "Air conditioning not cooling properly",
    "status": "new",
    "priority": "high",
    "location": {
      "street_1": "123 Main Street",
      "city": "Springfield", 
      "state": "IL",
      "zip_code": "62701",
      "unit_number": "5B"
    },
    "tenant_info": {
      "name": "Jennifer Adams",
      "phone": "555-0123",
      "email": "j.adams@email.com"
    },
    "custom_fields": {
      "work_order_type": "hvac",
      "estimated_hours": 2
    }
  }
}
```

### Search Work Orders

```json
{
  "name": "aptly_search_cards",
  "arguments": {
    "query": "broken faucet",
    "status": "open",
    "priority": "high",
    "date_from": "2024-01-01",
    "limit": 20
  }
}
```

### Generate Report

```json
{
  "name": "aptly_generate_report", 
  "arguments": {
    "report_type": "work_orders",
    "date_from": "2024-01-01",
    "date_to": "2024-01-31",
    "filters": {
      "status": ["completed", "in_progress"]
    }
  }
}
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `APTLY_API_TOKEN` | Your Aptly API token | Required |
| `APTLY_BASE_URL` | Aptly API base URL | `https://api.getaptly.com` |
| `APTLY_TIMEOUT` | Request timeout (ms) | `30000` |

### Getting Your API Token

1. Log into your Aptly Property Management account
2. Navigate to Settings → API Settings
3. Generate a new API token
4. Copy the token and set it as `APTLY_API_TOKEN`

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/rashidazarang/aptly-property-management-mcp.git
cd aptly-property-management-mcp

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your configuration

# Build the project
npm run build

# Run tests
APTLY_API_TOKEN=your-token npm test

# Start the MCP server
npm start
```

### Testing

```bash
# Run connection test
APTLY_API_TOKEN=your-token npm test

# Run with test card creation
APTLY_API_TOKEN=your-token npm test -- --create-test-card

# Run type checking
npm run type-check

# Run linting
npm run lint
```

## Error Handling

The MCP server provides comprehensive error handling:

- **Authentication Errors** - Invalid or expired API tokens
- **Rate Limiting** - Automatic rate limit handling with retries
- **Validation Errors** - Input validation with helpful error messages
- **Network Errors** - Connection and timeout handling
- **API Errors** - Aptly API error responses with context

## Security

- All API communication uses HTTPS
- API tokens are securely managed through environment variables
- Input validation prevents injection attacks
- Rate limiting prevents API abuse
- No sensitive data is logged

## Property Management Integrations

Supported property management systems:

- **Propertyware** - Full bi-directional sync
- **Yardi** - Work order and tenant sync
- **RealPage** - Maintenance workflow integration
- **AppFolio** - Basic work order sync
- **Rent Manager** - Tenant and property sync

## Troubleshooting

### Common Issues

1. **Authentication Failed**
   ```bash
   Error: Authentication failed - invalid API token
   ```
   - Verify your API token is correct
   - Check token hasn't expired
   - Ensure token has required permissions

2. **Rate Limit Exceeded**
   ```bash
   Error: Rate limit exceeded
   ```
   - The server automatically handles rate limits
   - Reduce request frequency if needed

3. **Board Not Found**
   ```bash
   Error: Board not found
   ```
   - Verify board ID is correct
   - Check you have access to the board
   - Use `aptly_get_boards` to list available boards

### Debug Mode

Set `LOG_LEVEL=DEBUG` for detailed logging:

```bash
LOG_LEVEL=DEBUG APTLY_API_TOKEN=your-token npm start
```

## Support

- 📖 [Documentation](https://github.com/rashidazarang/aptly-property-management-mcp/wiki)
- 🐛 [Issue Tracker](https://github.com/rashidazarang/aptly-property-management-mcp/issues)
- 💬 [Discussions](https://github.com/rashidazarang/aptly-property-management-mcp/discussions)
- 📧 [Email Support](mailto:rashidazarang@gmail.com)

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

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

## Changelog

### v1.0.0
- Initial release
- Complete Aptly API integration
- Full MCP compliance
- Work order management tools
- Comment and file attachment support
- Property management system integrations
- Analytics and reporting tools
- Comprehensive error handling
- Rate limiting and security features

---

Made with ❤️ for property management teams using AI assistants.