mastra-dev

name	mastra-dev
description	Ultimate Mastra Framework development toolkit for agent orchestration, workflow design, and MCP integration. Use when Codex should run the converted mastra-dev workflow. Inputs: command, options.

Mastra Dev

Converted Claude skill workflow for Codex/OpenAI use.

Source

Converted from skills/mastra-dev/SKILL.md.

Bundled Resources

Supporting files copied from the Claude source:

• references/README.md
• assets/examples
• scripts
• scripts/skill.sh
• assets/templates

Converted Instructions

The content below was adapted from the Claude source. Rewrite tool and runtime assumptions as needed when they refer to Claude-only features.

Ultimate Mastra Development Toolkit

A comprehensive skill for developing, managing, and debugging Mastra Framework applications. This toolkit provides six major capability areas to accelerate Mastra development with automated scaffolding, server management, and expert guidance.

Quick Start

# Check Mastra server status
$mastra-dev server status

# Analyze current Mastra setup
$mastra-dev analyze

# Create a new agent
$mastra-dev create-agent --name "contract-analyzer" --model "anthropic/claude-3-5-sonnet-20241022"

# Create a new workflow
$mastra-dev create-workflow --name "form-generation" --description "Auto-fill government forms"

# Start Mastra server
$mastra-dev server start

# Start Mastra Studio (observability UI)
$mastra-dev studio start

What This Skill Does

This skill answers critical questions for Mastra developers:

1. How do I create a new Mastra agent?

$mastra-dev create-agent \
  --name "proposal-writer" \
  --model "openai/gpt-4-turbo" \
  --description "Expert technical writer for government proposals" \
  --instructions "You are an expert technical writer..." \
  --tools "sam-gov-lookup,company-data"

What happens:

• Generates apps/mastra/src/agents/proposal-writer.ts with proper structure
• Registers agent in apps/mastra/src/config/mastra.config.ts
• Follows Mastra best practices with TypeScript typing
• Includes Zod schemas for validation
• Auto-imports required dependencies

2. How do I build a workflow with multiple steps?

# Create workflow
$mastra-dev create-workflow \
  --name "contract-analysis" \
  --description "Analyze government contract for risks"

# Add steps sequentially
$mastra-dev add-step \
  --workflow "contract-analysis" \
  --step-name "extract-text" \
  --step-type "transform" \
  --input-schema '{"documentUrl": "string"}' \
  --output-schema '{"text": "string"}'

$mastra-dev add-step \
  --workflow "contract-analysis" \
  --step-name "identify-clauses" \
  --step-type "transform" \
  --input-schema '{"text": "string"}' \
  --output-schema '{"clauses": "array"}'

# Test the workflow
$mastra-dev test-workflow \
  --name "contract-analysis" \
  --input '{"documentUrl": "https://example.com/contract.pdf"}'

What happens:

• Creates workflow file at apps/mastra/src/workflows/contract-analysis.ts
• Generates steps with proper DAG composition (.then(), .parallel(), .branch())
• Validates schema compatibility between steps
• Registers workflow in MCP server configuration
• Provides execution testing capability

3. How do I integrate external MCP servers?

# Add Wikipedia MCP server
$mastra-dev mcp add-client \
  --name "wikipedia" \
  --command "npx" \
  --args "-y,wikipedia-mcp"

# Add remote HTTP MCP server
$mastra-dev mcp add-client \
  --name "weather" \
  --url "https://server.smithery.ai/@smithery-ai/national-weather-service/mcp"

# Configure MCP server to expose workflows
$mastra-dev mcp configure-server \
  --agents "proposal-writer" \
  --workflows "contract-analysis"

# List all configured MCP servers
$mastra-dev mcp list-servers

# Test MCP connection
$mastra-dev mcp test --server "wikipedia"

What happens:

• Updates apps/mastra/src/config/mcp.config.ts with MCPClient configuration
• Supports both stdio (local) and HTTP (remote) transports
• Configures MCPServer to expose Mastra agents/workflows as tools
• Validates MCP connections and tool availability

4. How do I debug workflow execution?

# Debug specific workflow execution
$mastra-dev debug-workflow \
  --name "contract-analysis" \
  --execution-id "abc-123-def-456"

# Show workflow DAG visualization
$mastra-dev show-graph --workflow "contract-analysis"

# Validate all Mastra configurations
$mastra-dev validate

# View detailed logs
$mastra-dev server logs --tail 100

What happens:

• Queries mastra.workflow_executions table for execution state
• Retrieves step-by-step logs from mastra.step_execution_logs
• Identifies failed steps with error details
• Shows input/output data for each step
• Generates ASCII visualization of workflow DAG
• Validates schema compatibility and configuration correctness

5. What agents/workflows/tools are currently defined?

# List all agents
$mastra-dev list-agents

# Analyze specific agent
$mastra-dev analyze-agent --name "proposal-writer"

# List all workflows
$mastra-dev list-workflows

# List all tools
$mastra-dev list-tools

# Comprehensive analysis
$mastra-dev analyze

What happens:

