@functional-systems/lambdadb-mcp 0.1.1 → 0.1.2-dev.9

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+- Pin the LambdaDB TypeScript SDK to 0.7.0 and expose all 49 fixed lowercase
+  analyzer presets in collection-tool guidance; preserve analyzer serialization.
+- Add optional per-query managed reranking to the MCP schema and SDK request path,
+  preserving omission/null, distinct sizes, custom criteria, envelope scores and
+  status metadata, including document downloads. Retain SDK validation and errors.
+- Extend local and installed-package contracts for analyzer expansion and reranking;
+  update the opt-in live analyzer check without claiming live feature verification.
+- Add a separate opt-in managed-reranking live suite for real default/custom
+  inference, empty candidates, omitted/null behavior and docsUrl envelope
+  preservation, with owned-resource cleanup and no fixed relevance expectations.
+- Native SDK usage is unchanged; no Qdrant mapping exists in this server. Supporting
+  backend deployment/model availability remains required. No package is published
+  and existing MCP installations require a separately released update.
+
 ## [0.1.1] - 2026-09-29
 
 - Pin the LambdaDB TypeScript SDK to 0.6.0, including all 16 text analyzers.

package/README.md

@@ -15,20 +15,20 @@ 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-09-29 (KST),
-`latest` resolves to `0.1.0` and `dev` to `0.1.1-dev.7`. Use an exact version for
+`latest` resolves to `0.1.1` and `dev` to `0.1.1-dev.7`. Use an exact version for
 reproducibility or the default stable channel for initial setup. See
 [release status and policy](RELEASING.md).
 
