belle-mcp-server

Ein Referenz-Model Context Protocol (MCP)-Server, der echte Liegenschaftsverwaltungsdaten von Belle Realty – Liegenschaften, Mieter, Mietverträge, Instandhaltungstickets, Rent Roll – als Tools bereitstellt, die Claude Desktop, Cursor oder jeder andere MCP-kompatible Client direkt aufrufen kann.

Sechs Tools. Fünf davon sind strikt read-only. Eines ist ein durch HITL abgesicherter propose-write (Schreibvorschlag). Dieses Verhältnis ist beabsichtigt und genau darum geht es in diesem Repository.

Teil des AI Fluency Program — Level 2.

Warum es dieses Repository gibt

Die meisten Demos rund um „KI + deine Daten“ geben dem Modell uneingeschränkten Datenbankzugriff. Das ist ein Schuss in den eigenen Fuß.

Der Model Context Protocol wurde entwickelt, um eine kleine, kuratierte Oberfläche bereitzustellen – mit Authentifizierung pro Tool, Rate-Limits und Audit – also genau jene Disziplin, die auch auf eine öffentliche REST-API anwendest. Dieses Repository zeigt, wie das in einer realen Domäne aussieht: einem Einkaufszentrum in Louisiana, mit einem echten Postgres-Schema, einem funktionierenden Seed-Skript und genau einem HITL-abgesicherten Schreibpfad.

Wenn du dieses Repository verstanden hast, kannst du eines für jedes Unternehmen bauen, das du führst.

Was du bekommst

Jeder Aufruf ist ratenbegrenzt (Standard: 60/min) und wird in mcp_audit_log audit-logged.

Schnellstart

# 1. Clone + install
git clone https://github.com/OrangeOnyx/belle-mcp-server.git
cd belle-mcp-server
npm install

# 2. Configure
cp .env.example .env
# Paste your Supabase URL + service-role key

# 3. Set up the schema (Supabase project)
#    Copy supabase/migrations/0001_init.sql into the SQL editor and run.

# 4. Seed demo data
npm run db:seed

# 5. Build + inspect
npm run build
npm run inspect

Der MCP Inspector öffnet eine Benutzeroberfläche, in der du die Tools auflisten, aufrufen und die Raw-Antworten sehen kannst.

Anbindung an Claude Desktop

Füge die Konfiguration in ~/Library/Application Support/Claude/claude_desktop_config.json ein (macOS) bzw. unter dem entsprechenden Pfad unter Windows/Linux:

