# ellmos-homebase-mcp

<p align="center">
  <img src="assets/homebase-logo.jpg" alt="ellmos Homebase MCP Logo" width="640">
</p>

Alpha-MCP-Server für **local-first LLM-Orchestrierung**: Memory, Knowledge, Routing, Schwarmmuster, API-Probing, persistenter Zustand, Tests, Automatisierungsplanung und Plugin-Discovery in einem stdio-Server.

Homebase ist primär für **lokale LLMs** (Ollama, Qwen, Llama oder beliebige lokal gehostete Modelle über eine MCP-fähige Harness) konzipiert. Alle persistenten Daten werden per SQLite ohne Cloud-Abhängigkeit gespeichert. Externe LLM-Anbieter (Claude, Codex, Gemini, OpenAI) können sich ebenfalls als MCP-Clients verbinden, aber lokale, offline-fähige Setups sind das primäre Zielszenario.

Englische Standard-README: [README.md](README.md)

*Teil der [ellmos-ai](https://github.com/ellmos-ai)-Familie.*

[![Ecosystem: open-bricks](https://img.shields.io/badge/Ecosystem-open--bricks-blue.svg)](https://github.com/open-bricks)
[![Organization: ellmos-ai](https://img.shields.io/badge/Organization-ellmos--ai-blue.svg)](https://github.com/ellmos-ai)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://img.shields.io/npm/v/ellmos-homebase-mcp.svg)](https://www.npmjs.com/package/ellmos-homebase-mcp)
[![Python Matrix](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
[![Plattformen](https://img.shields.io/badge/plattformen-Linux%20%7C%20Windows%20%7C%20macOS-informational.svg)](https://github.com/ellmos-ai/ellmos-homebase-mcp)
[![Datenschutz](https://img.shields.io/badge/datenschutz-100%25%20Local--First%20%7C%20Zero--Egress-success.svg)](SECURITY.md)
[![Speicher](https://img.shields.io/badge/speicher-SQLite%20(WAL)-blueviolet.svg)](https://sqlite.org/)
[![MCP](https://img.shields.io/badge/MCP-stdio%20(51%20Tools)-blueviolet.svg)](https://modelcontextprotocol.io/)
[![Status: alpha](https://img.shields.io/badge/status-0.1.0--alpha.28-orange.svg)](https://www.npmjs.com/package/ellmos-homebase-mcp)
[![Tests](https://img.shields.io/badge/tests-152%20passed%20%7C%20100%25-brightgreen.svg)](tests/)
[![Security SLA](https://img.shields.io/badge/security-48h%20SLA%20%7C%205d%20Triage-blue.svg)](SECURITY.md)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![LLMs-Ready](https://img.shields.io/badge/LLMs--Ready-llms.txt-blueviolet.svg)](llms.txt)
[![Homebase tests](https://github.com/ellmos-ai/ellmos-homebase-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/ellmos-ai/ellmos-homebase-mcp/actions/workflows/tests.yml)

**Auffindbarkeit:** Veröffentlicht auf [npm](https://www.npmjs.com/package/ellmos-homebase-mcp) als `ellmos-homebase-mcp` und gepflegt in der Organisation [`ellmos-ai`](https://github.com/ellmos-ai).

> [!NOTE]
> **Für KI-Assistenten & LLM-Agenten:** Die maschinenlesbare Architekturzusammenfassung, der Index und die Tool-Fähigkeiten sind in [llms.txt](llms.txt) veröffentlicht. MCP-Registry-Metadaten sind in [server.json](server.json) verfügbar.

## Schnellnavigation / Quick Navigation

- [Systemarchitektur](#systemarchitektur)
- [Sequenzablauf & Lebenszyklus](#sequenzablauf--lebenszyklus)
- [Kernfähigkeiten & Sicherheitsinvarianten](#kernfähigkeiten--sicherheitsinvarianten)
- [Governance & Laufzeit-Invarianten](#governance--laufzeit-invarianten)
- [Zielgruppen & Auffindbarkeit](#zielgruppen--auffindbarkeit)
- [Vergleichsmatrix gegenüber Alternativen](#vergleichsmatrix-gegenüber-alternativen)
- [Einstieg](#einstieg)
- [Status](#status)
- [Installation](#installation)
- [MCP-Client-Konfiguration](#mcp-client-konfiguration)
- [Server-Konfiguration](#server-konfiguration)
- [Tools](#tools)
- [Discovery-Kontext](#discovery-kontext)
- [ellmos-ai-Ökosystem](#ellmos-ai-%C3%B6kosystem)
- [Drittanbieter-Lizenzen (THIRD_PARTY_LICENSES.md)](THIRD_PARTY_LICENSES.md)
- [Marketing-Protokoll (MARKETING-LOG.txt)](MARKETING-LOG.txt)
- [Sicherheit & Schwachstellenmeldung](#sicherheit--schwachstellenmeldung)
- [Entwicklung](#entwicklung)
- [Änderungsprotokoll (CHANGELOG.md)](CHANGELOG.md)
- [Englische Version (README.md)](README.md)

## Systemarchitektur

```mermaid
flowchart TD
    subgraph Clients ["MCP-Clients (Lokal / Remote)"]
        Ollama["Lokale LLMs (Ollama, Qwen, Llama)"]
        Claude["Claude Code / Desktop"]
        Codex["Codex / Antigravity"]
    end

    subgraph Transport ["Transportschicht"]
        Stdio["stdio (Python MCP SDK)"]
    end

    subgraph Core ["ellmos-homebase-mcp Core Engine"]
        Server["homebase.server"]
        Config["homebase.config"]
    end

    subgraph ToolGroups ["51 MCP-Tools über 14 funktionale Module"]
        Mem["hb_mem_* (SQLite-Memory)"]
        KB["hb_kb_* (Knowledge Digest)"]
        State["hb_state_* (State & Tasks)"]
        Route["hb_route_* (Model Router)"]
        Swarm["hb_swarm_* (Schwarm-Muster)"]
        Api["hb_api_* (API Probing)"]
        Conn["hb_conn_* (Connectors Queue)"]
        Auto["hb_auto_* (Automatisierungs-Ketten)"]
        Plug["hb_plug_* (Plugin-Discovery)"]
        Garden["hb_garden_* (Garden Store)"]
        Test["hb_test_* (Selbst-Tests)"]
        Policy["hb_policy_* (Policy Registry, nur lesend)"]
        Ticket["hb_ticket_* (Ticket Master, nur lesend)"]
        Lock["hb_lock_* (Lock Master, nur lesend)"]
    end

    subgraph Storage ["Lokaler Speicher (Offline-First)"]
        DB[(SQLite Speicher ~/.homebase/)]
    end

    Clients --> Stdio
    Stdio --> Server
    Server --> Config
    Server --> ToolGroups
    ToolGroups --> DB
```

## Sequenzablauf & Lebenszyklus

```mermaid
sequenceDiagram
    autonumber
    participant Client as MCP-Client (Lokales LLM / Claude / Codex)
    participant Stdio as Transportschicht (stdio)
    participant Server as Server & Registry (homebase)
    participant Module as Funktionales Modul (hb_mem / hb_state / hb_route)
    participant Engine as Engine-Schnittstelle (Bundled vs. Canonical)
    participant DB as SQLite-Speicher (~/.homebase/)

    Client->>Stdio: JSON-RPC 2.0 Request (tools/call: hb_mem_store, agent_id="agent-01")
    Stdio->>Server: Dekodiere & leite Tool-Aufruf weiter
    Server->>Module: Validiere Argumente & injiziere Agenten-Provenienz
    alt Bundled Engine Modus (Standard)
        Module->>DB: Führe SQLite-Abfrage aus (WAL-Modus, Busy-Timeout)
        DB-->>Module: Liefere strukturierte Datensätze / Mutationsstatus
    else Canonical Engine Modus ([engines].mode = "canonical")
        Module->>Engine: Schnittstellen-Prüfung (Gardener / TASKPLAN / USMC)
        alt Engine Verfügbar
            Engine-->>Module: Delegiere an kanonisches Subsystem
        else Engine Nicht Erreichbar
            Engine-->>Module: Werfe CanonicalEngineUnavailable (Fail-Closed)
        end
    end
    Module-->>Server: Formatiere Antwort in gewählter Sprache (i18n: en/de/es/zh/ja/ru)
    Server-->>Stdio: Enkodiere JSON-RPC 2.0 Response
    Stdio-->>Client: Ergebnisdaten (Zero Cloud-Egress, 100% lokal)
```

## Kernfähigkeiten & Sicherheitsinvarianten

| Fähigkeit / Invariante | Garantie | Technische Umsetzung |
|---|---|---|
| **100% Local-First & Zero-Egress** | Vollständige Privatsphäre und Offline-Fähigkeit; keine ungefragte Cloud-Kommunikation oder Telemetrie. | Alle Memory-, Knowledge- und Zustandsdaten verbleiben in lokalem SQLite (`~/.homebase/`). |
| **Strikte Engine-Seams & Fail-Closed** | Kein stillschweigender Fallback auf getrennte Datenbanken bei Anforderung kanonischer Systeme. | [`MODE-CONTRACT.md`](MODE-CONTRACT.md)-Durchsetzung: wirft `CanonicalEngineUnavailable` bei Nichterreichbarkeit. |
| **Team-Memory Provenienz (`agent_id`)** | Deterministische Nachvollziehbarkeit und filterbare Zuordnung für Multi-Agenten-Workflows. | Native `agent_id`-Verfolgung über Memory-Fakten, Knowledge-Einträge und Task-Zustände. |
| **Schlüsselfreie Discovery & Planung** | Null Geheimnis-Exposition bei lokalen Modell-Empfehlungen und API-Erkundungen. | `hb_route_*`, `hb_swarm_*` und `hb_api_*` laufen ohne Übertragung von API-Keys oder Token. |
| **Sichere Plan-and-Queue Adapter** | Gefahrloses Queueing und Ketten-Staging ohne unkontrollierte Remote-Code-Ausführung. | `hb_conn_*` und `hb_auto_*` führen plan-only Warteschlangen und Offline-Staging-Datensätze. |
| **Vollständige native i18n-Lokalisierung** | Nahtlose mehrsprachige Entwickler- und Agenteninteraktion. | Lokalisierte Tool-Beschreibungen und JSON-Schemas für `en`, `de`, `es`, `zh`, `ja`, `ru`. |
| **Non-Elevation & Geheimnis-Hygiene** | Unprivilegierte Ausführung und strikter Ausschluss sensibler Daten aus der Distribution. | Kompatibel mit unprivilegierten Benutzern; Live-Konfigurationen/Secrets in `.gitignore` & `.npmignore`. |
| **Multi-OS CI Smoke-Integrität** | Verifizierte plattformübergreifende Zuverlässigkeit auf allen Hauptbetriebssystemen. | Multi-Versionen CI-Matrix für Python 3.10–3.13 und Node.js 20–24 unter Linux/Windows/macOS. |

## Governance & Laufzeit-Invarianten

| Invarianten-ID | Titel & Geltungsbereich | Garantie & Technische Durchsetzung | Verifikations-Naht |
|---|---|---|---|
| **`INV-LOCAL-01`** | **100% Local-First & Zero-Egress** | Alle persistenten Memories, Wissenseinträge und Task-Zustände verbleiben lokal in SQLite (`~/.homebase/`). Keine Telemetrie, Analyse oder unaufgeforderte Cloud-Netzwerkverbindungen. | `tests/test_server_transport.py`, `tests/test_repository_hygiene.py` |
| **`INV-ENGINE-02`** | **Strikte Engine-Nähte & Fail-Closed** | Durchsetzung von [`MODE-CONTRACT.md`](MODE-CONTRACT.md): Der Modus `[engines].mode = "canonical"` fällt niemals still auf lokale Kopien zurück, wenn ein kanonisches System nicht erreichbar ist. | `tests/test_engine_seams.py` |
| **`INV-SEAM-03`** | **Kanonisch-Exklusive Seam-Isolation** | `hb_policy_*`, `hb_ticket_*` und `hb_lock_*` bieten ausschließlich Lese-Zugriff auf policy-registry, ticket-master und lock-master, besitzen keinen Bundled-Ersatz und versagen strikt fail-closed. | `tests/test_new_seams.py` |
| **`INV-PROV-04`** | **Deterministische Provenienz & Team-Memory** | Multi-Agenten-Koordination erfordert strikte Isolation. Alle Fakten, Wissenseinträge und Tasks zeichnen `agent_id`-Provenienz mit SQLite WAL-Modus und Busy-Timeouts auf. | `tests/test_module_contracts.py` |
| **`INV-CRED-05`** | **Schlüsselfreies Routing & API-Discovery** | Modell-Routing-Empfehlungen (`hb_route_*`), Schwarm-Baupläne (`hb_swarm_*`) und API-Erkundung (`hb_api_*`) arbeiten vollständig offline ohne private API-Keys oder Tokens. | `tests/test_module_contracts.py` |
| **`INV-STAGE-06`** | **Plan-Only Staging & Bounded Offline Queues** | Connector-Warteschlangen (`hb_conn_*`) und Automatisierungs-Pläne (`hb_auto_*`) erfassen Offline-Pläne und Staging-Manifeste ohne Ausführung von beliebigem Remote-Code. | `tests/test_module_contracts.py` |
| **`INV-I18N-07`** | **Vollständige native Lokalisierungs-Parität** | Alle 51 Tool-Definitionen, Input-Schemas und Fehlermeldungen bieten vollständige Parität über 6 Sprachen (`en`, `de`, `es`, `zh`, `ja`, `ru`) mit englischem Fallback. | `tests/test_i18n_completeness.py` |
| **`INV-PERM-08`** | **Nicht-Privilegiertes RunAsInvoker-Prinzip** | Homebase läuft strikt im unprivilegierten Anwendermodus (Non-Elevation). Keine Administrator-Rechte erforderlich; sensible Host-Dateien werden ignoriert. | `tests/test_repository_hygiene.py` |
| **`INV-SYNC-09`** | **Multi-Host Lock- & Konfliktkopien-Disziplin** | Strikter Ausschluss von Konfliktkopien (`*.sync-conflict-*`, `*-conflict-*`) und Einhaltung von Multi-Agenten-Locks (`LOCK.*`, `*.lock`) zum Schutz der lokalen Datenbank. | `tests/test_metadata.py` |
| **`INV-SLA-10`** | **48h Sicherheitsreaktions- & 5-Tage-Triage-SLA** | Sicherheitsmeldungen an `security@ellmos.ai`, `support@lukasgeiger.com` oder `security@open-bricks.org` erhalten eine garantierte Antwort binnen 48h und Triage in 5 Werktagen. | `SECURITY.md`, `tests/test_metadata.py` |

## Zielgruppen & Auffindbarkeit

Homebase wurde gezielt entwickelt, um architektonische und betriebliche Herausforderungen von vier technischen Kernzielgruppen zu lösen:

### `[PERSONA-01]` Entwickler lokaler LLMs & Edge-KI
- **Profil & Ziel:** KI-Entwickler, die Offline- oder Edge-Anwendungen mit Modellen wie Ollama, Qwen oder Llama betreiben und eine robuste Orchestrierungs-Harness benötigen.
- **Herausforderungen:** Cloud-Memory-APIs verursachen unerwünschte Latenzen, Datenschutzrisiken, monatliche Abokosten und Netzwerk-Fehlerquellen.
- **Homebase-Lösung:** Vollständige Unabhängigkeit von Cloud-Diensten, persistente lokale SQLite-WAL-Speicherung (`~/.homebase/`) und 51 einheitliche stdio-Tools für Gedächtnis, FTS5-Wissenssuche und Aufgabenverwaltung.
- **Beispielhafter Ablauf:**
  ```json
  {"tool": "hb_mem_store", "arguments": {"fact": "Benutzer bevorzugt kompakte JSON-Ausgaben", "agent_id": "ollama-coder"}}
  {"tool": "hb_kb_search", "arguments": {"query": "API Routing-Regeln", "fts": true}}
  ```

### `[PERSONA-02]` Multi-Agenten-Schwarm-Orchestrierer & Systemarchitekten
- **Profil & Ziel:** Softwarearchitekten, die heterogene Multi-Agenten-Kollektive (Claude Code, Codex, Antigravity, lokale Agenten) zeitgleich auf gemeinsamen Codebases koordinieren.
- **Herausforderungen:** Zustands-Kollisionen, fehlende Herkunftsnachweise, Race Conditions im gemeinsamen Speicher und unkoordinierte Aufgabenweitergabe.
- **Homebase-Lösung:** Native `agent_id`-Provenienz über alle Fakten, Erinnerungen und Aufgabenzustände; integrierte Schwarm-Vorlagen (Boss/Worker, parallele Chunks, Konsensabstimmung via `hb_swarm_*`).
- **Beispielhafter Ablauf:**
  ```json
  {"tool": "hb_swarm_plan", "arguments": {"goal": "Sicherheits-Schnittstellen auditieren", "pattern": "consensus"}}
  {"tool": "hb_state_task_create", "arguments": {"title": "Fail-Closed-Modus verifizieren", "agent_id": "worker-audit-01"}}
  ```

### `[PERSONA-03]` Enterprise Security & Data Governance Officers
- **Profil & Ziel:** CISOs, IT-Sicherheitsbeauftragte und Compliance-Auditoren in regulierten Branchen (Gesundheitswesen, Finanzen, Forschung), die Entwickler-Agentenwerkzeuge bewerten.
- **Herausforderungen:** Unbemerkte Cloud-Telemetrie, unkontrollierte Remote-Seiteneffekte, Privilegien-Eskalation und fehlende verbindliche SLAs.
- **Homebase-Lösung:** Strikte Zero-Egress-Architektur, Fail-Closed-Schnittstellen nach `MODE-CONTRACT.md`, unprivilegierte Ausführung (`RunAsInvoker`) und ein formales 48-Stunden-Sicherheits-SLA (`SECURITY.md`).
- **Beispielhafter Ablauf:**
  ```json
  {"tool": "hb_policy_list_rules", "arguments": {}}
  ```
  *Garantiertes Fail-Closed-Verhalten: wirft `CanonicalEngineUnavailable`, anstatt unbemerkt auf unsichere Notlösungen zurückzufallen.*

### `[PERSONA-04]` Cross-Framework KI-Assistenten & Pair Programmer
- **Profil & Ziel:** Entwickler, die verschiedene KI-Coding-Assistenten (Claude Desktop, Codex, Cursor, Gemini) einsetzen und systemübergreifende Kontext- und Tool-Parität erwarten.
- **Herausforderungen:** Inkompatible proprietäre Tool-APIs, fragmentierte Notizen und fehlende mehrsprachige Entwickler-Schemas.
- **Homebase-Lösung:** Standardisierter stdio-MCP-Transport, maschinenlesbare Projekt-Metadaten (`llms.txt`, `server.json`, `glama.json`) und lückenlose Schema-Lokalisierung über 6 Sprachen (`en`, `de`, `es`, `zh`, `ja`, `ru`).
- **Beispielhafter Ablauf:**
  ```json
  {"tool": "hb_ticket_list", "arguments": {"folder": "ACTIVE"}}
  ```

### High-Intent Suchbegriffe & Auffindbarkeit

- **Englische Suchintention:** `local-first LLM orchestration MCP server`, `offline agent memory SQLite WAL`, `stdio Model Context Protocol Ollama Qwen`, `multi-agent swarm planning persistent state`, `zero-egress MCP server enterprise AI`, `fail-closed engine seams MODE-CONTRACT`, `team-memory agent_id provenance`.
- **Deutsche Suchintention:** `Local-First LLM-Orchestrierung MCP-Server`, `Offline Agenten-Memory SQLite WAL`, `Model Context Protocol Stdio-Server Ollama`, `Multi-Agenten Schwarmplanung persistenter Zustand`, `Zero-Egress MCP-Server Unternehmens-KI`, `Fail-Closed Schnittstellen MODE-CONTRACT`, `Team-Memory Agenten-Provenienz`.

## Vergleichsmatrix gegenüber Alternativen

Homebase bietet im Vergleich zu spezialisierten Einzellösungen oder reinen Cloud-Plattformen einen vollständigen, lokalen MCP-Funktionsstack:

| Architektur- & Laufzeit-Dimension | `ellmos-homebase-mcp` | Cloud Memory SaaS (Letta, Pinecone, LangSmith) | Generische Memory-MCPs (mcp-server-memory, sqlite) | Schwere Agent-Frameworks (CrewAI, AutoGen, LangGraph) | Ad-Hoc Skripte / Eigene SQLite-DBs |
|---|---|---|---|---|---|
| **1. 100% Local-First & Zero Egress (`INV-LOCAL-01`)** | **Ja (100% lokales SQLite WAL, null Telemetrie)** | Nein (Cloud-Hosting, erzwungene Egress-Verbindungen) | Teilweise (Lokale Datei, aber ohne Egress-Vertrag) | Variabel (Erfordert häufig Cloud-API-Keys / SaaS) | Ja (Lokal, jedoch ohne Protokoll-Garantien) |
| **2. Schnittstellen & Fail-Closed (`INV-ENGINE-02`)** | **Ja (Strikter `MODE-CONTRACT.md`, wirft Fehler bei Ausfall)** | Nein (Undurchsichtige Cloud-Failovers) | Nein (Starres Einzel-Backend) | Nein (Unbehandelte Exceptions / stumme Fallbacks) | Nein (Ad-hoc Fehlerbehandlung) |
| **3. Kanonische Schnittstellen (`INV-SEAM-03`)** | **Ja (`hb_policy_*`, `hb_ticket_*`, `hb_lock_*` schlagen Fail-Closed fehl)** | Nein (Kein Verständnis für kanonische Systeme) | Nein (Keine Anbindung an Governance/Locks) | Nein (Keine Governance-Schicht vorhanden) | Nein (Manuelle Koordination) |
| **4. Team-Memory & Attribution (`INV-PROV-04`)** | **Ja (Native `agent_id` für Fakten, Wissen, Aufgaben)** | Teilweise (Nur auf Benutzerebene, keine Agentenfilter) | Nein (Ein einzelner globaler Graph ohne Trennung) | Teilweise (Flüchtiger Agentenstatus im RAM) | Nein (Manuelle Schemaverwaltung) |
| **5. Schlüsselfreie Discovery (`INV-CRED-05`)** | **Ja (Offline-Routing & Schwarmplanung ohne API-Tokens)** | Nein (Erfordert aktive kostenpflichtige API-Keys) | Nein (Keine Routing- oder Schwarmtools) | Nein (Erfordert API-Keys für LLM-Planer) | Nein (Keine strukturierte Planung) |
| **6. Plan-Only Staging-Queues (`INV-STAGE-06`)** | **Ja (Sichere Connector-Queues & Dry-Run-Automation)** | Nein (Direkte Ausführung oder nicht vorhanden) | Nein (Keine Connector- oder Automation-Tools) | Nein (Direkte Seiteneffekte zur Laufzeit) | Nein (Unsichere Ausführung von Fremdcode) |
| **7. Tool-Vielfalt & Oberfläche** | **51 Tools über 14 Module in einem einzigen stdio-Server** | 1-5 API-Endpunkte | 2-5 einfache Tools | Python-Bibliothek (nicht primär MCP-nativ) | Fragmentierte CLI-Skripte |
| **8. Mehrsprachige Schema-Parität (`INV-I18N-07`)** | **Ja (Vollständige Abdeckung für en, de, es, zh, ja, ru)** | Nur Englisch | Nur Englisch | Nur Englisch | Nur Englisch / Keine |
| **9. Non-Elevation-Sicherheit (`INV-PERM-08`)** | **Ja (Unprivilegiertes RunAsInvoker, Schutz vor Systemdateien)** | Cloud SaaS (Vertrauen auf Mandanten-Isolation) | Variabel (Lokale Dateirechte) | Variabel (Läuft oft in privilegierten Containern) | Variabel (Benutzerskripte) |
| **10. Sicherheitsreaktions-SLA (`INV-SLA-10`)** | **Ja (Verbindliches 48h Response SLA & 5d Triage in `SECURITY.md`)** | Kommerzielles SLA (Nur in Enterprise-Tarifen) | Keine / Best-effort Community | Keine / Best-effort Community | Keine |

## Einstieg

| Bedarf | Einstieg |
|---|---|
| Alpha-MCP-Server installieren | `npm install -g ellmos-homebase-mcp@alpha` |
| Aus einem Quellcode-Checkout starten | `python -m homebase.server` mit `PYTHONPATH=src` |
| Lokale LLM-Harness, Claude Code, Codex oder anderen MCP-Client konfigurieren | [MCP-Client-Konfiguration](#mcp-client-konfiguration) |
| Maschinenlesbare Projektzusammenfassung prüfen | [llms.txt](llms.txt) |
| Registry-Metadaten prüfen | [server.json](server.json) |

## Status

- Transport: stdio über das Python-MCP-SDK
- Paketstatus: öffentliches Alpha-Paket unter `ellmos-ai`
- Release-Metadaten: MIT-`LICENSE`, `CHANGELOG.md`, `llms.txt` und MCP-Registry-Metadaten in `server.json`
- Test-Gate: GitHub Actions prüft Python 3.10/3.11/3.12 sowie Node.js 20/22/24 mit Smoke- und npm-Paketchecks
- Aktiver Kern: Modul-Discovery, MCP-Tool-Liste, MCP-Tool-Dispatch, Config-Fallbacks, lokale Planungs-, Probing-, Queue- und Dry-run-Adapter
- Echte lokale SQLite-Module: `hb_mem_*`, `hb_kb_*`, `hb_garden_*`, `hb_state_*`
- Engine-Seams: `hb_garden_*`, `hb_state_task_*` und `hb_mem_*` können über
  `[engines].mode = "canonical"` an die echten Gardener-/Rinnsal-/USMC-Engines delegieren statt
  an die eingebauten SQLite-Kopien (Default bleibt `"bundled"` für eine
  Zero-Dependency-Installation). **Kein stiller Fallback:** Ist bei `canonical` die Engine
  unerreichbar, liefern diese Tools einen Fehler, statt still die bundled-DB zu benutzen — der
  Server startet weiterhin und listet seine Tools. Verbindliche Regel und Migration:
  **[MODE-CONTRACT.md](MODE-CONTRACT.md)**; Mechanismus:
  [KONZEPT.md](KONZEPT.md#engine-seams-canonicalbundled--umsetzungsstand-2026-07-04-ticket-t-20260704-01).
- Canonical-only-Seams (kein bundled-Alternative überhaupt): `hb_policy_*` (policy-registry),
  `hb_ticket_*` (ticket-master), `hb_lock_*` (lock-master) — alle nur lesend in v1. Eine lokal
  gefälschte Kopie von live-Policy-/Ticket-/Lock-Zustand würde eher irreführen als helfen; darum
  versuchen diese drei immer das kanonische Modul und scheitern unbedingt fail-closed, wenn es
  unerreichbar ist.
- Team-Memory-Grundlagen: `agent_id`-Herkunft und Filter für Memory, Knowledge, State-Memory und Tasks; SQLite nutzt WAL plus Busy-Timeout für sicherere parallele Agenten
- Credential-freie Alpha-Adapter: `hb_route_*`, `hb_swarm_*`, `hb_api_*`, `hb_test_*`, `hb_conn_*`, `hb_auto_*`, `hb_plug_*`
- i18n: vollständig lokalisierte MCP-Tool-Beschreibungen, Input-Schema-Feldbeschreibungen und Unknown-Tool-Fehler für `en`, `de`, `es`, `zh`, `ja`, `ru` (Englisch-Fallback für nicht gesetzte Keys)
- Roadmap: optionale echte LLM/API-Integrationen und explizite Ausführungsbackends

## Installation

Das npm-Paket enthält einen Node-Wrapper, der den Python-Server startet. Voraussetzung bleibt Python 3.10+ mit installiertem Python-Paket `mcp>=1.0.0`.

### Option 1: Installation per npm

```powershell
npm install -g ellmos-homebase-mcp@alpha
ellmos-homebase
```

### Option 2: Installation aus dem Quellcode

```powershell
git clone https://github.com/ellmos-ai/ellmos-homebase-mcp.git
cd ellmos-homebase-mcp
$env:PYTHONIOENCODING = "utf-8"
python -m pip install -e ".[dev]"
python -m pytest -q
```

Keine `.venv` in cloud-synchronisierten Ordnern anlegen, wenn der Sync-Client Dateien sperrt. Falls eine isolierte Umgebung gebraucht wird, außerhalb dieses Ordners erstellen.

## Start Aus Dem Quellbaum

```powershell
$env:PYTHONPATH = "src"
python -m homebase.server
```

## MCP-Client-Konfiguration

Homebase nutzt das standardisierte stdio-`mcpServers`-Format. Dasselbe Snippet funktioniert in jedem MCP-fähigen Client oder jeder Harness: BACH/Buddha (lokales Ollama), Claude Code, Codex, Cursor oder einem anderen MCP-Host.

> **Hinweis zu lokalen LLMs:** Eine bare Ollama-Instanz spricht kein MCP nativ — dafür braucht es eine MCP-fähige Harness (z.B. BACH, einen Open-Source-MCP-Proxy oder eine andere Orchestrierungsschicht). Diese Harness wird dann so konfiguriert, dass sie Homebase als MCP-Server einbindet (Snippet unten).

### Globale npm-Installation

```json
{
  "mcpServers": {
    "homebase": {
      "command": "ellmos-homebase"
    }
  }
}
```

### Quellcode-Checkout

```json
{
  "mcpServers": {
    "homebase": {
      "command": "python",
      "args": ["-m", "homebase.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/ellmos-homebase-mcp/src"
      }
    }
  }
}
```

`/absolute/path/to/ellmos-homebase-mcp` durch den eigenen lokalen Checkout-Pfad ersetzen.

## Server-Konfiguration

Beispiel: [config/homebase.example.toml](config/homebase.example.toml)

Maschinenlesbarer Projektkontext: [llms.txt](llms.txt)

MCP-Registry-Metadaten: [server.json](server.json)

Standardpfade:

- `%USERPROFILE%\.homebase\homebase.toml`
- `%USERPROFILE%\.config\homebase\homebase.toml`
- Override per `HOMEBASE_CONFIG`

Die Sprache kann über `[server].language`, `HOMEBASE_LANG` oder `HOMEBASE_LOCALE` gesetzt werden.
Der schreibende Agent kann pro Tool-Aufruf als `agent_id` übergeben werden; sonst nutzen die Module `HOMEBASE_AGENT_ID`, `AGENT_ID`, eine modulweite `agent_id` oder `unknown`.

```toml
[server]
name = "ellmos-homebase"
language = "de" # en, de, es, zh, ja, ru

[modules]
enabled = ["mem", "route", "kb", "swarm", "state", "garden", "api", "test", "conn", "auto", "plug"]
```

Module mit fehlenden optionalen Dependencies werden beim Laden übersprungen, ohne den Serverstart zu blockieren.

## Tools

Wichtige Tool-Gruppen:

- `hb_mem_*` für SQLite-Memory
- `hb_kb_*` für SQLite-Knowledge
- `hb_state_*` für persistenten SQLite-Zustand und Tasks
- `hb_garden_*` für den kleinen SQLite-Garden-Store
- `hb_route_*` für credential-freie Modell-Routing-Empfehlungen und Feedback-Statistiken
- `hb_swarm_*` für credential-freie Schwarm-Planungsmuster
- `hb_api_*` für passive HTTP-API-Discovery mit SQLite-Historie
- `hb_test_*` für eingebaute Metadata- und Smoke-Selbsttests
- `hb_conn_*` für eine lokale Connector-Registry plus SQLite-gestützte Inbox-/Outbox-Queues ohne Netzwerksends
- `hb_auto_*` für lokale Automatisierungsketten und queue-basierte Planläufe ohne Backend-Ausführung
- `hb_plug_*` für lokale Plugin-Discovery und Dry-run-Protokolle ohne Plugin-Code auszuführen
- `hb_policy_*` (nur lesend, canonical-only) zum Auflösen/Auflisten von policy-registry-Regeln
- `hb_ticket_*` (nur lesend, canonical-only) zum Auflisten/Anzeigen von ticket-master-Tickets je Lifecycle-Ordner
- `hb_lock_*` (nur lesend, canonical-only) zum Prüfen/Auflisten aktiver lock-master-Sperren

## Auffindbarkeitskontext

`ellmos-homebase-mcp` ist der passende Suchanker für einen local-first, offline-fähigen MCP-Server, der lokalen LLMs (Ollama, Qwen, Llama o.ä.) persistentes Gedächtnis, Knowledge-Management, Routing und Orchestrierung gibt — ohne Cloud-Abhängigkeit. Externe LLM-Anbieter können ihn ebenfalls als MCP-Server nutzen, aber lokale Setups sind das primäre Designziel.

Geeignete Suchphrasen:

- `ellmos Homebase MCP server`
- `local-first LLM orchestration MCP`
- `MCP server SQLite memory knowledge routing`
- `offline agent orchestration MCP server`
- `MCP swarm planning persistent state API discovery`

Nicht gemeint sind Elmo-/ELMO-Voice-Tools, AllenAI-ELMo-Embeddings, Eclipse LMOS, generische Cloud-Agent-Plattformen oder einzelne MCP-Memory-Server ohne Orchestrierungsschicht.

## ellmos-ai-Ökosystem

Dieser MCP-Server ist Teil des **[ellmos-ai](https://github.com/ellmos-ai)**-Ökosystems — KI-Infrastruktur, MCP-Server und intelligente Werkzeuge.

### MCP-Server-Familie

| Server | Tools | Fokus | npm |
|--------|-------|-------|-----|
| [FileCommander](https://github.com/ellmos-ai/ellmos-filecommander-mcp) | 47 | Dateisystem, Prozessverwaltung, interaktive Sitzungen, Cloud-Lock-sichere Operationen | [`ellmos-filecommander-mcp`](https://www.npmjs.com/package/ellmos-filecommander-mcp) |
| [CodeCommander](https://github.com/ellmos-ai/ellmos-codecommander-mcp) | 23 | Code-Analyse, JSON-Reparatur, Imports, Diffs, Regex | [`ellmos-codecommander-mcp`](https://www.npmjs.com/package/ellmos-codecommander-mcp) |
| [Clatcher](https://github.com/ellmos-ai/ellmos-clatcher-mcp) | 12 | Dateireparatur, Formatkonvertierung, Batch-Operationen | [`ellmos-clatcher-mcp`](https://www.npmjs.com/package/ellmos-clatcher-mcp) |
| [n8n Manager](https://github.com/ellmos-ai/n8n-manager-mcp) | 19 | n8n-Workflow-Verwaltung über KI-Assistenten | [`n8n-manager-mcp`](https://www.npmjs.com/package/n8n-manager-mcp) |
| [ControlCenter](https://github.com/ellmos-ai/ellmos-controlcenter-mcp) | 20 | MCP-Stack-Discovery, Profilverwaltung, Control Plane | [`ellmos-controlcenter-mcp`](https://www.npmjs.com/package/ellmos-controlcenter-mcp) |
| **[Homebase](https://github.com/ellmos-ai/ellmos-homebase-mcp)** | **51** | **Local-first LLM-Gedächtnis, Wissen, Zustand, Routing, Schwarm-Orchestrierung** | **[`ellmos-homebase-mcp`](https://www.npmjs.com/package/ellmos-homebase-mcp)** (alpha) |
| [ServerCommander](https://github.com/ellmos-ai/ellmos-servercommander-mcp) | 8 | Server-Operationen: Health-Checks, Log-Analyse, Deploy-Dry-Runs, Mail-Diagnose | [`ellmos-servercommander-mcp`](https://www.npmjs.com/package/ellmos-servercommander-mcp) (alpha) |
| [Blender Use](https://github.com/ellmos-ai/ellmos-blender-use-mcp) | 3 | Headless Blender-Asset-QA und FBX-Reimport-Verifikation | [`ellmos-blender-use-mcp`](https://www.npmjs.com/package/ellmos-blender-use-mcp) (alpha) |
| [Open Compute](https://github.com/ellmos-ai/open-compute-mcp) | 10 | Modell-agnostischer Computer-Use: Capture, safety-gated Aktionen, Windows-UIA | [`open-compute-mcp`](https://www.npmjs.com/package/open-compute-mcp) (alpha) |

### KI-Infrastruktur

| Projekt | Beschreibung |
|---------|-------------|
| [BACH](https://github.com/ellmos-ai/bach) | Local-first textbasiertes OS für LLM-Agenten — 113+ Handler, 550+ Tools, SQLite-Memory |
| [open-compute](https://github.com/ellmos-ai/open-compute) | Modell-agnostischer Computer-Use-Kern hinter Open Compute MCP |
| [clutch](https://github.com/ellmos-ai/clutch) | Provider-neutrale LLM-Orchestrierung mit Auto-Routing und Budget-Tracking |
| [rinnsal](https://github.com/ellmos-ai/rinnsal) | Leichte Agent-Memory-, Connector- und Automatisierungsinfrastruktur |
| [ellmos-stack](https://github.com/ellmos-ai/ellmos-stack) | Self-hosted AI Research Stack (Ollama + n8n + Rinnsal + KnowledgeDigest) |
| [MarbleRun](https://github.com/ellmos-ai/MarbleRun) | Autonomes Agent-Chain-Framework für Claude Code |
| [gardener](https://github.com/ellmos-ai/gardener) | Minimalistischer datenbankgetriebener LLM-OS-Prototyp (4 Funktionen, 1 Tabelle) |
| [ellmos-tests](https://github.com/ellmos-ai/ellmos-tests) | Testframework für LLM-Betriebssysteme (7 Dimensionen) |

### Desktop-Software & Geschwister-Ökosystem

Unsere Partner-Dachorganisation **[open-bricks](https://github.com/open-bricks)** und Schwesterorganisationen pflegen datenschutzkonforme, lokale Desktop-Software und Entwicklerwerkzeuge:

| Anwendung / Werkzeug | Organisation | Fokus & Integration |
|---|---|---|
| [ProFiler](https://github.com/file-bricks/ProFiler) | `file-bricks` | Lokaler Desktop-Datei-Organizer mit PII-sicherem Workspace-Exchange |
| [DokuZen](https://github.com/doc-bricks/DokuZen) | `doc-bricks` | Ablenkungsfreie Markdown- & PDF-Dokumentenverwaltung |
| [PDFtoPDFocr](https://github.com/doc-bricks/PDFtoPDFocr) | `doc-bricks` | Local-First PDF-OCR und Textebenen-Einbettung |
| [KnowledgeDigest](https://github.com/doc-bricks/KnowledgeDigest) | `doc-bricks` | Offline Dokumenten-Zusammenfassung und Embedding-Engine |
| [DevCenter](https://github.com/dev-bricks/DevCenter) | `dev-bricks` | Entwickler-Arbeitsplatz und Multi-Repository-Verwaltung |
| [CodeBox](https://github.com/dev-bricks/CodeBox) | `dev-bricks` | Isolierter Sandbox-Runner und lokaler Code-Ausführungsassistent |
| [MemoryHooker](https://github.com/ellmos-ai/memoryhooker-provenance) | `ellmos-ai` | Hook-basierte LLM-Gedächtnis-Provenienz und Sitzungsinjektion |
| [sqlite-transit-sync](https://github.com/ellmos-ai/sqlite-transit-sync) | `ellmos-ai` | Abhängigkeitsfreie SQLite-Schemamigration & Replikationsschicht |

## Sicherheit & Schwachstellenmeldung

`ellmos-homebase-mcp` folgt strikten Sicherheitsprinzipien für Offline-Betrieb, Zero-Egress und unprivilegierte Ausführung. Vollständige Richtlinien, SLAs und Kontaktwege sind in [SECURITY.md](SECURITY.md) dokumentiert:

- **Unterstützte Versionen**: `0.1.0-alpha.x`
- **Reaktions-SLA**: Erstbewertung und Rückmeldung innerhalb von **48 Stunden**.
- **Sicherheitskontakte**: `security@ellmos.ai` und `support@lukasgeiger.com`.
- **Private Advisory**: [GitHub Security Advisories](https://github.com/ellmos-ai/ellmos-homebase-mcp/security/advisories).

## Entwicklung

```powershell
$env:PYTHONIOENCODING = "utf-8"
$env:PYTHONDONTWRITEBYTECODE = "1"
python -m pytest -q
npm run smoke
npm pack --dry-run --json
```

Der nächste sinnvolle Schritt ist, optionale Ausführungsbackends nur explizit konfiguriert zu aktivieren.

## Bundles und Partner

Homebase MCP bleibt ein eigenständig nutzbarer Local-first-MCP-Server. In der
V4-Komposition ist er eine optionale **MCP-Zugangsfläche** des
`ellmos-memory-human-context-bundle`: Ein konfiguriertes System kann über ihn
Memory- und Human-Context-Fähigkeiten erreichen. Diese Zugangsrolle macht
Homebase nicht zum kanonischen Owner jeder Memory-, Wissens-, Zustands-,
Routing- oder Automatisierungsfunktion; der ausgewählte Host und die
Systemmanifeste behalten diese Bindungen.

Kanonische oder gebündelte Engines sind explizit konfigurierte
Integrationspartner, keine impliziten Ersetzungen dieses Servers. Verbindliche
Bundle-Mitgliedschaft, Versionen, Profile und private
Zusammensetzungsrezepte bleiben in den jeweiligen Bundle-Manifesten. Dieser
öffentliche Abschnitt dient ausschließlich der Discovery.