SpecLinter

SpecLinter MCP lets you convert vague specifications into structured, testable development tasks with AI-driven quality gates. It analyzes specs, auto-generates tasks and Gherkin scenarios, detects duplicate work through semantic similarity, and validates implementations against the original spec, all integrated as an MCP server for your AI IDE.

How to use

You reach for SpecLinter MCP from within your AI IDE. Start by ensuring the MCP server is running, then connect your IDE’s MCP client to the server using the provided runtime commands. Once connected, you can 1) analyze a rough spec to get a graded assessment and a list of structured tasks, 2) generate detailed Gherkin scenarios for automated testing, and 3) validate your implementation against the original spec to receive a quality score and concrete recommendations.

Typical workflows you will perform include parsing a vague spec to receive actionable improvement suggestions, producing a full set of tasks with acceptance criteria, and then running an AI-driven implementation check to ensure alignment between code and spec. You can also ask the system to detect similar features to avoid duplicating work across your project or team.

How to install

Prerequisites: Node.js 18+ and pnpm are recommended.

Clone the project and install dependencies, then build the MCP server.

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

Configure your MCP client

Add an MCP server configuration in your AI IDE to point to SpecLinter. Use the runtime commands shown below. You can run the server in either stdio mode (local process) or via Docker.

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

Alternative: run via Docker

If you prefer Docker, you can run the MCP server in a container and connect to it from your IDE.

git clone https://github.com/orangebread/speclinter-mcp.git
cd speclinter-mcp
docker build -t speclinter/mcp .

docker run -d --name speclinter-server -v $(pwd):/workspace speclinter/mcp

Verify the server is running

To verify the stdio-based run works locally, start the server with the suggested command and ensure it stays up.

node dist/cli.js serve

Documentation-based MCP integration (optional)

You can expose documentation and usage examples through an MCP docs integration. This is useful for quick reference and onboarding.

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

Available tools

AI-powered quality grading

Analyzes vague specs and assigns a quality grade from F to A+, guiding improvements.

Structured task generator

Auto-generates a set of implementation tasks with acceptance criteria based on the spec.

Semantic similarity detector

Detects duplicate or highly similar features to prevent redundant work across the project.

Implementation validation

AI scans the codebase to assess alignment with the original spec and provides recommendations.

Gherkin scenario generator

Creates comprehensive test scenarios in Gherkin format for each task.

MCP integration support

Facilitates connecting the MCP server to AI IDEs and managing docs-related integration.