How do I use SpecLinter MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SpecLinter MCP Parse this spec for a user profile page and generate tasks with Gherkin tests" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

██████╗ ██████╗ ███████╗ ██████╗██╗ ██╗███╗ ██╗████████╗███████╗██████╗ ██╔════╝ ██╔══██╗██╔════╝██╔════╝██║ ██║████╗ ██║╚══██╔══╝██╔════╝██╔══██╗ ███████╗ ██████╔╝█████╗ ██║ ██║ ██║██╔██╗ ██║ ██║ █████╗ ██████╔╝ ╚════██║ ██╔═══╝ ██╔══╝ ██║ ██║ ██║██║╚██╗██║ ██║ ██╔══╝ ██╔══██╗ ███████║ ██║ ███████╗╚██████╗███████╗██║██║ ╚████║ ██║ ███████╗██║ ██║ ╚══════╝ ╚═╝ ╚══════╝ ╚═════╝╚══════╝╚═╝╚═╝ ╚═══╝ ╚═╝ ╚══════╝╚═╝ ╚═╝ 🔍 AI-Powered Specification Analysis • 📊 Quality Grading • ⚡ Task Generation

SpecLinter MCP

🚀 Turn vague specs into structured tasks with AI-powered quality gates

Transform natural language specifications into actionable development tasks with built-in quality assessment, similarity detection, and implementation validation.

✨ What Makes SpecLinter Special

Feature	Traditional Tools	SpecLinter
Spec Analysis	Manual review	🤖 AI-powered quality grading (A+ to F)
Task Breakdown	Manual decomposition	⚡ Auto-generated structured tasks
Duplicate Detection	Manual checking	🔍 Semantic similarity analysis
Implementation Check	Code review	🧠 AI validates against original spec
Test Scenarios	Write from scratch	🧪 Auto-generated Gherkin scenarios

🎯 Quick Start (5 Minutes)

� Installation & Setup

git clone https://github.com/orangebread/speclinter-mcp.git cd speclinter-mcp pnpm install && pnpm build

🔌 MCP Configuration

Add this to your AI IDE's MCP configuration:

{ "mcpServers": { "speclinter": { "command": "node", "args": ["/absolute/path/to/speclinter-mcp/dist/cli.js", "serve"] } } }

� Try It Out

Ask your AI: "Initialize SpecLinter and parse this spec: Create a user login form with email validation"

📋 Table of Contents

Core Workflows • Setup Guide • Quality System • Advanced Features

🎯 Core Workflows

Scenario: Developer Gets Quality Feedback on Vague Spec

Given I have a vague specification: "Add social features" When I ask SpecLinter to parse it Then I get grade F with specific improvement suggestions And actionable feedback like "Define specific social features" And a template showing how to improve to grade A

Scenario: Developer Generates Structured Tasks

Given I have a detailed spec: "Create user authentication with email verification, password reset, and 2FA" When SpecLinter analyzes it Then I get grade A with 8-12 structured tasks And each task has acceptance criteria and Gherkin scenarios And tasks are saved in organized directories

Scenario: Developer Validates Implementation

Given I've implemented my authentication feature When I ask SpecLinter to validate it Then AI scans my codebase for related files And compares implementation against original spec And provides quality score with specific recommendations

Scenario: Team Avoids Duplicate Work

Given my teammate built user profile management When I try to add "user settings page" Then SpecLinter detects 85% similarity And recommends extending existing feature And prevents duplicate implementation

🚀 Setup Guide

Prerequisites

Node.js 18+ • pnpm (recommended)

Installation

pnpm install && pnpm build

MCP Integration

