@mastra/mcp-docs-server 1.1.39-alpha.8 → 1.1.39

package/.docs/reference/vectors/convex.md

@@ -1,6 +1,10 @@
 # Convex vector store
 
-The ConvexVector class provides vector storage and similarity search using [Convex](https://convex.dev). It stores embeddings inside Convex and performs cosine similarity search.
+The `ConvexVector` class provides vector storage and similarity search using [Convex](https://convex.dev). It stores embeddings inside Convex and performs cosine similarity search in the Mastra adapter.
+
+> **Development-scale search:** `ConvexVector` reads matching vectors through the Mastra storage handler, filters in JavaScript, computes cosine similarity, sorts results, and returns the top matches. Use it for local development, tests, and small datasets.
+>
+> For production vector search on Convex, use `ConvexNativeVector`. It uses the Convex native `vectorSearch` API, which requires a deployed Convex vector index and a Convex action.
 
 ## Installation
 
@@ -42,7 +46,7 @@ Before using `ConvexVector`, you need to set up the Convex schema and storage ha
 
 ## Constructor examples
 
-### Basic Configuration
+### Basic configuration
 
 ```ts
 import { ConvexVector } from '@mastra/convex'
@@ -54,7 +58,115 @@ const vectorStore = new ConvexVector({
 })
 ```
 
-### Custom Storage Function
+### Native Convex vector search
+
+Use `ConvexNativeVector` for production vector workloads. It stores vectors in a dedicated Convex table and queries a schema-defined Convex vector index.
+
+In `convex/schema.ts`, define a dedicated table for each Mastra vector index:
+
+```typescript
+import { defineSchema } from 'convex/server'
+import { defineMastraNativeVectorTable } from '@mastra/convex/schema'
+
+export default defineSchema({
+  docs_vectors: defineMastraNativeVectorTable({
+    dimensions: 1536,
+  }),
+})
+```
+
+In `convex/mastra/nativeVector.ts`, export the native vector handlers:
+
+```typescript
+import {
+  mastraNativeVectorAction,
+  mastraNativeVectorMutation,
+  mastraNativeVectorQuery,
+} from '@mastra/convex/server'
+
+export const query = mastraNativeVectorAction
+export const read = mastraNativeVectorQuery
+export const write = mastraNativeVectorMutation
+```
+
+In your Mastra app, configure `ConvexNativeVector` with the deployed table and vector index:
+
+```typescript
+import { ConvexNativeVector } from '@mastra/convex'
+
+const vectorStore = new ConvexNativeVector({
+  id: 'convex-native-vectors',
+  deploymentUrl: process.env.CONVEX_URL!,
+  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
+  indexes: {
+    docs: {
+      tableName: 'docs_vectors',
+      vectorIndexName: 'by_embedding',
+      dimension: 1536,
+    },
+  },
+})
+
+const results = await vectorStore.query({
+  indexName: 'docs',
+  queryVector: embedding,
+  topK: 10,
+})
+```
+
+For native filter support, declare filter fields in your Convex schema. The native vector handlers copy matching metadata fields to top-level document fields when vectors are written.
+
+```typescript
+import { defineSchema, defineTable } from 'convex/server'
+import { v } from 'convex/values'
+
+export default defineSchema({
+  docs_vectors: defineTable({
+    id: v.string(),
+    embedding: v.array(v.float64()),
+    metadata: v.optional(v.any()),
+    tenantId: v.string(),
+  })
+    .index('by_record_id', ['id'])
+    .vectorIndex('by_embedding', {
+      vectorField: 'embedding',
+      dimensions: 1536,
+      filterFields: ['tenantId'],
+    }),
+})
+```
+
+```typescript
+const vectorStore = new ConvexNativeVector({
+  id: 'convex-native-vectors',
+  deploymentUrl: process.env.CONVEX_URL!,
+  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
+  indexes: {
+    docs: {
+      tableName: 'docs_vectors',
+      dimension: 1536,
+      filterFields: ['tenantId'],
+    },
+  },
+})
+
+await vectorStore.upsert({
+  indexName: 'docs',
+  ids: ['chunk-1'],
+  vectors: [embedding],
+  metadata: [{ tenantId: 'acme', text: 'Account setup guide' }],
+})
+
+const results = await vectorStore.query({
+  indexName: 'docs',
+  queryVector: embedding,
+  filter: { tenantId: 'acme' },
+})
+```
+
+`ConvexNativeVector` supports Convex native vector filter shapes: one equality field, or `$or` of equality fields. It doesn't support metadata-only queries, filter-based updates, or filter-based deletes. Use vector IDs for updates and deletes.
+
+### Custom storage function
 
 ```ts
 const vectorStore = new ConvexVector({
@@ -237,7 +349,7 @@ interface QueryResult {
 
 ## Metadata filtering
 
-ConvexVector supports metadata filtering with various operators:
+`ConvexVector` supports metadata filtering with various operators. These filters are applied by the adapter after vectors are loaded from Convex.
 
 ```typescript
 // Simple equality
@@ -267,7 +379,7 @@ const results = await vectorStore.query({
 })
 ```
 
-### Supported Filter Operators
+### Supported filter operators
 
 | Operator | Description           |
 | -------- | --------------------- |
@@ -284,14 +396,24 @@ const results = await vectorStore.query({
 
 ## Architecture
 
-ConvexVector stores vectors in the `mastra_vectors` table with the following structure:
+`ConvexVector` stores vectors in the `mastra_vectors` table with the following structure:
 
 - `id`: Unique vector identifier
 - `indexName`: Name of the index
 - `embedding`: The vector data (array of floats)
 - `metadata`: Optional JSON metadata
 
-Vector similarity search is performed using cosine similarity, computed in the Convex function.
+Vector similarity search is performed with cosine similarity in the Mastra adapter. This keeps setup flexible, but it's not designed for large production vector collections.
+
+`ConvexNativeVector` stores each Mastra vector index in a dedicated Convex table. Its queries call a Convex action that uses `ctx.vectorSearch`, then load the matched documents through a Convex query. This follows the Convex native vector search model:
+
+- Vector indexes are declared in `convex/schema.ts`.
+- Vector search runs from a Convex action.
+- `topK` must be between `1` and `256`.
+- Filters must target fields listed in the Convex vector index `filterFields`.
+- Use one dedicated table per Mastra vector index to avoid cross-index results.
+
+Use an external vector database when you need dynamic index creation at runtime, metadata-only queries, complex filter operators, filter-based bulk updates or deletes, or result limits above Convex's native vector search cap.
 
 ## Related
 

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @mastra/mcp-docs-server
 
+## 1.1.39
+
+### Patch Changes
+
+- Updated dependencies [[`452036a`](https://github.com/mastra-ai/mastra/commit/452036a0d965b4f4c1efd93606e4f03b50b807a5), [`c272d50`](https://github.com/mastra-ai/mastra/commit/c272d50610a54496b6b6d92ccd4d37b333a2613a), [`27fd1b7`](https://github.com/mastra-ai/mastra/commit/27fd1b79ac62eb7694f92587eb7d1be05b59be01), [`5ba7253`](https://github.com/mastra-ai/mastra/commit/5ba7253745c85e8df8012a76d954c640ffa336f7), [`5556cc1`](https://github.com/mastra-ai/mastra/commit/5556cc1befec71518d84f826b3bfe3a079a9daf7), [`f73980d`](https://github.com/mastra-ai/mastra/commit/f73980d651eb5f7f1ab20582de4615a1b6f10fce), [`5499303`](https://github.com/mastra-ai/mastra/commit/54993032c1ebc09642625b78d2014e0cf84a3cae), [`a702009`](https://github.com/mastra-ai/mastra/commit/a702009d3cfaa745120f501e21c783ed4d6a3072), [`46cbb7e`](https://github.com/mastra-ai/mastra/commit/46cbb7e84a0fadcf8c26ddfad38278732c22143e), [`9430352`](https://github.com/mastra-ai/mastra/commit/94303523460cb09dcd0d8139c11926029631d6ba), [`9aee493`](https://github.com/mastra-ai/mastra/commit/9aee493ed6089b5133472623dcce49934bf2d509), [`d8692af`](https://github.com/mastra-ai/mastra/commit/d8692afa253028e39cdce2aafa0ac414071a762e), [`1a9cc60`](https://github.com/mastra-ai/mastra/commit/1a9cc6069f9910fc3d59e4953ac8cd95d89ad6f5), [`8cdb86c`](https://github.com/mastra-ai/mastra/commit/8cdb86ceed1137bc2768e147dce85a0692b9fb26), [`8534d79`](https://github.com/mastra-ai/mastra/commit/8534d791fa1cb70fe1c19e2604c4b63cc10dd051), [`eda90c5`](https://github.com/mastra-ai/mastra/commit/eda90c5bfd7de11805ecc9f4552716c895fbaf78), [`a935b0a`](https://github.com/mastra-ai/mastra/commit/a935b0a0977ae3f196b33ec7621f528069c82db0), [`9c88701`](https://github.com/mastra-ai/mastra/commit/9c8870195b41a38dc40b6ba2aa55eda04df8fa69), [`c78f8cd`](https://github.com/mastra-ai/mastra/commit/c78f8cd6222a86e6c60ae5210b6929ad5221b6fb), [`e146aad`](https://github.com/mastra-ai/mastra/commit/e146aadbba66c410ba0e74bac4c50135495cb8dd), [`4bd4e8e`](https://github.com/mastra-ai/mastra/commit/4bd4e8e042f6687559f49a560a7914cee9b85447), [`ac79462`](https://github.com/mastra-ai/mastra/commit/ac79462b98f1062394c45093aa515b0766f27ee2), [`1a0ec78`](https://github.com/mastra-ai/mastra/commit/1a0ec789a26cae443744e9abbd62ed6ee676af39), [`e47bca7`](https://github.com/mastra-ai/mastra/commit/e47bca7b72866d3abd173b9f530ac4318113a8ff), [`afc004f`](https://github.com/mastra-ai/mastra/commit/afc004f5cc7e30697809e7021820b9f5881e6719), [`0031d0f`](https://github.com/mastra-ai/mastra/commit/0031d0f13831d7843ac5d498734a7d92862e2ce3), [`841a222`](https://github.com/mastra-ai/mastra/commit/841a222560d8c19238f8213713f30535cdd82284), [`64c1e0b`](https://github.com/mastra-ai/mastra/commit/64c1e0b35165c96b659818bd0177aa18794ef11f), [`40d83a9`](https://github.com/mastra-ai/mastra/commit/40d83a90d9be31a1b83e04649edb703eb7753e33), [`4e88dc6`](https://github.com/mastra-ai/mastra/commit/4e88dc6b89f154c0eae37221c8126be0c23c569f), [`19018f0`](https://github.com/mastra-ai/mastra/commit/19018f05722af74a5978781a7731a654b26f7f2a), [`19281c7`](https://github.com/mastra-ai/mastra/commit/19281c70424f757219782de16c2699743c5e04d0), [`3498b49`](https://github.com/mastra-ai/mastra/commit/3498b4946be94f4313cd817733589680dcda5278), [`d52b6fe`](https://github.com/mastra-ai/mastra/commit/d52b6fe1c56853eb38864baae0bbfa75cc739ccb), [`408be73`](https://github.com/mastra-ai/mastra/commit/408be73449dfab92b51eab8c6623b6c443debc25), [`359439b`](https://github.com/mastra-ai/mastra/commit/359439bb8c635e048176306828195f8297f50021), [`71a820b`](https://github.com/mastra-ai/mastra/commit/71a820b2353fa1406772c50760a3732058a8b337), [`1698f5e`](https://github.com/mastra-ai/mastra/commit/1698f5ec141d34f22a873efdb145ce3cdf848a5e)]:
+  - @mastra/core@1.36.0
+  - @mastra/mcp@1.8.0
+
+## 1.1.39-alpha.19
+
+### Patch Changes
+
+- Updated dependencies [[`27fd1b7`](https://github.com/mastra-ai/mastra/commit/27fd1b79ac62eb7694f92587eb7d1be05b59be01), [`a702009`](https://github.com/mastra-ai/mastra/commit/a702009d3cfaa745120f501e21c783ed4d6a3072), [`46cbb7e`](https://github.com/mastra-ai/mastra/commit/46cbb7e84a0fadcf8c26ddfad38278732c22143e), [`8534d79`](https://github.com/mastra-ai/mastra/commit/8534d791fa1cb70fe1c19e2604c4b63cc10dd051), [`c78f8cd`](https://github.com/mastra-ai/mastra/commit/c78f8cd6222a86e6c60ae5210b6929ad5221b6fb), [`e146aad`](https://github.com/mastra-ai/mastra/commit/e146aadbba66c410ba0e74bac4c50135495cb8dd), [`1a0ec78`](https://github.com/mastra-ai/mastra/commit/1a0ec789a26cae443744e9abbd62ed6ee676af39), [`d52b6fe`](https://github.com/mastra-ai/mastra/commit/d52b6fe1c56853eb38864baae0bbfa75cc739ccb)]:
+  - @mastra/core@1.36.0-alpha.10
+  - @mastra/mcp@1.8.0-alpha.2
+
+## 1.1.39-alpha.17
+
+### Patch Changes
+
+- Updated dependencies [[`1698f5e`](https://github.com/mastra-ai/mastra/commit/1698f5ec141d34f22a873efdb145ce3cdf848a5e)]:
+  - @mastra/core@1.36.0-alpha.9
+
+## 1.1.39-alpha.16
+
+### Patch Changes
+
+- Updated dependencies [[`9aee493`](https://github.com/mastra-ai/mastra/commit/9aee493ed6089b5133472623dcce49934bf2d509)]:
+  - @mastra/core@1.36.0-alpha.8
+
+## 1.1.39-alpha.14
+
+### Patch Changes
+
+- Updated dependencies [[`a935b0a`](https://github.com/mastra-ai/mastra/commit/a935b0a0977ae3f196b33ec7621f528069c82db0)]:
+  - @mastra/core@1.36.0-alpha.7
+
+## 1.1.39-alpha.13
+
+### Patch Changes
+
+- Updated dependencies [[`71a820b`](https://github.com/mastra-ai/mastra/commit/71a820b2353fa1406772c50760a3732058a8b337)]:
+  - @mastra/core@1.36.0-alpha.6
+
+## 1.1.39-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [[`ac79462`](https://github.com/mastra-ai/mastra/commit/ac79462b98f1062394c45093aa515b0766f27ee2), [`19281c7`](https://github.com/mastra-ai/mastra/commit/19281c70424f757219782de16c2699743c5e04d0)]:
+  - @mastra/core@1.36.0-alpha.5
+
+## 1.1.39-alpha.11
+
+### Patch Changes
+
+- Updated dependencies [[`c272d50`](https://github.com/mastra-ai/mastra/commit/c272d50610a54496b6b6d92ccd4d37b333a2613a), [`d8692af`](https://github.com/mastra-ai/mastra/commit/d8692afa253028e39cdce2aafa0ac414071a762e), [`4bd4e8e`](https://github.com/mastra-ai/mastra/commit/4bd4e8e042f6687559f49a560a7914cee9b85447), [`841a222`](https://github.com/mastra-ai/mastra/commit/841a222560d8c19238f8213713f30535cdd82284)]:
+  - @mastra/core@1.36.0-alpha.4
+  - @mastra/mcp@1.8.0-alpha.1
+
+## 1.1.39-alpha.9
+
+### Patch Changes
+
+- Updated dependencies [[`5556cc1`](https://github.com/mastra-ai/mastra/commit/5556cc1befec71518d84f826b3bfe3a079a9daf7), [`5499303`](https://github.com/mastra-ai/mastra/commit/54993032c1ebc09642625b78d2014e0cf84a3cae), [`e47bca7`](https://github.com/mastra-ai/mastra/commit/e47bca7b72866d3abd173b9f530ac4318113a8ff), [`0031d0f`](https://github.com/mastra-ai/mastra/commit/0031d0f13831d7843ac5d498734a7d92862e2ce3), [`3498b49`](https://github.com/mastra-ai/mastra/commit/3498b4946be94f4313cd817733589680dcda5278), [`359439b`](https://github.com/mastra-ai/mastra/commit/359439bb8c635e048176306828195f8297f50021)]:
+  - @mastra/core@1.36.0-alpha.3
+
 ## 1.1.39-alpha.7
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.39-alpha.8",
+  "version": "1.1.39",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.36.0-alpha.2",
-    "@mastra/mcp": "^1.7.1-alpha.0"
+    "@mastra/core": "1.36.0",
+    "@mastra/mcp": "^1.8.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
-    "@internal/types-builder": "0.0.71",
-    "@internal/lint": "0.0.96",
-    "@mastra/core": "1.36.0-alpha.2"
+    "@internal/lint": "0.0.97",
+    "@internal/types-builder": "0.0.72",
+    "@mastra/core": "1.36.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {