@mastra/mcp-docs-server 1.2.28 → 1.3.0-alpha.1

package/.docs/models/gateways/netlify.md

@@ -4,7 +4,7 @@
 
 # Netlify
 
-Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 267 models through Mastra's model router.
+Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 268 models through Mastra's model router.
 
 Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
 
@@ -279,6 +279,7 @@ ANTHROPIC_API_KEY=ant-...
 | `openrouter/thinkingmachines/inkling`                                 |
 | `openrouter/thinkingmachines/inkling-small`                           |
 | `openrouter/undi95/remm-slerp-l2-13b`                                 |
+| `openrouter/upstage/solar-mini4`                                      |
 | `openrouter/upstage/solar-pro4`                                       |
 | `openrouter/x-ai/grok-4.20`                                           |
 | `openrouter/x-ai/grok-4.20-multi-agent`                               |

package/.docs/models/gateways/openrouter.md

@@ -4,7 +4,7 @@
 
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 382 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 383 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -389,6 +389,7 @@ ANTHROPIC_API_KEY=ant-...
 | `thinkingmachines/inkling:free`                            |
 | `unbiased/pareto`                                          |
 | `undi95/remm-slerp-l2-13b`                                 |
+| `upstage/solar-mini4`                                      |
 | `upstage/solar-pro-3`                                      |
 | `upstage/solar-pro4`                                       |
 | `writer/palmyra-x5`                                        |

package/.docs/models/index.md

@@ -4,7 +4,7 @@
 
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 7576 models from 210 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 7579 models from 210 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/edenai.md

