Stealth-Labs-LTD/WhyBuild

Claude Desktop Integration

1. Locate your Claude Desktop configuration file:

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

2. Add the whybuild MCP server:

{
  "mcpServers": {
    "whybuild": {
      "command": "whybuild",
      "env": {
        "GITHUB_TOKEN": "ghp_your_github_token",
        "OPENAI_API_KEY": "sk-your_openai_key"
      }
    }
  }
}

3. Restart Claude Desktop

4. Look for the MCP indicator showing "whybuild" as an available tool

Claude Code CLI Integration

Create or edit ~/.config/claude-code/mcp.json:

{
  "whybuild": {
    "command": "whybuild",
    "env": {
      "GITHUB_TOKEN": "ghp_your_github_token",
      "OPENAI_API_KEY": "sk-your_openai_key"
    }
  }
}

Or reference the source installation:

{
  "whybuild": {
    "command": "python",
    "args": ["-m", "whybuild.server"],
    "cwd": "/path/to/WhyBuild",
    "env": {
      "GITHUB_TOKEN": "ghp_your_github_token",
      "OPENAI_API_KEY": "sk-your_openai_key"
    }
  }
}

Cursor Integration

Cursor supports MCP servers through its configuration.

1. Open Cursor Settings (Cmd/Ctrl + ,)

2. Navigate to Features > MCP Servers

3. Click Add Server and configure:

{
  "whybuild": {
    "command": "whybuild",
    "env": {
      "GITHUB_TOKEN": "ghp_your_github_token",
      "OPENAI_API_KEY": "sk-your_openai_key"
    }
  }
}

Alternatively, create/edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "whybuild": {
      "command": "whybuild",
      "env": {
        "GITHUB_TOKEN": "ghp_your_github_token",
        "OPENAI_API_KEY": "sk-your_openai_key"
      }
    }
  }
}

4. Restart Cursor

GitHub Copilot Integration

GitHub Copilot in VS Code supports MCP servers via the Copilot extension settings.

1. Open VS Code Settings (Cmd/Ctrl + ,)

2. Search for "Copilot MCP"

3. Edit the github.copilot.chat.mcpServers setting in your settings.json:

{
  "github.copilot.chat.mcpServers": {
    "whybuild": {
      "command": "whybuild",
      "env": {
        "GITHUB_TOKEN": "ghp_your_github_token",
        "OPENAI_API_KEY": "sk-your_openai_key"
      }
    }
  }
}

4. Reload VS Code window (Cmd/Ctrl + Shift + P > "Developer: Reload Window")

5. In Copilot Chat, the whybuild tools will be available

Windsurf Integration

Windsurf (Codeium) supports MCP servers in its AI configuration.

1. Open Windsurf Settings

2. Navigate to AI > MCP Servers

3. Add the whybuild configuration:

{
  "mcpServers": {
    "whybuild": {
      "command": "whybuild",
      "env": {
        "GITHUB_TOKEN": "ghp_your_github_token",
        "OPENAI_API_KEY": "sk-your_openai_key"
      }
    }
  }
}

4. Restart Windsurf

Zed Integration

Zed editor supports MCP servers through its assistant configuration.

1. Open Zed Settings (Cmd + ,)

2. Edit your settings.json to add:

{
  "assistant": {
    "mcp_servers": {
      "whybuild": {
        "command": "whybuild",
        "env": {
          "GITHUB_TOKEN": "ghp_your_github_token",
          "OPENAI_API_KEY": "sk-your_openai_key"
        }
      }
    }
  }
}

3. Restart Zed

Continue.dev Integration

Continue supports MCP servers in its configuration.

1. Edit your Continue config at ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "whybuild",
      "command": "whybuild",
      "env": {
        "GITHUB_TOKEN": "ghp_your_github_token",
        "OPENAI_API_KEY": "sk-your_openai_key"
      }
    }
  ]
}

2. Reload Continue extension

Generic MCP Configuration

For any MCP-compatible tool, the server can be configured with:

Command: whybuild

Environment Variables:

• GITHUB_TOKEN - Your GitHub personal access token
• OPENAI_API_KEY - Your OpenAI API key

Alternative (HTTP/SSE mode):

Run the server in SSE mode for HTTP-based connections:

