Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PropAgent MCP Book the service elevator for my move-in in Flat T1-101 on Saturday 9am-1pm"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Autonomous multi-agent property management system coordinating tenants, owners, and society administration via Google Gemini and Model Context Protocol.
PropAgent is an automated management system for residential apartment complexes. It coordinates tenants, apartment owners, and society managers during move-in and move-out operations. The system automates elevator bookings, enforces society bylaws, verifies owner approvals, and issues digital passes for gate security.
Related MCP server: Real Estate MCP Server
Run these commands in your terminal:
# 1. Clone the repository and navigate into it
git clone https://github.com/Riser01/prop-agent-mcp.git
cd prop-agent-mcp
# 2. Install required dependencies
pip install -r requirements.txt
# 3. (Optional) Provide your Gemini API key
export GEMINI_API_KEY="your-key-here"
# 4. Launch the web application server
python -m uvicorn src.main:app --host 127.0.0.1 --port 8000Open your browser at http://127.0.0.1:8000 to access the dashboard.
To run the automated tests:
python -m pytest tests/ -vRun the end-to-end simulation script to reproduce this output:
python tests/test_user_simulation.py==============================================================================
PROPOSITIONS & DEMO: PropAgent MCP Multi-Agent System Simulation
==============================================================================
[SCENARIO 1: COLD START & DIRECTORY INITIALIZATION]
✓ Society Bylaws Loaded: Allowed Days: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
✓ Shifting Window: 09:00 to 18:00 (Max 1 move/tower)
✓ Society Fees: Move-In ₹2000, Lift Deposit ₹5000
✓ Flat Registry Initialized: 3 flats, 6 residents.
[SCENARIO 2: RESIDENT ATTEMPTS SUNDAY MOVE (BLOCKED BY BYLAWS)]
Resident attempts booking on Sunday (2026-10-04) at 10:00 AM...
[TENANT_AGENT] BYLAW_EVALUATION: Tenant Agent checking society bylaws (allowed days, hours, vehicle limits)...
[FAILED] POLICY_VIOLATION: Your requested move on 2026-10-04 (09:00-13:00) cannot be submitted: Shifting on Sunday is prohibited by society bylaws. Allowed days: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. Allowed shifting hours are 09:00 - 18:00 on Monday, Tuesday, Wednesday, Thursday, Friday, Saturday.
[SCENARIO 3: RESIDENT SCHEDULES COMPLIANT SATURDAY MOVE]
Resident re-submits for Saturday (2026-10-03) 09:00-13:00...
[TENANT_AGENT_DONE] LIFT_HELD: Bylaw checks passed! Service elevator locked for 2026-10-03 (09:00-13:00) with a 15-minute reservation hold. Ready for owner tenancy verification.
[OWNER_AGENT_DONE] OWNER_NOC_APPROVED: Owner verification complete. Tenancy terms and zero-dues validated. Owner NOC granted for MOVE_IN on Flat T1-101.
[COMPLETED] GATE_PASS_ISSUED: Move-in/out dossier approved by Society Administration! Service elevator permanently reserved. Digital Gate Pass #GP-REQ-SAT issued with security OTP: 244882.
>>> DIGITAL GATE PASS ISSUED:
Pass ID: GP-REQ-SAT
Security OTP: 244882
Valid Slot: 2026-10-03 (09:00-13:00)
Truck Reg: KA-01-MJ-5566
[SCENARIO 4: SECURITY CHECKPOINT VERIFICATION & DIRECTORY REFRESH]
Mover truck arrives at Society Main Gate. Security enters OTP: 244882...
[SECURITY VERIFY] Status: True, Check-in Time: 2026-09-26T10:37:56.142411+00:00
[SECURITY VERIFY] Result: Tenant ACTIVATE completed for Flat T1-101.
✓ Flat T1-101 Final Occupancy State: OCCUPIED_TENANT
✓ Flat T1-101 Current Tenant: Priya Nair
==============================================================================
SIMULATION COMPLETED WITH ZERO ERRORS
==============================================================================A resident submits an apartment move request with preferred date, time slot, and moving truck size.
The system checks society bylaws to verify that shifting is allowed on that day and hour.
The freight elevator is locked temporarily so other moving teams cannot double-book it.
The apartment owner confirms lease terms and verifies that past maintenance dues are zero.
Society management signs off on the move, generating a secure six-digit gate code for security.
sequenceDiagram
autonumber
actor Tenant as Resident
participant TA as Tenant Agent
participant FSM as Supervisor Orchestrator
participant OA as Owner Agent
participant AA as Admin Agent
participant MCP as MCP Registry
actor Guard as Security Guard
Tenant->>TA: Request Move (Flat, Date, Slot, Vehicle)
TA->>MCP: eval_shift_bylaws(date, slot, vehicle)
MCP-->>TA: Policy evaluation (Approved / Blocked)
TA->>MCP: reserve_service_lift(flat_id, slot)
MCP-->>TA: 15-min lazy-TTL elevator reservation
TA-->>FSM: Transition state to LIFT_HELD
FSM->>OA: Request Tenancy & Dues Verification
OA->>MCP: verify_dues_and_fees(flat_id)
MCP-->>OA: Dues status report
OA->>MCP: submit_owner_noc(request_id, 'APPROVED')
OA-->>FSM: Transition state to OWNER_NOC_APPROVED
FSM->>AA: Request Society Clearance
AA->>MCP: generate_gate_pass(request_id, mover_details)
MCP-->>AA: 6-digit OTP & Digital Token
AA-->>FSM: Transition state to GATE_PASS_ISSUED
Guard->>MCP: validate_gate_pass_at_security(otp_code)
MCP->>MCP: sync_resident_directory(flat_id, 'ACTIVATE')
MCP-->>Guard: Entry granted, Occupancy directory updatedTenant Agent: Guides residents, checks shifting hours, and requests elevator reservations.
Owner Agent: Validates tenancy contracts, verifies unpaid dues, and grants owner approvals.
Admin Agent: Enforces society bylaws, oversees pending requests, and generates digital gate passes.
Supervisor Orchestrator: Manages state transitions deterministically across the move lifecycle.
MCP Tool Registry: Provides authoritative tools with role-based access control for agent execution.
SQLite WAL Database: Persists resident records, bylaws, and elevator reservations with concurrency locks.
Layer | Tool | Why |
Agent Intelligence | Google Gemini 2.0 Flash | Fast inference latency (<1s), native function calling, and zero-cost free tier. |
Tool Interface | Model Context Protocol (MCP) | Decouples reasoning from data stores while enforcing role-based permissions. |
Backend & API | Python 3.11+ / FastAPI | High-performance asynchronous execution and Server-Sent Events (SSE) streaming. |
Storage & Concurrency | SQLite 3 + WAL ( | Zero-configuration relational persistence with in-process mutex locks for elevator slots. |
Frontend | Vanilla JS + Tailwind CSS (CDN) | Zero-build simplicity without Node.js, npm packages, or dual development servers. |
Testing | Pytest + Pytest-Asyncio | Automated unit, concurrency, and end-to-end integration test coverage. |
All 28 automated test specifications pass cleanly with zero flakes:
Test Domain | Target Invariant | Result |
Playwright Browser Simulation | Full headless Chrome persona lifecycle: Tenant chat -> Owner NOC -> Admin clearance -> Guard keypad | PASS (2/2 tests) |
Conversational Chat & Concierge | Inquiry follow-ups, Sunday curfew alternatives, dossier assembly | PASS (3/3 tests) |
Human-in-the-Loop Approvals | Multi-persona step flow, Owner NOC, Admin clearance, rejection hold release | PASS (3/3 tests) |
Bylaw Verification | Sunday ban, curfew hours (09:00-18:00), truck restrictions | PASS (5/5 tests) |
Elevator Concurrency | Race condition prevention, 15-minute lazy-TTL release | PASS (3/3 tests) |
Agent & FSM Pipeline | Deterministic state transitions, approval flow, rejection path | PASS (2/2 tests) |
MCP Tools & RBAC | Schema conformance, role-based boundary enforcement | PASS (2/2 tests) |
MCP Stdio Server | JSON-RPC 2.0 list_tools and call_tool protocol handling | PASS (4/4 tests) |
End-to-End API | Full REST life-cycle, SSE streaming, directory sync | PASS (4/4 tests) |
Gemini Integration | Key detection, model initialization, offline fallback | PASS (2/2 tests) |
12-Profile Simulation | 12 user/reviewer profiles (tenants, owners, admins, guards) | PASS (1/1 suite) |
The MCP server adheres strictly to JSON-RPC 2.0 over standard I/O (stdio). It can be configured in any MCP-compliant client (such as standard MCP desktop clients, IDE extensions, or command-line hosts):
{
"mcpServers": {
"prop-agent-mcp": {
"command": "python",
"args": ["-m", "src.mcp.server"],
"env": {
"PYTHONPATH": "."
}
}
}
}The server exposes 8 authoritative society management tools with role-based access control (RBAC):
eval_shift_bylaws: Evaluates dates, hours, and vehicle limits against society rules.
reserve_service_lift: Acquires an atomic lazy-TTL hold on the tower freight elevator.
verify_dues_and_fees: Computes shifting charges, lift deposits, and outstanding ledger dues.
submit_owner_noc: Grants or rejects apartment owner No-Objection Certificate.
generate_gate_pass: Issues authenticated digital gate pass with 6-digit security OTP.
validate_gate_pass_at_security: Verifies 6-digit pass code at main security gate.
sync_resident_directory: Transitions flat occupancy registry (ACTIVATE / ARCHIVE / REFRESH).
update_society_bylaws: Dynamically updates shifting policies, allowed days, and fees.
prop-agent-mcp/
├── LICENSE # MIT License
├── README.md # System overview, quickstart, and demo
├── requirements.txt # Minimal Python dependencies
├── pytest.ini # Pytest configuration and asyncio setup
├── .env.example # Environment variable template
├── .gitignore # Git ignore configuration
├── mcp_config.json # Model Context Protocol stdio client configuration
├── docs/
│ ├── GUIDE.md # System architectural guide and walkthrough
│ └── MCP_SPECIFICATION.md # MCP schemas, role permissions, and tool contracts
├── output/
│ ├── demo_cli.txt # Captured terminal output from simulation
│ └── project_report.html # Standalone deliverable report
├── src/
│ ├── database.py # SQLite schema, queries, and elevator concurrency locks
│ ├── main.py # FastAPI server, REST routes, and SSE streaming
│ ├── agents/
│ │ ├── gemini_client.py # Gemini API client with deterministic fallback
│ │ ├── tenant_agent.py # Tenant representative agent & conversational chat
│ │ ├── owner_agent.py # Property owner representative agent logic
│ │ ├── admin_agent.py # Society administrator agent logic
│ │ └── orchestrator.py # Multi-agent state machine coordinator
│ ├── mcp/
│ │ ├── tools.py # 8 authoritative MCP tools with RBAC enforcement
│ │ └── server.py # Standalone stdio JSON-RPC MCP server runner
│ └── static/
│ ├── index.html # Responsive web dashboard with persona switcher
│ └── app.js # Dashboard controller and live SSE event handler
└── tests/
├── conftest.py # Isolated test database fixture
├── test_bylaws.py # Bylaw rule enforcement tests
├── test_lift_locks.py # Concurrency and elevator lock tests
├── test_agents_fsm.py # Multi-agent state machine tests
├── test_human_in_the_loop.py # Multi-persona human approval workflow tests
├── test_mcp_tools.py # MCP tool contract and RBAC tests
├── test_mcp_server.py # JSON-RPC stdio protocol tests
├── test_e2e_api.py # End-to-end REST and SSE API tests
├── test_gemini_client.py # Gemini client and fallback engine tests
├── test_user_simulation.py# Realistic end-to-end user simulation runner
├── test_multi_profile_simulation.py # 12-profile user & reviewer simulation runner
└── test_playwright_simulation.py # Playwright headless Chrome E2E simulationPrajwal Rao
This server cannot be deployed
Manage AggREIgator buy-boxes and compliant real-estate deal workflows
Negotiate B2B deals agent to agent: every offer recorded, owner rules checked, agreements locked.
AI open-house assistant for agents: sign-in kiosk + automated, consent-aware follow-ups.
Connect, monitor, and control AI agents — tasks, approvals, schedules, and governance.
