convez.ai
MCP ServerIntegração & APIsIntermediário
immortalbob

MiniSearch

immortalbob/MiniSearch

API unificada de busca local com roteamento inteligente para homelabs

Ver no GitHub
InicialPluginScore · de 0 a 100

Um 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/MiniSearch

1 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

Estrelas
20
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
v3.56.1
Issues abertas
1
Contribuidores
1

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

ClientProtocolHow
Open WebUIRESTLightweight tool that POSTs to /search
MiniSearch IntentsRESTNative HA LLM API integration
Any MCP client (Claude Desktop, Cursor, etc.)MCP/SSEConnect to http://your-host:8888/mcp/sse

Sources

SourceBackendDescription
kiwixKiwixOffline knowledge base — Wikipedia, Stack Exchange, iFixit, FreeCodeCamp, DevDocs
forecastOpen-Meteo3-day weather forecast, no API key required
newsFreshRSSRecent articles from your RSS feeds via GReader API
webSearXNGLive web search via your local SearXNG instance
uptimeUptime KumaService monitor status — reports any down services
haHome AssistantEntity 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:

VariableDescriptionDefault
KIWIX_URLKiwix container URLhttp://kiwix:8080
FRESHRSS_URLFreshRSS container URLhttp://freshrss
FRESHRSS_USERFreshRSS username
FRESHRSS_API_PASSWORDFreshRSS API password
FRESHRSS_MAX_ARTICLESMax articles to fetch10
SEARXNG_URLSearXNG container URLhttp://searxng:8080
FORECAST_LATITUDEForecast location latitude35.1894
FORECAST_LONGITUDEForecast location longitude-114.0530
FORECAST_LOCATION_NAMEHuman-readable location nameKingman, Arizona
FORECAST_TIMEZONETimezone for forecast timesAmerica/Phoenix
UPTIME_KUMA_URLUptime Kuma URL(blank — disables uptime source)
UPTIME_KUMA_USERNAMEUptime Kuma username
UPTIME_KUMA_PASSWORDUptime Kuma password
HA_URLHome Assistant URL(blank — disables HA source)
HA_TOKENHome Assistant long-lived access token
LLM_URLLLM backend URL for intelligent routing(blank — disables LLM routing)
LLM_MODELModel to use for source and book selectionqwen3:8b
LLM_API_TYPEAPI format: ollama or openaiollama

FreshRSS API setup

  1. Enable API access: Administration → Authentication → Allow API access
  2. Set an API password: Profile → API password
  3. 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:

  1. Source selection — when auto is 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.
  2. Book selection — once routed to Kiwix, the LLM picks the best 1-2 ZIM books from your catalog for the query
  3. Fusion source selection — when fusion is 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:

  1. Go to your Profile (click your username in the sidebar)
  2. Scroll to Long-lived access tokens
  3. Click Create Token, give it a name, copy the token
  4. Set HA_URL to your HA instance URL (e.g. http://192.168.3.6:8123)
  5. Set HA_TOKEN to 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:

SourceTTL
kiwix24 hours
web1 hour
fusion30 minutes
forecast30 minutes
news15 minutes
uptime1 minute
ha30 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 Wikipedia
  • unix.stackexchange.com_en_all — Unix & Linux Stack Exchange
  • raspberrypi.stackexchange.com_en_all — Raspberry Pi Stack Exchange
  • ifixit_en_all — iFixit repair guides
  • freecodecamp_en_all — FreeCodeCamp
  • devdocs_en_python — Python DevDocs

Adding a New Source

  1. Create app/sources/your_source.py with a search(query: str) -> str function
  2. Add any config vars to app/config.py and docker-compose.yml
  3. Import and register it in app/router.py — add to SOURCE_MAP, INTENT_MAP, SOURCE_DESCRIPTIONS, and CACHE_TTL
  4. 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
Ver o original no GitHub

Bom para

Relacionados