# Society Maintenance Tracker — MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes society maintenance and expense data as tools, so any MCP-compatible AI agent (Claude Desktop, Cursor, watsonx, etc.) can query it using natural language.

---

## What it does

The server reads two Excel files (`Maintenance.xlsx` and `Expenses.xlsx`) and registers **8 tools** that an AI agent can call:

| Tool | What it answers |
|------|----------------|
| `tool_get_all_months` | Which months have data? |
| `tool_get_pending_maintenance` | Which flats haven't paid? (by month or year) |
| `tool_get_collected_maintenance` | Which flats have paid? (by month or year) |
| `tool_get_balance_sheet` | Income vs expenses — surplus or deficit? |
| `tool_get_expense_summary` | Expenses broken down by category |
| `tool_get_flat_history` | Full payment history for a specific flat |
| `tool_download_pending_report` | Generate & save pending maintenance Excel report |
| `tool_download_balance_report` | Generate & save balance sheet Excel report |

---

## Project structure

```
Society Maintenance Tracker/
├── server.py               # MCP server entry point (8 tools registered)
├── server/
│   ├── __init__.py
│   └── data_loader.py      # Loads & queries Maintenance.xlsx + Expenses.xlsx
├── reports/
│   ├── __init__.py
│   └── generator.py        # Generates styled Excel reports
├── data/                   # ← YOU must supply these (not included in repo)
│   ├── Maintenance.xlsx
│   └── Expenses.xlsx
├── downloads/              # Auto-created — generated reports saved here
├── requirements.txt
├── Dockerfile
└── README.md
```

---

## Prerequisites

- Python 3.11 or 3.12
- The two Excel data files (see [Data files](#data-files) below)

---

## Installation

### 1. Clone the repo

```bash
git clone https://github.com/YOUR_USERNAME/society-maintenance-tracker.git
cd society-maintenance-tracker
```

### 2. Create a virtual environment (recommended)

```bash
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate
```

### 3. Install dependencies

```bash
pip install -r requirements.txt
```

### 4. Add your data files

Create a `data/` folder and place your Excel files inside:

```
data/
├── Maintenance.xlsx    ← sheet name must be "Maintenance"
└── Expenses.xlsx       ← sheet name must be "Expenses"
```

**Expected columns:**

`Maintenance.xlsx` — `Month | Date | Flat No | Name | Amount | Late Charges`

`Expenses.xlsx` — `Month | Date | Expence Type | Details | Amount | Spend By`

---

## Running the server

### stdio mode — for AI agents that spawn it as a subprocess (Claude Desktop, Cursor, etc.)

```bash
python server.py
```

> ⚠️ Do not type into the terminal in this mode — the server speaks JSON-RPC over stdin/stdout. It will look frozen; that is normal.

### SSE mode — for persistent servers / external clients

```bash
python server.py --sse
```

Server listens at `http://localhost:8100/sse`.

---

## Connecting to AI clients

### Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "society-maintenance": {
      "command": "python",
      "args": ["C:/full/path/to/society-maintenance-tracker/server.py"]
    }
  }
}
```

Restart Claude Desktop. You can now ask questions like:
- *"Which flats haven't paid maintenance for January 2024?"*
- *"What is the balance sheet for 2024?"*
- *"Give me the payment history for flat 601."*

### Cursor / VS Code (MCP extension)

Add to your MCP settings:

```json
{
  "society-maintenance": {
    "command": "python",
    "args": ["/full/path/to/server.py"]
  }
}
```

### MCP Inspector (browser UI — best for testing)

```bash
npx @modelcontextprotocol/inspector python server.py
```

Opens at `http://localhost:5173` — browse and call all tools interactively.

---

## Running with Docker

```bash
# Build
docker build -t society-mcp .

# Run (mount your local data/ folder into the container)
docker run -v $(pwd)/data:/app/data society-mcp
```

---

## Testing

### Quick data sanity check

```bash
python -c "
import sys; sys.path.insert(0, '.')
from server.data_loader import get_all_months, get_balance_sheet
print(get_all_months())
print(get_balance_sheet(year=2024))
"
```

### Full MCP protocol test (stdio)

```bash
python _test_server.py
```

This sends a proper JSON-RPC handshake and lists all registered tools.

---

## Data files

The `data/` folder is **excluded from this repository** (see `.gitignore`) because the Excel files contain private resident information.

To use this server:
1. Create your own `Maintenance.xlsx` and `Expenses.xlsx` following the column format above.
2. Place them in the `data/` folder.
3. The server will load them automatically on first tool call.

---

## Month format

Months in the Excel file must follow the pattern `MonthName_YYYY`, e.g.:

```
Jan_2024   Feb_2024   March_2024   April_2024
May_2024   June_2024  July_2024    Aug_2024
Sep_2024   Oct_2024   Nov_2024     Dec_2024
```

The server normalises common variants automatically (`january_2024`, `MARCH_2025`, `jun_2024`, etc.).

---

## License

MIT