ellmos-homebase-mcp
ellmos-ai/ellmos-homebase-mcp
Alpha MCP server for local-first LLM orchestration: memory, knowledge, state, routing, swarm planning, API discovery, tests, automation, and plugins.
Instalação
npx convez-ai ellmos-ai/ellmos-homebase-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
ellmos-homebase-mcp
Alpha MCP server for local LLM orchestration: memory, knowledge, routing, swarm patterns, API probing, persistent state, tests, automation planning, and plugin discovery in one stdio server.
German README: README_de.md
Part of the ellmos-ai family.
Discoverability: Published on npm as ellmos-homebase-mcp and maintained in the ellmos-ai organization.
Status
- Transport: stdio via the Python MCP SDK
- Package status: public alpha package under
ellmos-ai - Release metadata: MIT
LICENSE,CHANGELOG.md,llms.txt, and MCP Registry metadata inserver.json - Test gate: GitHub Actions covers Python 3.10/3.11/3.12 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_* - Credential-free alpha adapters:
hb_route_*,hb_swarm_*,hb_api_*,hb_test_*,hb_conn_*,hb_auto_*,hb_plug_* - i18n: localized MCP tool descriptions, input-schema field descriptions, and unknown-tool errors for
en,de,es,zh,ja,ruwith English fallback - Roadmap: optional real LLM/API integrations and explicit execution backends
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
npm install -g ellmos-homebase-mcp@alpha
ellmos-homebase
Option 2: Install From Source
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
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
$env:PYTHONPATH = "src"
python -m homebase.server
MCP Client Configuration
Global npm Install
{
"mcpServers": {
"homebase": {
"command": "ellmos-homebase"
}
}
}
Source Checkout
{
"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.
Server Configuration
Example: config/homebase.example.toml
Machine-readable project context: llms.txt
MCP Registry metadata: 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.
[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.
Tools
Important tool groups:
hb_mem_*for SQLite-backed memoryhb_kb_*for SQLite-backed knowledge entrieshb_state_*for persistent SQLite state and taskshb_garden_*for a small SQLite garden storehb_route_*for credential-free model-routing recommendations and feedback statshb_swarm_*for credential-free swarm planning patternshb_api_*for passive HTTP API discovery with SQLite historyhb_test_*for built-in metadata and smoke self-testshb_conn_*for a local connector registry plus SQLite-backed inbox/outbox queues without network sendshb_auto_*for local automation chain definitions and queued plan-only runs without backend executionhb_plug_*for local plugin discovery and dry-run records without executing plugin code
Development
$env:PYTHONIOENCODING = "utf-8"
$env:PYTHONDONTWRITEBYTECODE = "1"
python -m pytest -q
npm run smoke
npm pack --dry-run --json
Next useful step: add optional execution backends behind explicit configuration.