Development Guide

Building, testing, and running SPECTRA locally.

Quick Start

# Build and install tools
dotnet build -c Release -p:NoWarn=CA1062
dotnet pack src/Spectra.CLI/Spectra.CLI.csproj -c Release -p:NoWarn=CA1062
dotnet pack src/Spectra.MCP/Spectra.MCP.csproj -c Release -p:NoWarn=CA1062
dotnet tool install -g --add-source src/Spectra.CLI/nupkg Spectra.CLI
dotnet tool install -g --add-source src/Spectra.MCP/nupkg Spectra.MCP

# Verify
spectra --help
spectra-mcp --help

Prerequisites

.NET 8.0+ SDK
Git

Project Structure

src/
├── Spectra.CLI/       # AI test generation CLI
├── Spectra.MCP/       # MCP execution server
├── Spectra.Core/      # Shared library (parsing, validation, models, coverage)
└── Spectra.GitHub/    # GitHub integration (future)

tests/
├── Spectra.CLI.Tests/     # CLI unit/integration tests
├── Spectra.MCP.Tests/     # MCP server tests
├── Spectra.Core.Tests/    # Core library tests
└── TestFixtures/          # Sample test data
    ├── docs/              # Sample documentation
    └── test-cases/        # Sample test case suites with _index.json

Building

dotnet build                                    # Entire solution
dotnet build src/Spectra.MCP/Spectra.MCP.csproj # Specific project
dotnet build -c Release                         # Release mode

Running Tests

dotnet test                          # All tests
dotnet test tests/Spectra.MCP.Tests/ # Specific project
dotnet test -v n                     # Verbose output

Running Locally

CLI (from source)

dotnet run --project src/Spectra.CLI -- validate --path tests/TestFixtures
dotnet run --project src/Spectra.CLI -- dashboard --output ./site
dotnet run --project src/Spectra.CLI -- ai generate checkout --count 5

MCP Server (from source)

# Against TestFixtures
dotnet run --project src/Spectra.MCP -- "tests/TestFixtures"

# Against your project
dotnet run --project src/Spectra.MCP -- /path/to/your/project

The MCP server uses stdio transport. It expects JSON-RPC messages on stdin and writes responses to stdout.

Install as Global Tools

# Pack and install
dotnet pack src/Spectra.CLI/Spectra.CLI.csproj -c Release
dotnet pack src/Spectra.MCP/Spectra.MCP.csproj -c Release

dotnet tool uninstall -g Spectra.CLI 2>/dev/null
dotnet tool uninstall -g Spectra.MCP 2>/dev/null

dotnet tool install -g --add-source src/Spectra.CLI/nupkg Spectra.CLI
dotnet tool install -g --add-source src/Spectra.MCP/nupkg Spectra.MCP

# Run from anywhere
spectra validate
spectra-mcp /path/to/project

Dashboard (from source)

# Generate
dotnet run --project src/Spectra.CLI -- dashboard --output ./site

# Serve
cd site && python -m http.server 8080
# or: npx serve site
# or: dotnet serve -d site -p 8080

MCP Server Configuration

VS Code (project-level) — .vscode/mcp.json:

{
  "servers": {
    "spectra": {
      "command": "spectra-mcp",
      "args": ["."]
    }
  }
}

VS Code (from source) — .vscode/mcp.json:

{
  "servers": {
    "spectra": {
      "command": "dotnet",
      "args": [
        "run", "--project",
        "C:/SourceCode/Spectra/src/Spectra.MCP/Spectra.MCP.csproj",
        "--", "${workspaceFolder}"
      ]
    }
  }
}

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "spectra": {
      "command": "spectra-mcp",
      "args": ["C:/path/to/your/test/project"]
    }
  }
}

Claude Code — .mcp.json:

{
  "mcpServers": {
    "spectra": {
      "command": "spectra-mcp",
      "args": ["."]
    }
  }
}

Using TestFixtures

The tests/TestFixtures/ folder contains ready-to-use sample data:

dotnet run --project src/Spectra.MCP -- tests/TestFixtures

Available suites in fixtures: auth (3 test cases), checkout (1 test case).

Troubleshooting

Build errors (CA1062 warnings)

dotnet build -p:NoWarn=CA1062

“Suite not found”

Ensure your test case folder has test-cases/ with suite subdirectories containing valid _index.json files.

“Index stale”

spectra index --rebuild

MCP server exits immediately

Check that:

The base path argument is valid
The .execution/ directory can be created
No other process is using the SQLite database

VS Code doesn’t see the MCP server

Verify .vscode/mcp.json exists
Verify spectra-mcp is in PATH (where spectra-mcp)
Test manually: echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | spectra-mcp .
Reload VS Code window after changing MCP config

“No spectra.config.json found”

spectra init

AI provider not available

For GitHub Copilot: Ensure you’re signed in to GitHub in VS Code
For BYOK: Set the API key environment variable (OPENAI_API_KEY or ANTHROPIC_API_KEY)