gherkin-docs-mcp

MCP (Model Context Protocol) server for Gherkin Docs - manage living documentation via Claude.

Overview

This MCP server allows Claude Desktop to interact with your Gherkin Docs instance, enabling:

• Browse projects, domains, features, scenarios, and steps
• Create new documentation entities with AI_DRAFT status
• Update existing content with change tracking
• Search across all your documentation
• Export features as .feature files
• Bulk operations for status updates

Installation

Option 1: npx (Recommended)

No installation required. Configure Claude Desktop to run via npx:

{
  "mcpServers": {
    "gherkin-docs": {
      "command": "npx",
      "args": ["gherkin-docs-mcp"],
      "env": {
        "GHERKIN_DOCS_URL": "https://your-app.vercel.app/api/v1",
        "GHERKIN_API_KEY": "ghdocs_YOUR_KEY_HERE"
      }
    }
  }
}

Option 2: Global Install

npm install -g gherkin-docs-mcp

Then configure Claude Desktop:

{
  "mcpServers": {
    "gherkin-docs": {
      "command": "gherkin-docs-mcp",
      "env": {
        "GHERKIN_DOCS_URL": "https://your-app.vercel.app/api/v1",
        "GHERKIN_API_KEY": "ghdocs_YOUR_KEY_HERE"
      }
    }
  }
}

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GHERKIN_DOCS_URL | Yes | Base URL of your Gherkin Docs API (e.g., https://your-app.vercel.app/api/v1) | | GHERKIN_API_KEY | Yes | API key with appropriate permissions (starts with ghdocs_) |

Claude Desktop Config Location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Getting an API Key

1. Log in to Gherkin Docs as an admin
2. Go to User Menu > API Keys
3. Click Create API Key
4. Select the projects and permissions needed
5. Copy the key (shown only once)

Available Tools

Projects

| Tool | Description | |------|-------------| | list_projects | List all accessible projects |

Domains

| Tool | Description | |------|-------------| | list_domains | List domains in a project | | get_domain | Get domain with features | | create_domain | Create new domain (AI_DRAFT) | | update_domain | Update domain |

Features

| Tool | Description | |------|-------------| | list_features | List features (filter by project/domain) | | get_feature | Get feature with scenarios and steps | | create_feature | Create new feature (AI_DRAFT) | | update_feature | Update feature content/status |

Scenarios

| Tool | Description | |------|-------------| | list_scenarios | List scenarios for a feature | | get_scenario | Get scenario with steps | | create_scenario | Create new scenario (AI_DRAFT) | | update_scenario | Update scenario |

Steps

| Tool | Description | |------|-------------| | list_steps | List steps for a scenario | | get_step | Get step details | | create_step | Create new step | | update_step | Update step | | delete_step | Delete step |

Search & Export

| Tool | Description | |------|-------------| | search | Full-text search across all entities | | export_feature | Export as .feature file |

Bulk Operations

| Tool | Description | |------|-------------| | bulk_update_status | Update status of multiple features/scenarios |

Content Status

Content created via MCP defaults to AI_DRAFT status, indicating it needs human review.

Available statuses:

• DRAFT - Work in progress
• AI_DRAFT - AI-generated, needs review
• PROPOSED - Submitted for approval
• CONFIRMED - Approved and active
• FUTURE - Planned for later
• DEPRECATED - Outdated
• INCORRECT - Flagged as wrong
• HIDDEN - Admin-only visibility

Example Usage

Once configured, ask Claude to:

"List all domains in the 'my-project' project"
"Create a new feature for user authentication in the auth domain"
"Search for login scenarios"
"Export the password-reset feature as a .feature file"
"Update the status of feature abc123 to CONFIRMED"

Architecture

┌─────────────────┐     stdio     ┌─────────────────┐     HTTPS     ┌─────────────────┐
│ Claude Desktop  │──────────────▶│ MCP Server      │──────────────▶│ Gherkin Docs    │
│ (local)         │               │ (npm package,   │               │ API (Vercel)    │
│                 │◀──────────────│  runs locally)  │◀──────────────│                 │
└─────────────────┘               └─────────────────┘               └─────────────────┘

The MCP server runs locally on your machine and communicates with Claude Desktop via stdio. It makes authenticated HTTPS requests to your Gherkin Docs API.

Development

# Clone the repository
git clone https://github.com/your-org/gherkin-docs.git
cd gherkin-docs/mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run locally
GHERKIN_DOCS_URL=http://localhost:3030/api/v1 \
GHERKIN_API_KEY=ghdocs_test_key \
npm start

Troubleshooting

"API Error (401): Unauthorized"

• Verify your API key is correct and not expired
• Check that the key has permissions for the requested operation

"API Error (403): Forbidden"

• The API key may not have access to this project
• Check project permissions in the API key settings

"Cannot find module '@modelcontextprotocol/sdk'"

• Run npm install in the mcp-server directory
• Or use the npx installation method

Server not appearing in Claude

• Verify the config file path is correct for your OS
• Restart Claude Desktop after config changes
• Check Claude Desktop logs for errors

License

MIT