chore(main): release 3.0.0

[alex-feel]

🚀 New Release

3.0.0 (2026-08-01)

⚠ BREAKING CHANGES

• ENABLE_EMBEDDING_COMPRESSION defaults to true. New deployments will store embeddings in the bit-packed compressed format and write a singleton compression_metadata row on first start; the configured (provider, bits, variant, seed, dim) tuple becomes load-bearing and immutable thereafter. Existing deployments are unaffected at runtime because their compression_metadata table does not exist until a compression-aware start, but operators upgrading to v3.0.0 who want to retain fp32 storage MUST set ENABLE_EMBEDDING_COMPRESSION=false before first start; otherwise the server will initialize compressed storage using the default seed (0). In multi-pod Kubernetes deployments all pods MUST inherit the SAME COMPRESSION_SEED via a shared ConfigMap; changing the seed after compressed data exists corrupts every decode/search with no recovery path besides restoring from backup.
• The public type of context_entries.id and all foreign keys referencing it has changed from a 64-bit integer to a UUIDv7 value. MCP tools now accept and return 32-character lowercase hex strings, and the 36-character hyphenated form is also accepted at the boundary. Existing databases created with the integer-PK layout are NOT auto-migrated by the server, and operators MUST run the new mcp-context-server-migrate CLI against a backup of the source database before pointing the upgraded server at it. See docs/MIGRATION-v2-to-v3.md for the full step-by-step procedure. Clients that parse or persist context IDs as integers MUST be updated to handle string UUIDv7 values.
• the project license changed from the MIT License to the Elastic License 2.0; earlier published releases remain under the MIT License, and providing the software to third parties as a hosted or managed service that exposes a substantial set of its functionality now requires a commercial agreement with the licensor.

Features

• add configurable summary inclusion for get_context_by_ids (800eb21)
• add grep/navigate/read context tools with index_tree node summaries (2304bc6)
• add migration CLI --re-embed flag for switching embedding models (238aa8e)
• add optional pagination to list_threads (51a1e30)
• add TurboQuant embedding compression (989cde1)
• allow overriding the provider existingSecret data key name in the chart (c23308e)
• auto-enable search tools by default (8045194)
• auto-set search_path on every pooled asyncpg connection (26639f3)
• expose compression configuration via startup log and get_statistics (72033be)
• migrate context-entry primary keys to UUIDv7 (31877ae)
• overlap store/update generation and guard concurrent updates (612e77c)
• relicense under the Elastic License 2.0 (6ae2e42)
• report embeddings_size_mb and fix get_statistics on PostgreSQL (4406a11)
• warn on oversized pool behind a Supabase Session Pooler (f6b4691)

Bug Fixes

