StepWeaver 🧪

An intelligent MCP (Model Context Protocol) server that helps LLMs generate high-quality Cucumber/Gherkin test scenarios by learning from your existing test suite.

🚀 What is StepWeaver?

StepWeaver analyzes your Cucumber step definitions and feature files to understand:

• All available Given/When/Then steps in your test suite
• How steps typically flow together based on historical usage
• Common patterns and data table structures

This enables LLMs (like Claude) to:

• 🔍 Search for existing step definitions using natural language
• 💡 Get suggestions for logical next steps in a scenario
• ✅ Generate scenarios that use only implemented, executable steps
• 📊 Follow patterns established in your existing test suite

📦 Installation

Using with Claude Desktop

Add StepWeaver to Claude using the CLI:

claude mcp add @provusinc/stepweaver -e TEST_DIR=/path/to/your/test/directory

Or manually add to your Claude Desktop config:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stepweaver": {
      "command": "npx",
      "args": ["@provusinc/stepweaver"],
      "env": {
        "TEST_DIR": "/path/to/your/test/directory"
      }
    }
  }
}

Local Development

# Clone the repository
git clone https://github.com/provusinc/stepweaver.git
cd stepweaver

# Install dependencies (using bun or npm)
bun install
# or
npm install

# Build the project
bun run build
# or
npm run build

# For development with watch mode
bun run watch
# or
npm run watch

🛠️ How It Works

1. Step Definition Parsing

StepWeaver scans your step definition files (.js, .ts) to extract all Given/When/Then patterns:

// Example step definition
Given('the user is logged in as {string}', async function(username) {
  // ...
});

2. Relationship Analysis

Analyzes your .feature files to understand how steps connect:

Given the user is on the login page
When the user enters valid credentials
Then the user should see the dashboard

3. Intelligent Suggestions

When you're writing new scenarios, StepWeaver can suggest what typically comes next based on patterns in your test suite.

🔧 Available MCP Tools

search-steps

Search for existing step definitions using natural language:

// Example: Find steps related to user login
{
  "query": "user login",
  "stepType": "Given", // optional: filter by Given/When/Then
  "limit": 5
}

get-next-steps

Get suggestions for what steps typically follow your current scenario:

// Example: What usually comes after login?
{
  "currentSteps": [
    "Given the user is logged in",
    "When the user clicks on profile"
  ],
  "stepType": "Then", // optional: filter suggestions
  "limit": 3
}

📝 MCP Prompts

new-scenario

Generate complete Cucumber/Gherkin test scenarios using AI assistance:

/stepweaver:new-scenario (MCP) create a quote test

This prompt will:

• Search for relevant existing step definitions in your test suite
• Build scenarios using ONLY implemented steps
• Follow established patterns from your test suite
• Ensure proper Gherkin structure (Given/When/Then)
• Suggest appropriate data tables when needed

Example output:

Given the user is logged in
And the user is on the quotes page
When the user creates a new quote
Then the quote should be saved successfully

📊 Performance

StepWeaver includes intelligent caching to handle large test suites efficiently:

• ⚡ Caches parsed step definitions and analysis results
• 🔄 Automatically invalidates cache when files change
• 🚀 Fast startup even with thousands of test files