@functional-systems/lambdadb-mcp 0.1.0 → 0.1.1-dev.7

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## Unreleased
+
+- Pin the LambdaDB TypeScript SDK to 0.6.0, including all 16 text analyzers.
+- Add keyword facets, query omission for match-all, and facet-only `size: 0` to
+  `lambdadb_query_collection`. Preserve omitted/null bucket sizes and facet results,
+  including automatic document downloads; retain existing search options and refs.
+- Expose facet limits and the `size: 0` condition in MCP JSON Schema and validate
+  them through tool calls, SDK HTTP contracts, installed-package tests, and the
+  opt-in live suite. Read-only defaults and explicit write opt-in are unchanged.
+- Facets require a supporting server and newly built keyword indexes. Existing
+  Collections are not migrated, and existing MCP installations require an update
+  to a separately published MCP version containing this change.
+
 ## [0.1.0] - 2026-09-20
 
 - Package `@functional-systems/lambdadb-mcp` and the `lambdadb-mcp` executable for npm/npx distribution under Apache-2.0.

package/README.md

@@ -14,19 +14,20 @@ MCP server for LambdaDB using the official TypeScript MCP SDK and the official L
 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 package is published on the `dev` channel. Until a stable release exists,
-select `@dev` or an exact published prerelease. As verified on 2026-09-20 (KST),
-`dev` resolves to `0.1.0-dev.5`; `latest` still points to the bootstrap prerelease
-`0.1.0-dev.1` and does not indicate a stable release. See
+The stable package is available on npm. As verified on 2026-09-20 (KST),
+`latest` resolves to `0.1.0` and `dev` to `0.1.0-dev.5`. Use an exact version for
+reproducibility or the default stable channel for initial setup. See
 [release status and policy](RELEASING.md).
 
 ```sh
-npx --yes @functional-systems/lambdadb-mcp@dev
-# After a stable release exists:
+npx --yes @functional-systems/lambdadb-mcp
+# Pin the first stable release:
+npx --yes @functional-systems/lambdadb-mcp@0.1.0
+# Or install globally:
 npm install -g @functional-systems/lambdadb-mcp
 lambdadb-mcp
-# Or run without a global installation:
-npx --yes @functional-systems/lambdadb-mcp
+# Opt into development builds explicitly:
+npx --yes @functional-systems/lambdadb-mcp@dev
 ```
 
 Set the environment variables below in your MCP client or securely in the parent
@@ -94,10 +95,11 @@ Optional write tools:
 
 ## API contract and tool inputs
 
-The LambdaDB SDK is pinned to `@functional-systems/lambdadb@0.5.1`.
-The tool contract was checked against LambdaDB develop
-[`d1a76659884a9ed09283a0b2e2989897dc799247`](https://github.com/lambdadb/lambdadb/commit/d1a76659884a9ed09283a0b2e2989897dc799247).
-This source revision does not establish which API revision is deployed.
+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).
+This dependency update applies to builds containing this change. Publishing the SDK
+alone does not update previously published or installed MCP packages.
 
 - Collection creation requires a nonempty `indexConfigs` and accepts `description`,
   metadata `tags`, `partitionConfig`, and `snapshotRetentionInDays` (1–31).
@@ -105,6 +107,12 @@ This source revision does not establish which API revision is deployed.
 - Query, Fetch, and List accept `ref: { kind: "branch" | "tag" | "alias", name: "..." }`.
   Omitting `ref` reads from `main`. `consistentRead: true` is supported only by
   Query/Fetch with an omitted ref or a direct Branch ref. List has no `consistentRead`.
+- Query may omit `query` for match-all and accepts `facets` for keyword bucket counts
+  across all matches. Document `size` is 1–100, or 0 when at least one facet is supplied.
+  Up to five facet fields (including dotted paths) are allowed. Each field's options
+  accept only `size`: an integer from 1–100, omitted, or `null`. Omitted/null bucket
+  size uses the server default of 10; MCP forwards it unchanged. Empty `facets: {}`
+  is accepted except with `size: 0`. Facet results survive inline and `docsUrl` responses.
 - List also accepts `filter`, `fields`, `includeVectors`, and `partitionFilter`.
   The SDK selects the extended POST endpoint when needed and preserves pagination tokens.
 - Upsert/Delete accept an optional `branch`; omitting it writes to `main`.
