Show HN: Speclinter-MCP, better specs for your coding agent

3 months ago 5

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

🚀 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)

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

Add this to your AI IDE's MCP configuration:

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

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

Core Workflows • Setup Guide • Quality System • Advanced Features

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

Node.js 18+ • pnpm (recommended)

pnpm install && pnpm build

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"] } } }

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

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.

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

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

🧪 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 "[email protected]" 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 "[email protected]" When I submit login form with email "[email protected]" 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

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

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

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

"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"

"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!

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

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

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

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.

🔒 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

MIT

Read Entire Article