• Scans apps/mastra/src/agents/*.ts for agent definitions
• Scans apps/mastra/src/workflows/*.ts for workflows
• Scans apps/mastra/src/tools/*.ts for tools
• Parses TypeScript files to extract configurations
• Shows registration status in mastra.config.ts
• Displays model providers, tool usage, and dependencies

Features

1. Agent Management

Create, list, and analyze Mastra agents with intelligent scaffolding.

Commands:

# Create new agent
$mastra-dev create-agent \
  --name <agent-name> \
  --model <provider/model> \
  --description <description> \
  [--instructions <instructions-text>] \
  [--tools <comma-separated-tool-ids>]

# List all agents
$mastra-dev list-agents

# Analyze agent configuration
$mastra-dev analyze-agent --name <agent-name>

Example - Create Contract Analysis Agent:

$mastra-dev create-agent \
  --name "contract-analyzer" \
  --model "anthropic/claude-3-5-sonnet-20241022" \
  --description "Federal contract analysis expert" \
  --instructions "You are an expert in analyzing federal contracts for compliance, risks, and key terms. Focus on FAR/DFARS requirements." \
  --tools "document-parser,sam-gov-lookup,far-compliance"

Generated File: apps/mastra/src/agents/contract-analyzer.ts

import { Agent } from '@mastra/core';

export const contractAnalyzerAgent = new Agent({
  id: 'contract-analyzer',
  name: 'Federal Contract Analysis Expert',
  description: 'Federal contract analysis expert',
  instructions: `You are an expert in analyzing federal contracts for compliance, risks, and key terms. Focus on FAR/DFARS requirements.`,
  model: {
    provider: 'anthropic',
    model: 'claude-3-5-sonnet-20241022'
  },
  tools: ['document-parser', 'sam-gov-lookup', 'far-compliance']
});

What Gets Updated:

• ✅ Agent file created at apps/mastra/src/agents/contract-analyzer.ts
• ✅ Registered in apps/mastra/src/config/mastra.config.ts
• ✅ Proper TypeScript imports and exports
• ✅ Zod validation ready
• ✅ Compatible with Mastra Studio

2. Workflow Management

Design, build, and test DAG-based workflows with step composition.

Commands:

# Create new workflow
$mastra-dev create-workflow \
  --name <workflow-name> \
  --description <description> \
  [--input-schema <json-schema>] \
  [--output-schema <json-schema>]

# Add step to workflow
$mastra-dev add-step \
  --workflow <workflow-name> \
  --step-name <step-name> \
  --step-type <transform|api-call|agent-call|parallel|branch> \
  [--input-schema <json-schema>] \
  [--output-schema <json-schema>]

# Test workflow execution
$mastra-dev test-workflow \
  --name <workflow-name> \
  --input <json-input>

# List all workflows
$mastra-dev list-workflows

Example - Build Form Generation Workflow:

# Step 1: Create workflow
$mastra-dev create-workflow \
  --name "form-generation" \
  --description "Auto-fill government forms from SAM.gov data" \
  --input-schema '{"opportunityId": "string"}' \
  --output-schema '{"formData": "object", "pdfUrl": "string"}'

# Step 2: Add fetch step
$mastra-dev add-step \
  --workflow "form-generation" \
  --step-name "fetch-opportunity" \
  --step-type "api-call" \
  --input-schema '{"opportunityId": "string"}' \
  --output-schema '{"opportunity": "object"}'

# Step 3: Add transform step
$mastra-dev add-step \
  --workflow "form-generation" \
  --step-name "extract-data" \
  --step-type "transform" \
  --input-schema '{"opportunity": "object"}' \
  --output-schema '{"formData": "object"}'

# Step 4: Add PDF generation step
$mastra-dev add-step \
  --workflow "form-generation" \
  --step-name "generate-pdf" \
  --step-type "transform" \
  --input-schema '{"formData": "object"}' \
  --output-schema '{"pdfUrl": "string"}'

# Test the workflow
$mastra-dev test-workflow \
  --name "form-generation" \
  --input '{"opportunityId": "abc-123"}'

Generated File: apps/mastra/src/workflows/form-generation.ts

import { createWorkflow, createStep } from '@mastra/core/workflows';
import { z } from 'zod';

const fetchOpportunityStep = createStep({
  id: 'fetch-opportunity',
  inputSchema: z.object({ opportunityId: z.string() }),
  outputSchema: z.object({ opportunity: z.any() }),
  execute: async ({ inputData }) => {
    // API call implementation
    const response = await fetch(`https://api.sam.gov/opportunities/${inputData.opportunityId}`);
    return { opportunity: await response.json() };
  }
});

const extractDataStep = createStep({
  id: 'extract-data',
  inputSchema: z.object({ opportunity: z.any() }),
  outputSchema: z.object({ formData: z.any() }),
  execute: async ({ inputData }) => {
    // Transform logic
    return { formData: { /* extracted data */ } };
  }
});