• acquire the schema-init advisory lock under the migration timeout (517ad7e)
• align embedding provisioning gates and guard probes with bare-name resolution (df76b5e)
• align SQLite/PostgreSQL behavior and harden edge cases (c284a9b)
• align the hybrid all-modes-failed response with the documented shape (ce94a9d)
• always clear stale index_tree node summaries on a text-change update (488dfa9)
• always return at least one chunk from split_text (8f91abb)
• attach explain-gated stats to remaining search validation-error responses (2cda68e)
• await every compression encode before propagating a failure (dd3c104)
• bound metadata filter and grep pattern inputs at the tool boundary (36fcb12)
• bound POSTGRESQL_PORT to a valid TCP port range (370167a)
• bound search pagination offset and clamp overfetch windows (604c9cd)
• bound the PostgreSQL pool size fields at the configuration layer (31841f2)
• bracket IPv6 host literals in the built PostgreSQL DSN (72e13cf)
• canonicalize date filter parameters for cross-backend parity (51db9ec)
• cap node-id slug segments below the PostgreSQL index-tuple ceiling (2602eba)
• cap tags filters and metadata membership lists at 100 members (2576023)
• cap the delete_context ID list at the tool boundary (d63396b)
• charge SQLite connection-creation faults and stop charging locked reads (3759087)
• chunk ID-list binds and enforce the batch ID caps (cf2a221)
• clamp the numeric filter float8 underflow band to match SQLite (3fbf0e4)
• classify a malformed DSN as a configuration error in the pgvector pre-check (79faae0)
• classify PostgreSQL acquire timeouts by elapsed wait (7943531)
• classify provider errors precisely and align summary provider docs (adbe5d6)
• clear stale summary on text-change batch update without a provider (810d60a)
• compare bearer tokens as UTF-8 bytes for non-ASCII tokens (783f254)
• compensate the preserved-summary count on discarded batch entries (edbb504)
• complete search diagnostics for timing, backend, and degraded modes (c1120e2)
• complete search stats parity on degraded and validation-error responses (7452586)
• constrain the SQLite thread delete to the cleanup snapshot (d752e63)
• correct decompress rebuild, metadata operators, and cleanup scoping (4ab35be)
• correct PostgreSQL schema-qualified DDL, vector provisioning, and guard ordering (734c995)
• correct the semantic and hybrid tool-registration descriptions (6643649)
• count a literal grep match toward the cap only after the terminator check (2f10fc2)
• degrade a boolean FTS query with a non-integer NEAR distance to a term match (f68f69d)
• degrade a leading-asterisk boolean FTS query to a safe term match (307af02)
• degrade malformed SQLite FTS boolean query to a safe term match (2073ca5)
• delete exactly the snapshotted ids in SQLite batch deletes (2c4c550)
• derive the Helm container port from the server bind port (259b555)
• detect cross-host codebook divergence and guard compress dimension (1206d21)
• disable the LLM SDK internal retry in the summary providers (9e892a4)
• drain the executor future on every SQLite transaction-boundary hop (bac6858)
• drain the executor future on the SQLite read-execution hop (a3bb3dc)
• enforce SQLite/PostgreSQL parity in metadata filters and FTS queries (ddc2f28)
• exit with the configuration code when settings validation fails at import (4f30b1a)
• exit with the configuration code when the auth token is missing (725ec9f)
• filter the non-atomic update-batch existence errors by original index (07d4520)
• floor migration statement timeouts at one millisecond (a6164b3)
• floor the derived statement_timeout at one millisecond (0c063ea)
• fold an empty summary effort env value to None (916efdc)
• force stateful sessions for the SSE transport (891a12a)
• forward the explicit tool name to the FastMCP registration (26090cd)
• freeze the source table before streaming in the compression CLI (cdca1c8)
• gate compression provisioning on embedding generation (8b0ab75)
• gate delete embedding cleanup on table presence, not runtime toggles (3678307)
• gate delete_context embedding cleanup on generation or compression (1b642fb)
• gate pgvector provisioning on generation and the active payload format (8bc9be6)
• gate the SQLite full-text-search operator-bareword drop on the configured language (1aea4d9)
• give hyphenated hybrid terms phrase semantics on PostgreSQL (34c6300)
• guard populated fp32 stores before the generation-off compression skip (43c6011)
• guard the full sealed compression tuple before backfilling embeddings (21e5a7e)
• guard the open-breaker resolution against a completed future (7901a4b)
• harden grep/navigate generation against regex blowups and outline edge cases (1649790)
• harden metadata index configuration validation and strict-mode failure (1d875b7)
• harden PostgreSQL and timing configuration at the boundary (125293b)
• harden storage integrity across dedup, updates, batch, and backends (6c9619d)
• harden the migrate CLI against invalid settings and FTS-less targets (560f89f)
• include content_hash in the cross-backend unstorable-string pre-check (a0334f2)
• initialize a pgvector-less migration target without the vector extension (0a51c1a)
• isolate batch reconcile embedding failure to the failing entry (59145fe)
• join the executor closure before a cancelled SQLite transaction unwinds (15a0de5)
• keep control-flow rejections out of the failed-query read metric (baab1a2)
• leave an already-bracketed IPv6 host literal unmodified in the DSN (e0b1d6c)
• list the metadata equality filter in the served full-text-search description (6feb450)
• list the real embedding tables in the PostgreSQL dimension-mismatch message (758db4b)
• load the sqlite-vec extension whenever the package is installed (7b3da6d)
• lock the parent row during transactional presence checks on PostgreSQL (7b0049a)
• make cross-backend migration CLI schema-aware and source-tolerant (0cb168b)
• make LOG_LEVEL govern FastMCP logging and pin lax input validation (464e606)
• make LOG_LEVEL govern the uvicorn logger tree and silence FastMCP when disabled (4203f34)
• make v2-to-v3 migration robust across backends and settings (94600a7)
• map the numeric filter overflow guard to the true float8 boundary (1a7aa65)
• match SQLite for high-magnitude float metadata filters on PostgreSQL (4665a39)
• match SQLite for numeric metadata filters and reject non-finite values (0ac460e)
• normalize base64 image payloads strictly and enforce the image count limit (c773417)
• normalize context IDs before ctx.info log emission (5db4b79)
• offload large-entry outline and line parsing off the event loop (ee48c34)
• omit the orphaned chart OpenAI Secret key when an existingSecret is used (0cdeaf1)
• open sqlite databases from POSIX absolute URLs and URI-special paths (df80022)
• prevent FTS metadata-key corruption and offload large-entry CPU work (bd46319)
• prevent run_generation task leak and depth-shifted outline node ids (7636401)
• probe a compression-safe marker for the chunking migration on PostgreSQL (0e7762c)
• probe for more matches before flagging a budget-stopped grep scan truncated (ffdc708)
• probe the version token when retaking the navigate snapshot (5b8653b)
• propagate non-absence read errors from the index-node repository (dc318fd)
• provision a migrated PostgreSQL target's full-text search from source presence (7e9842c)
• provision the database file only for the SQLite backend (9fb49e8)
• qualify metadata column by alias and provision dedup index in base schema (1e8aea8)
• quote metadata index identifiers and drop base-schema metadata indexes (9b4b0de)
• quote the configured schema in patch_metadata's runtime function call (02c3e67)
• quote the schema in the orphan metadata-index drop (d33ad8d)
• raise ConfigurationError on embedding provider 4xx in is_available (88210e4)
• raise dependency floors to releases that fix known vulnerabilities (05bc942)
• re-assert the dedup decision in the store UPDATE predicate (38711c8)
• re-attach stored node summaries by span after a slug algorithm change (10c226b)
• re-create the compressed payload table when compression is re-enabled (6260302)
• read numeric metadata-filter values as exact NUMERIC on PostgreSQL (c1a3464)
• refuse fp32 pgvector provisioning above the index dimension cap (7fd2a6f)
• refuse to disable compression while compressed data is present (4a8c874)
• refuse to enable compression while uncompressed fp32 embeddings exist (f04d065)
• regenerate a reused summary on dedup divergence and honor empty replacements (df567da)
• regenerate reconcile summaries once per text and source pair (65b7402)
• reject a blank DB_PATH at the configuration boundary (62f0434)
• reject a boolean for the ordered metadata comparison operators (b3637f9)
• reject a non-finite float in per-image metadata before generation (4fad432)
• reject a non-string image data or mime_type in the shared validator (943680a)
• reject a pool floor above the pool ceiling at the configuration boundary (edd5c2b)
• reject a sub-minute UTC offset that SQLite evaluates to NULL (596ca87)
• reject a trailing-newline metadata key on both validators (0ea56b5)
• reject a zero retry budget at the configuration boundary (18f195c)
• reject an embedding dimension above the pgvector index cap (71d11f3)
• reject an image mime_type that PostgreSQL cannot store (177887f)
• reject an image whose base64 data decodes to zero bytes (1870dfb)
• reject non-string thread_id and text in the batch tools (f459f57)
• reject NUL bytes in full-text queries and keep client input errors out of the circuit breaker (97d75db)
• reject PostgreSQL-unstorable client input and exempt invalid metadata filters from the circuit breaker (99673c7)
• reject tag filters that normalize to empty (7780476)
• reject unpaired-surrogate FTS queries via the shared bind probe (d0b1fa6)
• relax image mime_type to a free-form advisory label (1903b5f)
• render a single OPENAI_API_KEY in the Helm chart (61b4a63)
• repair model-generated summaries that PostgreSQL cannot store (85f6b6f)
• replace MAX(id) with array_agg in list_threads PostgreSQL branch (8870c45)
• report not-found when an atomic batch update loses its row mid-write (79bc785)
• report repeated metadata index fields with an accurate diagnostic (c9ccc5a)
• require a positive image size limit and correct the hybrid toggle docs (911a44a)
• require positive connection-pool sizes and drop the unreachable embedding-dimension check (4e3461c)
• resolve an in-flight write future when the queue processor shuts down (89c28ff)
• resolve four code-audit defects in store/search/batch paths (2d55a21)
• resolve grep/navigate, index_tree, and breaker control-flow defects (742d8d5)
• resolve the full-text-search availability probe through search_path (f9e8fa8)
• resolve the SQLite target embedding dimension from settings in the migration CLI (5810a3a)
• restrict metadata index field names to SQL identifiers (80c2e5a)
• retake the navigate snapshot when a concurrent update splits its reads (41cd013)
• retarget pool-timeout advisory to connection acquire-wait (8a727d5)
• retry PostgreSQL writes cancelled by statement timeout (d353f0d)
• retry SQLite lock contention instead of charging the circuit breaker (cb2eb0b)
• retry transaction-rollback failures instead of charging the circuit breaker (23f5821)
• return structured validation errors when all hybrid search modes fail (0b39333)
• reverse response counters for batch entries discarded at commit time (e20ccd7)
• run every PostgreSQL migration DDL under the configured migration timeout (b5d334e)
• run metadata index DDL under the configured migration timeout (6172899)
• run PostgreSQL migration DDL under the configured migration timeout (b3cde8b)
• run schema-init statements under the migration timeout budget (9375170)
• run SQLite transaction closures on the executor thread pool (1a970bb)
• run the compression CLI recounts under the migration budget (093d081)
• run the compression CLI's estimate and zero-data counts under the migration budget (ae4d471)
• run the compression migration DDL under the migration timeout (3fa712e)
• run the full-text-search language migration under the configured migration timeout (5de946a)
• run the full-text-search migration probes under the migration timeout (d19091a)
• run the steady-state fingerprint ensure under the migration discipline (c24a382)
• screen grep tags for strings PostgreSQL cannot bind (e67faae)
• serialize the BLAS thread-count pin across concurrent codec calls (2698a6e)
• service a dequeued write before honoring a same-batch shutdown signal (4eec7f0)
• skip pgvector provisioning for a compressed generation-on server (00213f8)
• skip PostgreSQL-unstorable rows in the SQLite-to-PostgreSQL migration instead of aborting (9aa2103)
• skip rows with malformed metadata JSON in the migration pre-check (c03d09e)
• snapshot the duplicate candidate summary atomically in the pre-check (b887f53)
• stop case-sensitive string array_contains matching container elements on SQLite (42ff7c5)
• stop charging the circuit breaker for transient PostgreSQL write conditions (31c2c84)
• stop retrying pool-saturation timeouts at the tool layer (5d70fcb)
• strip internal chunk-boundary fields from semantic search results (b5e2ee7)
• surface a clean not-found error when an update targets a deleted entry (8b34955)
• thread the pgvector decision through the decompress CLI so it runs on a host without pgvector (d358e59)
• tolerate a compression_metadata table without the fingerprint column (0878ee5)
• tolerate a source embedding_chunks table without the boundary columns (4d3868b)
• type PostgreSQL connection-establishment timeouts and charge acquire-phase faults (8fd0b52)
• type the returned image shape for context and search results (99debc6)
• unify ID-prefix resolution and align PostgreSQL is_null semantics (6fdc997)
• unwedge and guard the zero-data decompress path (ed6c353)
• URL-encode the user and database in the PostgreSQL connection string (714d3e6)
• validate an omitted metadata-filter value against its operator (8f15976)
• validate stored node-id hits against their recorded span (c758202)
• validate the settings-fallback embedding dimension in the migrate pre-flight (dcf87b9)
• verify the codebook fingerprint before decompressing embeddings (9221304)
• verify the realized codebook fingerprint before CLI embedding backfill (fcd761a)

---

This PR was generated with Release Please. See documentation.