# Belong MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes the Belong Resident Application APIs as tools. This lets AI assistants like Claude interact with your Belong society account -- manage visitors, vehicles, maintenance issues, amenity bookings, finances, and more.

## Prerequisites

- [Node.js](https://nodejs.org/) v18 or later
- An active [Belong](https://belongapp.in) resident account

## Setup

1. **Clone the repo**
   ```bash
   git clone https://github.com/arjunbhasin/belong-mcp.git
   cd belong-mcp
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Create a `.env` file** (optional -- you can authenticate via OTP through the MCP tools instead)
   ```bash
   cp .env.example .env
   ```
   If you already have tokens, populate them:
   ```
   ACCESS_TOKEN=your_access_token
   REFRESH_TOKEN=your_refresh_token
   MOBILE_NUMBER=your_mobile_number
   ```

## Running the Server

The server communicates over **stdio**, which is how MCP clients (like Claude Code or Claude Desktop) connect to it.

```bash
node index.js
```

Or using the npm script:

```bash
npm start
```

## Connecting to Claude Code

Add to your Claude Code MCP config (`~/.claude/claude_code_config.json` or project-level `.mcp.json`):

```json
{
  "mcpServers": {
    "belong-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/belong-mcp/index.js"]
    }
  }
}
```

## Connecting to Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "belong-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/belong-mcp/index.js"]
    }
  }
}
```

## Authentication

There are two ways to authenticate:

### Option 1: OTP via MCP tools (recommended)
Once the server is connected, use the built-in authentication tools:
1. Call `request_otp` with your mobile number
2. Call `verify_otp` with the OTP you received
3. Tokens are saved to `.env` automatically

### Option 2: Manual `.env` file
If you have tokens from another session, add them to the `.env` file directly (see Setup step 3).

The server automatically refreshes expired access tokens using the refresh token.

## Available Tools

### Authentication
| Tool | Description |
|------|-------------|
| `request_otp` | Send OTP to mobile number |
| `verify_otp` | Verify OTP to complete login |
| `check_auth_status` | Check current auth state |

### Profile & Flats
| Tool | Description |
|------|-------------|
| `get_resident_profile` | Get your profile (name, mobile, email) |
| `get_flat_access` | Get flat feature flags and access details |
| `get_occupancy_detail` | Get tower/wing/floor info for a flat |
| `list_flats` | List all your associated flats |
| `list_flats_by_occupancy` | Filter flats by occupancy ID |
| `get_flats_by_resident_ids` | Look up flats for specific residents |

### Visitors & Gate
| Tool | Description |
|------|-------------|
| `get_visitor_approvals` | List gate entries for a date |
| `get_approvals_count` | Monthly visitor approval count |
| `get_exit_passes` | Material movement exit passes |
| `get_entry_stats` | Visitor entry statistics |
| `list_visitor_companies` | Delivery companies by category |

### Staff & Services
| Tool | Description |
|------|-------------|
| `list_service_staffs` | Registered staff (maid, cook, etc.) |
| `list_service_staff_bookings` | Staff booking schedules |
| `list_service_types` | Available service types |

### Vehicles
| Tool | Description |
|------|-------------|
| `list_resident_vehicles` | Vehicles registered to a flat |
| `search_vehicles` | Search by registration number |
| `list_vehicle_brands` | Available vehicle brands |

### Maintenance Issues
| Tool | Description |
|------|-------------|
| `list_maintenance_issues` | Your complaints and issues |
| `list_issue_categories` | Available issue categories |
| `get_issue_stats` | Issue statistics |

### Amenities
| Tool | Description |
|------|-------------|
| `list_booked_slots` | Amenity bookings (gym, pool, etc.) |
| `get_booking_stats` | Booking statistics |

### Community
| Tool | Description |
|------|-------------|
| `get_announcements` | Community announcements |
| `list_community_feeds` | Community feed posts |
| `get_banners` | Promotional banners |
| `list_campaigns` | Active campaigns |
| `list_rwa_members` | RWA committee members |

### Buggy Service
| Tool | Description |
|------|-------------|
| `list_buggy_stops` | Golf cart pickup/drop stops |
| `get_buggy_activity` | Buggy ride history |

### Chat
| Tool | Description |
|------|-------------|
| `list_chat_enabled_residents` | Residents available for chat |
| `list_chat_wings` | Wings available for chat |
| `list_chat_flat_residents` | Residents on a floor |

### Infrastructure
| Tool | Description |
|------|-------------|
| `get_towers` | Buildings in a project |
| `get_module_access` | Enabled modules/features |
| `list_external_services` | Integrated services (laundry, food) |
| `list_languages` | Available languages |

### Finance & Billing
| Tool | Description |
|------|-------------|
| `get_financial_ledger` | Transaction history for a date range |
| `get_invoice_stats` | Unpaid amounts, interest, balance |
| `list_demandnote_requests` | Payment demands from management |
| `get_payment_config` | Payment method configuration |

### Notifications & Delivery
| Tool | Description |
|------|-------------|
| `get_notifications_count` | Unread notification count |
| `get_delivery_preferences` | Auto-approve delivery settings |

## License

ISC