const generatePdfStep = createStep({
  id: 'generate-pdf',
  inputSchema: z.object({ formData: z.any() }),
  outputSchema: z.object({ pdfUrl: z.string() }),
  execute: async ({ inputData }) => {
    // PDF generation
    return { pdfUrl: 'https://example.com/form.pdf' };
  }
});

export const formGenerationWorkflow = createWorkflow({
  id: 'form-generation',
  description: 'Auto-fill government forms from SAM.gov data',
  inputSchema: z.object({ opportunityId: z.string() }),
  outputSchema: z.object({ formData: z.any(), pdfUrl: z.string() })
})
  .then(fetchOpportunityStep)
  .then(extractDataStep)
  .then(generatePdfStep)
  .commit();

Control Flow Patterns:

• Sequential: .then(stepA).then(stepB).then(stepC)
• Parallel: .parallel([stepA, stepB, stepC])
• Conditional: .branch({ when: (data) => data.score > 0.8, then: highPath, otherwise: lowPath })

3. Tool Management

Create reusable tools with schema validation and type safety.

Commands:

# Create new tool
$mastra-dev create-tool \
  --name <tool-name> \
  --description <description> \
  [--input-schema <json-schema>] \
  [--output-schema <json-schema>]

# List all tools
$mastra-dev list-tools

# Test tool execution
$mastra-dev test-tool \
  --name <tool-name> \
  --input <json-input>

Example - Create PDF Generator Tool:

$mastra-dev create-tool \
  --name "pdf-generator" \
  --description "Generate PDF from template and data" \
  --input-schema '{"template": "string", "data": "object"}' \
  --output-schema '{"pdfUrl": "string", "size": "number"}'

Generated File: apps/mastra/src/tools/pdf-generator.ts

import { createTool } from '@mastra/core/tools';
import { z } from 'zod';

export const pdfGeneratorTool = createTool({
  id: 'pdf-generator',
  description: 'Generate PDF from template and data',
  inputSchema: z.object({
    template: z.string(),
    data: z.record(z.any())
  }),
  outputSchema: z.object({
    pdfUrl: z.string(),
    size: z.number()
  }),
  execute: async ({ inputData }) => {
    // PDF generation logic
    const pdfUrl = await generatePdf(inputData.template, inputData.data);
    return {
      pdfUrl,
      size: 12345
    };
  }
});

4. Server Management

Control Mastra server lifecycle and monitor logs.

Commands:

# Start Mastra server
$mastra-dev server start

# Stop Mastra server
$mastra-dev server stop

# Check server status
$mastra-dev server status

# View server logs
$mastra-dev server logs [--tail <lines>]

# Start Mastra Studio (observability UI)
$mastra-dev studio start

Example - Server Management Workflow:

# Check if server is running
$mastra-dev server status
# Output: ❌ Mastra server is not running (port 6000)

# Start the server
$mastra-dev server start
# Output: ✅ Mastra server started on port 6000 (PID: 12345)

# Verify it's running
$mastra-dev server status
# Output: ✅ Mastra server is running on port 6000 (PID: 12345)
#         Uptime: 5 minutes
#         Memory: 245 MB

# View recent logs
$mastra-dev server logs --tail 50
# Output: [Shows last 50 lines from apps/mastra/logs/mastra.log]

# Start Mastra Studio for observability
$mastra-dev studio start
# Output: ✅ Mastra Studio started on http://localhost:4111
#         Connected to Mastra API at http://localhost:6000

What Happens:

• server start: Launches Mastra Express server via npm run dev:mastra
• server stop: Gracefully terminates process via SIGTERM
• server status: Checks port 6000, parses ps aux | grep mastra
• server logs: Tails from apps/mastra/logs/mastra.log
• studio start: Launches Mastra Studio CLI on port 4111

5. MCP Management

Configure Model Context Protocol integration for external tool access.

Commands:

# Add MCPClient for consuming external servers
$mastra-dev mcp add-client \
  --name <server-name> \
  --command <command> \
  [--args <comma-separated-args>] \
  [--url <http-url>]

# Configure MCPServer to expose Mastra tools
$mastra-dev mcp configure-server \
  [--agents <comma-separated-agent-ids>] \
  [--workflows <comma-separated-workflow-ids>] \
  [--tools <comma-separated-tool-ids>]

# List all MCP servers
$mastra-dev mcp list-servers

# Test MCP server connection
$mastra-dev mcp test --server <server-name>

Example - Add External MCP Servers:

# Add local stdio MCP server (Wikipedia)
$mastra-dev mcp add-client \
  --name "wikipedia" \
  --command "npx" \
  --args "-y,wikipedia-mcp"

# Add remote HTTP MCP server (Weather)
$mastra-dev mcp add-client \
  --name "weather" \
  --url "https://server.smithery.ai/@smithery-ai/national-weather-service/mcp"

# Add Puppeteer for browser automation
$mastra-dev mcp add-client \
  --name "puppeteer" \
  --command "npx" \
  --args "-y,@modelcontextprotocol/server-puppeteer"

Updated Configuration: apps/mastra/src/config/mcp.config.ts

