MiniSearch
immortalbob/MiniSearch
API unificada de busca local com roteamento inteligente para homelabs
Ver no GitHubUm broker de conhecimento local para homelabs que unifica consultas para múltiplas fontes (Kiwix, FreshRSS, SearXNG, Open-Meteo, Uptime Kuma, Home Assistant) através de uma única API. Implementa roteamento inteligente assistido por LLM com fusão automática de múltiplas fontes, expondo tanto REST API quanto servidor MCP para integração nativa com Open WebUI e Home Assistant.
Instalação
npx convez-ai immortalbob/MiniSearch1 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
Casos de uso
- Consolidar buscas em conhecimento offline, RSS, previsão do tempo e status de serviços
- Implementar assistentes de voz inteligentes com roteamento automático de consultas
- Integrar múltiplas fontes de dados em pipelines de automação doméstica
Veredito

Excelente solução para quem mantém infraestrutura local. O roteamento inteligente com fusão de fontes é robusto, e a dupla exposição REST+MCP amplia significativamente o alcance. Recomendado para automação doméstica avançada e homelabs.
README
A tradução para o português deste README ainda está na fila.
MiniSearch
A unified local knowledge search API for self-hosted homelabs. MiniSearch runs as a Docker container on your internal network and routes queries to the appropriate backend — offline knowledge, weather forecast, RSS news, live web search, service monitoring, or multiple sources concurrently — via a single endpoint.
Exposes both a REST API and an MCP server so any client can connect to it.
Architecture
Voice Assistant Flow
ESP32 Voice Assistant
│
▼
Home Assistant
│
▼
MiniSearch Intents
│
▼
MiniSearch
│
├────────────────────┐
│ │
▼ ▼
LLM Backend Source Providers
│ ├─ Kiwix
│ ├─ FreshRSS
▼ ├─ SearXNG
Smart Routing ├─ Open-Meteo
├─ Single source ├─ Uptime Kuma
└─ Auto-fusion ────►└─ Home Assistant
│
▼
Response
│
▼
Home Assistant TTS
│
▼
ESP32
Multi-Client Architecture
Open WebUI Claude Desktop Cursor Home Assistant
│ │ │ (MiniSearch Intents)
REST API MCP MCP REST API
│ │ │ │
└────────────────┴─────────────┴───────────────┘
│
▼
MiniSearch
│
Smart Routing
┌────────────┴────────────┐
▼ ▼
Single Source Auto-Fusion
(keyword or LLM) (multi-keyword or LLM)
│ │
└────────────┬────────────┘
│
┌────┴────┐
▼ ▼
REST API MCP/SSE
│ │
Home Assistant Any MCP
(MiniSearch Intents) Client
│
Voice Pipeline
Source Fusion
source="auto" source="fusion"
│ │
▼ ▼
Keyword scan all sources LLM picks 2-3 sources
Multiple match? → fuse (or you specify explicitly)
Single match? → direct │
│ │
└────────────┬───────────────┘
│
┌───────────┼───────────┐
▼ ▼ ▼
Kiwix HA Forecast
FreshRSS SearXNG Uptime
(any combination of available sources,
queried concurrently)
│ │ │
└───────────┴───────────┘
│
Filter empty / failed results
Partial failure OK — best effort
│
Merge with [SOURCE] attribution headers
│
Single Response
Fusion queries all specified sources concurrently, filters empty or failed results, and merges the remainder with source attribution headers. If only one source returns results, it is returned directly without headers.
Integrations
| Client | Protocol | How |
|---|---|---|
| Open WebUI | REST | Lightweight tool that POSTs to /search |
| MiniSearch Intents | REST | Native HA LLM API integration |
| Any MCP client (Claude Desktop, Cursor, etc.) | MCP/SSE | Connect to http://your-host:8888/mcp/sse |
Sources
| Source | Backend | Description |
|---|---|---|
kiwix | Kiwix | Offline knowledge base — Wikipedia, Stack Exchange, iFixit, FreeCodeCamp, DevDocs |
forecast | Open-Meteo | 3-day weather forecast, no API key required |
news | FreshRSS | Recent articles from your RSS feeds via GReader API |
web | SearXNG | Live web search via your local SearXNG instance |
uptime | Uptime Kuma | Service monitor status — reports any down services |
ha | Home Assistant | Entity state summaries — lights, locks, sensors, motion, batteries, power |
fusion | — | Query multiple sources concurrently and merge results |
auto | — | MiniSearch detects intent and picks the best source |
Requirements
- Docker + Docker Compose
- A Docker network for container communication (default:
ai-net) - One or more of the supported backends running and reachable on the same network
Quick Start
Full stack (recommended)
The repo includes an example compose file and SearXNG config to get all services running together:
git clone https://github.com/immortalbob/MiniSearch
cd MiniSearch
# Create the shared network if it doesn't exist
docker network create ai-net
# Copy and edit the example compose file
cp docker-compose.example.yml docker-compose.yml
# Fill in credentials, your coordinates, and secret_key in searxng/settings.yml
docker compose up -d
What's not in the full stack
The example compose intentionally excludes Home Assistant, your LLM backend, and Uptime Kuma — these are typically long-running services with their own existing setup.
If you're running any of these in Docker and want them reachable by MiniSearch, connect them to ai-net:
docker network connect ai-net ollama
docker network connect ai-net homeassistant
MiniSearch only
If you already have the backends running:
git clone https://github.com/immortalbob/MiniSearch
cd MiniSearch
# Edit docker-compose.yml with your settings
docker compose up -d
Hit http://your-host:8888/health to confirm it's running.
Full API docs at http://your-host:8888/docs.
Configuration
All settings are passed as environment variables in docker-compose.yml:
| Variable | Description | Default |
|---|---|---|
KIWIX_URL | Kiwix container URL | http://kiwix:8080 |
FRESHRSS_URL | FreshRSS container URL | http://freshrss |
FRESHRSS_USER | FreshRSS username | |
FRESHRSS_API_PASSWORD | FreshRSS API password | |
FRESHRSS_MAX_ARTICLES | Max articles to fetch | 10 |
SEARXNG_URL | SearXNG container URL | http://searxng:8080 |
FORECAST_LATITUDE | Forecast location latitude | 35.1894 |
FORECAST_LONGITUDE | Forecast location longitude | -114.0530 |
FORECAST_LOCATION_NAME | Human-readable location name | Kingman, Arizona |
FORECAST_TIMEZONE | Timezone for forecast times | America/Phoenix |
UPTIME_KUMA_URL | Uptime Kuma URL | (blank — disables uptime source) |
UPTIME_KUMA_USERNAME | Uptime Kuma username | |
UPTIME_KUMA_PASSWORD | Uptime Kuma password | |
HA_URL | Home Assistant URL | (blank — disables HA source) |
HA_TOKEN | Home Assistant long-lived access token | |
LLM_URL | LLM backend URL for intelligent routing | (blank — disables LLM routing) |
LLM_MODEL | Model to use for source and book selection | qwen3:8b |
LLM_API_TYPE | API format: ollama or openai | ollama |
FreshRSS API setup
- Enable API access: Administration → Authentication → Allow API access
- Set an API password: Profile → API password
- Use that password for
FRESHRSS_API_PASSWORD(it's separate from your login password)
SearXNG JSON format
MiniSearch queries SearXNG's JSON API. The included searxng/settings.yml already has this enabled. If you're using an existing SearXNG instance, make sure json is in your formats list:
search:
formats:
- html
- json
Also generate a unique secret_key in searxng/settings.yml:
openssl rand -hex 32
LLM-assisted routing
MiniSearch uses a local LLM backend in three ways:
- Source selection — when
autois used and no keyword matches, the LLM picks the best source based on the query. For complex multi-topic queries it returns multiple sources, triggering fusion automatically. - Book selection — once routed to Kiwix, the LLM picks the best 1-2 ZIM books from your catalog for the query
- Fusion source selection — when
fusionis used without specifying sources, the LLM picks the best 2-3 sources for the query
Auto-fusion escalation — source="auto" now detects multi-topic queries at the keyword level too. If a query matches triggers from multiple sources (e.g. "weather" + "services up"), fusion is triggered automatically without an LLM call.
Routing decisions are cached for 1 hour so repeated queries skip the LLM call entirely.
Supported backends via LLM_API_TYPE:
ollama— Ollama native API (default)openai— OpenAI-compatible API (llama-server, LM Studio, etc.)
The book list is built dynamically from your Kiwix catalog at startup. To force a refresh after adding ZIMs:
curl -X POST http://your-host:8888/catalog/refresh
If LLM_URL is left blank, MiniSearch falls back to keyword-based routing and Wikipedia for all Kiwix queries.
Home Assistant setup
Generate a long-lived access token in Home Assistant:
- Go to your Profile (click your username in the sidebar)
- Scroll to Long-lived access tokens
- Click Create Token, give it a name, copy the token
- Set
HA_URLto your HA instance URL (e.g.http://192.168.3.6:8123) - Set
HA_TOKENto the generated token
The ha source handles analytical queries that go beyond HA's built-in single-entity intent handling:
- "house status summary" — lights, locks, sensors, motion, batteries
- "indoor air quality" — CO2, temperature, humidity from indoor sensors
- "security status" — locks, doors, recent motion with time-ago
- "battery status" — all device battery levels
- "outdoor conditions" — weather station sensors
- "how much power am I using" — current and historical consumption
The ha source also participates in fusion — "house status and what's the weather" automatically fuses ha + forecast.
REST API
POST /search
Single source:
{
"query": "what is molybdenum",
"source": "auto"
}
Fusion — LLM picks sources automatically:
{
"query": "what is happening with the space program lately",
"source": "fusion"
}
Fusion — explicit source list:
{
"query": "what is happening with the space program lately",
"source": "fusion",
"fusion_sources": ["kiwix", "web", "news"]
}
Response:
{
"query": "what is molybdenum",
"source_used": "kiwix",
"result": "# Molybdenum\nSource: wikipedia_en_all_maxi_2026-02\n\n...",
"success": true,
"cached": false,
"error": null
}
GET /sources
Returns the list of available sources.
GET /health
Returns status, number of Kiwix books loaded, and current result cache entry count.
GET /catalog
Lists all books currently loaded from the Kiwix OPDS catalog.
POST /catalog/refresh
Forces a re-scan of the Kiwix catalog without restarting the container.
GET /cache
Shows all current result cache entries with age and remaining TTL.
POST /cache/clear
Clears all result cache entries from memory and disk.
GET /cache/routing
Shows all current routing cache entries — source and Kiwix book selection decisions cached to avoid redundant LLM calls.
POST /cache/routing/clear
Clears all routing cache entries from memory and disk.
Caching
MiniSearch caches results in memory and persists them to disk so the cache survives container restarts. TTLs are set per source:
| Source | TTL |
|---|---|
kiwix | 24 hours |
web | 1 hour |
fusion | 30 minutes |
forecast | 30 minutes |
news | 15 minutes |
uptime | 1 minute |
ha | 30 seconds |
Routing decisions (which source, Kiwix books, and fusion source sets to use) are cached separately for 1 hour.
MCP
MiniSearch exposes an MCP server via SSE at /mcp/sse on the same port as the REST API.
Connecting Claude Desktop
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"minisearch": {
"url": "http://your-host-ip:8888/mcp/sse"
}
}
}
Connecting any MCP client
SSE endpoint: http://your-host-ip:8888/mcp/sse
The MCP server exposes a single search tool with the same interface as the REST API, including fusion_sources support.
Kiwix ZIM files
Download ZIM files from library.kiwix.org and place them in ./data/kiwix/. The example compose mounts this directory into the Kiwix container automatically.
Popular ZIMs for a homelab stack:
wikipedia_en_all_maxi— full English Wikipediaunix.stackexchange.com_en_all— Unix & Linux Stack Exchangeraspberrypi.stackexchange.com_en_all— Raspberry Pi Stack Exchangeifixit_en_all— iFixit repair guidesfreecodecamp_en_all— FreeCodeCampdevdocs_en_python— Python DevDocs
Adding a New Source
- Create
app/sources/your_source.pywith asearch(query: str) -> strfunction - Add any config vars to
app/config.pyanddocker-compose.yml - Import and register it in
app/router.py— add toSOURCE_MAP,INTENT_MAP,SOURCE_DESCRIPTIONS, andCACHE_TTL - Rebuild:
docker compose up -d --build
The new source is automatically available via both REST and MCP — and immediately fusable with any other source.
Running Tests
docker exec minisearch python3 -m pytest /app/tests/ -v
202 tests covering intent routing, multi-keyword fusion escalation, cache logic, routing cache, Kiwix scoring and stemming, search term cleaning, FreshRSS article filtering, all source modules via mocking, fusion behavior, and Home Assistant entity filtering.
Project Structure
MiniSearch/
├── Dockerfile
├── docker-compose.yml # your config (not committed)
├── docker-compose.example.yml # full stack example
├── requirements.txt
├── pytest.ini
├── CHANGELOG.md
├── minisearch_tool.py # Open WebUI bridge tool
├── README.md
├── searxng/
│ └── settings.yml # SearXNG config with JSON enabled
├── tests/
│ ├── test_router.py # intent detection, cache, fallback logic
│ ├── test_routing_cache.py # routing cache logic
│ ├── test_kiwix.py # scoring and search term cleaning
│ ├── test_freshrss.py # general query detection, article scoring
│ ├── test_freshrss_network.py # FreshRSS network calls via mocking
│ ├── test_forecast.py # forecast parsing and thresholds via mocking
│ ├── test_searxng.py # SearXNG search and guard via mocking
│ ├── test_uptime_kuma.py # Uptime Kuma status parsing via mocking
│ ├── test_fusion.py # fusion source merging and failure handling
│ └── test_home_assistant.py # HA entity filtering, exclusions, formatting
└── app/
├── main.py # FastAPI app + MCP mount + cache/catalog endpoints
├── mcp_server.py # MCP SSE server
├── router.py # Intent detection, source routing, and caching
├── llm.py # LLM client — Ollama native and OpenAI-compatible
├── config.py # Settings via environment variables
└── sources/
├── kiwix.py # Offline knowledge base — dynamic catalog + LLM routing
├── forecast.py # Open-Meteo weather forecast
├── freshrss.py # FreshRSS RSS reader
├── searxng.py # SearXNG web search
├── uptime_kuma.py # Uptime Kuma service monitoring
├── home_assistant.py # Home Assistant entity state summaries
└── fusion.py # Multi-source concurrent fusion
Philosophy
Local-first, privacy-preserving, subscription-free. MiniSearch is designed for homelabs where the data stays home. Open-Meteo is the only external network call — every other source (Kiwix, FreshRSS, SearXNG, Uptime Kuma, Home Assistant) runs on your own infrastructure.
Contributing
PRs welcome. New source modules are the easiest contribution — drop a file in sources/, register it in the router, done. The new source is immediately available via REST, MCP, and fusion with no additional work.
Proposed modules
Looking for contributors interested in building out additional sources:
- Jellyfin — search local media library by title, genre, or actor
- Paperless-ngx — search scanned documents and OCR'd content
- Mealie — search self-hosted recipe library
- Grocy — query pantry inventory, shopping list, or expiring items
- Calibre — search local ebook library
- Navidrome — search self-hosted music library by artist, album, or track
- Immich — search local photo library by date, album, or description
Each source only needs a single search(query: str) -> str function. See any existing file in app/sources/ as a reference.
Part of the MiniNet stack
- MiniSearch Intents — native Home Assistant LLM integration for MiniSearch
- MiniSense-T7S3 — ESP32-S3 room sensor node with voice assistant and CO2 monitoring