@functional-systems/lambdadb-mcp 0.1.2 → 0.1.3-dev.11

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+- Pin the stable LambdaDB SDK to 0.8.0; expose Bayesian candidate budgets and
+  native embedding configuration in MCP guidance while preserving free-form
+  queries, SDK/server validation, rerank defaults, errors and response metadata.
+- Retain legacy `managedEmbedding: true` and existing tool names/inputs. Native
+  embedding-only requests require a supporting server; no defaults are promoted.
+- Add Bayesian/native contract tests, installed-package coverage, practical MCP
+  examples and an opt-in live suite with verified temporary-collection cleanup.
+
 ## [0.1.2] - 2026-10-04
 
 - Pin the LambdaDB TypeScript SDK to 0.7.0 and expose all 49 fixed lowercase

package/README.md

@@ -15,22 +15,22 @@ Package: `@functional-systems/lambdadb-mcp`. Executable: `lambdadb-mcp`.
 Requires Node.js >=22.14.0; CI tests the minimum and current Node 22/24 LTS.
 
 The stable package is available on npm. As verified on 2026-10-04 (KST),
-`latest` resolves to `0.1.1` and `dev` to `0.1.2-dev.9`. Use an exact version for
+`latest` resolves to `0.1.2` and `dev` to `0.1.2-dev.9`. Use an exact version for
 reproducibility or the default stable channel for initial setup. See
 [release status and policy](RELEASING.md).
 