import { MCPClient } from '@mastra/mcp';

export const mcpClient = new MCPClient({
  id: 'mastra-mcp-client',
  servers: {
    wikipedia: {
      command: 'npx',
      args: ['-y', 'wikipedia-mcp']
    },
    weather: {
      url: new URL('https://server.smithery.ai/@smithery-ai/national-weather-service/mcp')
    },
    puppeteer: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-puppeteer']
    }
  }
});

Example - Expose Mastra Workflows via MCP:

# Configure MCPServer to expose workflows
$mastra-dev mcp configure-server \
  --workflows "form-generation,contract-analysis"

Updated Configuration:

import { MCPServer } from '@mastra/mcp';
import { formGenerationWorkflow } from '../workflows/form-generation.js';
import { contractAnalysisWorkflow } from '../workflows/contract-analysis.js';

export const mastraMcpServer = new MCPServer({
  id: 'mastra-workflows',
  name: 'Mastra Workflow Engine',
  version: '1.0.0',
  workflows: {
    formGeneration: formGenerationWorkflow,
    contractAnalysis: contractAnalysisWorkflow
  }
});

Testing MCP Connection:

$mastra-dev mcp test --server "wikipedia"
# Output: ✅ Connected to wikipedia MCP server
#         Available tools: search_wikipedia, get_article, get_summary
#         Transport: stdio
#         Status: healthy

6. Analysis & Debugging

Analyze Mastra setup, debug workflow execution, and validate configurations.

Commands:

# Analyze entire Mastra setup
$mastra-dev analyze

# Debug workflow execution
$mastra-dev debug-workflow \
  --name <workflow-name> \
  --execution-id <execution-id>

# Show workflow DAG visualization
$mastra-dev show-graph --workflow <workflow-name>

# Validate all configurations
$mastra-dev validate

Example - Comprehensive Analysis:

$mastra-dev analyze

Output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 Mastra Setup Analysis
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 AGENTS (3 found)
  ✅ contract-analyzer
     Model: anthropic/claude-3-5-sonnet-20241022
     Tools: document-parser, sam-gov-lookup, far-compliance
     Status: Registered in mastra.config.ts

  ✅ proposal-writer
     Model: openai/gpt-4-turbo
     Tools: sam-gov-lookup, company-data
     Status: Registered in mastra.config.ts

  ✅ data-analyst
     Model: anthropic/claude-3-5-sonnet-20241022
     Tools: database-query, chart-generator
     Status: Registered in mastra.config.ts

📊 WORKFLOWS (2 found)
  ✅ form-generation
     Steps: 3 (fetch-opportunity, extract-data, generate-pdf)
     Type: Sequential DAG
     Status: Registered in MCP Server

  ✅ contract-analysis
     Steps: 4 (extract-text, identify-clauses, check-compliance, assess-risks)
     Type: Sequential DAG
     Status: Registered in MCP Server

📊 TOOLS (5 found)
  ✅ pdf-generator
  ✅ document-parser
  ✅ sam-gov-lookup
  ✅ far-compliance
  ✅ database-query

📊 MCP SERVERS (3 configured)
  ✅ wikipedia (stdio)
  ✅ weather (HTTP)
  ✅ puppeteer (stdio)

📊 DATABASE
  ✅ PostgreSQL connected
  ✅ Schema: mastra
  ✅ Tables: tenants, workflows, workflow_executions, step_execution_logs

📊 SERVER STATUS
  ✅ Running on port 6000
  ✅ PID: 12345
  ✅ Uptime: 2 hours 15 minutes
  ✅ Memory: 245 MB

✅ All configurations valid

Example - Debug Failed Workflow:

$mastra-dev debug-workflow \
  --name "contract-analysis" \
  --execution-id "550e8400-e29b-41d4-a716-446655440000"

Output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🐛 Workflow Execution Debug
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Workflow: contract-analysis
Execution ID: 550e8400-e29b-41d4-a716-446655440000
Status: ❌ FAILED
Started: 2026-02-11 14:23:15
Completed: 2026-02-11 14:23:47
Duration: 32 seconds

📊 STEP EXECUTION BREAKDOWN:

  ✅ Step 1: extract-text
     Status: COMPLETED
     Duration: 8s
     Input: {"documentUrl": "https://example.com/contract.pdf"}
     Output: {"text": "CONTRACT AGREEMENT..."}

  ✅ Step 2: identify-clauses
     Status: COMPLETED
     Duration: 12s
     Input: {"text": "CONTRACT AGREEMENT..."}
     Output: {"clauses": ["FAR 52.212-4", "FAR 52.212-5"]}

  ❌ Step 3: check-compliance
     Status: FAILED
     Duration: 5s
     Input: {"clauses": ["FAR 52.212-4", "FAR 52.212-5"]}
     Error: TypeError: Cannot read property 'farClause' of undefined
     Stack Trace:
       at checkComplianceStep.execute (workflows/contract-analysis.ts:45:23)

  ⏸️ Step 4: assess-risks
     Status: SKIPPED (previous step failed)