AI IDE	Configuration File	Location
Cursor	`mcp_servers.json`	`~/.cursor/`
Claude Desktop	`claude_desktop_config.json`	`~/Library/Application Support/Claude/` (macOS) `%APPDATA%\Claude\` (Windows)
Windsurf	Check Windsurf docs	Varies

Add this configuration:

{ "mcpServers": { "speclinter": { "command": "node", "args": ["/absolute/path/to/speclinter-mcp/dist/cli.js", "serve"] } } }

✅ Verify Setup

# Test server starts node dist/cli.js serve # In your AI IDE, try: "Initialize SpecLinter in my project" "Parse this spec: Create a user login form"

📖 GitMCP Integration

For documentation access and examples, you can also add GitMCP integration:

{ "mcpServers": { "speclinter-docs": { "command": "npx", "args": ["mcp-remote", "https://gitmcp.io/orangebread/speclinter-mcp"] } } }

This provides AI access to SpecLinter documentation and usage examples.

🐳 Docker Alternative

Quick Docker Setup:

# Clone and build git clone https://github.com/orangebread/speclinter-mcp.git cd speclinter-mcp docker build -t speclinter/mcp . # Run SpecLinter server docker run -d --name speclinter-server -v $(pwd):/workspace speclinter/mcp

MCP Configuration for Docker:

{ "mcpServers": { "speclinter": { "command": "docker", "args": ["exec", "-i", "speclinter-server", "node", "/app/dist/cli.js", "serve"] } } }

Benefits:

✅ No Node.js installation required
✅ Isolated environment
✅ Consistent across all platforms
✅ Easy cleanup with docker rm -f speclinter-server

📊 Quality System

SpecLinter grades your specifications and provides actionable feedback:

Grade	Score	What It Means	Example Issues
🏆 A+	95-100	Exceptional spec	None - ready to implement
⭐ A	90-94	Excellent spec	Minor clarity improvements
✅ B	80-89	Good spec	Missing some acceptance criteria
⚠️ C	70-79	Needs work	Vague terms, brief description
❌ D	60-69	Poor spec	Major gaps in requirements
🚫 F	0-59	Failing spec	Too vague to implement

Quality Criteria Checklist

✅ Clear acceptance criteria - What defines "done"?
✅ Specific requirements - Avoid vague terms like "user-friendly"
✅ Error handling - What happens when things go wrong?
✅ Sufficient detail - Enough info for implementation
✅ User story format - "As a... I want... So that..." (optional)

Example: F → A Transformation

❌ Grade F Spec:

"Add social features to the app"

✅ Grade A Spec:

As a user, I want to send direct messages to other users so that I can communicate privately. Acceptance Criteria: - Users can search for other users by username - Messages are delivered in real-time using WebSocket - Message history is preserved and searchable - Users can block/unblock other users - All messages are encrypted end-to-end Error Handling: - Show "User not found" for invalid usernames - Display "Message failed to send" with retry option - Handle offline users with message queuing

🔧 Advanced Features

🧪 AI-Powered Gherkin Scenarios

Every task gets comprehensive, actionable test scenarios with enhanced AI generation:

Feature: User Authentication System Implement secure user login and registration with email verification Scenario: Successfully authenticate user with valid credentials Given the user registration system is available And a user exists with email "user@example.com" and password "SecurePass123" When I submit login form with valid credentials Then the user should be authenticated successfully And a JWT token should be generated and returned And the user should be redirected to the dashboard And the login attempt should be logged Scenario: Handle invalid login attempts Given a user exists with email "user@example.com" When I submit login form with email "user@example.com" and password "WrongPassword" Then the authentication should be rejected And an error message "Invalid credentials" should be displayed And no JWT token should be generated And the failed attempt should be logged Scenario: Validate input format during login Given the login system is ready to accept input When I provide malformed email "invalid-email" and password "test123" Then input validation should be triggered And specific validation errors should be shown And the user should understand what needs to be corrected

🎯 Enhanced Scenario Features:

AI-Generated Quality: Scenarios tailored to your project's tech stack and patterns
Multiple Types: Happy path, error handling, edge cases, security, and performance scenarios
Specific Data: Concrete examples instead of generic placeholders
Actionable Steps: Each step can be implemented as an automated test
Business Focus: User-centric language with technical accuracy
Comprehensive Coverage: All acceptance criteria addressed
Configurable Complexity: Adjust scenario depth and coverage via configuration

🔍 Semantic Similarity Detection

Prevents duplicate work by finding similar features:

Input: "user profile management" Found: "user settings page" (85% similarity) Recommendation: Extend existing feature

🤖 AI Implementation Validation

Advanced AI-powered validation that understands your code:

Intelligent Codebase Scanning - Finds implementation files using semantic analysis
Context-Aware Analysis - Understands your project's patterns and tech stack
Quality Assessment - Provides detailed scoring with specific recommendations
Acceptance Criteria Validation - Checks each requirement against actual implementation
Auto-Status Updates - Updates task statuses based on implementation findings
Architectural Review - Ensures consistency with project patterns and standards

📁 Project Structure

your-project/ ├── .speclinter/ │ ├── config.json # Settings │ └── context/ # AI-generated project docs └── speclinter-tasks/ └── [feature-name]/ ├── _active.md # Status dashboard ├── task_*.md # Individual tasks └── gherkin/ # Test scenarios

💬 How to Use SpecLinter

Just talk to your AI assistant naturally! Here are the most common commands:

🚀 Getting Started

"Initialize SpecLinter in my project" "Analyze my codebase to understand patterns and tech stack"

📝 Working with Specs

"Parse this spec: Create a user authentication system with email verification" "Grade this specification: [your spec here]" "Find similar features to: user profile management" "Generate comprehensive Gherkin scenarios for my authentication feature"

📊 Managing Tasks

"Show me the status of my authentication tasks" "Mark the database setup task as completed" "Validate the implementation of my login feature" "Update task status for WebSocket connection to completed"

💡 Pro Tip: SpecLinter works through your AI IDE - no CLI commands needed for daily use!

🏗️ Real-World Examples

Example 1: E-commerce Product Catalog

Input Spec:

Create a product catalog page with filtering and search

SpecLinter Output:

Grade: C (needs more detail)
Generated Tasks: 6 structured tasks
Improvements: Add specific filter types, search behavior, pagination

Example 2: User Authentication System

Input Spec:

As a user, I want to log in with email and password so I can access my account. Acceptance Criteria: - Email validation with proper error messages - Password must be 8+ characters - Failed attempts are rate-limited (3 attempts/5 minutes) - Successful login redirects to dashboard - Remember me option for 30 days

SpecLinter Output:

Grade: A (excellent specification)
Generated Tasks: 12 detailed tasks including security, validation, and UX
Gherkin Scenarios: Auto-generated for each task

🤝 Team Collaboration

Preventing Duplicate Work

Scenario: Team coordination Given developer A built "user profile management" When developer B wants to add "user settings page" Then SpecLinter detects 85% similarity And recommends extending existing feature And prevents duplicate implementation

Cross-Project Similarity

SpecLinter can detect similar features across multiple repositories and microservices, helping large teams avoid redundant work.

🔧 Development & Contributing

git clone https://github.com/orangebread/speclinter-mcp.git cd speclinter-mcp # Traditional development pnpm install && pnpm build # Available scripts pnpm build # Build for production pnpm test # Run Vitest tests (implementation validation) pnpm lint # Lint code with ESLint pnpm dev # Watch mode for development pnpm start # Start MCP server # Docker development docker build -t speclinter/mcp:latest . docker run -it --rm -v $(pwd):/workspace speclinter/mcp

🧪 Testing

SpecLinter uses Vitest for implementation validation rather than traditional unit tests. The test framework validates that features are implemented according to their specifications using AI-generated Gherkin scenarios.

🏗️ Architecture

🔒 Type Safety: Full TypeScript with Zod validation
🤖 AI-Leveraged: Two-step pattern for semantic analysis
💾 Database: SQLite for task management and feature history
🔌 MCP Integration: Full Model Context Protocol support

📄 License

MIT

SpecLinter MCP

✨ What Makes SpecLinter Special

🎯 Quick Start (5 Minutes)

� Installation & Setup

🔌 MCP Configuration

� Try It Out

📋 Table of Contents

🎯 Core Workflows

Scenario: Developer Gets Quality Feedback on Vague Spec

Scenario: Developer Generates Structured Tasks

Scenario: Developer Validates Implementation

Scenario: Team Avoids Duplicate Work

🚀 Setup Guide

Prerequisites

Installation

MCP Integration

✅ Verify Setup

📖 GitMCP Integration

🐳 Docker Alternative

📊 Quality System

Quality Criteria Checklist

Example: F → A Transformation

🔧 Advanced Features

🧪 AI-Powered Gherkin Scenarios

🔍 Semantic Similarity Detection

🤖 AI Implementation Validation

📁 Project Structure

💬 How to Use SpecLinter

🚀 Getting Started

📝 Working with Specs

📊 Managing Tasks

🏗️ Real-World Examples

Example 1: E-commerce Product Catalog

Example 2: User Authentication System

🤝 Team Collaboration

Preventing Duplicate Work

Cross-Project Similarity

🔧 Development & Contributing

🧪 Testing

🏗️ Architecture

📄 License

Resources

New MCP Servers

Latest Blog Posts

MCP directory API