whybuild --sse --port 8765

Then configure your tool to connect to http://localhost:8765

Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env and configure:

# Required: GitHub token for API access
GITHUB_TOKEN=ghp_your_github_token_here

# Required: Choose ONE of the following OpenAI options:

# OPTION 1: Standard OpenAI
OPENAI_API_KEY=sk-your_openai_key_here

# OPTION 2: Azure OpenAI (enterprise)
# AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
# AZURE_OPENAI_API_KEY=your_azure_key
# AZURE_OPENAI_API_VERSION=2023-05-15
# AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-ada-002

# Optional: Custom config path
# WHYBUILD_CONFIG=/path/to/custom/organizations.yaml

Configuring Organizations

Edit config/organizations.yaml to customize which GitHub organizations to search:

organizations:
  # Add your own organizations
  - name: your-company
    description: Your Company Internal Tools

  - name: your-open-source-org
    description: Your Open Source Projects

  # Keep or remove default UK Gov orgs as needed
  - name: alphagov
    description: Government Digital Service (GDS)

settings:
  cache_ttl_hours: 24
  max_results: 10
  similarity_threshold: 0.3

Note: For private repositories, ensure your GitHub token has appropriate access permissions.

check_similar

Search for similar projects before building something new.

Parameters:

Example:

You: I want to build a notification service for sending emails and SMS

Claude: [Uses check_similar tool]

Why build from scratch? Similar projects already exist:

1. alphagov/notifications-api (89% match)
   GOV.UK Notify is a government notification service...
   https://github.com/alphagov/notifications-api

plan_pr_contribution

Generate an implementation plan to add missing features to an existing repository.

Parameters:

Example:

You: The govuk-notify looks perfect but doesn't support WhatsApp

Claude: [Uses plan_pr_contribution tool]

I've analyzed the repository. Here's a plan to add WhatsApp support:

1. Study existing patterns in src/
2. Create new provider module for WhatsApp
3. Add tests following existing patterns
4. Update documentation
...

Adding Organizations

Edit config/organizations.yaml:

organizations:
  # Your private company repos
  - name: acme-corp
    description: ACME Corporation Internal Tools

  # Filter specific repos within an org
  - name: acme-opensource
    description: ACME Open Source
    repos_filter:
      - "frontend-*"
      - "api-*"

settings:
  cache_ttl_hours: 24
  max_results: 15
  similarity_threshold: 0.4

Similarity Threshold

The similarity_threshold controls matching strictness:

• 0.0 - 0.3: Permissive, many loosely related results
• 0.3 - 0.5: Balanced (default: 0.3)
• 0.5 - 0.7: Strict, highly similar only
• 0.7 - 1.0: Very strict, near-exact matches

Lower = more discovery, Higher = less noise.

Components

whybuild/
├── server.py              # FastMCP server entry point
├── tools/
│   ├── check_existing.py  # check_similar implementation
│   └── contribute.py      # plan_pr_contribution implementation
├── search/
│   ├── github_search.py   # GitHub API client
│   ├── hybrid.py          # Hybrid search orchestration
│   └── semantic.py        # OpenAI embeddings
├── cache/
│   └── sqlite_cache.py    # SQLite caching layer
└── config/
    └── loader.py          # YAML config loader

Data Flow

Developer describes what they want to build
              │
              ▼
┌─────────────────────────────────────┐
│ whybuild searches organizations     │
│ 1. GitHub API keyword search        │
│ 2. Fetch README excerpts            │
│ 3. Generate semantic embeddings     │
│ 4. Re-rank by similarity score      │
└─────────────────────────────────────┘
              │
              ▼
Returns ranked results with
"Why build from scratch?" message
              │
              ▼
If missing features needed:
plan_pr_contribution generates
implementation plan and PR template

Development Setup

git clone https://github.com/Stealth-Labs-LTD/WhyBuild.git
cd WhyBuild
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Running Tests

pytest                          # Run all tests
pytest --cov=whybuild          # With coverage
pytest -v                       # Verbose output

Code Quality

ruff check .                    # Lint
ruff format .                   # Format
mypy src/whybuild              # Type check

Local Testing

# stdio mode
whybuild

# SSE/HTTP mode
whybuild --sse --port 8765