Working with AI & IDEs

Get Spectral working with your favorite AI assistant or code editor in under 5 minutes.

Quick Setup (Choose One)

Option 1: VS Code (Recommended)

Best for: Most developers, beginners

1. Install the Spectral extension from VS Code marketplace
2. Open any .spectral file
3. Get instant syntax highlighting, autocomplete, and error checking

That's it!

Option 2: Claude Desktop + AI Tools

Best for: AI-powered development

1. Open ~/Library/Application Support/Claude/claude_desktop_config.json
2. Add:

   {
     "mcpServers": {
       "spectral": {
         "command": "/usr/local/bin/spectral-bin",
         "args": ["mcp", "--stdio"]
       }
     }
   }
   

3. Restart Claude

Now ask Claude: "Validate my Spectral code" or "Generate TypeScript from this spec"

Option 3: Other IDEs (Cursor, Windsurf, Zed)

Best for: Advanced users, specific IDE preferences

Same config as Claude, different location:

• Cursor: ~/.cursor/mcp_settings.json
• Windsurf: ~/Library/Application Support/Windsurf/mcp_config.json
• Zed: ~/.config/zed/settings.json

Find your path: which spectral-bin

What You Can Do

Once set up, you can:

• Ask AI to validate your Spectral code
• Generate TypeScript/Python/Rust from specs
• Get autocomplete in your editor
• See errors as you type
• Convert natural language to Spectral

Generate Artifacts with AI Inference

Use the spectral inference command to generate production-ready artifacts:

# Generate GraphQL schema
spectral inference graphql app.spectral -o schema.graphql

# Generate Prisma database schema
spectral inference prisma app.spectral -o prisma/schema.prisma

# Generate route tree for React Router
spectral inference routes app.spectral --framework react-router

# Generate E2E test specifications
spectral inference e2e app.spectral -o tests/

See CLI Commands for the full list of inference subcommands.

Detailed Setup Guides

Config Locations

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

Configuration

{
  "mcpServers": {
    "spectral": {
      "command": "/usr/local/bin/spectral-bin",
      "args": ["mcp", "--stdio"]
    }
  }
}

Restart Claude Desktop after saving.

Example Prompts

"Validate this Spectral code: visitor Admin { can manage users }"
"Generate TypeScript from: type User { id: string, name: string }"
"Explain what workflow OrderProcess does"

Config: ~/.cursor/mcp_settings.json

{
  "mcpServers": {
    "spectral": {
      "command": "/usr/local/bin/spectral-bin",
      "args": ["mcp", "--stdio"]
    }
  }
}

Restart Cursor, then use Cmd+K or Ctrl+K to access tools.

macOS: ~/Library/Application Support/Windsurf/mcp_config.json
Windows: %APPDATA%\Windsurf\mcp_config.json
Linux: ~/.config/Windsurf/mcp_config.json

{
  "mcpServers": {
    "spectral": {
      "command": "/usr/local/bin/spectral-bin",
      "args": ["mcp", "--stdio"]
    }
  }
}

Open VS Code settings (JSON) and add:

{
  "cline.mcpServers": {
    "spectral": {
      "command": "/usr/local/bin/spectral-bin",
      "args": ["mcp", "--stdio"]
    }
  }
}

Config: ~/.config/zed/settings.json

{
  "context_servers": {
    "spectral": {
      "command": {
        "path": "/usr/local/bin/spectral-bin",
        "args": ["mcp", "--stdio"]
      }
    }
  }
}

Config: .continue/config.json

{
  "mcpServers": [
    {
      "name": "spectral",
      "command": "/usr/local/bin/spectral-bin",
      "args": ["mcp", "--stdio"]
    }
  ]
}

Copilot works indirectly:

1. Install Spectral VS Code extension (for context)
2. Use CLI: spectral implement app.spectral --agent copilot
3. Or generate code and let Copilot enhance it

VS Code Setup

1. Open VS Code Extensions (Cmd+Shift+X)
2. Search "Spectral"
3. Click Install

You get: Syntax highlighting, autocomplete, error checking, go-to-definition

• See errors as you type (red squiggles)
• Auto-complete types, visitors, workflows
• Hover for documentation
• Click to jump to definitions (F12)
• Find all references (Shift+F12)

Other Editors (Neovim, Emacs, Sublime)

require('lspconfig').spectral.setup{
  cmd = { "spectral", "lsp" },
  filetypes = { "spectral" },
}

(lsp-register-client
 (make-lsp-client :new-connection (lsp-stdio-connection '("spectral" "lsp"))
                  :major-modes '(spectral-mode)
                  :server-id 'spectral))

{
  "clients": {
    "spectral": {
      "enabled": true,
      "command": ["spectral", "lsp"],
      "selector": "source.spectral"
    }
  }
}

Troubleshooting

AI not responding?

• Run spectral mcp --list-tools to check MCP server
• Verify path with which spectral-bin
• Restart your AI client

VS Code extension not working?

• Reload window (Cmd+Shift+P -> "Reload Window")
• Check extension is installed and enabled

Need help?

• Check spectral lsp command works
• See CLI Commands for more options

Next Steps

• Read the Language Reference for syntax details
• Explore Workflow Features for advanced patterns
• Check out Examples to see Spectral in action
• Join the community for tips and support

Need help? Ask your AI assistant or check the CLI Commands guide.