🔍 ROOT CAUSE:
  Step 'check-compliance' failed due to undefined property access.

  Likely issue: Missing FAR compliance database connection or
  incorrect data structure returned from identify-clauses step.

💡 SUGGESTED FIX:
  1. Verify far-compliance tool is properly configured
  2. Check inputData schema in check-compliance step
  3. Add null checking: if (!inputData.clauses) throw new Error(...)
  4. Review step schema compatibility

📝 LOGS:
  [2026-02-11 14:23:40] ERROR: FAR compliance check failed
  [2026-02-11 14:23:40] ERROR: Database connection timeout

Example - Show Workflow DAG:

$mastra-dev show-graph --workflow "form-generation"

Output (ASCII DAG):

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Workflow DAG: form-generation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Input: { opportunityId: string }
  │
  ├─> [fetch-opportunity]
  │     Input: { opportunityId: string }
  │     Output: { opportunity: object }
  │
  ├─> [extract-data]
  │     Input: { opportunity: object }
  │     Output: { formData: object }
  │
  ├─> [generate-pdf]
  │     Input: { formData: object }
  │     Output: { pdfUrl: string }
  │
  └─> Output: { formData: object, pdfUrl: string }

Composition: Sequential (.then chain)
Total Steps: 3
Schema Validation: ✅ All schemas compatible

Example - Validate All Configurations:

$mastra-dev validate

Output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 Configuration Validation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ mastra.config.ts
   - All agents registered correctly
   - All workflows registered correctly
   - Storage configuration valid (PostgresStore)
   - MCP servers configured properly

✅ mcp.config.ts
   - MCPClient configuration valid
   - 3 servers configured (wikipedia, weather, puppeteer)
   - MCPServer exports 2 workflows

✅ Agent Files
   - contract-analyzer.ts: Valid TypeScript, proper imports
   - proposal-writer.ts: Valid TypeScript, proper imports
   - data-analyst.ts: Valid TypeScript, proper imports

✅ Workflow Files
   - form-generation.ts: Valid DAG, schemas compatible
   - contract-analysis.ts: Valid DAG, schemas compatible

✅ Tool Files
   - pdf-generator.ts: Valid TypeScript, Zod schemas correct
   - document-parser.ts: Valid TypeScript, Zod schemas correct

✅ Database Schema
   - mastra schema exists
   - All required tables present
   - Migrations up to date

⚠️ WARNINGS (1):
  - Tool 'far-compliance' referenced in agent but not found in tools directory
    Recommendation: Create tools/far-compliance.ts or remove from agent

✅ Overall Status: VALID (1 warning)

Configuration

The skill supports optional configuration via .mastra-dev-config.json in your project root:

{
  "mastraPath": "apps/mastra",
  "defaultModel": "anthropic/claude-3-5-sonnet-20241022",
  "defaultProvider": "anthropic",
  "serverPort": 6000,
  "studioPort": 4111,
  "autoRegister": true,
  "templateDefaults": {
    "agent": {
      "instructions": "You are a helpful AI assistant.",
      "tools": []
    },
    "workflow": {
      "composition": "sequential"
    }
  },
  "logging": {
    "level": "info",
    "format": "pretty"
  }
}

Configuration Options:

• mastraPath - Relative path to Mastra app (default: "apps/mastra")
• defaultModel - Default LLM model for agents
• defaultProvider - Default LLM provider
• serverPort - Mastra server port (default: 6000)
• studioPort - Mastra Studio port (default: 4111)
• autoRegister - Automatically register agents/workflows in config files
• templateDefaults - Default values for generated files
• logging - Log level and format configuration

Integration with Mastra App

This skill integrates seamlessly with the existing Mastra app at /home/artsmc/applications/low-code/apps/mastra:

Directory Structure

apps/mastra/
├── src/
│   ├── agents/                  # ← Generated agent files
│   │   ├── contract-analyzer.ts
│   │   ├── proposal-writer.ts
│   │   └── data-analyst.ts
│   ├── workflows/               # ← Generated workflow files
│   │   ├── hello-world.ts       # Existing example
│   │   ├── form-generation.ts
│   │   └── contract-analysis.ts
│   ├── tools/                   # ← Generated tool files
│   │   ├── pdf-generator.ts
│   │   ├── document-parser.ts
│   │   └── sam-gov-lookup.ts
│   ├── config/
│   │   ├── mastra.config.ts     # ← Auto-updated registration
│   │   └── mcp.config.ts        # ← Auto-updated MCP config
│   └── app.ts                   # Express server (unchanged)
└── package.json

Auto-Registration

When you create agents, workflows, or tools, the skill automatically:

1. Generates TypeScript files in the correct directories
2. Updates mastra.config.ts to register new constructs
3. Updates mcp.config.ts to expose workflows as MCP tools
4. Validates TypeScript syntax before writing
5. Preserves existing code (no destructive edits)

Example Registration Update:

Before:

// apps/mastra/src/config/mastra.config.ts
export const mastra = new Mastra({
  storage,
  agents: {},
  workflows: {},
  tools: {}
});

