@squadrules/mcp 4.8.6 → 5.0.0

package/README.md

@@ -1,8 +1,8 @@
 # SquadRules MCP
 
-<!-- kairos-lint-allow-protocol-synonyms -->
+<!-- squadrules-lint-allow-protocol-synonyms -->
 
-<img src="logo/kairos-mcp.svg" width="128" alt="SquadRules MCP logo" />
+<img src="logo/squadrules-mcp.svg" width="128" alt="SquadRules MCP logo" />
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D24.0.0-brightgreen)](https://nodejs.org/)
@@ -62,11 +62,6 @@ flowchart LR
 The server generates challenge data (`nonce`, `proof_hash`, URIs); agents echo
 those values back exactly.
 
-> **Migrating from KAIROS?** This project was formerly named KAIROS. See
-> [Migration from KAIROS](docs/migration-from-kairos.md) for the old-to-new
-> name mapping and compatibility notes. Older `kairos` CLI binaries, `KAIROS_*`
-> environment variables, and `kairos://` URIs keep working.
-
 ## Protocol execution
 
 Authoritative behavior for agents is defined in the MCP tool resources under
@@ -107,7 +102,7 @@ The current codebase includes:
 
 - **HTTP application server** — Express app for MCP, REST, auth routes, and UI
 - **stdio MCP transport** — direct local-host launch path for desktop/IDE MCP clients
-- **Qdrant-backed adapter store** — required for runtime
+- **Vector/trace store** — embedded LanceDB by default; Qdrant when `QDRANT_URL` is set
 - **Optional Redis cache / proof-of-work state store** — enabled when `REDIS_URL` is set
 - **Optional Keycloak auth integration** — browser session + Bearer JWT validation
 - **React UI** — served from the same origin at `/ui`
@@ -139,15 +134,13 @@ Compose — install the package globally and point your host at `squadrules serv
 ### Prerequisites
 
 - **Node.js 24+**.
-- **A Qdrant instance on `http://localhost:6333`** — SquadRules cannot start
-  without it, and no auth is required for local use. If you don't already run
-  one, this is the quickest option (optional convenience):
-
-  ```bash
-  docker run -p 6333:6333 qdrant/qdrant
-  ```
-
-- **One embedding backend**, supplied through the host `env` below.
+- **One embedding backend**, supplied through the host `env` below (the embedded
+  store removes the vector *database* dependency, not the embedding provider).
+- **No database required.** By default SquadRules keeps its vectors in an embedded,
+  file-backed LanceDB store under `~/.config/squadrules/lancedb` (created on first
+  run) — no Qdrant, Redis, or Docker. To keep an existing Qdrant, set `QDRANT_URL`;
+  the single-switch selection rule and limitations live in
+  [Known issues & limitations](docs/known-issues-and-limitations.md#vector-store-backends).
 
 ### Install
 
@@ -158,8 +151,8 @@ squadrules --help
 
 The global install provides both the **`squadrules`** CLI (bulk operations, auth,
 server management) and the MCP server binary used by your agent host. The
-package also installs **`squadrules-mcp`** and retains the former **`kairos`**
-and **`kairos-mcp`** command names as compatibility aliases.
+package also installs **`squadrules-mcp`** and retains the former **`squadrules`**
+and **`squadrules-mcp`** command names as compatibility aliases.
 
 ### Configure your MCP host
 
@@ -172,23 +165,24 @@ Add SquadRules to your host's `mcp.json` (Cursor, Claude Desktop, Claude Code,
     "SquadRules": {
       "command": "squadrules",
       "args": ["serve"],
-      "env": {
-        "QDRANT_URL": "http://localhost:6333",
-        "QDRANT_API_KEY": "",
-        "OPENAI_API_KEY": "sk-..."
-      }
+      "env": {}
     }
   }
 }
 ```
 
-`QDRANT_API_KEY=""` selects no-auth localhost Qdrant. For the embedding backend,
-supply **one** of:
+An empty `env` is enough: with no `QDRANT_URL` the server uses the embedded
+LanceDB store (created on first run under `~/.config/squadrules/lancedb`), and
+embeddings run **locally with fastembed** (no API key, no inference service; the
+model is downloaded once into `~/.config/squadrules/models`). To use an existing
+Qdrant instead, add `"QDRANT_URL": "http://localhost:6333"` (and
+`"QDRANT_API_KEY": ""` for no-auth localhost Qdrant). To override the local
+embedding default with an external backend, supply **one** of:
 
 - **OpenAI** — `OPENAI_API_KEY`
 - **Ollama / OpenAI-compatible** — `OPENAI_API_URL`, `OPENAI_EMBEDDING_MODEL`,
   and `OPENAI_API_KEY=ollama`
-- **TEI** — `TEI_BASE_URL` (+ optional `TEI_MODEL`)
+- **TEI** (deprecated) — `TEI_BASE_URL` (+ optional `TEI_MODEL`)
 
 Every parameter is **ENV-overridable**. To run SquadRules as an HTTP listener
 instead of stdio, add `"--transport", "http"` to `args` (see
@@ -242,7 +236,7 @@ This repository ships its agent skills under
 | `squadrules` | Users | Run SquadRules protocols; install and update guidance; bug reports |
 | `squadrules-dev` | Developers | Docker Compose dev environment and maintainer workflows (internal; not installed by `npx skills add`) |
 
-The former `kairos` and `kairos-dev` skill directories are retained for
+The former `squadrules` and `squadrules-dev` skill directories are retained for
 compatibility with existing installations; hosts prefer `squadrules` when both
 are present.
 
@@ -275,13 +269,20 @@ The Helm chart for Kubernetes deployment now lives in the
 published to `oci://ghcr.io/squadrules/charts/mcp`. See that repository for
 installation, values, and chart-testing details.
 