@@ -121,6 +129,67 @@ Query/Fetch/List download top-level document arrays and retain legacy `{ "docs":
 support without sending the project API key to the download URL. No additional SDK
 patch is needed for this issue.
 
+### Query examples
+
+Arguments for `lambdadb_query_collection`, returning only facets across all documents:
+
+```json
+{
+  "collectionName": "products",
+  "size": 0,
+  "facets": { "category": {}, "metadata.brand": { "size": null } }
+}
+```
+
+Return matching documents and facets together:
+
+```json
+{
+  "collectionName": "products",
+  "query": { "queryString": { "query": "title:coffee" } },
+  "size": 10,
+  "facets": { "category": { "size": 5 } },
+  "fields": { "include": ["id", "title", "category"] }
+}
+```
+
+For match-all documents without facets, use `{ "collectionName": "products", "size": 10 }`.
+MCP returns JSON in its text content, with `docs`, `total`, `took`, and (when returned
+by the service) `facets`, for example `"facets": { "category": { "buckets": [
+{ "value": "drinks", "count": 42 } ] } }`. Bucket counts cover all matching
+documents, independently of document `size`; duplicate keyword array values count
+once per document. `total` counts returned documents (0 for facet-only requests),
+not all matching documents. Counts use JavaScript Number and may lose integer precision
+above `Number.MAX_SAFE_INTEGER`.
+
+Facets require a supporting server deployment and newly built keyword indexes.
+This MCP update does not migrate existing Collections or indexes. Partial updates,
+segment merging, and old Tags do not upgrade old indexes. If migration is needed,
+plan and authorize reinsertion into a new Collection separately.
+
+### Text analyzers in collection creation
+
+With write tools explicitly enabled, `lambdadb_create_collection` accepts:
+
+```json
+{
+  "collectionName": "products",
+  "indexConfigs": {
+    "title": { "type": "text", "analyzers": ["english", "chinese", "french"] },
+    "category": { "type": "keyword" },
+    "metadata": { "type": "object", "objectIndexConfigs": { "brand": { "type": "keyword" } } }
+  }
+}
+```
+
+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
+`["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.
+
 ## Tests
 
 ```bash
@@ -133,7 +202,10 @@ npm run test:package
 client to this server and exercise the installed SDK against a local HTTP fixture.
 They cover read-only defaults, write opt-in, List/Get response validation, creation
 HTTP 201, ref/branch forwarding, invalid combinations, pagination, and `docsUrl`
-arrays/errors and local environment-file loading. They do not require credentials
+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
 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.
@@ -151,7 +223,10 @@ 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 writes two 3 MiB documents to force actual `docsUrl` array downloads
+reads. It also checks all 16 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
 through the MCP tools and checks full payload integrity and download credential
 isolation. It allows up to five minutes for committed visibility, deletes its
 temporary collection in cleanup, and verifies that the collection is absent.

package/RELEASING.md

@@ -13,13 +13,13 @@ As verified on **2026-09-20 (KST)**:
 - Automatic dev publication is enabled (`NPM_DEV_PUBLISH_ENABLED=true`). Eligible
   develop pushes publish after validation; a documentation-only merge can also
   produce a new dev version.
-- `dev=0.1.0-dev.5`; `latest=0.1.0-dev.1` is still the bootstrap prerelease.
-  There is no rc/stable release or GitHub Release yet. Prefer `@dev` or an exact
-  published version until stable is available.
-- The `0.1.0` stable candidate carries the publishing workflow and matching dated
-  release metadata for main review. Merging the candidate validates main but does
-  not publish a package. Publication requires the explicit GitHub release
-  `v0.1.0` with `prerelease: false`, which publishes to `latest`; see [explicit rc/stable publication](#explicit-rcstable-publication).
+- First stable release: [`v0.1.0`](https://github.com/lambdadb/lambdadb-mcp/releases/tag/v0.1.0).
+  The [release workflow](https://github.com/lambdadb/lambdadb-mcp/actions/runs/35494365745)
+  published `0.1.0` with OIDC and provenance; `latest=0.1.0`, `dev=0.1.0-dev.5`.
+- main contains the stable release and publishing workflow. develop resumes with
+  the `0.1.1-dev.1` base; CI generates its dev counter from first-parent history.
+  Eligible develop pushes can publish the next dev version while leaving
+  `latest` on `0.1.0`.
 - See the [validation record](https://github.com/lambdadb/lambdadb-mcp/blob/develop/docs/validation/2026-09-20-npm.md) for package,
   provenance, and live-service evidence and their separate scopes.
 

package/dist/tools/read.js

@@ -2,6 +2,13 @@ import { z } from "zod";
 import { createLambdaDBClient } from "../lambdadb/client.js";
 import { formatLambdaDBError } from "../lambdadb/errors.js";
 import { fieldsSchema, jsonResult, nameSchema, partitionFilterSchema, readOptions, readRefSchema } from "./shared.js";
+const facetsSchema = z.record(z.string(), z.strictObject({
+    size: z.number().int().min(1).max(100).nullable().optional()
+        .describe("Maximum buckets; omitted or null uses the server default of 10.")
+})).refine((facets) => Object.keys(facets).length <= 5, "At most five facet fields may be requested.")
+    // 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.");
 export function registerReadTools(server, config) {
     server.registerTool("lambdadb_list_collections", {
         title: "List Collections",
@@ -46,15 +53,17 @@ export function registerReadTools(server, config) {
     });
     server.registerTool("lambdadb_query_collection", {
         title: "Query Collection",
-        description: "Run a search query against a collection and return the matching documents.",
+        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.",
         annotations: {
             readOnlyHint: true,
             openWorldHint: false
         },
         inputSchema: z.strictObject({
             collectionName: nameSchema,
-            size: z.number().int().min(1).max(100).optional(),
-            query: z.record(z.string(), z.any()),
+            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."),
+            facets: facetsSchema.optional(),
             ref: readRefSchema.optional(),
             consistentRead: z.boolean().optional().describe("true requires a direct branch ref or omitted ref (main)."),
             includeVectors: z.boolean().optional(),
@@ -62,12 +71,23 @@ export function registerReadTools(server, config) {
             sort: z.array(z.record(z.string(), z.string().regex(/^([aA][sS][cC]|[dD][eE][sS][cC])$/))).optional(),
             fields: fieldsSchema.optional(),
             partitionFilter: partitionFilterSchema.optional()
+        }).superRefine((input, context) => {
+            if (input.size === 0 && Object.keys(input.facets ?? {}).length === 0) {
+                context.addIssue({ code: "custom", path: ["facets"], message: "size: 0 requires at least one facet." });
+            }
+        }).meta({
+            // Keep the cross-field rule visible to MCP clients as well as tools/call.
+            allOf: [{
+                    if: { properties: { size: { const: 0 } }, required: ["size"] },
+                    then: { required: ["facets"], properties: { facets: { minProperties: 1 } } }
+                }]
         })
-    }, async ({ collectionName, size, query, ref, consistentRead, includeVectors, sort, fields, partitionFilter }) => {
+    }, async ({ collectionName, size, query, facets, ref, consistentRead, includeVectors, sort, fields, partitionFilter }) => {
         try {
             const client = createLambdaDBClient(config);
             const input = {
                 query,
+                facets,
                 size,
                 ...readOptions(ref, consistentRead),
                 includeVectors,

package/dist/tools/write.js

@@ -5,7 +5,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.",
+        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.",
         annotations: {
             openWorldHint: false
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@functional-systems/lambdadb-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1-dev.7",
   "private": false,
   "description": "MCP server for LambdaDB data plane",
   "type": "module",
@@ -22,7 +22,7 @@
     "test:package": "node scripts/test-package.mjs"
   },
   "dependencies": {
-    "@functional-systems/lambdadb": "0.5.1",
+    "@functional-systems/lambdadb": "0.6.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "zod": "^4.1.12"
   },
@@ -60,5 +60,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "gitHead": "29be7b9cca26c6e619e9f9ad689cca3663c09d46"
+  "gitHead": "d1a041ed8497eb8113b616faf87b2702fb5b80c5"
 }