ellmos-homebase-mcp

Alpha MCP server for local LLM orchestration: memory, knowledge, routing, swarm patterns, API probing, persistent state, tests, and later automation in one stdio server.

German README: README_de.md

Status

• Transport: stdio via the Python MCP SDK
• Package status: public alpha package under ellmos-ai
• Current core: module discovery, MCP tool listing, MCP tool dispatch, config fallbacks, local planning/probing adapters
• Real local SQLite modules: hb_mem_*, hb_kb_*, hb_garden_*, hb_state_*
• Credential-free alpha adapters: hb_route_*, hb_swarm_*, hb_api_*, hb_test_*
• i18n: localized MCP tool descriptions, input-schema field descriptions, and unknown-tool errors for en, de, es, zh, ja, ru with English fallback
• Roadmap: backend execution adapters for automation, connectors, plugins, and optional real LLM/API integrations

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.

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

For local development:

cd "C:\Users\User\OneDrive\.TOPICS\.AI\.MCP\ellmos-homebase-mcp"
$env:PYTHONIOENCODING = "utf-8"
python -m pip install -e ".[dev]"
python -m pytest -q

Do not create a .venv inside a OneDrive-synced folder. If you need an isolated environment, create it outside OneDrive.

Start From Source

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

Configuration

Example: config/homebase.example.toml

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.

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

[modules]
enabled = ["mem", "route", "kb", "swarm", "state", "garden", "api", "test"]

Modules with missing optional dependencies are skipped without blocking server startup.

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

Development

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

Next useful step: wire the remaining automation, connector, and plugin modules to credential-free local adapters, then add optional execution backends behind explicit configuration.