After running $mastra-dev create-agent --name "proposal-writer":

import { proposalWriterAgent } from '../agents/proposal-writer.js';

export const mastra = new Mastra({
  storage,
  agents: {
    proposalWriter: proposalWriterAgent  // ← Auto-added
  },
  workflows: {},
  tools: {}
});

Development Workflow

1. Start Mastra server (if not running):

   $mastra-dev server start
   

2. Create constructs as needed:

   $mastra-dev create-agent --name "my-agent"
   $mastra-dev create-workflow --name "my-workflow"
   $mastra-dev create-tool --name "my-tool"
   

3. Edit generated files to implement logic:

   • Agents: Add custom instructions and tool configurations
   • Workflows: Implement step execute functions
   • Tools: Add business logic to execute functions

4. Test locally:

   $mastra-dev test-workflow --name "my-workflow" --input '{...}'
   $mastra-dev test-tool --name "my-tool" --input '{...}'
   

5. Use Mastra Studio for visual debugging:

   $mastra-dev studio start
   # Open http://localhost:4111
   

6. Validate before commit:

   $mastra-dev validate
   

Templates

The skill uses four TypeScript templates for code generation:

1. Agent Template

File: templates/agent.template.ts

Variables:

• {{agentName}} - Camel-cased agent name (e.g., "contractAnalyzer")
• {{agentId}} - Kebab-cased agent ID (e.g., "contract-analyzer")
• {{agentDisplayName}} - Human-readable name (e.g., "Contract Analyzer")
• {{description}} - Agent description
• {{instructions}} - Agent behavior instructions
• {{provider}} - LLM provider (e.g., "anthropic", "openai")
• {{model}} - Model name (e.g., "claude-3-5-sonnet-20241022")
• {{tools}} - Comma-separated tool IDs

Example Usage:

$mastra-dev create-agent \
  --name "contract-analyzer" \
  --model "anthropic/claude-3-5-sonnet-20241022" \
  --description "Federal contract analysis expert"

2. Workflow Template

File: templates/workflow.template.ts

Variables:

• {{workflowName}} - Camel-cased workflow name
• {{workflowId}} - Kebab-cased workflow ID
• {{workflowDisplayName}} - Human-readable name
• {{description}} - Workflow description
• {{inputSchema}} - Zod object schema for input
• {{outputSchema}} - Zod object schema for output
• {{steps}} - Step definitions (generated)
• {{composition}} - DAG composition (.then(), .parallel(), etc.)

Example Usage:

$mastra-dev create-workflow \
  --name "form-generation" \
  --description "Auto-fill government forms"

3. Tool Template

File: templates/tool.template.ts

Variables:

• {{toolName}} - Camel-cased tool name
• {{toolId}} - Kebab-cased tool ID
• {{toolDisplayName}} - Human-readable name
• {{description}} - Tool description
• {{inputSchema}} - Zod object schema for input
• {{outputSchema}} - Zod object schema for output
• {{executeBody}} - Function body implementation

Example Usage:

$mastra-dev create-tool \
  --name "pdf-generator" \
  --description "Generate PDF from template"

4. Step Template

File: templates/step.template.ts

Variables:

• {{stepName}} - Camel-cased step name
• {{stepId}} - Kebab-cased step ID
• {{stepDisplayName}} - Human-readable name
• {{description}} - Step description
• {{inputSchema}} - Zod object schema for input
• {{outputSchema}} - Zod object schema for output
• {{executeBody}} - Function body implementation

Example Usage:

$mastra-dev add-step \
  --workflow "my-workflow" \
  --step-name "fetch-data" \
  --step-type "api-call"

Best Practices

1. Agent Development

✅ DO:

• Use clear, specific instructions
• Choose appropriate models for tasks (Opus for complex reasoning, Sonnet for speed)
• Register only necessary tools (avoid tool overload)
• Test agents with agent.generate() before production use
• Use memory systems for conversation context

❌ DON'T:

• Use generic instructions like "You are a helpful assistant"
• Register all available tools (increases latency and confusion)
• Skip testing agent behavior
• Hardcode API keys or secrets in agent definitions

2. Workflow Design

✅ DO:

• Define clear input/output schemas for every step
• Use .parallel() for independent operations
• Implement retry policies for unstable external APIs
• Add error handling with lifecycle callbacks
• Validate schema compatibility between steps
• Use .commit() to finalize workflow definitions

❌ DON'T:

• Create circular dependencies (DAG must be acyclic)
• Skip schema definitions (causes runtime errors)
• Use .branch() without proper conditionals
• Forget to call .commit() at the end
• Ignore step execution order requirements

3. Tool Development

✅ DO:

• Write descriptive tool descriptions for agents
• Use Zod for comprehensive input validation
• Handle edge cases and errors gracefully
• Return structured data matching output schema
• Test tools independently before agent integration

❌ DON'T:

