npm package: @provusinc/stepweaver
Description: MCP server for intelligent Cucumber/Gherkin test scenario generation
Author: Provus
Latest version: 0.0.17

# 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.

[![Built with MCP Framework](https://img.shields.io/badge/Built%20with-MCP%20Framework-blue)](https://mcp-framework.com)

## 🚀 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:

```bash
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`

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

### Local Development

```bash
# 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:

```javascript
// 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:

```gherkin
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:

```typescript
// 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:

```typescript
// 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:
```gherkin
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