+## Container images
+
+Container images are built, scanned, signed and published from the
+[`SquadRules/containers`](https://github.com/SquadRules/containers) repository,
+FROM the published `@squadrules/mcp` npm package, to Docker Hub
+(`docker.io/squadrules/mcp`) and quay.io. This repository publishes npm only;
+see that repository for the image pipeline, base-image OS scanning and signing.
+
 ## Documentation map
 
 - [Documentation index](docs/README.md)
 - [Install and environment](docs/install/README.md)
 - [Cursor and MCP](docs/install/README.md#cursor-and-mcp)
 - [CLI reference](docs/CLI.md)
-- [Migration from KAIROS](docs/migration-from-kairos.md)
 - [Architecture (SquadRules wiki)](https://github.com/SquadRules/mcp/wiki)
 - [Adapter examples](docs/examples/README.md)
 - [Contributing](CONTRIBUTING.md)
@@ -309,17 +310,21 @@ health endpoint (`curl http://localhost:3000/health`).
 
 ### Embeddings fail on startup
 
-Set one working embedding backend in the host `env`:
+By default embeddings run **locally with fastembed** — no key required — but the
+**first run downloads the model**, so it needs network access once (cached under
+`~/.config/squadrules/models`; air-gapped hosts must pre-seed it). Override the
+model or location with `FASTEMBED_MODEL` / `FASTEMBED_CACHE_DIR`. To use an
+external backend instead, set one working provider in the host `env`:
 
 - OpenAI: `OPENAI_API_KEY`
 - Ollama/OpenAI-compatible: `OPENAI_API_URL`, `OPENAI_EMBEDDING_MODEL`, `OPENAI_API_KEY=ollama`
-- TEI: `TEI_BASE_URL` (+ optional `TEI_MODEL`)
+- TEI (deprecated): `TEI_BASE_URL` (+ optional `TEI_MODEL`)
 
 ### The CLI keeps asking for login
 
 The CLI stores tokens per API URL. Confirm that:
 
-- you are using the expected `--url` / `KAIROS_API_URL`
+- you are using the expected `--url` / `SQUADRULES_API_URL`
 - the token is still valid
 - Keycloak and the SquadRules server agree on issuer and audience