• Use vague descriptions (agents won't know when to call)
• Skip input validation (leads to runtime errors)
• Return inconsistent output structures
• Assume external APIs are always available
• Expose sensitive operations without safeguards

4. MCP Integration

✅ DO:

• Use stdio transport for local MCP servers
• Use HTTP transport for remote MCP servers
• Test MCP connections with $mastra-dev mcp test
• Document which agents use which MCP tools
• Version MCP server configurations

❌ DON'T:

• Mix stdio and HTTP incorrectly
• Skip connection testing
• Hardcode URLs in MCP config
• Forget to restart server after MCP changes

5. Testing & Debugging

✅ DO:

• Test workflows with representative data
• Use Mastra Studio for visual debugging
• Check logs regularly during development
• Validate configurations before committing
• Debug failed executions with execution IDs

❌ DON'T:

• Skip testing with real data
• Ignore workflow execution failures
• Deploy without validating configurations
• Debug in production (use staging/dev environments)

Troubleshooting

Issue 1: "Mastra server is not running"

Symptoms:

❌ Mastra server is not running (port 6000)

Solutions:

# Start the server
$mastra-dev server start

# If that fails, check if port is in use
lsof -i :6000

# Kill existing process if needed
kill -9 <PID>

# Start again
$mastra-dev server start

Issue 2: "Agent not found in mastra.config.ts"

Symptoms:

⚠️ Agent 'my-agent' exists but not registered in mastra.config.ts

Solutions:

# Re-run create-agent with --force flag (if implemented)
$mastra-dev create-agent --name "my-agent" --force

# Or manually add to mastra.config.ts:
# 1. Import: import { myAgent } from '../agents/my-agent.js';
# 2. Register: agents: { myAgent }

Issue 3: "Workflow execution failed with schema error"

Symptoms:

❌ Step 'fetch-data' failed: Input validation error
Expected { userId: string }, got { user_id: string }

Solutions:

• Verify step schemas match data flow
• Check previous step's output schema
• Update input schema to match actual data structure
• Use schema transformation step if needed

# Debug the workflow
$mastra-dev debug-workflow --name "my-workflow" --execution-id "abc-123"

# Check DAG visualization
$mastra-dev show-graph --workflow "my-workflow"

Issue 4: "MCP server connection timeout"

Symptoms:

❌ Failed to connect to MCP server 'wikipedia'
Connection timeout after 5000ms

Solutions:

# Test MCP server independently
npx -y wikipedia-mcp

# Check if command is correct
$mastra-dev mcp list-servers

# Remove and re-add server
$mastra-dev mcp remove-client --name "wikipedia"
$mastra-dev mcp add-client --name "wikipedia" --command "npx" --args "-y,wikipedia-mcp"

# Restart Mastra server
$mastra-dev server stop
$mastra-dev server start

Issue 5: "Mastra Studio shows blank page"

Symptoms:

• Studio loads but shows empty interface
• "Cannot connect to server" error

Solutions:

# Ensure Mastra server is running first
$mastra-dev server status

# If not running, start it
$mastra-dev server start

# Then start Studio
$mastra-dev studio start

# Check CORS configuration in apps/mastra/src/app.ts
# Should include: http://localhost:4111 in allowed origins

Issue 6: "TypeScript compilation errors after generation"

Symptoms:

Error: Cannot find module '@mastra/core'

Solutions:

# Install dependencies
cd apps/mastra
npm install

# Or from monorepo root
npm install

# Rebuild
npm run build:mastra

Issue 7: "Database connection error"

Symptoms:

❌ PostgreSQL connection failed
Error: connect ECONNREFUSED 127.0.0.1:5432

Solutions:

# Check if PostgreSQL is running
pg_isready -h localhost -p 5432

# Start PostgreSQL (Docker)
cd apps/mastra
docker-compose up -d postgres

# Or use system PostgreSQL
sudo service postgresql start

# Verify DATABASE_URL environment variable
echo $DATABASE_URL

Issue 8: "Permission denied when running skill"

Symptoms:

bash: /home/artsmc/.claude/skills$mastra-dev/skill.sh: Permission denied

Solutions:

# Make skill executable
chmod +x /home/artsmc/.claude/skills$mastra-dev/skill.sh

# Or run with bash explicitly
bash /home/artsmc/.claude/skills$mastra-dev/skill.sh server status

Issue 9: "Python not found"

Symptoms:

❌ Error: Python 3 is required

Solutions:

# Check Python installation
python3 --version

# Install Python 3 (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install python3

# Install Python 3 (macOS)
brew install python3

Issue 10: "Workflow not exposed in MCP server"

Symptoms:

• Workflow exists but not available as MCP tool
• External MCP clients can't see workflow

Solutions:

# Configure workflow for MCP exposure
$mastra-dev mcp configure-server --workflows "my-workflow"

# Verify MCP configuration
$mastra-dev mcp list-servers

# Restart Mastra server to apply changes
$mastra-dev server stop
$mastra-dev server start

# Test MCP connection
$mastra-dev mcp test --server "mastra-workflows"

Use Cases

Use Case 1: Building a Government Contract Analysis System

Scenario: Create an AI system that analyzes federal contracts for compliance and risk.

# 1. Create contract analysis agent
$mastra-dev create-agent \
  --name "contract-analyzer" \
  --model "anthropic/claude-3-5-sonnet-20241022" \
  --description "Expert in federal contract analysis" \
  --instructions "Analyze contracts for FAR/DFARS compliance, identify risks, and extract key terms"

# 2. Create tools for contract processing
$mastra-dev create-tool \
  --name "pdf-parser" \
  --description "Extract text from PDF contracts"

$mastra-dev create-tool \
  --name "far-lookup" \
  --description "Look up FAR/DFARS clauses"

$mastra-dev create-tool \
  --name "risk-calculator" \
  --description "Calculate contract risk score"

# 3. Create contract analysis workflow
$mastra-dev create-workflow \
  --name "contract-analysis" \
  --description "End-to-end contract analysis pipeline"

# 4. Add workflow steps
$mastra-dev add-step --workflow "contract-analysis" --step-name "extract-text"
$mastra-dev add-step --workflow "contract-analysis" --step-name "identify-clauses"
$mastra-dev add-step --workflow "contract-analysis" --step-name "check-compliance"
$mastra-dev add-step --workflow "contract-analysis" --step-name "assess-risks"
$mastra-dev add-step --workflow "contract-analysis" --step-name "generate-report"

# 5. Test the workflow
$mastra-dev test-workflow \
  --name "contract-analysis" \
  --input '{"contractUrl": "https://example.com/contract.pdf"}'

# 6. Start Mastra Studio to monitor execution
$mastra-dev studio start

Use Case 2: Automating Government Form Filling

Scenario: Auto-fill complex government forms using SAM.gov API data.

# 1. Add SAM.gov MCP server for data access
$mastra-dev mcp add-client \
  --name "sam-gov" \
  --url "https://api.sam.gov/mcp"

# 2. Create form generation workflow
$mastra-dev create-workflow \
  --name "form-generation" \
  --description "Auto-fill government forms from opportunity data"

# 3. Add steps
$mastra-dev add-step --workflow "form-generation" --step-name "fetch-opportunity"
$mastra-dev add-step --workflow "form-generation" --step-name "extract-requirements"
$mastra-dev add-step --workflow "form-generation" --step-name "fill-form-fields"
$mastra-dev add-step --workflow "form-generation" --step-name "generate-pdf"

# 4. Create PDF generator tool
$mastra-dev create-tool \
  --name "pdf-generator" \
  --description "Generate PDF from form data"

# 5. Expose workflow via MCP for external access
$mastra-dev mcp configure-server --workflows "form-generation"

# 6. Test end-to-end
$mastra-dev test-workflow \
  --name "form-generation" \
  --input '{"opportunityId": "abc-123"}'

Use Case 3: Multi-Agent Research System

Scenario: Build a research system with specialized agents working together.

# 1. Create specialized agents
$mastra-dev create-agent \
  --name "researcher" \
  --model "anthropic/claude-3-opus-20240229" \
  --description "Deep research expert"

$mastra-dev create-agent \
  --name "summarizer" \
  --model "anthropic/claude-3-5-sonnet-20241022" \
  --description "Expert summarizer"

$mastra-dev create-agent \
  --name "fact-checker" \
  --model "openai/gpt-4-turbo" \
  --description "Fact verification specialist"

# 2. Add external research tools via MCP
$mastra-dev mcp add-client --name "wikipedia" --command "npx" --args "-y,wikipedia-mcp"
$mastra-dev mcp add-client --name "arxiv" --command "npx" --args "-y,arxiv-mcp"

# 3. Create research workflow
$mastra-dev create-workflow \
  --name "research-pipeline" \
  --description "Multi-agent research system"

# 4. Add parallel research steps
$mastra-dev add-step --workflow "research-pipeline" --step-name "gather-sources"
$mastra-dev add-step --workflow "research-pipeline" --step-name "parallel-research" --step-type "parallel"
$mastra-dev add-step --workflow "research-pipeline" --step-name "synthesize-findings"
$mastra-dev add-step --workflow "research-pipeline" --step-name "fact-check"
$mastra-dev add-step --workflow "research-pipeline" --step-name "generate-report"

# 5. Validate setup
$mastra-dev validate

# 6. Start server and Studio
$mastra-dev server start
$mastra-dev studio start

Metadata

• Version: 1.0.0
• Status: Active
• Author: AIForge Development Team
• Last Updated: 2026-02-11
• Dependencies: Python 3.x (stdlib only), Mastra Framework, TypeScript, Node.js 20+
• Compatibility: Mastra v1.3.0+, AIForge monorepo structure
• License: MIT

Related Skills

• $feature-new - Complete feature development workflow
• $security-quality-assess - Security vulnerability scanning
• $pm-db - Project management database

Support

For issues, questions, or contributions:

• GitHub Issues: https://github.com/your-org/aiforge/issues
• Documentation: /home/artsmc/applications/low-code/job-queue/product-forge/
• Mastra Docs: https://mastra.ai/docs