@mastra/cursor 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# @mastra/cursor
+
+## 0.1.0-alpha.1
+
+### Minor Changes
+
+- Added `@mastra/cursor`, a package for running Cursor SDK agents through Mastra. ([#16906](https://github.com/mastra-ai/mastra/pull/16906))
+
+  Create a Cursor SDK agent, register it with Mastra, and call `generate()` or `stream()` with Mastra-compatible outputs. Runs keep Cursor SDK usage and observability data available to Mastra.
+
+  ```ts
+  import { CursorSDKAgent } from '@mastra/cursor';
+
+  export const cursorAgent = new CursorSDKAgent({
+    id: 'cursor-sdk-agent',
+    description: 'Use Cursor Agent SDK through Mastra.',
+    sdkOptions: {
+      apiKey: process.env.CURSOR_API_KEY,
+      model: { id: process.env.CURSOR_MODEL_ID! },
+      local: {
+        cwd: process.cwd(),
+      },
+    },
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies:
+  - @mastra/core@1.38.0-alpha.7
+
+## 0.1.0-alpha.0
+
+Initial release.

package/README.md

@@ -0,0 +1,93 @@
+# @mastra/cursor
+
+`@mastra/cursor` connects Mastra to the Cursor SDK. Use it when you want to register a Cursor SDK agent with Mastra and call it through Mastra-compatible `generate()` and `stream()` methods.
+
+## Installation
+
+```bash
+npm install @mastra/cursor @cursor/sdk
+```
+
+## Overview
+
+The package exports `CursorSDKAgent`, a Mastra `Agent` wrapper around a Cursor SDK agent.
+
+`CursorSDKAgent` keeps the Cursor SDK run loop in charge. Mastra receives compatible outputs, usage data, and tracing data for the run.
+
+## Create a Cursor SDK agent
+
+Pass Cursor SDK configuration through `sdkOptions`. `CursorSDKAgent` creates the Cursor SDK agent on first use.
+
+```typescript
+import { CursorSDKAgent } from '@mastra/cursor';
+
+export const cursorAgent = new CursorSDKAgent({
+  id: 'cursor-sdk-agent',
+  name: 'Cursor SDK Agent',
+  description: 'Use Cursor Agent SDK through Mastra.',
+  sdkOptions: {
+    apiKey: process.env.CURSOR_API_KEY,
+    model: { id: process.env.CURSOR_MODEL_ID! },
+    local: {
+      cwd: process.cwd(),
+    },
+  },
+});
+```
+
+You can also pass an existing Cursor SDK agent when your app already creates or owns it.
+
+```typescript
+import { Agent as CursorAgent } from '@cursor/sdk';
+import { CursorSDKAgent } from '@mastra/cursor';
+
+export const cursorAgent = new CursorSDKAgent({
+  id: 'cursor-sdk-agent',
+  description: 'Use Cursor Agent SDK through Mastra.',
+  agent: CursorAgent.create({
+    apiKey: process.env.CURSOR_API_KEY,
+    model: { id: process.env.CURSOR_MODEL_ID! },
+    local: {
+      cwd: process.cwd(),
+    },
+  }),
+});
+```
+
+You can register the wrapper anywhere Mastra accepts an `Agent`.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+
+export const mastra = new Mastra({
+  agents: {
+    cursorAgent,
+  },
+});
+```
+
+## Run the agent
+
+```typescript
+const result = await cursorAgent.generate('Find and explain the failing test.', {
+  runId: 'cursor-run',
+});
+
+console.log(result.text);
+```
+
+```typescript
+const stream = await cursorAgent.stream('Inspect this repository and suggest the smallest fix.');
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'text-delta') {
+    process.stdout.write(chunk.payload.text);
+  }
+}
+```
+
+## Configure Cursor
+
+`CursorSDKAgent` forwards `sdkOptions` to `CursorAgent.create()` when `agent` is not provided or when `agent` is a factory. These include `apiKey`, `model`, `local`, `cloud`, `mcpServers`, `agents`, `agentId`, `idempotencyKey`, and `platform`.
+
+`apiKey` defaults to `process.env.CURSOR_API_KEY` when it is not provided.

package/dist/docs/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: mastra-cursor
+description: Documentation for @mastra/cursor. Use when working with @mastra/cursor APIs, configuration, or implementation.
+metadata:
+  package: "@mastra/cursor"
+  version: "0.0.0"
+---
+
+## When to use
+
+Use this skill whenever you are working with @mastra/cursor to obtain the domain-specific knowledge.
+
+## How to use
+
+Read the individual reference documents for detailed explanations and code examples.
+
+### Docs
+
+- [SDK agents](references/docs-agents-sdk-agents.md) - Use Claude Agent SDK and Cursor Agent SDK agents from Mastra.
+
+
+Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "0.0.0",
+  "package": "@mastra/cursor",
+  "exports": {},
+  "modules": {}
+}

package/dist/docs/references/docs-agents-sdk-agents.md

@@ -0,0 +1,261 @@
+# SDK agents
+
+SDK agents let you use other agent SDK frameworks inside Mastra. Use them to register SDK-backed agents in a Mastra project while the provider SDK keeps its own runtime, tools, permissions, and agent loop.
+
+## When to use SDK agents
+
+- A vendor SDK already owns the agent loop, tools, permissions, or local runtime.
+- You want to register that SDK-backed agent in a Mastra project.
+- You need Mastra-compatible `generate()` and `stream()` outputs.
+- You want usage, cost, and tool activity from the SDK run to appear in Mastra observability.
+
+## Supported SDK agents
+
+- [Claude Agent SDK](#claude-agent-sdk): Use `@mastra/claude` to register a Claude SDK agent and call it with Mastra `generate()` and `stream()`.
+- [Cursor Agent SDK](#cursor-agent-sdk): Use `@mastra/cursor` to register a Cursor SDK agent and call it with Mastra `generate()` and `stream()`.
+
+## Claude Agent SDK
+
+Use `@mastra/claude` for Claude Code runtime configuration, permissions, tools, and agent-loop behavior.
+
+### Install Claude packages
+
+Install the Mastra package and the Claude Agent SDK peer dependency:
+
+**npm**:
+
+```bash
+npm install @mastra/claude @anthropic-ai/claude-agent-sdk
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/claude @anthropic-ai/claude-agent-sdk
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/claude @anthropic-ai/claude-agent-sdk
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/claude @anthropic-ai/claude-agent-sdk
+```
+
+Set the Claude SDK credential:
+
+```bash
+export ANTHROPIC_API_KEY="..."
+```
+
+### Create a Claude SDK agent
+
+Configure Claude Agent SDK through `sdkOptions`.
+
+```typescript
+import { ClaudeSDKAgent } from '@mastra/claude'
+
+export const claudeSDKAgent = new ClaudeSDKAgent({
+  id: 'claude-sdk-agent',
+  name: 'Claude SDK Agent',
+  description: 'Use Claude Agent SDK through Mastra.',
+  sdkOptions: {
+    model: 'claude-sonnet-4-6',
+    cwd: process.cwd(),
+  },
+})
+```
+
+### Add Claude SDK tools
+
+Claude Agent SDK tools are provided through Claude SDK Model Context Protocol (MCP) servers. Create the server with the Claude SDK, then pass it through `sdkOptions.mcpServers`.
+
+```typescript
+import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk'
+import { ClaudeSDKAgent } from '@mastra/claude'
+import { getTemperature } from '../tools/get-temperature'
+
+const weatherServer = createSdkMcpServer({
+  name: 'weather',
+  version: '1.0.0',
+  tools: [getTemperature],
+})
+
+export const claudeSDKAgent = new ClaudeSDKAgent({
+  id: 'claude-sdk-agent',
+  name: 'Claude SDK Agent',
+  description: 'Use Claude Agent SDK through Mastra.',
+  sdkOptions: {
+    model: 'claude-sonnet-4-6',
+    cwd: process.cwd(),
+    mcpServers: {
+      weather: weatherServer,
+    },
+    allowedTools: ['mcp__weather__get_temperature'],
+  },
+})
+```
+
+The `allowedTools` value uses Claude Agent SDK MCP tool naming: `mcp__<server name>__<tool name>`.
+
+## Cursor Agent SDK
+
+Use `@mastra/cursor` to register a Cursor SDK agent in Mastra while keeping Cursor-specific setup in Cursor SDK options.
+
+### Install Cursor packages
+
+Install the Mastra package and the Cursor SDK peer dependency:
+
+**npm**:
+
+```bash
+npm install @mastra/cursor @cursor/sdk
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/cursor @cursor/sdk
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/cursor @cursor/sdk
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/cursor @cursor/sdk
+```
+
+Set the Cursor SDK credential:
+
+```bash
+export CURSOR_API_KEY="..."
+```
+
+### Create a Cursor SDK agent
+
+Configure Cursor Agent SDK through `sdkOptions`.
+
+```typescript
+import { CursorSDKAgent } from '@mastra/cursor'
+
+export const cursorSDKAgent = new CursorSDKAgent({
+  id: 'cursor-sdk-agent',
+  name: 'Cursor SDK Agent',
+  description: 'Use Cursor Agent SDK through Mastra.',
+  sdkOptions: {
+    apiKey: process.env.CURSOR_API_KEY,
+    model: {
+      id: 'gpt-5.5',
+    },
+    local: {
+      cwd: process.cwd(),
+    },
+  },
+})
+```
+
+Cursor local agents require an explicit model. Set it in `sdkOptions.model`.
+
+### Use an existing Cursor SDK agent
+
+If your app already creates a Cursor SDK agent, pass that agent to `CursorSDKAgent` instead:
+
+```typescript
+import { Agent as CursorAgent } from '@cursor/sdk'
+import { CursorSDKAgent } from '@mastra/cursor'
+
+const cursorAgent = CursorAgent.create({
+  apiKey: process.env.CURSOR_API_KEY,
+  model: {
+    id: 'gpt-5.5',
+  },
+  local: {
+    cwd: process.cwd(),
+  },
+})
+
+export const cursorSDKAgent = new CursorSDKAgent({
+  id: 'cursor-sdk-agent',
+  name: 'Cursor SDK Agent',
+  description: 'Use Cursor Agent SDK through Mastra.',
+  agent: cursorAgent,
+})
+```
+
+### Add Cursor SDK tools
+
+Cursor Agent SDK tools are configured with Cursor SDK options. Pass Model Context Protocol (MCP) servers through `sdkOptions.mcpServers`:
+
+```typescript
+import { CursorSDKAgent } from '@mastra/cursor'
+import { mcpServers } from '../mcp/cursor'
+
+export const cursorSDKAgent = new CursorSDKAgent({
+  id: 'cursor-sdk-agent',
+  name: 'Cursor SDK Agent',
+  description: 'Use Cursor Agent SDK through Mastra.',
+  sdkOptions: {
+    apiKey: process.env.CURSOR_API_KEY,
+    model: {
+      id: 'gpt-5.5',
+    },
+    local: {
+      cwd: process.cwd(),
+    },
+    mcpServers,
+  },
+})
+```
+
+## Register SDK agents
+
+Register SDK agents in the Mastra instance like other agents:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { claudeSDKAgent } from './agents/claude-sdk-agent'
+import { cursorSDKAgent } from './agents/cursor-sdk-agent'
+
+export const mastra = new Mastra({
+  agents: {
+    claudeSDKAgent,
+    cursorSDKAgent,
+  },
+})
+```
+
+After registration, call them with `mastra.getAgentById()`:
+
+```typescript
+import { mastra } from './index'
+
+const agent = mastra.getAgentById('cursor-sdk-agent')
+const stream = await agent.stream('Inspect this project and describe the test setup.')
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+## Observability
+
+SDK agents create Mastra agent and model spans for `generate()` and `stream()` calls. Mastra records SDK-provided usage, tool activity, and provider metadata when the vendor SDK exposes those events.
+
+Claude SDK runs can include SDK-estimated cost from the Claude result message. Cursor SDK runs include token usage from Cursor interaction updates.
+
+For storage and dashboard setup, see [Observability](https://mastra.ai/docs/observability/overview).
+
+## Related
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)
+- [Tools](https://mastra.ai/docs/agents/using-tools)
+- [Observability](https://mastra.ai/docs/observability/overview)