ellmos-homebase-mcp
Officialby ellmos-ai
README.md
# ellmos-homebase-mcp
<p align="center">
<img src="assets/homebase-logo.jpg" alt="ellmos Homebase MCP logo" width="640">
</p>
Alpha MCP server for **local-first LLM orchestration**: memory, knowledge, routing, swarm patterns, API probing, persistent state, tests, automation planning, and plugin discovery in one stdio server.
Homebase is designed primarily for **local LLMs** (Ollama, Qwen, Llama, or any locally-hosted model via a MCP-capable harness). All persistent storage uses SQLite with no cloud dependency. External LLM providers (Claude, Codex, Gemini, OpenAI) can also connect as MCP clients, but local, offline-capable setups are the primary target.
German README: [README_de.md](README_de.md)
*Part of the [ellmos-ai](https://github.com/ellmos-ai) family under the [open-bricks](https://github.com/open-bricks) umbrella.*
[](https://github.com/open-bricks)
[](https://github.com/ellmos-ai)
[](https://opensource.org/licenses/MIT)
[](NOTICE)
[](https://www.npmjs.com/package/ellmos-homebase-mcp)
[](https://www.python.org/)
[](https://nodejs.org/)
[](https://github.com/ellmos-ai/ellmos-homebase-mcp)
[](SECURITY.md)
[-blueviolet.svg)](https://sqlite.org/)
[-blueviolet.svg)](https://modelcontextprotocol.io/)
[](https://www.npmjs.com/package/ellmos-homebase-mcp)
[](tests/)
[](SECURITY.md)
[-success.svg)](SECURITY.md)
[](THIRD_PARTY_LICENSES.txt)
[](MARKETING-LOG.txt)
[](CHANGELOG.md)
[](https://github.com/astral-sh/ruff)
[](llms.txt)
[](https://github.com/ellmos-ai/ellmos-homebase-mcp/actions/workflows/tests.yml)
**Discoverability:** Published on [npm](https://www.npmjs.com/package/ellmos-homebase-mcp) as `ellmos-homebase-mcp` and maintained in the [`ellmos-ai`](https://github.com/ellmos-ai) organization.
> [!NOTE]
> **For AI Assistants & LLM Agents:** Machine-readable architecture summary, index, and tool capabilities are published in [llms.txt](llms.txt). MCP registry metadata is available in [server.json](server.json).
## Quick Navigation / Schnellnavigation
- [System Architecture](#system-architecture) (`#sec-01`)
- [Sequence Flow & Lifecycle](#sequence-flow--lifecycle) (`#sec-02`)
- [Core Capabilities & Security Invariants](#core-capabilities--security-invariants) (`#sec-03`)
- [Governance & Runtime Invariants](#governance--runtime-invariants) (`#sec-04`)
- [Target Personas & Discoverability](#target-personas--discoverability) (`#sec-05`)
- [Comparative Matrix vs. Alternatives](#comparative-matrix-vs-alternatives) (`#sec-06`)
- [Start Here](#start-here) (`#sec-07`)
- [Status](#status) (`#sec-08`)
- [Install](#install) (`#sec-09`)
- [MCP Client Configuration](#mcp-client-configuration) (`#sec-10`)
- [Server Configuration](#server-configuration) (`#sec-11`)
- [Tools](#tools) (`#sec-12`)
- [Discovery Context](#discovery-context) (`#sec-13`)
- [ellmos-ai Ecosystem](#ellmos-ai-ecosystem) (`#sec-14`)
- [Third-Party Licenses (THIRD_PARTY_LICENSES.md)](THIRD_PARTY_LICENSES.md) (`#sec-15`)
- [Security & Vulnerability Reporting](#security--vulnerability-reporting) (`#sec-16`)
- [Development](#development) (`#sec-17`)
- [License & Statutory Liability Disclaimer (§ 521 BGB)](#license--statutory-disclaimer) (`#sec-18`)
- [Marketing Log (MARKETING-LOG.txt)](MARKETING-LOG.txt) | [Changelog (CHANGELOG.md)](CHANGELOG.md) | [Legal Attribution (NOTICE)](NOTICE) | [Deutsche Version (README_de.md)](README_de.md)
---
<a id="sec-01"></a><a id="system-architecture"></a>
## System Architecture
```mermaid
flowchart TD
subgraph Clients ["MCP Clients (Local / Remote)"]
Ollama["Local LLMs (Ollama, Qwen, Llama)"]
Claude["Claude Code / Desktop"]
Codex["Codex / Antigravity"]
end
subgraph Transport ["Transport Layer"]
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 across 14 Functional Modules"]
Mem["hb_mem_* (SQLite Memory)"]
KB["hb_kb_* (Knowledge Digest)"]
State["hb_state_* (State & Tasks)"]
Route["hb_route_* (Model Router)"]
Swarm["hb_swarm_* (Swarm Patterns)"]
Api["hb_api_* (API Probing)"]
Conn["hb_conn_* (Connectors Queue)"]
Auto["hb_auto_* (Automation Chains)"]
Plug["hb_plug_* (Plugin Discovery)"]
Garden["hb_garden_* (Garden Store)"]
Test["hb_test_* (Self Tests)"]
Policy["hb_policy_* (Policy Registry, read-only)"]
Ticket["hb_ticket_* (Ticket Master, read-only)"]
Lock["hb_lock_* (Lock Master, read-only)"]
end
subgraph Storage ["Local Storage (Offline-First)"]
DB[(SQLite Storage ~/.homebase/)]
end
Clients --> Stdio
Stdio --> Server
Server --> Config
Server --> ToolGroups
ToolGroups --> DB
```
### Four-View Architectural Topology Projection
```text
+-------------------------------------------------------------------------------+
| VIEW 1: CALLER RUNTIMES, AGENT CLIENTS & ENTRYPOINTS |
| - Local LLM Engines: Ollama (Qwen, Llama, Mistral, DeepSeek), Local Harnesses|
| - Multi-Agent Orchestrators: Claude Code, Claude Desktop, OpenAI Codex, AGY |
| - IDE & Extension Interfaces: Cursor, VS Code MCP Extension, Windsurf |
| - stdio Protocol Transport: JSON-RPC 2.0 via Python Model Context Protocol |
+---------------------------------------+---------------------------------------+
| JSON-RPC 2.0 stdio (tools/list, tools/call)
v
+-------------------------------------------------------------------------------+
| VIEW 2: HOMEBASE MCP SOVEREIGN CORE & DISPATCH ORCHESTRATOR |
| - Core Server & Life Cycle: homebase.server (stdio loop, signal handling) |
| - Module Registry & Dispatch: homebase.registry (i18n schemas, locale norm) |
| - 51 Sovereign MCP Tools across 14 Specialized Functional Modules: |
| * Memory & Knowledge: hb_mem_* (SQLite memory), hb_kb_* (FTS5 search) |
| * State & Planning: hb_state_* (tasks & KV), hb_garden_* (garden store) |
| * Routing & Swarms: hb_route_* (offline routing), hb_swarm_* (blueprints) |
| * Exploration & Testing: hb_api_* (schema probe), hb_test_* (diagnostics) |
| * Integration & Staging: hb_conn_* (safe queues), hb_auto_* (chain plans) |
| * Extensibility: hb_plug_* (dry-run discovery, no remote code execution) |
| * Canonical Seams: hb_policy_*, hb_ticket_*, hb_lock_* (read-only views) |
+-------------------+-----------------------------------+-----------------------+
| |
v (bundled SQLite mode) v (canonical engine mode)
+---------------------------------------+ +-------------------------------------+
| VIEW 3: RUNTIME PERSISTENCE & | | VIEW 3-ALT: CANONICAL SEAMS |
| SQLITE STORAGE ENGINE | | (MODE-CONTRACT.md) |
| - Database: ~/.homebase/homebase.db | | - Policy Registry (hb_policy_*) |
| - Concurrency: Write-Ahead Log (WAL) | | - Ticket Master (hb_ticket_*) |
| - Multi-Agent Provenance: agent_id | | - Lock Master (hb_lock_*) |
| - Search Engine: SQLite FTS5 index | | - Fail-Closed Discipline: |
| - Integrity: Busy timeouts & rollback| | Raises CanonicalEngineUnavailable|
+-------------------+-------------------+ +-----------------+-------------------+
| |
+-------------------+-------------------+
|
v
+-------------------------------------------------------------------------------+
| VIEW 4: AIR-GAP DEFENSE PERIMETER, RUNASINVOKER & ZERO-EGRESS BOUNDARY |
| - 100% Local-First & Zero Egress: INV-LOCAL-01 (0 cloud calls, 0 telemetry) |
| - Unprivileged Execution: INV-PERM-08 (RunAsInvoker non-elevation principle) |
| - Engine Seam Integrity: INV-ENGINE-02 & INV-SEAM-03 (strict fail-closed) |
| - Deterministic Provenance: INV-PROV-04 (agent_id attribution on all state) |
| - Credential-Free Operation: INV-CRED-05 & INV-STAGE-06 (no tokens/secrets) |
| - Multi-Host Lock Defense: INV-SYNC-09 (.gitignore sync/lock immunity) |
| - Permissive Licensing: Zero-Copyleft stack (MIT, PSFL-2.0, Apache-2.0) |
| - Statutory SLA & Disclaimer: INV-SLA-10 (48h response SLA, § 521 BGB) |
+-------------------------------------------------------------------------------+
```
---
<a id="sec-02"></a><a id="sequence-flow--lifecycle"></a>
## Sequence Flow & Lifecycle
```mermaid
sequenceDiagram
autonumber
participant Client as MCP Client (Local LLM / Claude / Codex)
participant Stdio as Transport Layer (stdio)
participant Server as Server & Registry (homebase)
participant Module as Functional Module (hb_mem / hb_state / hb_route)
participant Engine as Engine Seam (Bundled vs Canonical)
participant DB as SQLite Storage (~/.homebase/)
Client->>Stdio: JSON-RPC 2.0 Request (tools/call: hb_mem_store, agent_id="agent-01")
Stdio->>Server: Decode & dispatch tool call
Server->>Module: Validate arguments & inject agent provenance
alt Bundled Engine Mode (Default)
Module->>DB: Execute SQLite query (WAL mode, busy timeout)
DB-->>Module: Return structured records / mutation status
else Canonical Engine Mode ([engines].mode = "canonical")
Module->>Engine: Seam check (Gardener / TASKPLAN / USMC)
alt Engine Available
Engine-->>Module: Delegate to canonical subsystem
else Engine Unreachable
Engine-->>Module: Raise CanonicalEngineUnavailable (Fail-Closed)
end
end
Module-->>Server: Format response in requested language (i18n: en/de/es/zh/ja/ru)
Server-->>Stdio: Encode JSON-RPC 2.0 Response
Stdio-->>Client: Result payload (Zero cloud egress, 100% local)
```
---
<a id="sec-03"></a><a id="core-capabilities--security-invariants"></a>
## Core Capabilities & Security Invariants
| Capability / Invariant | Guarantee | Technical Implementation |
|---|---|---|
| **100% Local-First & Zero-Egress** | Complete privacy and offline operation; no unexpected cloud communication or telemetry. | All persistent memory, knowledge, and state are saved in local SQLite (`~/.homebase/`). |
| **Strict Engine Seams & Fail-Closed** | No silent fallback into disconnected databases when requesting canonical systems. | [`MODE-CONTRACT.md`](MODE-CONTRACT.md) enforcement: raises `CanonicalEngineUnavailable` if target is unreachable. |
| **Team-Memory Provenance (`agent_id`)** | Deterministic audit trail and filterable ownership for multi-agent workflows. | Native `agent_id` tracking across memory facts, knowledge entries, and task state. |
| **Credential-Free Discovery & Planning** | Zero secret exposure during local routing recommendations and API probing. | `hb_route_*`, `hb_swarm_*`, and `hb_api_*` run without transmitting API keys or private tokens. |
| **Safe Plan-and-Queue Adapters** | Safe queueing and chain staging without arbitrary remote code execution. | `hb_conn_*` and `hb_auto_*` maintain plan-only queues and offline staging records. |
| **Full Native i18n Localization** | Seamless multilingual developer and agent interaction. | Localized tool descriptions and JSON schemas for `en`, `de`, `es`, `zh`, `ja`, `ru`. |
| **Non-Elevation & Secret Hygiene** | Unprivileged execution and strict credential exclusion from distribution. | Non-root compatibility; live configs/secrets ignored in `.gitignore` and `.npmignore`. |
| **Multi-OS CI Smoke Integrity** | Verified cross-platform reliability on all major operating systems. | Multi-version CI matrix covering Python 3.10–3.13 and Node.js 20–24 on Linux/Windows/macOS. |
---
<a id="sec-04"></a><a id="governance--runtime-invariants"></a>
## Governance & Runtime Invariants
| Invariant ID | Title & Scope | Guarantee & Technical Enforcement | Verification Seam |
|---|---|---|---|
| **`INV-LOCAL-01`** | **100% Local-First & Zero-Egress** | All persistent memory, knowledge entries, and task states are stored locally in SQLite (`~/.homebase/`). Zero telemetry, analytics, or unrequested outbound cloud network calls. | `tests/test_server_transport.py`, `tests/test_repository_hygiene.py` |
| **`INV-ENGINE-02`** | **Strict Engine Seams & Fail-Closed** | [`MODE-CONTRACT.md`](MODE-CONTRACT.md) enforcement: switching `[engines].mode = "canonical"` never silently falls back to bundled storage if the canonical engine is unreachable. | `tests/test_engine_seams.py` |
| **`INV-SEAM-03`** | **Canonical-Only Isolation** | `hb_policy_*`, `hb_ticket_*`, and `hb_lock_*` provide read-only views into policy-registry, ticket-master, and lock-master. They possess no bundled imitation and fail closed unconditionally. | `tests/test_new_seams.py` |
| **`INV-PROV-04`** | **Deterministic Provenance & Team-Memory** | Multi-agent coordination requires strict isolation. All memories, knowledge facts, and task transitions record `agent_id` attribution with SQLite WAL concurrency and busy timeouts. | `tests/test_module_contracts.py` |
| **`INV-CRED-05`** | **Credential-Free Discovery & Probing** | Model routing suggestions (`hb_route_*`), swarm pattern blueprints (`hb_swarm_*`), and API schema probing (`hb_api_*`) function without private API keys, tokens, or credentials. | `tests/test_module_contracts.py` |
| **`INV-STAGE-06`** | **Plan-Only Staging & Bounded Offline Queues** | Connector queues (`hb_conn_*`) and automation plans (`hb_auto_*`) record offline blueprints and dry-run staging manifests without executing arbitrary remote code or side-effects. | `tests/test_module_contracts.py` |
| **`INV-I18N-07`** | **Native Multilingual Schema Parity** | All 51 tool definitions, input schemas, and validation errors maintain 100% complete localization across 6 supported languages (`en`, `de`, `es`, `zh`, `ja`, `ru`). | `tests/test_i18n_completeness.py` |
| **`INV-PERM-08`** | **Non-Elevation & RunAsInvoker Principle** | Homebase runs strictly in unprivileged user space. It requires no administrator or root privileges and ignores sensitive local dotfiles and system credentials. | `tests/test_repository_hygiene.py` |
| **`INV-SYNC-09`** | **Multi-Host Lock & Conflict Discipline** | Strict exclusion of conflict copies (`*.sync-conflict-*`, `*-conflict-*`) and honor of multi-agent lock mechanisms (`LOCK.*`, `*.lock`) to preserve database integrity across hosts. | `tests/test_metadata.py` |
| **`INV-SLA-10`** | **48h Response, 5-Day Triage & 30-Day Remediation SLA** | Security disclosures sent to `security@ellmos.ai`, `support@lukasgeiger.com`, or `security@open-bricks.org` receive guaranteed initial response in <=48h, triage within 5 business days, and verified remediation within 30 calendar days. | `SECURITY.md`, `tests/test_metadata.py` |
---
<a id="sec-05"></a><a id="target-personas--discoverability"></a>
## Target Personas & Discoverability
Homebase is purpose-built to solve architectural and operational challenges across four core technical audiences:
### `[PERSONA-01]` Local LLM & Edge AI Developers
- **Profile & Objective:** AI engineers building offline or edge applications with Ollama, Qwen, or Llama models who need a robust orchestration harness.
- **Pain Points:** Cloud memory APIs introduce unwanted latency, privacy leaks, subscription billing, and network failure modes.
- **Homebase Solution:** Zero-cloud dependency, local SQLite WAL persistence (`~/.homebase/`), and 51 standard stdio tools providing memory, FTS5 knowledge search, and task tracking.
- **Reference Workflow:**
```json
{"tool": "hb_mem_store", "arguments": {"fact": "User prefers compact JSON output", "agent_id": "ollama-coder"}}
{"tool": "hb_kb_search", "arguments": {"query": "API routing rules", "fts": true}}
```
### `[PERSONA-02]` Multi-Agent Swarm Orchestrators & Swarm Architects
- **Profile & Objective:** System architects orchestrating multi-agent collectives (Claude Code, Codex, Antigravity, local agents) operating concurrently on shared codebases.
- **Pain Points:** State collisions, lack of origin tracking, race conditions in shared memory, and uncoordinated task delegation.
- **Homebase Solution:** Native `agent_id` provenance across all facts, memories, and task states; built-in swarm templates (boss/worker, chunked parallel, consensus voting via `hb_swarm_*`).
- **Reference Workflow:**
```json
{"tool": "hb_swarm_plan", "arguments": {"goal": "Audit security seams", "pattern": "consensus"}}
{"tool": "hb_state_task_create", "arguments": {"title": "Verify fail-closed mode", "agent_id": "worker-audit-01"}}
```
### `[PERSONA-03]` Enterprise Security & Data Governance Officers
- **Profile & Objective:** CISOs, SecOps teams, and compliance auditors in regulated industries (healthcare, finance, defense) evaluating developer agent toolchains.
- **Pain Points:** Silent cloud telemetry, unvetted remote side-effects, privilege escalation risks, and missing SLA assurances.
- **Homebase Solution:** Strict zero-egress architecture, fail-closed canonical engine seams (`MODE-CONTRACT.md`), unprivileged `RunAsInvoker` operation, and formal 48h Security Response SLA (`SECURITY.md`).
- **Reference Workflow:**
```json
{"tool": "hb_policy_list_rules", "arguments": {}}
```
*Guaranteed fail-closed behavior: raises `CanonicalEngineUnavailable` instead of silently falling back to insecure stubs.*
### `[PERSONA-04]` Cross-Framework AI Assistants & Pair Programmers
- **Profile & Objective:** Developers utilizing multiple AI coding assistants (Claude Desktop, Codex, Cursor, Gemini) seeking uniform context and tool parity across environments.
- **Pain Points:** Incompatible custom tool APIs, fragmented scratchpads, and lack of multilingual developer schemas.
- **Homebase Solution:** Standard stdio MCP transport, machine-readable project metadata (`llms.txt`, `server.json`, `glama.json`), and 100% complete schema localization across 6 languages (`en`, `de`, `es`, `zh`, `ja`, `ru`).
- **Reference Workflow:**
```json
{"tool": "hb_ticket_list", "arguments": {"folder": "ACTIVE"}}
```
### High-Intent Search & SEO Keywords
- **English Intent:** `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`.
- **German Intent:** `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`.
---
<a id="sec-06"></a><a id="comparative-matrix-vs-alternatives"></a>
## Comparative Matrix vs. Alternatives
Homebase provides a uniquely comprehensive, local-first MCP capability stack compared to specialized or cloud-bound alternatives:
| Architectural & Runtime Dimension | `ellmos-homebase-mcp` | Cloud Memory SaaS (Letta, Pinecone, LangSmith) | Generic Memory MCPs (mcp-server-memory, sqlite) | Heavy Agent Frameworks (CrewAI, AutoGen, LangGraph) | Ad-Hoc Scripts / Custom SQLite |
|---|---|---|---|---|---|
| **1. 100% Local-First & Zero Egress (`INV-LOCAL-01`)** | **Yes (100% local SQLite WAL, zero telemetry)** | No (Cloud-hosted, mandatory egress, PII risk) | Partial (Local file, but no strict egress contracts) | Variable (Often requires cloud API keys / SaaS) | Yes (Local, but no protocol guarantees) |
| **2. Engine Seams & Fail-Closed (`INV-ENGINE-02`)** | **Yes (Strict `MODE-CONTRACT.md`, raises error on failure)** | No (Opaque cloud failovers) | No (Single hardcoded backend) | No (Unchecked exceptions / silent fallbacks) | No (Ad-hoc failure handling) |
| **3. Canonical-Only Seams (`INV-SEAM-03`)** | **Yes (`hb_policy_*`, `hb_ticket_*`, `hb_lock_*` fail closed)** | No (No canonical system awareness) | No (No policy or lock integration) | No (No governance seam layer) | No (Manual coordination) |
| **4. Team-Memory & Attribution (`INV-PROV-04`)** | **Yes (Native `agent_id` on facts, knowledge, tasks)** | Partial (User-level only, lacks multi-agent filters) | No (Single global unpartitioned graph) | Partial (In-memory agent state, lost on restart) | No (Manual schema management) |
| **5. Credential-Free Discovery (`INV-CRED-05`)** | **Yes (Offline routing & swarm planning without tokens)** | No (Requires active paid cloud credentials) | No (No model routing or swarm tools) | No (Requires API keys for LLM planners) | No (No structured planning) |
| **6. Plan-Only Staging Queues (`INV-STAGE-06`)** | **Yes (Safe connector queues & dry-run automation)** | No (Direct execution or none) | No (No connector or automation support) | No (Direct runtime side-effects) | No (Unsafe arbitrary execution) |
| **7. Tool Breadth & Surface** | **51 Tools across 14 Modules in single stdio server** | 1-5 API endpoints | 2-5 basic tools | Framework-level Python library (not MCP native) | Fragmented CLI utilities |
| **8. Multilingual Schema Parity (`INV-I18N-07`)** | **Yes (Full en, de, es, zh, ja, ru schema coverage)** | English only | English only | English only | English only / None |
| **9. Non-Elevation Security (`INV-PERM-08`)** | **Yes (Unprivileged RunAsInvoker, dotfile defense)** | Cloud SaaS (Tenant-isolation trust model) | Variable (Local file permissions) | Variable (Often runs in root containers) | Variable (User scripts) |
| **10. Security Response SLA (`INV-SLA-10`)** | **Yes (Formal 48h Response, 5d Triage & 30d Remediation in `SECURITY.md`)** | Commercial SLA (Paid tiers only) | None / Best-effort community | None / Best-effort community | None |
---
<a id="sec-07"></a><a id="start-here"></a>
## Start Here
| Need | Entry point |
|---|---|
| Install the alpha MCP server | `npm install -g ellmos-homebase-mcp@alpha` |
| Run from a source checkout | `python -m homebase.server` with `PYTHONPATH=src` |
| Configure a local LLM harness, Claude Code, Codex, or any MCP client | [MCP Client Configuration](#mcp-client-configuration) |
| Inspect the machine-readable project summary | [llms.txt](llms.txt) |
| Check registry metadata | [server.json](server.json) |
---
<a id="sec-08"></a><a id="status"></a>
## Status
- Transport: stdio via the Python MCP SDK
- Package status: public alpha package under `ellmos-ai`
- Release metadata: MIT `LICENSE`, `NOTICE`, `CHANGELOG.md`, `llms.txt`, and MCP Registry metadata in `server.json`
- Test gate: GitHub Actions covers Python 3.10/3.11/3.12/3.13 plus Node.js 20/22/24 smoke and npm package checks
- Current core: module discovery, MCP tool listing, MCP tool dispatch, config fallbacks, local planning/probing/queue/dry-run adapters
- Real local SQLite modules: `hb_mem_*`, `hb_kb_*`, `hb_garden_*`, `hb_state_*`
- Engine seams: `hb_garden_*`, `hb_state_task_*` and `hb_mem_*` can delegate to the real
canonical Gardener/Rinnsal/USMC engines instead of the bundled SQLite copies via
`[engines].mode = "canonical"` (default remains `"bundled"` for a zero-dependency install).
**No silent fallback:** if you request `canonical` and the engine is unreachable, those tools
return an error rather than quietly using the bundled DB — the server still starts and lists
its tools. Binding rule and migration notes: **[MODE-CONTRACT.md](MODE-CONTRACT.md)**;
mechanism: [KONZEPT.md](KONZEPT.md#engine-seams-canonicalbundled--umsetzungsstand-2026-07-04-ticket-t-20260704-01).
- Canonical-only seams (no bundled alternative at all): `hb_policy_*` (policy-registry),
`hb_ticket_*` (ticket-master), `hb_lock_*` (lock-master) — all read-only in v1. A locally
faked copy of live policy/ticket/lock state would mislead rather than help, so these three
always attempt the canonical module and fail closed unconditionally if it is unreachable.
- Team-memory basics: `agent_id` provenance and filters for memory, knowledge, state memory, and tasks; SQLite uses WAL plus a busy timeout for safer concurrent agents
- Credential-free alpha adapters: `hb_route_*`, `hb_swarm_*`, `hb_api_*`, `hb_test_*`, `hb_conn_*`, `hb_auto_*`, `hb_plug_*`
- i18n: fully localized MCP tool descriptions, input-schema field descriptions, and unknown-tool errors for `en`, `de`, `es`, `zh`, `ja`, `ru` (English fallback for any unset key)
- Roadmap: optional real LLM/API integrations and explicit execution backends
---
<a id="sec-09"></a><a id="install"></a>
## Install
The npm package contains a Node wrapper that starts the Python server. You still need Python 3.10+ and the Python package `mcp>=1.0.0`.
### Option 1: Install From npm
```powershell
npm install -g ellmos-homebase-mcp@alpha
ellmos-homebase
```
### Option 2: Install From Source
```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 -ra -v
```
Avoid creating a `.venv` inside cloud-synced folders if your sync client locks files. If you need an isolated environment, create it outside that folder.
### Start From Source
```powershell
$env:PYTHONPATH = "src"
python -m homebase.server
```
---
<a id="sec-10"></a><a id="mcp-client-configuration"></a>
## MCP Client Configuration
Homebase uses the standard stdio `mcpServers` configuration format. The same snippet works in any MCP-capable client or harness: BACH/Buddha (local Ollama), Claude Code, Codex, Cursor, or any other MCP host.
> **Note on local LLMs:** A bare Ollama instance does not speak MCP natively — you need a MCP-capable harness on top of it (e.g., BACH, an open-source MCP proxy, or another orchestration layer). Configure that harness to include Homebase as an MCP server using the snippet below.
### Global npm Install
```json
{
"mcpServers": {
"homebase": {
"command": "ellmos-homebase"
}
}
}
```
### Source Checkout
```json
{
"mcpServers": {
"homebase": {
"command": "python",
"args": ["-m", "homebase.server"],
"env": {
"PYTHONPATH": "/absolute/path/to/ellmos-homebase-mcp/src"
}
}
}
}
```
Replace `/absolute/path/to/ellmos-homebase-mcp` with your local checkout path.
---
<a id="sec-11"></a><a id="server-configuration"></a>
## Server Configuration
Example: [config/homebase.example.toml](config/homebase.example.toml)
Machine-readable project context: [llms.txt](llms.txt)
MCP Registry metadata: [server.json](server.json)
Default paths:
- `%USERPROFILE%\.homebase\homebase.toml`
- `%USERPROFILE%\.config\homebase\homebase.toml`
- override with `HOMEBASE_CONFIG`
Language can be configured with `[server].language`, `HOMEBASE_LANG`, or `HOMEBASE_LOCALE`.
The writing agent can be passed per tool call as `agent_id`; otherwise modules use
`HOMEBASE_AGENT_ID`, `AGENT_ID`, a module-level `agent_id`, or `unknown`.
```toml
[server]
name = "ellmos-homebase"
language = "en" # en, de, es, zh, ja, ru
[modules]
enabled = ["mem", "route", "kb", "swarm", "state", "garden", "api", "test", "conn", "auto", "plug"]
```
Modules with missing optional dependencies are skipped without blocking server startup.
---
<a id="sec-12"></a><a id="tools"></a>
## Tools
Important tool groups:
- `hb_mem_*` for SQLite-backed memory
- `hb_kb_*` for SQLite-backed knowledge entries
- `hb_state_*` for persistent SQLite state and tasks
- `hb_garden_*` for a small SQLite garden store
- `hb_route_*` for credential-free model-routing recommendations and feedback stats
- `hb_swarm_*` for credential-free swarm planning patterns
- `hb_api_*` for passive HTTP API discovery with SQLite history
- `hb_test_*` for built-in metadata and smoke self-tests
- `hb_conn_*` for a local connector registry plus SQLite-backed inbox/outbox queues without network sends
- `hb_auto_*` for local automation chain definitions and queued plan-only runs without backend execution
- `hb_plug_*` for local plugin discovery and dry-run records without executing plugin code
- `hb_policy_*` (read-only, canonical-only) for resolving/listing policy-registry rules
- `hb_ticket_*` (read-only, canonical-only) for listing/showing ticket-master tickets by lifecycle folder
- `hb_lock_*` (read-only, canonical-only) for checking/listing active lock-master locks
---
<a id="sec-13"></a><a id="discovery-context"></a>
## Discovery Context
Use `ellmos-homebase-mcp` when searching for a local-first, offline-capable MCP server that gives local LLMs (Ollama, Qwen, Llama, or similar) persistent memory, knowledge management, routing, and orchestration — without requiring any cloud dependency. External LLM providers can also use it as an MCP server, but local-first setups are the primary design target.
Good search phrases:
- `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`
Not the same as Elmo/ELMO voice tools, AllenAI ELMo embeddings, Eclipse LMOS, generic cloud agent platforms, or single-purpose MCP memory servers.
---
<a id="sec-14"></a><a id="ellmos-ai-ecosystem"></a>
## ellmos-ai Ecosystem
This MCP server is part of the **[ellmos-ai](https://github.com/ellmos-ai)** ecosystem — AI infrastructure, MCP servers, and intelligent tools.
### MCP Server Family
| Server | Tools | Focus | npm |
|--------|-------|-------|-----|
| [FileCommander](https://github.com/ellmos-ai/ellmos-filecommander-mcp) | 47 | Filesystem, process management, interactive sessions, cloud-lock-safe operations | [`ellmos-filecommander-mcp`](https://www.npmjs.com/package/ellmos-filecommander-mcp) |
| [CodeCommander](https://github.com/ellmos-ai/ellmos-codecommander-mcp) | 23 | Code analysis, JSON repair, imports, diffs, regex | [`ellmos-codecommander-mcp`](https://www.npmjs.com/package/ellmos-codecommander-mcp) |
| [Clatcher](https://github.com/ellmos-ai/ellmos-clatcher-mcp) | 12 | File repair, format conversion, batch operations | [`ellmos-clatcher-mcp`](https://www.npmjs.com/package/ellmos-clatcher-mcp) |
| [n8n Manager](https://github.com/ellmos-ai/n8n-manager-mcp) | 19 | n8n workflow management via AI assistants | [`n8n-manager-mcp`](https://www.npmjs.com/package/n8n-manager-mcp) |
| [ControlCenter](https://github.com/ellmos-ai/ellmos-controlcenter-mcp) | 20 | MCP stack discovery, profile management, 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 memory, knowledge, state, routing, swarm orchestration** | **[`ellmos-homebase-mcp`](https://www.npmjs.com/package/ellmos-homebase-mcp)** (alpha) |
| [ServerCommander](https://github.com/ellmos-ai/ellmos-servercommander-mcp) | 8 | Server operations: health checks, log analysis, deploy dry-runs, mail diagnostics | [`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 and FBX reimport verification | [`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 | Model-agnostic computer use: capture, safety-gated actions, Windows UIA | [`open-compute-mcp`](https://www.npmjs.com/package/open-compute-mcp) (alpha) |
### AI Infrastructure
| Project | Description |
|---------|-------------|
| [BACH](https://github.com/ellmos-ai/bach) | Local-first text-based OS for LLM agents — 113+ handlers, 550+ tools, SQLite memory |
| [open-compute](https://github.com/ellmos-ai/open-compute) | Model-agnostic computer-use core powering Open Compute MCP |
| [clutch](https://github.com/ellmos-ai/clutch) | Provider-neutral LLM orchestration with auto-routing and budget tracking |
| [rinnsal](https://github.com/ellmos-ai/rinnsal) | Lightweight agent memory, connectors, and automation infrastructure |
| [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) | Autonomous agent chain framework for Claude Code |
| [gardener](https://github.com/ellmos-ai/gardener) | Minimalist database-driven LLM OS prototype (4 functions, 1 table) |
| [ellmos-tests](https://github.com/ellmos-ai/ellmos-tests) | Testing framework for LLM operating systems (7 dimensions) |
### Desktop Software & Sibling Ecosystem
Our partner umbrella organization **[open-bricks](https://github.com/open-bricks)** and sister organizations maintain local-first, privacy-centric desktop software and developer tools:
| Application / Tool | Organization | Focus & Integration |
|---|---|---|
| [ProFiler](https://github.com/file-bricks/ProFiler) | `file-bricks` | Local-first desktop file organizer and PII-safe workspace exchange |
| [DokuZen](https://github.com/doc-bricks/DokuZen) | `doc-bricks` | Distraction-free Markdown & PDF documentation manager |
| [PDFtoPDFocr](https://github.com/doc-bricks/PDFtoPDFocr) | `doc-bricks` | Local-first PDF OCR and text layer embedding |
| [KnowledgeDigest](https://github.com/doc-bricks/KnowledgeDigest) | `doc-bricks` | Offline document summarization and embedding engine |
| [DevCenter](https://github.com/dev-bricks/DevCenter) | `dev-bricks` | Developer workspace hub and multi-repository management |
| [CodeBox](https://github.com/dev-bricks/CodeBox) | `dev-bricks` | Isolated sandbox runner and local code execution assistant |
| [MemoryHooker](https://github.com/ellmos-ai/memoryhooker-provenance) | `ellmos-ai` | Hook-based LLM memory provenance and session injection gate |
| [sqlite-transit-sync](https://github.com/ellmos-ai/sqlite-transit-sync) | `ellmos-ai` | Zero-dependency SQLite schema migration & replication layer |
---
<a id="sec-15"></a><a id="third-party-licenses"></a>
## Third-Party Licenses & Level 1 SBOM
`ellmos-homebase-mcp` is verified to contain 0% copyleft dependencies. All runtime dependencies are permissively licensed (MIT, BSD-2-Clause, Apache-2.0, PSFL).
Full inventory, Level 1 SBOM Invariant Cross-Reference Matrix, and non-elevation certifications are documented in [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) and plain-text companion [THIRD_PARTY_LICENSES.txt](THIRD_PARTY_LICENSES.txt). Canonical copyright and author attribution is maintained in [NOTICE](NOTICE).
---
<a id="sec-16"></a><a id="security--vulnerability-reporting"></a>
## Security & Vulnerability Reporting
`ellmos-homebase-mcp` strictly adheres to local-first, zero-egress, and non-elevation security principles. Full policies, SLAs, and security guarantees are documented in [SECURITY.md](SECURITY.md):
- **Supported Versions**: `0.1.0-alpha.x`
- **Response SLA**: Initial acknowledgment and triage within **48 hours**. Detailed triage within 5 business days; remediation within 30 calendar days.
- **Security Contacts**: `security@ellmos.ai`, `support@lukasgeiger.com`, and `security@open-bricks.org`.
- **Private Advisory**: [GitHub Security Advisories](https://github.com/ellmos-ai/ellmos-homebase-mcp/security/advisories).
---
<a id="sec-17"></a><a id="development"></a>
## Development
```powershell
$env:PYTHONIOENCODING = "utf-8"
$env:PYTHONDONTWRITEBYTECODE = "1"
python -m pytest -ra -v
npm run smoke
npm pack --dry-run --json
```
Next useful step: add optional execution backends behind explicit configuration.
---
<a id="sec-18"></a><a id="license--statutory-disclaimer"></a>
## License & Statutory Liability Disclaimer (§ 521 BGB)
### Software License
`ellmos-homebase-mcp` is open-source software licensed under the **[MIT License](LICENSE)**.
Canonical attribution to Lukas Geiger, the `ellmos-ai` family, and the `open-bricks` ecosystem is formally preserved in [`NOTICE`](NOTICE).
Third-party component licenses are cataloged in [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md).
### Statutory Notice & Liability Limitation (§ 521 BGB - German Law)
This software is made available free of charge as an open-source project. Under German statutory law governing gratuitous software provision (**§ 521 BGB Gefälligkeitsrecht**):
1. **Liability Limitation**: The author and contributors are liable only in cases of intentional misconduct (**Vorsatz**) or gross negligence (**grobe Fahrlässigkeit**).
2. **Warranty Limitation**: In accordance with §§ 523, 524 BGB, warranty claims for material and legal defects (**Sach- und Rechtsmängel**) are excluded, except in cases where defects have been fraudulently concealed (**arglistiges Verschweigen**).
3. **Local-First & Non-Elevation Principle**: `ellmos-homebase-mcp` is provided on an "as is" and "as available" basis without any express or implied warranty. Operators run Homebase in unprivileged user mode (`RunAsInvoker`) at their own discretion.
### Coordinated Security Response SLA
For vulnerability reporting or security inquiries, our coordinated disclosure policy guarantees an initial response within **48 hours** and triage within 5 business days:
- Security Contact: `security@ellmos.ai` | `support@lukasgeiger.com` | `security@open-bricks.org`
- Advisory Portal: [GitHub Security Advisories](https://github.com/ellmos-ai/ellmos-homebase-mcp/security/advisories)
- Policy Documentation: [`SECURITY.md`](SECURITY.md)
---
## Bundles and partners
Homebase MCP remains a standalone local-first MCP server. In the V4
composition it is an optional **MCP access surface** of the
`ellmos-memory-human-context-bundle`: a configured system may use it to reach
memory and human-context capabilities. This access role does not make Homebase
the canonical owner of every memory, knowledge, state, routing or automation
function; the selected host and system manifests retain those bindings.
Canonical or bundled engines are integration partners selected by explicit
configuration, not implicit replacements for this server. Authoritative
bundle membership, versions, profiles and private composition recipes remain
in the corresponding bundle manifests. This public section is discovery-only.
TDQS
C2.7/5.0
Scored across 51 tools
Disambiguation4/5
Most tools are cleanly separated by domain prefix and verb. Minor overlaps exist: hb_api_probe vs hb_api_discover (probe-all-strategies vs schema auto-detect), and hb_mem_* vs hb_state_mem_* memory families could be confused by an agent. The many *_run/*_list/*_get tools are differentiated by their domain prefix, so ambiguity is limited.
Naming Consistency4/5
Strong, predictable hb_<domain>_<verb> pattern across nearly all tools (hb_kb_search, hb_mem_store, hb_lock_check). A few deviations: hb_auto_list_chains inverts the order used by hb_auto_run/status/result, and accessors are inconsistently named hb_garden_get / hb_kb_get vs hb_ticket_show.
Tool Count2/5
51 tools is well above the heavy threshold and far beyond what an agent can reliably select from in one session. The surface bundles at least a dozen separate domains (plugins, memory, routing, KB, swarm, state, garden, API, tests, connectors, automation, policy, tickets, locks), which should be split into focused servers.
Completeness3/5
Coverage is broad per domain but shallow: plugins have no install/enable, KB and garden lack update/delete, tasks have create/update but no delete, and policy/ticket tools are read-only by design. Read-only design is defensible, but the missing mutating operations leave lifecycle dead ends in several domains.
Maintenance
ActivityActive
ResponsivenessNo issues