-This source targets MCP **0.1.1**, with SDK 0.6.0, keyword facets, match-all queries,
-and 16 text analyzers. Check [GitHub Releases](https://github.com/lambdadb/lambdadb-mcp/releases)
-and npm for publication status; source version metadata alone is not evidence of publication.
+[MCP 0.1.1](https://github.com/lambdadb/lambdadb-mcp/releases/tag/v0.1.1) is published
+with SDK 0.6.0, keyword facets, match-all queries, and 16 text analyzers. Develop
+starts the next `0.1.2-dev.1` base; check npm for the current published dev version.
 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 first stable release:
-npx --yes @functional-systems/lambdadb-mcp@0.1.0
+# Pin the stable release:
+npx --yes @functional-systems/lambdadb-mcp@0.1.1
 # Or install globally:
 npm install -g @functional-systems/lambdadb-mcp
 lambdadb-mcp
@@ -101,9 +101,8 @@ Optional write tools:
 
 ## API contract and tool inputs
 
-The LambdaDB SDK is pinned to `@functional-systems/lambdadb@0.6.0`, checked against
-the published package and [v0.6.0 release](https://github.com/lambdadb/lambdadb-typescript-client/releases/tag/v0.6.0)
-at [`491d01e`](https://github.com/lambdadb/lambdadb-typescript-client/commit/491d01e0eb54bd135823fab79cbe32396ec03691).
+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).
 This dependency update applies to builds containing this change. Publishing the SDK
 alone does not update previously published or installed MCP packages.
 
@@ -173,6 +172,69 @@ 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.
 
+### Optional managed reranking
+
+`lambdadb_query_collection` accepts per-query `rerank`; omission or `null`
+preserves existing searches. Collection creation has no rerank setting.
+LambdaDB manages provider credentials; only the existing project API key is needed.
+See the [managed reranking contract](https://github.com/lambdadb/lambdadb-typescript-client/blob/v0.7.0/docs/managed-reranking.md).
+
+```json
+{
+  "collectionName": "articles",
+  "size": 10,
+  "query": { "knn": { "field": "bodyEmbedding", "queryText": "Restore a collection", "k": 50 } },
+  "fields": { "include": ["id", "title"] },
+  "rerank": {
+    "provider": "typesafe",
+    "model": "jev-1.13.0",
+    "queryText": "Restore a collection",
+    "fields": ["title", "body"],
+    "candidateSize": 50,
+    "onFailure": "error"
+  }
+}
+```
+
+Provider/model are fixed. `queryText` is required nonblank text, at most 8 KiB
+UTF-8, even with raw vectors. Rerank `fields` selects 1–8 unique stored scalar
+text paths in input order, independently of returned document projection.
+Optional `criteria` replaces the default with 2–10 distinct nonblank descriptions
+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.
+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`,
+match-all and filter-only Boolean requests, and preserves ref/consistentRead
+restrictions. It does not enable vector/hybrid facets; supported lexical facets
+still count all matches. Field types, candidate text and model availability
+remain server validations.
+
+Results retain server order, precision and zero. Applied envelope `score` is the
+final evaluation score in [0,1], not a probability; envelope `retrievalScore`
+retains the search score. Top-level `rerank` retains status (`applied`, `skipped`,
+`fallback`), provider/model, optional resolvedModel, counts, stage took, optional
+criteriaVersion and reason. Applied criteriaVersion is `default-relevance-v1`
+or `custom`; `custom` is not a unique rubric identity. `maxScore` retains zero;
+empty results omit it and report skipped/noCandidates with zero counts.
+Without reranking, rerank metadata and retrievalScore are absent. Metadata and
+scores survive `docsUrl` downloads.
+
+Omitted/null `onFailure` defaults to `error`. `returnOriginal` applies only to
+provider timeout, rateLimit, unavailable, invalidResponse and credentials failures.
+Fallback retains retrieval order/scores for the first size documents, discards
+partial evaluation scores and omits retrievalScore/criteriaVersion. Invalid
+input/candidates, disabled models, authorization, retrieval/hydration/ref, quota
+and capacity failures remain errors; cancellation or an exhausted deadline does
+not trigger fallback. A hybrid fallback can differ from a separate query with
+a smaller candidate cap. No extra client fallback is implemented.
+
+SDK publication and local fixtures do not establish deployment to an endpoint,
+search quality, load/failure coverage or billing readiness. Backend feature/model
+availability and operational verification remain separate dependencies.
+
 ### Text analyzers in collection creation
 
 With write tools explicitly enabled, `lambdadb_create_collection` accepts:
@@ -190,12 +252,29 @@ With write tools explicitly enabled, `lambdadb_create_collection` accepts:
 
 Supported lowercase names: `standard`, `english`, `korean`, `japanese`, `chinese`,
 `cjk`, `arabic`, `french`, `german`, `hindi`, `indonesian`, `italian`, `portuguese`,
-`russian`, `spanish`, `turkish`. Omitting `analyzers` uses the server default
+`russian`, `spanish`, `turkish`, `armenian`, `basque`, `bengali`, `brazilian`,
+`bulgarian`, `catalan`, `czech`, `danish`, `dutch`, `estonian`, `finnish`, `galician`,
+`greek`, `hungarian`, `irish`, `latvian`, `lithuanian`, `norwegian`, `persian`,
+`romanian`, `serbian`, `sorani`, `swedish`, `thai`, `simple`, `whitespace`, `stop`,
+`keyword`, `pattern`, `fingerprint`, `nepali`, `tamil`, `telugu` (49 total).
+Omitting `analyzers` uses the server default
 `["standard"]`; an empty list is passed through and does not select that default.
 Analyzers run independently without automatic language detection. Lists are sent
 unchanged; avoid duplicate names, which the server rejects. Index configuration
 validation remains in the SDK. Write tools remain disabled by default.
 
+These are fixed presets with backend default settings; custom pipelines/options
+are unsupported. The `keyword` analyzer keeps text in one token and is distinct
+from the `keyword` field type used for sorting/facets. Nepali, Tamil and Telugu
+are Lucene extensions, not common Elasticsearch/OpenSearch support. New presets
+require a supporting backend deployment. See the [analyzer contract](https://github.com/lambdadb/lambdadb-typescript-client/blob/v0.7.0/docs/models/analyzer.md).
+
+This repository uses the native SDK only and has no Qdrant payload-schema mapping.
+The SDK's [Qdrant adapter](https://github.com/lambdadb/lambdadb-typescript-client/blob/v0.7.0/docs/compatibility/qdrant.md)
+now rejects extra schema options with `UnsupportedQdrantFeatureError`. Its mapping
+remains type-only; text omits analyzers for the standard default. Migration callers
+must reject or explicitly resolve unsupported options rather than discard them.
+
 ## Tests
 
 ```bash
@@ -211,7 +290,9 @@ HTTP 201, ref/branch forwarding, invalid combinations, pagination, and `docsUrl`
 arrays/errors and local environment-file loading. Facet tests validate the published
 MCP JSON Schema and actual tool-to-SDK HTTP path, including match-all, facet-only,
 document+facet, omitted/null/default bucket options, boundaries, invalid requests,
-and all 16 analyzers. They do not require credentials
+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
 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.
@@ -229,7 +310,7 @@ LAMBDADB_RUN_LIVE_TESTS=1 LAMBDADB_LIVE_CONFIRM_PROJECT=YOUR_DEV_PROJECT npm run
 
 The live test creates one uniquely named temporary collection, checks real HTTP
 201/202 responses, metadata, pagination, filters, sorting, and Branch/Tag/Alias
-reads. It also checks all 16 analyzers in collection metadata, match-all, facet-only
+reads. It also checks all 49 analyzers in collection metadata, match-all, facet-only
 and document+facet results, default/null bucket size, keyword arrays, dotted paths,
 and facet preservation across refs and `docsUrl` downloads. The designated server
 must support these features. It writes two 3 MiB documents to force actual `docsUrl` array downloads
@@ -239,6 +320,27 @@ temporary collection in cleanup, and verifies that the collection is absent.
 Branch/Tag/Alias setup and collection cleanup use the SDK directly because these
 operations are not exposed as MCP tools. This test is separate from `npm run check`.
 
+Managed reranking has a separate live suite because it requires an enabled
+`typesafe` / `jev-1.13.0` model and can incur inference cost. Use the same explicitly
+authorized development project and write opt-in, with an additional inference opt-in:
+
+```bash
+LAMBDADB_RUN_LIVE_TESTS=1 LAMBDADB_RUN_LIVE_RERANK_TESTS=1 LAMBDADB_LIVE_CONFIRM_PROJECT=YOUR_DEV_PROJECT npm run test:live:rerank
+```
+
+It creates one temporary collection and two synthetic documents. It verifies
+omitted/null retrieval behavior, applied default and custom criteria, final size
+versus candidate count, envelope evaluation/retrieval scores, inline and actual
+`docsUrl` order/precision/metadata preservation, download credential isolation,
+and empty `skipped` results. Only short stored text is sent for evaluation; the
+large synthetic payload forces document offload without enlarging model input.
+Cleanup deletes the collection and verifies its absence even after a failed check.
+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
+checks and credential-free CI.
+
 If the environment file is outside the worktree:
 
 ```bash

package/RELEASING.md

@@ -1,27 +1,27 @@
 # Releasing LambdaDB MCP
 
-## Prepared stable candidate: 0.1.1 (2026-09-29 KST)
-
-The `release/0.1.1` branch promotes reviewed develop commit
-`d1a041ed8497eb8113b616faf87b2702fb5b80c5` with matching package/lock versions and
-a dated changelog. SDK 0.6.0 adds keyword facets, match-all and facet-only queries,
-and all 16 text analyzers. Read-only defaults and explicit write opt-in remain.
-See `docs/validation/2026-09-29-0.1.1.md` in the reviewed release source for the
-candidate validation record.
-
-Review the release PR into **main using a merge commit** to preserve ancestry.
-Preparation does not publish 0.1.1. After the main candidate is verified and
-publication is authorized, tag that main commit `v0.1.1` and publish a non-prerelease
-GitHub Release. The existing workflow validates, packs, tests, and publishes its
-exact tarball to npm `latest` with OIDC. Verify version, gitHead, integrity,
-provenance, and installed behavior before announcing availability.
-
-After publication, synchronize main back into develop through a PR with the next
-base `0.1.2-dev.1`. Do not merge stable version metadata directly into develop.
+## Current 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
+PR with preserved ancestry. The [release workflow](https://github.com/lambdadb/lambdadb-mcp/actions/runs/36557646939)
+passed Node 22.14.0 / 22 / 24 validation and published the tested artifact with
+OIDC and provenance. Registry snapshot: `latest=0.1.1`, `dev=0.1.1-dev.7`.
+SDK 0.6.0 adds keyword facets, match-all and facet-only queries, and all 16 text
+analyzers. Read-only defaults and explicit write opt-in remain.
+
+See `docs/validation/2026-09-29-0.1.1.md` in this source for separate candidate,
+development-service, and published-package evidence. Do not repeat the 0.1.1
+publication or move its tag.
+
+This synchronization brings main back into develop with the next base
+`0.1.2-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.1. Do not merge stable version metadata directly into develop.
 Facets need a supporting server and newly built keyword indexes; this release
 does not migrate existing Collections or indexes.
 
-## Status and policy
+## Historical bootstrap and 0.1.0 status
 
 As verified on **2026-09-20 (KST)**:
 

package/dist/tools/read.js

@@ -9,6 +9,21 @@ const facetsSchema = z.record(z.string(), z.strictObject({
     // Zod refinements are not represented in JSON Schema without explicit metadata.
     .meta({ maxProperties: 5 })
     .describe("Keyword field names (including dotted paths) mapped to bucket options. Requires newly built keyword indexes on a supporting server.");
+// The SDK validates UTF-8 byte budgets, nonblank text, unique paths/criteria,
+// scoring-query requirements and cross-field bounds before sending HTTP.
+const rerankSchema = z.strictObject({
+    provider: z.literal("typesafe"),
+    model: z.literal("jev-1.13.0"),
+    queryText: z.string().min(1).describe("Required nonblank query text, at most 8 KiB UTF-8, including for raw vector queries."),
+    fields: z.array(z.string().min(1)).min(1).max(8).meta({ uniqueItems: true })
+        .describe("Unique stored scalar text paths in model input order; separate from returned fields projection."),
+    candidateSize: z.number().int().min(1).max(100).nullable().optional()
+        .describe("Merged candidate cap, at least final size. Omitted/null defaults to max(50, size); never changes knn.k."),
+    onFailure: z.enum(["error", "returnOriginal"]).nullable().optional()
+        .describe("Omitted/null defaults to error. returnOriginal covers only eligible provider failures."),
+    criteria: z.array(z.string().min(1)).min(2).max(10).meta({ uniqueItems: true }).nullable().optional()
+        .describe("Distinct nonblank descriptions from lowest to highest relevance, at most 2 KiB each and 8 KiB total UTF-8. Omitted/null uses defaults.")
+}).nullable().optional().describe("Optional per-query managed reranking; requires a scoring query and positive size, forbids sort. LambdaDB manages provider credentials.");
 export function registerReadTools(server, config) {
     server.registerTool("lambdadb_list_collections", {
         title: "List Collections",
@@ -53,7 +68,7 @@ export function registerReadTools(server, config) {
     });
     server.registerTool("lambdadb_query_collection", {
         title: "Query Collection",
-        description: "Search documents and optionally return keyword facet counts across all matches. Omit query for match-all; size: 0 requires at least one facet and returns only facets. Facets require a supporting server and newly built keyword indexes.",
+        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.",
         annotations: {
             readOnlyHint: true,
             openWorldHint: false
@@ -64,6 +79,7 @@ export function registerReadTools(server, config) {
                 .describe("Documents to return (1–100), or 0 with nonempty facets."),
             query: z.record(z.string(), z.any()).optional().describe("Omit for match-all."),
             facets: facetsSchema.optional(),
+            rerank: rerankSchema,
             ref: readRefSchema.optional(),
             consistentRead: z.boolean().optional().describe("true requires a direct branch ref or omitted ref (main)."),
             includeVectors: z.boolean().optional(),
@@ -80,14 +96,22 @@ export function registerReadTools(server, config) {
             allOf: [{
                     if: { properties: { size: { const: 0 } }, required: ["size"] },
                     then: { required: ["facets"], properties: { facets: { minProperties: 1 } } }
+                }, {
+                    if: { properties: { rerank: { type: "object" } }, required: ["rerank"] },
+                    then: {
+                        required: ["query"],
+                        properties: { size: { minimum: 1 } },
+                        not: { required: ["sort"] }
+                    }
                 }]
         })
-    }, async ({ collectionName, size, query, facets, ref, consistentRead, includeVectors, sort, fields, partitionFilter }) => {
+    }, async ({ collectionName, size, query, facets, rerank, ref, consistentRead, includeVectors, sort, fields, partitionFilter }) => {
         try {
             const client = createLambdaDBClient(config);
             const input = {
                 query,
                 facets,
+                rerank,
                 size,
                 ...readOptions(ref, consistentRead),
                 includeVectors,

package/dist/tools/write.js

@@ -1,3 +1,4 @@
+import { Analyzer } from "@functional-systems/lambdadb/models";
 import { z } from "zod";
 import { createLambdaDBClient } from "../lambdadb/client.js";
 import { formatLambdaDBError } from "../lambdadb/errors.js";
@@ -5,7 +6,7 @@ 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. Text index analyzers: standard, english, korean, japanese, chinese, cjk, arabic, french, german, hindi, indonesian, italian, portuguese, russian, spanish, turkish. 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.`,
         annotations: {
             openWorldHint: false
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@functional-systems/lambdadb-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2-dev.9",
   "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: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",
     "inspect": "bash ./scripts/inspect.sh",
@@ -22,7 +23,7 @@
     "test:package": "node scripts/test-package.mjs"
   },
   "dependencies": {
-    "@functional-systems/lambdadb": "0.6.0",
+    "@functional-systems/lambdadb": "0.7.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "zod": "^4.1.12"
   },
@@ -60,5 +61,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "gitHead": "40a8afc25bb93fb14d03d23e3ab38aa1924cf060"
+  "gitHead": "99896e0279fa7610358e9abafc032dd507b10f40"
 }