-[MCP 0.1.1](https://github.com/lambdadb/lambdadb-mcp/releases/tag/v0.1.1) remains the
-published stable release with SDK 0.6.0. Published `0.1.2-dev.9` contains SDK 0.7.0,
-49 fixed text analyzer presets and optional managed reranking. This source prepares
-stable `0.1.2`; it has not yet been published. To preview the published changes,
-use `npx --yes @functional-systems/lambdadb-mcp@0.1.2-dev.9`.
+[MCP 0.1.2](https://github.com/lambdadb/lambdadb-mcp/releases/tag/v0.1.2) is the
+published stable release with SDK 0.7.0, 49 fixed text analyzer presets and optional
+managed reranking. This synchronization starts the next `0.1.3-dev.1` source base;
+check npm for the current published dev version. Use the exact stable version
+`0.1.2` for reproducible installed execution.
 Existing installations need an MCP version containing these changes; upgrading
 the SDK separately does not update them.
 
 ```sh
 npx --yes @functional-systems/lambdadb-mcp
 # Pin the stable release:
-npx --yes @functional-systems/lambdadb-mcp@0.1.1
+npx --yes @functional-systems/lambdadb-mcp@0.1.2
 # Or install globally:
 npm install -g @functional-systems/lambdadb-mcp
 lambdadb-mcp
@@ -103,8 +103,8 @@ Optional write tools:
 
 ## API contract and tool inputs
 
-The LambdaDB SDK is pinned to `@functional-systems/lambdadb@0.7.0`, checked against
-the published package and [v0.7.0 release](https://github.com/lambdadb/lambdadb-typescript-client/releases/tag/v0.7.0).
+The LambdaDB SDK is pinned to `@functional-systems/lambdadb@0.8.0`, checked against
+the published package and [v0.8.0 release](https://github.com/lambdadb/lambdadb-typescript-client/releases/tag/v0.8.0).
 This dependency update applies to builds containing this change. Publishing the SDK
 alone does not update previously published or installed MCP packages.
 
@@ -174,6 +174,114 @@ This MCP update does not migrate existing Collections or indexes. Partial update
 segment merging, and old Tags do not upgrade old indexes. If migration is needed,
 plan and authorize reinsertion into a new Collection separately.
 
+### Bayesian hybrid search
+
+Arguments for `lambdadb_query_collection` using an existing two-dimensional
+caller-provided vector field `embedding` and text field `body`:
+
+```json
+{
+  "collectionName": "articles",
+  "query": {
+    "bayesian": [
+      { "queryString": { "query": "body:restore" } },
+      { "knn": { "field": "embedding", "queryVector": [1, 0], "k": 30 } }
+    ]
+  },
+  "size": 10,
+  "candidateSize": 30
+}
+```
+
+Bayesian requires exactly two signals. Boolean subqueries may combine clauses
+within a signal, but explicit boosts (even `1`) on either signal or its Boolean
+descendants and nested rank-fusion queries are unsupported. Do not supply fusion
+weights. Without rerank, top-level `candidateSize` is required and must satisfy
+`1 <= size <= candidateSize <= 100`; omitted `size` retains the server default of
+10. The budget is per signal, independent of final output size and `knn.k`.
+
+With rerank, omit top-level `candidateSize` and use `rerank.candidateSize`:
+
+```json
+{
+  "collectionName": "articles",
+  "query": {
+    "bayesian": [
+      { "queryString": { "query": "body:restore" } },
+      { "knn": { "field": "embedding", "queryVector": [1, 0], "k": 30 } }
+    ]
+  },
+  "size": 10,
+  "rerank": {
+    "provider": "typesafe",
+    "model": "jev-1.13.0",
+    "queryText": "How do I restore a previous version?",
+    "fields": ["body"],
+    "candidateSize": 30
+  }
+}
+```
+
+Omitted/null `rerank.candidateSize` retains `max(50, size)`; omitted/null `rerank`
+requires the top-level Bayesian budget. Ordinary text/KNN/RRF/Min-Max/L2 queries
+must omit top-level `candidateSize`. MCP preserves free-form queries, passes
+integer candidate budgets unchanged, and leaves Bayesian structure, bounds and
+cross-field validation to the server, retaining service errors. No query defaults,
+weights or candidate counts are inserted by MCP. Bayesian scores are heuristic
+fusion scores; applied reranking preserves them in `retrievalScore` and retains
+all rerank status metadata, including through SDK-managed `docsUrl` downloads.
+
+The [Bayesian contract](https://github.com/lambdadb/lambdadb-typescript-client/blob/v0.8.0/docs/bayesian-search.md)
+and native embedding additions below are pinned to backend
+`9072a1bc8925954369a887f558f1eaf387b7ea0e`. A source pin does not establish deployment
+in another environment. Existing fusion methods and tool names remain unchanged.
+
+### Native embedding configuration
+
+With write tools enabled, call `lambdadb_create_collection` with:
+
+```json
+{
+  "collectionName": "native-articles",
+  "indexConfigs": {
+    "body": { "type": "text" },
+    "embedding": {
+      "type": "vector",
+      "embedding": {
+        "provider": "openai",
+        "model": "text-embedding-3-small",
+        "sourceField": "body",
+        "dimensions": 512,
+        "similarity": "cosine"
+      }
+    }
+  }
+}
+```
+
+Then call `lambdadb_upsert_docs` with
+`{"collectionName":"native-articles","docs":[{"id":"one","body":"Restore a saved version."}]}`.
+The source must be a text field; omit the generated vector from documents.
+Use `knn.queryText` instead of `queryVector` for this field, including in either
+Bayesian example above. For example, call `lambdadb_query_collection` with:
+
+```json
+{
+  "collectionName": "native-articles",
+  "query": { "knn": { "field": "embedding", "queryText": "Restore a version", "k": 30 } },
+  "size": 10
+}
+```
+
+Native dimensions and similarity are optional and belong inside `embedding`.
+MCP does not infer a flag, provider, model or native dimensions/similarity default.
+The SDK rejects `managedEmbedding: false` with `embedding`, and native embedding
+with top-level dimensions/similarity. Caller-provided vectors continue to use
+top-level dimensions/similarity. Free-form nested object configurations retain
+server validation. For older servers, explicitly add `managedEmbedding: true`
+beside `type`; it is preserved. Normalized collection metadata may still contain
+that true flag. See the [native embedding contract](https://github.com/lambdadb/lambdadb-typescript-client/blob/v0.8.0/docs/native-embeddings.md).
+
 ### Optional managed reranking
 
 `lambdadb_query_collection` accepts per-query `rerank`; omission or `null`
@@ -205,7 +313,7 @@ Optional `criteria` replaces the default with 2–10 distinct nonblank descripti
 ordered from lowest to highest relevance (2 KiB each, 8 KiB total UTF-8).
 Omitted/null criteria uses defaults; text, order, nulls and omission are preserved.
 
-Final `size`, vector-leg `knn.k`, and merged `candidateSize` are separate.
+Final `size`, vector-leg `knn.k`, and merged `rerank.candidateSize` are separate.
 Require `1 <= size <= candidateSize <= 100`; omitted/null candidateSize defaults
 on the server to `max(50, size)`, with final size defaulting to 10. MCP never
 increases `k`. Reranking requires a scoring retrieval query, forbids `sort`,
@@ -294,7 +402,9 @@ MCP JSON Schema and actual tool-to-SDK HTTP path, including match-all, facet-onl
 document+facet, omitted/null/default bucket options, boundaries, invalid requests,
 and all 49 analyzers. Rerank tests cover JSON Schema, request preservation,
 local bounds/UTF-8 rejection, score envelopes, skipped/fallback results and
-metadata downloads. They do not require credentials
+metadata downloads. Bayesian tests cover untouched free-form requests, candidate
+budgets, server errors, native/legacy configurations and contradictory inputs.
+They do not require credentials
 or create remote collections. `test:package` additionally installs the actual
 tarball in a clean consumer directory and repeats the tool contracts over real
 stdio, checking version identity, config errors, stdout and process termination.
@@ -340,9 +450,23 @@ Cleanup deletes the collection and verifies its absence even after a failed chec
 It does not assert fixed model scores or relevance rankings, and a fallback result
 does not pass as applied inference. Provider failures remain fixture tests; this
 suite does not deliberately induce failures or verify search quality, load,
-production deployment or billing readiness. Both live suites are outside default
+production deployment or billing readiness. These live suites are outside default
 checks and credential-free CI.
 
+Bayesian/native embedding verification also requires explicit managed inference
+opt-in for OpenAI embeddings and TypeSafe reranking:
+
+```bash
+LAMBDADB_RUN_LIVE_TESTS=1 LAMBDADB_RUN_LIVE_RERANK_TESTS=1 LAMBDADB_LIVE_CONFIRM_PROJECT=YOUR_DEV_PROJECT npm run test:live:bayesian
+```
+
+This suite creates one owned collection with native, legacy and caller-provided
+vector fields. It checks real embedding generation and text queries, Bayesian
+budgets and server rejections, existing fusion methods, applied reranking with
+retrieval scores and actual docsUrl hydration, then deletes and verifies absence.
+These live suites are outside default checks and credential-free CI. Verify the
+target's deployment provenance before running; the source pin alone is insufficient.
+
 If the environment file is outside the worktree:
 
 ```bash

package/RELEASING.md

@@ -1,31 +1,35 @@
 # Releasing LambdaDB MCP
 
-## Prepared stable candidate: 0.1.2 (2026-10-04 KST)
-
-[PR #11](https://github.com/lambdadb/lambdadb-mcp/pull/11) merged SDK 0.7.0,
-49 fixed text analyzer presets and optional per-query managed reranking into
-develop at `99896e0279fa7610358e9abafc032dd507b10f40`. The
-[develop workflow](https://github.com/lambdadb/lambdadb-mcp/actions/runs/37189420462)
-completed and published `0.1.2-dev.9`. Registry metadata matches that commit and
-pins SDK 0.7.0; a downloaded tarball was integrity-checked and passed clean
-consumer stdio contracts. As verified on 2026-10-04, `latest` remains `0.1.1`.
-
-`release/0.1.2` prepares stable package/lock versions and a dated changelog for
-review into main. Source, tests, scripts and CI match the merged develop tree.
-Candidate validation is recorded in `docs/validation/2026-10-04-0.1.2.md`.
-Do not treat this preparation as a published stable release. Merge into main with
-a merge commit to retain ancestry, then obtain separate authorization to tag the
-verified main commit as `v0.1.2` and publish its GitHub Release. The release
-workflow tests its exact publication artifact before publishing to `latest`.
-After verification, synchronize main into develop through a PR with the next
-`0.1.3-dev.1` base; do not put stable version metadata on develop.
+## Current stable release: 0.1.2 (2026-10-04 KST)
+
+[v0.1.2](https://github.com/lambdadb/lambdadb-mcp/releases/tag/v0.1.2) tags main
+commit `627ffbb3161bc3d41d5f2a5f2a0f5289fd73de3f`, which merged
+[release PR #12](https://github.com/lambdadb/lambdadb-mcp/pull/12) with preserved
+ancestry. The [release workflow](https://github.com/lambdadb/lambdadb-mcp/actions/runs/37191117220)
+passed Node 22.14.0 / 22 / 24 validation and published its exact tested artifact
+with OIDC and provenance. Registry snapshot: `latest=0.1.2`, `dev=0.1.2-dev.9`.
+A downloaded stable tarball matched registry integrity, source commit and SDK
+0.7.0 and passed 31 clean-consumer stdio tests. Provenance statement repository,
+workflow, tag, source commit and subject digest matched the publication.
+
+SDK 0.7.0 adds 49 fixed text analyzer presets and optional per-query managed
+reranking. Read-only defaults and explicit write opt-in remain. See
+`docs/validation/2026-10-04-0.1.2.md` for separate candidate, authorized
+source-build live, published dev and published stable evidence. Do not repeat the
+0.1.2 publication or move its tag.
+
+This synchronization brings main back into develop with the next base
+`0.1.3-dev.1`. Review it into develop using a merge commit to preserve ancestry.
+Eligible develop merges may publish a new dev version while `latest` stays on
+0.1.2. Do not merge stable version metadata directly into develop.
 
 Both live suites require explicit designation of a development project. Reranking
 also requires managed inference opt-in; no Jev API key is required. Live contract
 checks do not establish production deployment, search quality, load/failure
-coverage or billing readiness. Backend feature/model availability remains required.
+coverage or billing readiness. Supporting backend deployment/model availability
+and keyword-index requirements remain; existing collections/indexes are not migrated.
 
-## Current stable release: 0.1.1 (2026-09-29 KST)
+## Previous stable release: 0.1.1 (2026-09-29 KST)
 
 [v0.1.1](https://github.com/lambdadb/lambdadb-mcp/releases/tag/v0.1.1) tags main
 commit `40a8afc25bb93fb14d03d23e3ab38aa1924cf060`, which merged the reviewed release

package/dist/tools/read.js

@@ -68,7 +68,7 @@ export function registerReadTools(server, config) {
     });
     server.registerTool("lambdadb_query_collection", {
         title: "Query Collection",
-        description: "Search documents with optional managed reranking and keyword facet counts across all matches. Omit query for match-all; size: 0 requires facets and forbids reranking. Reranking requires a scoring query and forbids sort; it does not enable vector/hybrid facets. Applied envelope score is an evaluation score, retrievalScore preserves search score, and rerank metadata reports status. Features require a supporting server; facets require newly built keyword indexes.",
+        description: "Search documents with optional Bayesian hybrid search, managed reranking and keyword facet counts across all matches. Omit query for match-all; size: 0 requires facets and forbids reranking. Reranking requires a scoring query and forbids sort; it does not enable vector/hybrid facets. Applied envelope score is an evaluation score, retrievalScore preserves search score, and rerank metadata reports status. Features require a supporting server; facets require newly built keyword indexes.",
         annotations: {
             readOnlyHint: true,
             openWorldHint: false
@@ -77,7 +77,9 @@ export function registerReadTools(server, config) {
             collectionName: nameSchema,
             size: z.number().int().min(0).max(100).optional()
                 .describe("Documents to return (1–100), or 0 with nonempty facets."),
-            query: z.record(z.string(), z.any()).optional().describe("Omit for match-all."),
+            // Preserve SDK/server validation and error classification for free-form queries.
+            candidateSize: z.number().int().optional().describe("Bayesian without rerank requires 1 <= size <= candidateSize <= 100 (size defaults to 10 on the server). With rerank, omit this field and use rerank.candidateSize, whose default is unchanged. Unsupported for other queries; server validates these combinations."),
+            query: z.record(z.string(), z.any()).optional().describe("Free-form query; omit for match-all. Top-level bayesian is an array of exactly two subqueries, with no explicit boosts on either subquery or its Boolean descendants. Nested rank fusion and fusion weights are unsupported. Server validates the query contract."),
             facets: facetsSchema.optional(),
             rerank: rerankSchema,
             ref: readRefSchema.optional(),
@@ -105,7 +107,7 @@ export function registerReadTools(server, config) {
                     }
                 }]
         })
-    }, async ({ collectionName, size, query, facets, rerank, ref, consistentRead, includeVectors, sort, fields, partitionFilter }) => {
+    }, async ({ collectionName, size, candidateSize, query, facets, rerank, ref, consistentRead, includeVectors, sort, fields, partitionFilter }) => {
         try {
             const client = createLambdaDBClient(config);
             const input = {
@@ -113,6 +115,7 @@ export function registerReadTools(server, config) {
                 facets,
                 rerank,
                 size,
+                candidateSize,
                 ...readOptions(ref, consistentRead),
                 includeVectors,
                 sort,

package/dist/tools/write.js

@@ -6,13 +6,13 @@ import { jsonResult, nameSchema, partitionFilterSchema } from "./shared.js";
 export function registerWriteTools(server, config) {
     server.registerTool("lambdadb_create_collection", {
         title: "Create Collection",
-        description: `Create a new collection in the configured project. Fixed lowercase text analyzer presets: ${Object.values(Analyzer).join(", ")}. Omitted analyzers uses standard; custom pipelines/options are unsupported. The keyword text analyzer is distinct from the keyword field type. Keyword indexes built on a supporting server support facets.`,
+        description: `Create a new collection in the configured project. Fixed lowercase text analyzer presets: ${Object.values(Analyzer).join(", ")}. Omitted analyzers uses standard; custom pipelines/options are unsupported. The keyword text analyzer is distinct from the keyword field type. Keyword indexes built on a supporting server support facets. Native vector fields accept embedding without managedEmbedding; explicit managedEmbedding: true remains supported for older servers.`,
         annotations: {
             openWorldHint: false
         },
         inputSchema: z.strictObject({
             collectionName: nameSchema,
-            indexConfigs: z.record(z.string(), z.any()).refine((value) => Object.keys(value).length > 0, "indexConfigs must contain at least one field."),
+            indexConfigs: z.record(z.string(), z.any()).refine((value) => Object.keys(value).length > 0, "indexConfigs must contain at least one field.").describe("Field configurations validated by the SDK/server. Native vectors: {type: 'vector', embedding: {provider, model, sourceField, dimensions?, similarity?}}; declare sourceField as text. Native dimensions/similarity belong inside embedding, never at the field top level. Do not combine embedding with managedEmbedding: false. Legacy true is preserved; no provider/model or native defaults are inferred. Caller-provided vectors retain top-level dimensions/similarity."),
             description: z.string().max(255).optional(),
             tags: z.record(z.string().regex(/^[A-Za-z0-9_.-]{1,63}$/), z.string().min(1).max(127).regex(/^[^:#,]+$/))
                 .refine((value) => Object.keys(value).length <= 5, "At most five tags are allowed.")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@functional-systems/lambdadb-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3-dev.11",
   "private": false,
   "description": "MCP server for LambdaDB data plane",
   "type": "module",
@@ -11,6 +11,7 @@
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/index.js', 0o755)\"",
     "check": "npm run check:version && npm run typecheck && npm test",
     "test": "npm run build && node --test test/*.test.mjs",
+    "test:live:bayesian": "npm run build && bash ./scripts/with-env.sh --test test/integration/bayesian-live.test.mjs",
     "test:live:rerank": "npm run build && bash ./scripts/with-env.sh --test test/integration/rerank-live.test.mjs",
     "test:live": "npm run build && bash ./scripts/with-env.sh --test test/integration/live.test.mjs",
     "dev": "tsx watch src/index.ts",
@@ -23,7 +24,7 @@
     "test:package": "node scripts/test-package.mjs"
   },
   "dependencies": {
-    "@functional-systems/lambdadb": "0.7.0",
+    "@functional-systems/lambdadb": "0.8.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "zod": "^4.1.12"
   },
@@ -61,5 +62,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "gitHead": "627ffbb3161bc3d41d5f2a5f2a0f5289fd73de3f"
+  "gitHead": "bd1ae5547f868991a22c92b5a07849edfcf696fb"
 }