{
  "mcpServers": {
    "belle-realty": {
      "command": "node",
      "args": ["/absolute/path/to/belle-mcp-server/dist/index.js"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

Starte Claude Desktop anschließend neu. Du siehst jetzt das Toolset belle-realty. Probiere zum Beispiel:

„Welche Einheiten sind derzeit in On The Boulevard belegt, und wie viel Monatsmiete erzielen sie?“

Claude ruft daraufhin get_rent_roll auf und beantwortet die Frage. Daten antwortet die Frage anhand der zurückgegebenen.

Das HITL-Schreibmuster

Das einzige Schreib-Tool (draft_maintenance_response) verdeutlicht ein allgemeines Muster, das du für jeden Dienst mit KI-Schnittstelle übernehmen solltest:

1. Die KI schlägt eine Änderung vor – hier eine Antwort auf das Instandhaltungsticket eines Mieters.

2. Der Server speichert den Vorschlag unter approved=false.

3. Nichts wird zugestellt, versendet oder angewendet, bis ein Mensch die Änderung außerhalb der MCP-Kanals freigibt (in der Regel über die Admin-Oberfläche der Liegenschaftsverwaltung).

4. Die MCP-Oberfläche stellt absichtlich kein Freigabe-Tool bereit. Die Freigabe ist eine rein menschliche Operation.

Das bedeutet: Ein übereifriger oder per Prompt-Injection gesteuerter Agent kann nicht stillschweigend Text an einen Mieter senden. Er kann einen Vorschlag machen – und zwar auch einen deutlichen. Er kann ihn nicht ausliefern.

Einen längeren Durchlauf findest du in docs/hitl-pattern.md.

Anleitung für den privaten Gebrauch

Du bist ein privater Vermieter mit drei vermieteten Häusern oder einem kleinen Gewerbegebäude.

1. Führe die Migration deines Supabase-Projekts aus.

2. Fülle eigene Daten ein (bearbeite supabase/seed.ts oder füge Zeilen manuell ein).

3. Richte Claude Desktop auf den Server aus.

4. Stelle Fragen wie „Welcher Mieter hat einen Mietvertrag, der in den nächsten 90 Tagen ausläuft?“ oder „Entwirf eine Antwort auf das Ticket zum Boiler.“

Du hast damit eine KI-native Ebene für den Mietbetrieb gebaut, die deine eigenen Daten verbindet und zum Sprechen bringt. Gekostet hat das nur einen Abend.

Anleitung für den Unternehmensgebrauch

Du betreibst Belle Realty (oder eine vergleichbare Managementgesellschaft). Mehrere Mitarbeiter brauchen Claude-Zugriff auf Portfoliodaten, ohne Roh-SQL zu sehen und ganz ohne das Risiko unbeabsichtigter Schreibzugriffe.

1. Betreibe diesen Server als persistenten Prozess (Railway, Cloud Foundry, Fly or Docker-Host).

2. Setze MCP_TRANSPORT=http und MCP_HTTP_TOKEN=<shared-secret>.

3. Jedes Teammitglied konfiguriert Claude Desktop oder Cursor mit URL + Token.

4. Die schreibgeschützten Tools geben allen im Team einen wirksamen Hebel. Das einzige Schreib-Tool schützt die Beziehung zum Mieter.

5. mcp_audit_log liefert die nachträgliche und revisionssichere Aufzeichnung jeder KI-Aktion.

Architektur

graph LR
    A[Claude Desktop / Cursor] -->|MCP stdio or HTTP| B[belle-mcp-server]
    B --> C[RateLimiter]
    B --> D[Zod validation]
    B --> E[Supabase Postgres]
    B --> F[mcp_audit_log]
    E --> G[(properties, tenants, leases, tickets)]

Details finden sich in docs/architecture.md.

Erweitern

Ein neues Tool ist schritten in 4 Schritten:

1. Lege ein Zod-Schema für die Eingabe in src/schemas/domain.ts an (falls es sich um ein Format handelt).

2. Lege src/tools/<name>.ts mit einem input-Schema, einem Handler und einer JSON-Schema-Definition an.

3. Registriere es in src/tools/index.ts.

4. Ergänze Testfälle unter tests/.

Jedes Schreib-Tool sollte dem propose-write-Muster in draft_maintenance_response folgen.

Deploy

Railway (empfohlen für HTTP-Transport)

railway up

railway.json baut den Server und setzt den Befehl node dist/index.js. In M übergibt man die Umgebungsvariablen im Railway-Dashboard.

Lokal (nur stdio)

Einfach bauen und den MCP-Client auf dist/index.js aus. Kein Hosting enthalten.

Entwicklung

npm run dev       # tsx watch mode
npm run test      # vitest
npm run build     # tsc → dist/
npm run inspect   # MCP Inspector UI

Verwandte Repos

• lease-abstractor – Extrahiert eine strukturierte Abstraktion aus einem Mietvertrags-PDF/DOCX.

• support-triage-agent – Wendet dasselbe HITL-Muster auf Support-Nachrichten an.

• diligence-agent – RAG-basierte Prüfung über einen Ordner mit Unterlagen.

• ai-fluency-program – übergeordnetes Curriculum

Lizenz

MIT – siehe LICENSE.

Dieses Projekt ist weder Rechts- noch Steuer- oder Liegenschaftsverwaltungsberatung. Für compliance-kritische Entscheidungen nicht ohne die Einbindung eines bzw. einer zugelassenen Fachperson verwenden.