@@ -138,7 +138,7 @@ for await (const chunk of stream) {
 | `edenai/fireworks_ai/gpt-oss-120b`                                     | 131K    |       |           |       |       |       | $0.15      | $0.60       |
 | `edenai/flexai/DeepSeek-V4-Flash-0731`                                 | 1.0M    |       |           |       |       |       | $0.07      | $0.18       |
 | `edenai/flexai/gpt-oss-120b`                                           | 131K    |       |           |       |       |       | $0.04      | $0.17       |
-| `edenai/flexai/gpt-oss-20b`                                            | 131K    |       |           |       |       |       | $0.03      | $0.13       |
+| `edenai/flexai/gpt-oss-20b`                                            | 131K    |       |           |       |       |       | $0.02      | $0.09       |
 | `edenai/flexai/Muse-Glimmer-30B`                                       | 131K    |       |           |       |       |       | $0.30      | $1          |
 | `edenai/flexai/Step-3.7-Flash`                                         | 262K    |       |           |       |       |       | $0.20      | $1          |
 | `edenai/google/gemini-2.5-flash-image`                                 | 33K     |       |           |       |       |       | $0.30      | $3          |

package/.docs/models/providers/kilo.md

@@ -4,7 +4,7 @@
 
 # ![Kilo Gateway logo](https://models.dev/logos/kilo.svg)Kilo Gateway
 
-Access 389 Kilo Gateway models through Mastra's model router. Authentication is handled automatically using the `KILO_API_KEY` environment variable.
+Access 390 Kilo Gateway models through Mastra's model router. Authentication is handled automatically using the `KILO_API_KEY` environment variable.
 
 Learn more in the [Kilo Gateway documentation](https://kilo.ai).
 
@@ -42,9 +42,9 @@ for await (const chunk of stream) {
 | `kilo/~anthropic/claude-haiku-latest`                           | 200K    |       |           |       |       |       | $1         | $5          |
 | `kilo/~anthropic/claude-opus-latest`                            | 1.0M    |       |           |       |       |       | $4         | $20         |
 | `kilo/~anthropic/claude-sonnet-latest`                          | 1.0M    |       |           |       |       |       | $2         | $10         |
-| `kilo/~deepseek/deepseek-flash-latest`                          | 1.0M    |       |           |       |       |       | $0.08      | $0.60       |
+| `kilo/~deepseek/deepseek-flash-latest`                          | 1.0M    |       |           |       |       |       | $0.10      | $0.50       |
 | `kilo/~deepseek/deepseek-pro-latest`                            | 1.0M    |       |           |       |       |       | $0.40      | $4          |
-| `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.03      | $0.80       |
+| `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.04      | $0.55       |
 | `kilo/~google/gemini-flash-latest`                              | 1.0M    |       |           |       |       |       | $0.75      | $4          |
 | `kilo/~google/gemini-pro-latest`                                | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $1         | $11         |
@@ -396,6 +396,7 @@ for await (const chunk of stream) {
 | `kilo/thinkingmachines/inkling-small:free`                      | 1.0M    |       |           |       |       |       | —          | —           |
 | `kilo/unbiased/pareto`                                          | 262K    |       |           |       |       |       | $3         | $8          |
 | `kilo/undi95/remm-slerp-l2-13b`                                 | 6K      |       |           |       |       |       | $0.35      | $0.65       |
+| `kilo/upstage/solar-mini4`                                      | 524K    |       |           |       |       |       | $0.10      | $0.40       |
 | `kilo/upstage/solar-pro-3`                                      | 131K    |       |           |       |       |       | $0.15      | $0.60       |
 | `kilo/upstage/solar-pro4`                                       | 524K    |       |           |       |       |       | $0.30      | $1          |
 | `kilo/writer/palmyra-x5`                                        | 1.0M    |       |           |       |       |       | $0.60      | $6          |

package/.docs/reference/observability/tracing/interfaces.md

@@ -136,10 +136,10 @@ import {
 } from '@mastra/core/observability'
 
 const input = describeSpanInput(span)
-// { type: 'text' | 'messages' | 'agent-run-resume' | 'json'; value } | undefined
+// { type: 'text' | 'messages' | 'agent-run-resume' | 'processor' | 'json'; value } | undefined
 
 const output = describeSpanOutput(span)
-// { type: 'interrupted' | 'agent-run-result' | 'model-generation-result' | 'model-step-result' | 'text' | 'json'; value } | undefined
+// { type: 'interrupted' | 'agent-run-result' | 'model-generation-result' | 'model-step-result' | 'processor' | 'text' | 'json'; value } | undefined
 
 switch (output?.type) {
   case 'interrupted':
@@ -151,6 +151,42 @@ switch (output?.type) {
 describeSpanError(span) // SpanErrorInfo | undefined
 ```
 
+### Processor spans
+
+A processor span records which pipeline phase produced it, so a reader narrows its payloads on that phase instead of on the payload's shape. The recorded phase is finer than the one a processor declares: `outputStream` and `outputResult` are separate here, because they record different payloads.
+
+```typescript
+import { describeProcessorPipeline, describeSpanOutput } from '@mastra/core/observability'
+
+const output = describeSpanOutput(span)
+
+if (output?.type === 'processor') {
+  output.value.phase // 'input' | 'inputStep' | 'llmRequest' | 'llmResponse'
+  // | 'outputStream' | 'outputResult' | 'outputStep' | 'toolResult' | 'requestError'
+  output.value.phaseLabel // 'Tool result'
+  if (output.value.phase === 'outputStream') {
+    output.value.data.totalChunks // number
+  }
+}
+```
+
+`describeProcessorPipeline` reads the attributes Mastra owns and keeps everything else apart, so a reader can show the known fields without repeating them beside a raw JSON view:
+
+```typescript
+const pipeline = describeProcessorPipeline(span)
+
+pipeline?.executor // 'workflow' | 'legacy'
+pipeline?.processorIndex // position in the chain
+pipeline?.hookDurationMs // time spent inside the processor hook
+pipeline?.messageListMutations // 'add' | 'addSystem' | 'removeByIds' | 'clear'
+pipeline?.tripwireAbort?.reason // why the processor blocked the run
+pipeline?.rest // attributes this description does not explain
+```
+
+`PROCESSOR_RUN` is absent from `SpanInputMap` and `SpanOutputMap` on purpose: three executors emit processor spans and record different shapes. The payload is narrowed at read time instead, by the phase the span recorded, and narrowing on `phase` narrows `data` to that phase alone.
+
+`describeSpanInput` and `describeSpanOutput` return the JSON fallback for a span with no recorded phase, one written by a newer version with a phase this release doesn't know, or an empty payload. `describeProcessorPipeline` returns `undefined` when the phase is missing or unknown, and still describes the pipeline when the payload is empty. The stored payload and the JSON view remain unchanged.
+
 ### Span
 
 Span interface, used internally for tracing.

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

@@ -624,6 +624,20 @@ Keyset cursors are bound to the operation, accepted normalized query, and orderi
 
 Numbered-page handoff cursors and delta cursors also bind the authorization state. Changes to the caller's roles or permissions invalidate these cursors and return `409`. If a delta poll returns `409`, reload the numbered pages and resume polling with the new `deltaCursor`. A malformed cursor returns `400`.
 
+### Trusted tenant scope
+
+Hosts that serve more than one tenant supply a trusted scope outside the query document. The server reads the reserved `organizationId` request-context key, which only server-side authentication can set, and passes `{ organizationId }` to the planner. The scope is carried on the trusted plan and ANDed into every scan: current roots, related spans, scores, feedback, and both discovery routes. A related record from another tenant that shares a `traceId` never qualifies a trace.
+
+Hosts that call storage directly can pass a fuller scope to `planTraceQuery()`, `planThreadQuery()`, `planTraceQueryObservedFields()`, and `planTraceQueryValues()`:
+
+```typescript
+const plan = planTraceQuery(parseTraceQueryRequest(request), {
+  scope: { organizationId: 'org_123', resourceId: 'project_456' },
+})
+```
+
+`resourceId` is optional and narrows within the organization. Keyset and delta cursors are bound to the scope, so a cursor minted under one scope and reused under another returns `409` before storage runs. A scoped request against an observability store or `@mastra/core` that predates tenant scope returns `501` instead of running unscoped. Stores advertise support through the `trace-query-tenant-scope` feature. Callers can't name `organizationId` or `projectId` in predicates. Without a scope the routes behave as before, so self-hosted installations keep their own tenant model.
+
 Cursor pagination is deterministic, but it isn't a database snapshot. Traces or replacement signals written between page requests can change later pages.
 
 PostgreSQL and ClickHouse stop advanced trace and thread queries after 15 seconds by default and return `504` when the database timeout is exceeded. Set `traceQueryTimeoutMs` in the store's vNext observability configuration to an integer from 1 through 300,000 milliseconds to change the timeout. DuckDB doesn't currently provide query-scoped timeout or cancellation through its driver wrapper, so this `504` guarantee doesn't apply to DuckDB.

package/.docs/reference/streaming/ChunkType.md

@@ -136,6 +136,8 @@ A tool is being called.
 
 **payload.toolName** (`string`): Name of the tool being called
 
+**payload.title** (`string`): Human-readable display name for the tool, when the tool defines one
+
 **payload.args** (`Record<string, any>`): Arguments passed to the tool
 
 **payload.providerExecuted** (`boolean`): Whether the provider executed the tool
@@ -178,6 +180,8 @@ Signals the start of streaming tool call arguments.
 
 **payload.toolName** (`string`): Name of the tool being called
 
+**payload.title** (`string`): Human-readable display name for the tool, when the tool defines one
+
 **payload.providerExecuted** (`boolean`): Whether the provider executed the tool
 
 **payload.dynamic** (`boolean`): Whether the tool call is dynamic

package/.docs/reference/tools/create-tool.md

@@ -39,6 +39,8 @@ The first `execute` parameter is the validated value from `inputSchema`. Destruc
 
 **id** (`string`): A unique identifier for the tool.
 
+**title** (`string`): A human-readable display name for the tool. It is not sent to the model. It travels on the tool-call and tool-call-input-streaming-start stream chunks and on the stored tool-invocation part, so chat UIs can read it to label the call. MCP clients receive it as the tool title.
+
 **description** (`string`): A description of what the tool does. This is used by the agent to decide when to use the tool.
 
 **inputSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the expected input parameters for the tool's execute function.

package/.docs/reference/tools/mcp-client.md

@@ -151,6 +151,8 @@ Per the MCP specification: **clients MUST consider tool annotations to be untrus
 
 The same annotations are also exposed on the tools returned by `listTools()` and `listToolsets()` under `tool.mcp.annotations`, so you can inspect them when wiring tools into an agent.
 
+Each tool also carries `tool.title`, set from the server's tool `title` and falling back to `annotations.title`. When the server provides neither, `tool.title` is `undefined` and the tool name is the display fallback, matching the MCP display-name precedence.
+
 ## Server instructions
 
 When an MCP server advertises instructions during initialization, `MCPClient` stores them for that server. Forwarding those instructions into an agent's system prompt is **opt-in**: set `forwardInstructions: true` on a server to have agents that use its tools (via `listTools()` or `listToolsets()`) receive its instructions automatically.
@@ -289,7 +291,7 @@ When called without options, the method omits only `durations`; `toolsets`, `err
 
 Returns every server's tools as plain, serializable definitions, grouped by server name and keyed by the server's own tool name (without the `serverName_toolName` namespacing that `listTools()` applies).
 
-Unlike `listTools()`, the result contains no functions or references to a live client, so it can be passed through `JSON.stringify` and cached in Redis or a database, as well as a build artifact. Each definition holds the data from the MCP `tools/list` response (name, description, input schema, output schema, annotations, and `_meta`), plus the server name, version, and instructions captured at discovery time.
+Unlike `listTools()`, the result contains no functions or references to a live client, so it can be passed through `JSON.stringify` and cached in Redis or a database, as well as a build artifact. Each definition holds the data from the MCP `tools/list` response (name, title, description, input schema, output schema, annotations, and `_meta`), plus the server name, version, and instructions captured at discovery time.
 
 ```typescript
 const definitions = await mcp.listToolDefinitions()

package/dist/index.d.ts

@@ -1,5 +1,16 @@
 import { MCPServer } from '@mastra/mcp';
-declare let server: MCPServer;
+import { MCPServer as LegacyMCPServer } from '@mastra/mcp-legacy';
+import type { ProtocolEra } from './protocol-era.js';
+/**
+ * Build the docs server for a protocol era. The same tools and prompts are
+ * registered either way; only the protocol implementation differs.
+ *
+ * `@mastra/mcp` 2.x serves the 2026-07-28 revision. Hosts that still open with
+ * a legacy `initialize` handshake get the published `@mastra/mcp` 1.x server
+ * (installed under the `@mastra/mcp-legacy` alias) so `npx @mastra/mcp-docs-server`
+ * keeps working while editors adopt the new revision.
+ */
+declare function createDocsServer(era: ProtocolEra): MCPServer | LegacyMCPServer;
 declare function runServer(): Promise<void>;
-export { runServer, server };
+export { runServer, createDocsServer };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAexC,QAAA,IAAI,MAAM,EAAE,SAAS,CAAC;AAsBtB,iBAAe,SAAS,kBAQvB;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,IAAI,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAIlE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AA8BlD;;;;;;;;GAQG;AACH,iBAAS,gBAAgB,CAAC,GAAG,EAAE,WAAW,+BAEzC;AAED,iBAAe,SAAS,kBAYvB;AAED,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-import { n as server, t as runServer } from "./src-D-W-bx5t.js";
-export { runServer, server };
+import { n as runServer, t as createDocsServer } from "./src-CGZ6-uLS.js";
+export { createDocsServer, runServer };

package/dist/logger.d.ts

@@ -1,4 +1,3 @@
-import type { MCPServer } from '@mastra/mcp';
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
 export declare function setLogLevel(level: LogLevel): void;
 export declare function getLogLevel(): LogLevel;
@@ -13,6 +12,6 @@ export interface Logger {
     emergency: (message: string, error?: any) => Promise<void>;
 }
 export declare const writeErrorLog: (message: string, data?: any) => void;
-export declare function createLogger(server?: MCPServer): Logger;
+export declare function createLogger(): Logger;
 export declare const logger: Logger;
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAkCpE,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AASD,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,eAAO,MAAM,aAAa,YAAa,MAAM,SAAS,GAAG,SA2BxD,CAAC;AAGF,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CA4FvD;AAGD,eAAO,MAAM,MAAM,QAAiB,CAAC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAkCpE,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AASD,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,eAAO,MAAM,aAAa,YAAa,MAAM,SAAS,GAAG,SA2BxD,CAAC;AAIF,wBAAgB,YAAY,IAAI,MAAM,CAuErC;AAGD,eAAO,MAAM,MAAM,QAAiB,CAAC"}

package/dist/prompts/migration.d.ts

@@ -1,6 +1,16 @@
-import type { MCPServerPrompts } from '@mastra/mcp';
+import type { Prompt, PromptMessage } from '@mastra/mcp';
 /**
- * Prompt messages callback that generates contextual migration guidance
+ * Prompt callbacks that generate contextual migration guidance.
+ *
+ * Typed by what the callbacks read rather than by one package's
+ * `MCPServerPrompts`, so the same object registers on both the 2026-07-28
+ * server and the legacy 1.x server.
  */
-export declare const migrationPromptMessages: MCPServerPrompts;
+export declare const migrationPromptMessages: {
+    listPrompts: () => Promise<Prompt[]>;
+    getPromptMessages: ({ name, args, }: {
+        name: string;
+        args?: Record<string, unknown>;
+    }) => Promise<PromptMessage[]>;
+};
 //# sourceMappingURL=migration.d.ts.map

package/dist/prompts/migration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/prompts/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,aAAa,CAAC;AA8BlE;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,gBAmBrC,CAAC"}
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/prompts/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA2BzD;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;IAClC,WAAW,QAAY,OAAO,CAAC,MAAM,EAAE,CAAC;IAExC,iBAAiB,oBAGd;QACD,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChC,KAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CAiB7B,CAAC"}

package/dist/protocol-era.d.ts

@@ -0,0 +1,29 @@
+import type { Readable } from 'node:stream';
+/**
+ * Which MCP protocol family the connecting host speaks.
+ *
+ * - `legacy`: pre-2026 hosts. They open the connection with an `initialize`
+ *   request (protocol revisions `2024-11-05` through `2025-11-25`).
+ * - `2026-07-28`: hosts on the current revision. They never send `initialize`;
+ *   their first message is `server/discover` or an envelope-bearing request.
+ */
+export type ProtocolEra = 'legacy' | '2026-07-28';
+/**
+ * Decide the protocol era from the first JSON-RPC line a host writes to stdin.
+ *
+ * Anything that is not a legacy `initialize` request is handed to the
+ * 2026-07-28 server, which produces the spec-defined error for malformed or
+ * unsupported requests. Only a well-formed legacy handshake selects the 1.x
+ * server.
+ */
+export declare function detectProtocolEra(firstLine: string | undefined): ProtocolEra;
+/**
+ * Read up to and including the first newline from `stream`, then push every
+ * byte back so the MCP transport that starts afterwards sees the untouched
+ * message stream.
+ *
+ * Resolves with `undefined` if the stream ends before a newline arrives; the
+ * partial bytes are dropped because no transport can act on a closed stdin.
+ */
+export declare function peekFirstLine(stream: Readable): Promise<string | undefined>;
+//# sourceMappingURL=protocol-era.d.ts.map

package/dist/protocol-era.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-era.d.ts","sourceRoot":"","sources":["../src/protocol-era.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAa5E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA8C3E"}

package/dist/{src-D-W-bx5t.js → src-CGZ6-uLS.js}

@@ -1,5 +1,6 @@
 import fs from "fs/promises";
 import { MCPServer } from "@mastra/mcp";
+import { MCPServer as MCPServer$1 } from "@mastra/mcp-legacy";
 import * as fs$1 from "fs";
 import { existsSync, mkdirSync } from "fs";
 import * as os$1 from "os";
@@ -55,24 +56,17 @@ const writeErrorLog = (message, data) => {
 		console.error("Failed to write to log file:", err);
 	}
 };
-function createLogger(server) {
+function createLogger() {
 	const sendLog = async (level, message, data) => {
-		if (!server) return;
 		if (!shouldLog(level)) return;
-		try {
-			const sdkServer = server.getServer();
-			if (!sdkServer) return;
-			await sdkServer.sendLoggingMessage({
-				level,
-				data: {
-					message,
-					...data ? typeof data === "object" ? data : { data } : {}
-				}
-			});
-		} catch (error) {
-			if (error instanceof Error && (error.message === "Not connected" || error.message.includes("does not support logging") || error.message.includes("Connection closed"))) return;
-			console.error(`Failed to send ${level} log:`, error instanceof Error ? error.message : error);
-		}
+		console.error(JSON.stringify(data === void 0 ? {
+			level,
+			message
+		} : {
+			level,
+			message,
+			data
+		}));
 	};
 	return {
 		debug: async (message, data) => {
@@ -134,7 +128,6 @@ const logger = createLogger();
 */
 const migrationPrompts = [{
 	name: "upgrade-to-v1",
-	version: "v1",
 	description: "Get a guided migration plan for upgrading from Mastra v0.x to v1.0. Provides step-by-step instructions for handling all breaking changes.",
 	arguments: [{
 		name: "area",
@@ -143,17 +136,23 @@ const migrationPrompts = [{
 	}]
 }, {
 	name: "migration-checklist",
-	version: "v1",
 	description: "Get a comprehensive checklist for migrating to Mastra v1.0. Lists all breaking changes that need to be addressed."
 }];
 /**
-* Prompt messages callback that generates contextual migration guidance
+* Prompt callbacks that generate contextual migration guidance.
+*
+* Typed by what the callbacks read rather than by one package's
+* `MCPServerPrompts`, so the same object registers on both the 2026-07-28
+* server and the legacy 1.x server.
 */
 const migrationPromptMessages = {
 	listPrompts: async () => migrationPrompts,
 	getPromptMessages: async ({ name, args }) => {
 		if (!migrationPrompts.find((p) => p.name === name)) throw new Error(`Prompt not found: ${name}`);
-		if (name === "upgrade-to-v1") return getUpgradeToV1Messages(args?.area);
+		if (name === "upgrade-to-v1") {
+			const area = args?.area;
+			return getUpgradeToV1Messages(typeof area === "string" ? area : void 0);
+		}
 		if (name === "migration-checklist") return getMigrationChecklistMessages();
 		throw new Error(`No message handler for prompt: ${name}`);
 	}
@@ -218,6 +217,70 @@ Group the checklist by area (Agents, Tools, Workflows, etc.) so I can tackle one
 	}];
 }
 //#endregion
+//#region src/protocol-era.ts
+/**
+* Decide the protocol era from the first JSON-RPC line a host writes to stdin.
+*
+* Anything that is not a legacy `initialize` request is handed to the
+* 2026-07-28 server, which produces the spec-defined error for malformed or
+* unsupported requests. Only a well-formed legacy handshake selects the 1.x
+* server.
+*/
+function detectProtocolEra(firstLine) {
+	if (!firstLine) return "2026-07-28";
+	try {
+		const message = JSON.parse(firstLine);
+		if (message && typeof message === "object" && message.method === "initialize") return "legacy";
+	} catch {}
+	return "2026-07-28";
+}
+/**
+* Read up to and including the first newline from `stream`, then push every
+* byte back so the MCP transport that starts afterwards sees the untouched
+* message stream.
+*
+* Resolves with `undefined` if the stream ends before a newline arrives; the
+* partial bytes are dropped because no transport can act on a closed stdin.
+*/
+function peekFirstLine(stream) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		const detach = () => {
+			stream.off("readable", onReadable);
+			stream.off("end", onEnd);
+			stream.off("error", onError);
+		};
+		const finish = (line) => {
+			detach();
+			for (let i = chunks.length - 1; i >= 0; i--) stream.unshift(chunks[i]);
+			resolve(line);
+		};
+		const onReadable = () => {
+			let chunk;
+			while ((chunk = stream.read()) !== null) {
+				const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+				chunks.push(buffer);
+				if (buffer.indexOf(10) !== -1) {
+					const head = Buffer.concat(chunks);
+					finish(head.subarray(0, head.indexOf(10)).toString("utf8"));
+					return;
+				}
+			}
+		};
+		const onEnd = () => {
+			detach();
+			resolve(void 0);
+		};
+		const onError = (error) => {
+			detach();
+			reject(error);
+		};
+		stream.on("readable", onReadable);
+		stream.on("end", onEnd);
+		stream.on("error", onError);
+	});
+}
+//#endregion
 //#region src/utils.ts
 const mdFileCache = /* @__PURE__ */ new Map();
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -1742,8 +1805,7 @@ This tool works like a file browser - navigate through directories to find migra
 };
 //#endregion
 //#region src/index.ts
-let server;
-server = new MCPServer({
+const serverConfig = {
 	name: "Mastra Documentation Server",
 	version: JSON.parse(await fs.readFile(fromPackageRoot(`package.json`), "utf8")).version,
 	tools: {
@@ -1757,18 +1819,31 @@ server = new MCPServer({
 		...embeddedDocsTools
 	},
 	prompts: migrationPromptMessages
-});
-Object.assign(logger, createLogger(server));
+};
+/**
+* Build the docs server for a protocol era. The same tools and prompts are
+* registered either way; only the protocol implementation differs.
+*
+* `@mastra/mcp` 2.x serves the 2026-07-28 revision. Hosts that still open with
+* a legacy `initialize` handshake get the published `@mastra/mcp` 1.x server
+* (installed under the `@mastra/mcp-legacy` alias) so `npx @mastra/mcp-docs-server`
+* keeps working while editors adopt the new revision.
+*/
+function createDocsServer(era) {
+	return era === "legacy" ? new MCPServer$1(serverConfig) : new MCPServer(serverConfig);
+}
 async function runServer() {
 	try {
-		await server.startStdio();
-		logger.info("Started Mastra Docs MCP Server");
+		const era = detectProtocolEra(await peekFirstLine(process.stdin));
+		await createDocsServer(era).startStdio();
+		process.stdin.resume();
+		logger.info("Started Mastra Docs MCP Server", { protocol: era });
 	} catch (error) {
 		logger.error("Failed to start server", error);
 		process.exit(1);
 	}
 }
 //#endregion
-export { writeErrorLog as i, server as n, setLogLevel as r, runServer as t };
+export { writeErrorLog as i, runServer as n, setLogLevel as r, createDocsServer as t };
 
-//# sourceMappingURL=src-D-W-bx5t.js.map
+//# sourceMappingURL=src-CGZ6-uLS.js.map