@mastra/mcp-docs-server 1.2.25-alpha.1 → 1.2.25-alpha.5

package/.docs/reference/observability/tracing/trace-query.md

@@ -24,6 +24,7 @@ const result = await mastraClient.queryTraces({
         op: 'and',
         args: [
           { op: 'eq', left: { path: 'scorerId' }, right: { literal: 'factuality' } },
+          { op: 'eq', left: { path: 'scorerVersion' }, right: { literal: '2.1.0' } },
           { op: 'lt', left: { path: 'score' }, right: { literal: 0.6 } },
         ],
       },
@@ -34,7 +35,7 @@ const result = await mastraClient.queryTraces({
 })
 ```
 
-A `some` clause matches when one related record satisfies its complete nested predicate. In this example, `scorerId` and `score` must match on the same score record. A `none` clause matches when no related record satisfies its complete nested predicate.
+A `some` clause matches when one related record satisfies its complete nested predicate. In this example, `scorerId`, `scorerVersion`, and `score` must match on the same score record. A `none` clause uses anti-existence semantics: it matches when no related record satisfies its complete nested predicate. A trace with no related scores therefore matches `scores.none`.
 
 Span clauses examine the current root span and current child spans. The root `timeRange` applies only to the selected current root's `startedAt`. Related spans and scores can participate even when their own timestamps are outside that range. Related records correlate only through a matching non-null `traceId`.
 
@@ -99,17 +100,176 @@ Hono and Fastify enforce the request-body limit before JSON parsing. Express and
 
 ## Fields and operators
 
-| Predicate context | Fields                                                                                   | Operators                                                                  |
-| ----------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| Trace             | `traceId`, `threadId`, `resourceId`, `entityName`, `entityType`, `environment`, `status` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Trace             | `startedAt`, `endedAt`                                                                   | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
-| Span              | `spanType`                                                                               | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Span              | `error`                                                                                  | `exists`, `notExists`                                                      |
-| Score             | `scorerId`                                                                               | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Score             | `score`                                                                                  | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Predicate context | Fields                                                                                                                                                       | Operators                                                                  |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| Trace             | `traceId`, `threadId`, `resourceId`, `entityName`, `entityType`, `environment`, `status`                                                                     | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Trace metadata    | `metadata.<key>`                                                                                                                                             | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Trace             | `startedAt`, `endedAt`                                                                                                                                       | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Span              | `name`, `spanType`, `model`, `provider`, `status`, `entityType`, `entityId`, `entityName`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Span              | `startedAt`, `endedAt`, `durationMs`                                                                                                                         | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Span              | `error`                                                                                                                                                      | `exists`, `notExists`                                                      |
+| Score             | `scorerId`, `scorerVersion`, `scoreSource`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`                                                | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Score             | `score`, `timestamp`                                                                                                                                         | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Score             | `spanId`                                                                                                                                                     | `exists`, `notExists`                                                      |
 
 Compose predicates with `{ op: 'and', args: [...] }`, `{ op: 'or', args: [...] }`, and `{ op: 'not', arg: ... }`. Comparison predicates place a field reference on the left and a literal on the right. Membership predicates use a field reference in `value` and a homogeneous literal array in `set`.
 
+String comparisons are case-sensitive, and literals are never coerced. Canonical string fields compare exact stored values. Metadata string values are trimmed before comparison, as described below. Numeric predicates, including `score` and `durationMs`, require numbers, while timestamp predicates require ISO timestamp strings. A missing value satisfies neither positive nor ordered predicates, although it does satisfy the negative operators `ne` and `notIn`. Combine a negative predicate with `exists` when the field must also be present.
+
+### Filter by span properties
+
+Every condition inside one `spans.some` or `spans.none` clause applies to the same current span. For example, this predicate finds a failed tool span whose name is `medication_lookup`; a matching name on one span and an error on another don't satisfy it:
+
+```typescript
+const failedMedicationLookup = {
+  spans: {
+    some: {
+      op: 'and',
+      args: [
+        { op: 'eq', left: { path: 'name' }, right: { literal: 'medication_lookup' } },
+        { op: 'eq', left: { path: 'spanType' }, right: { literal: 'tool_call' } },
+        { op: 'exists', path: 'error' },
+      ],
+    },
+  },
+}
+```
+
+Use `status` for the derived `success` or `error` outcome. Use `error` when you only need to test whether error details are present.
+
+`durationMs` is the span's elapsed time in milliseconds. Span `startedAt` and `endedAt` conditions filter related spans independently of the top-level root `timeRange`:
+
+```typescript
+const slowModelCalls = {
+  spans: {
+    some: {
+      op: 'and',
+      args: [
+        { op: 'eq', left: { path: 'spanType' }, right: { literal: 'model_generation' } },
+        { op: 'gt', left: { path: 'durationMs' }, right: { literal: 5000 } },
+        {
+          op: 'gte',
+          left: { path: 'startedAt' },
+          right: { literal: '2026-07-15T00:00:00.000Z' },
+        },
+      ],
+    },
+  },
+}
+```
+
+`model` and `provider` read the canonical `attributes.model` and `attributes.provider` span attributes. Only stored string values are queryable; missing, null, and non-string values count as missing.
+
+```typescript
+const selectedModel = {
+  spans: {
+    some: {
+      op: 'and',
+      args: [
+        {
+          op: 'eq',
+          left: { path: 'model' },
+          right: { literal: 'claude-sonnet-4-6' },
+        },
+        { op: 'eq', left: { path: 'provider' }, right: { literal: 'anthropic' } },
+      ],
+    },
+  },
+}
+```
+
+Use generic entity fields for tool and retrieval identity. The version fields let one clause qualify the same span by its entity lineage:
+
+```typescript
+const versionedRetrieval = {
+  spans: {
+    some: {
+      op: 'and',
+      args: [
+        { op: 'eq', left: { path: 'entityType' }, right: { literal: 'rag_ingestion' } },
+        { op: 'eq', left: { path: 'entityId' }, right: { literal: 'medication-index' } },
+        { op: 'eq', left: { path: 'entityVersionId' }, right: { literal: 'index-v3' } },
+        { op: 'eq', left: { path: 'rootEntityVersionId' }, right: { literal: 'agent-v2' } },
+      ],
+    },
+  },
+}
+```
+
+### Filter by score time
+
+Score timestamps are independent of the required top-level trace `timeRange`. The top-level range selects trace candidates by trace start time. A nested `timestamp` predicate limits related score records:
+
+```typescript
+const query = {
+  timeRange: {
+    from: '2026-08-01T00:00:00.000Z',
+    to: '2026-08-08T00:00:00.000Z',
+  },
+  where: {
+    scores: {
+      some: {
+        op: 'and',
+        args: [
+          { op: 'eq', left: { path: 'scoreSource' }, right: { literal: 'automated' } },
+          {
+            op: 'gte',
+            left: { path: 'timestamp' },
+            right: { literal: '2026-07-15T00:00:00.000Z' },
+          },
+          {
+            op: 'lt',
+            left: { path: 'timestamp' },
+            right: { literal: '2026-08-01T00:00:00.000Z' },
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+### Filter by span anchoring
+
+Use `spanId` only to test whether a score targets a span. The predicate doesn't join the score to a matching span predicate:
+
+```typescript
+// At least one score targets a span.
+const anchoredToSpanWhere = { scores: { some: { op: 'exists', path: 'spanId' } } }
+
+// At least one score applies to the trace rather than a span.
+const traceLevelScoreWhere = { scores: { some: { op: 'notExists', path: 'spanId' } } }
+```
+
+The deprecated `source` field and `scorerName` aren't available as score predicate fields. Use the canonical `scoreSource` and `scorerId` fields.
+
+### Filter by metadata
+
+Use `metadata.<key>` paths for custom dimensions stored on the current root span. Metadata predicates compare trimmed, non-empty string values exactly and case-sensitively. Leading and trailing whitespace in a stored string value is ignored. Values empty after trimming count as missing. Null, numeric, boolean, object, and array values also count as missing.
+
+```typescript
+const messageTrace = {
+  op: 'and',
+  args: [
+    { op: 'eq', left: { path: 'metadata.messageId' }, right: { literal: 'message-123' } },
+    { op: 'in', value: { path: 'metadata.actorRole' }, set: ['assistant', 'tool'] },
+    { op: 'exists', path: 'metadata.protocolVersion' },
+    {
+      op: 'or',
+      args: [
+        { op: 'eq', left: { path: 'metadata.temporalRunId' }, right: { literal: 'run-456' } },
+        { op: 'eq', left: { path: 'metadata.externalTraceId' }, right: { literal: 'trace-789' } },
+      ],
+    },
+    { op: 'not', arg: { op: 'exists', path: 'metadata.parentMessageId' } },
+  ],
+}
+```
+
+The key must name one top-level property. Empty keys and nested paths are rejected. Metadata keys aren't trimmed, so leading and trailing whitespace remains part of the exact key identity. When metadata duplicates a canonical trace field, such as `resourceId`, `threadId`, or `environment`, prefer the canonical field because it uses the dedicated storage column. The `metadata.<key>` form remains available when you specifically need the value from the metadata object. Metadata and canonical values may differ.
+
+Metadata fields aren't available for grouping or field discovery.
+
 ## Responses
 
 An ungrouped query returns only lightweight completed traces:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.25-alpha.1",
+  "version": "1.2.25-alpha.5",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.66.0-alpha.0",
+    "@mastra/core": "1.66.0-alpha.2",
     "@mastra/mcp": "^1.17.3"
   },
   "devDependencies": {
@@ -45,7 +45,7 @@
     "typescript": "^7.0.2",
     "vitest": "4.1.10",
     "@internal/lint": "0.0.131",
-    "@mastra/core": "1.66.0-alpha.0",
+    "@mastra/core": "1.66.0-alpha.2",
     "@internal/types-builder": "0.0.106"
   },
   "homepage": "https://mastra.ai",