# DIY Helper MCP Servers

Model Context Protocol (MCP) servers for the DIY Helper platform. Provides building code lookups, material specifications, and manufacturer guide access for real-time consultation support.

## Servers

### Building Codes Server
Provides access to residential building codes including:
- NEC (National Electrical Code)
- IRC (International Residential Code)
- IPC (International Plumbing Code)

**Tools:**
- `search_building_codes` - Natural language code search
- `get_code_section` - Retrieve specific code sections
- `check_code_compliance` - Verify scenario compliance
- `list_code_categories` - Browse available codes

### Material Specs Server
Provides real-time material search, pricing, and quantity calculations.

**Tools:**
- `search_materials` - Search for products across suppliers
- `get_product_details` - Get detailed product specifications
- `find_alternatives` - Find similar products at different price points
- `check_compatibility` - Verify product compatibility
- `calculate_wire_needed` - Calculate electrical wire quantities
- `calculate_outlets_needed` - Calculate outlet requirements per NEC
- `calculate_tile_needed` - Calculate tile quantities
- `calculate_paint_needed` - Calculate paint requirements
- `calculate_deck_lumber` - Calculate deck framing materials
- `calculate_pex_pipe` - Calculate plumbing pipe needs
- `create_shopping_list` - Generate complete shopping lists

**Running:**
```bash
python src/material_specs_server/server.py
```

## Installation

### Prerequisites
- Python 3.8+
- pip

### Setup

1. Clone the repository:
```bash
git clone https://github.com/yourusername/diy-helper-mcp-servers.git
cd diy-helper-mcp-servers
```

2. Create virtual environment:
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install dependencies:
```bash
pip install -r requirements.txt
```

4. Configure environment:
```bash
cp .env.example .env
# Edit .env and add your API keys
```

## Usage

### Running the Building Codes Server
```bash
python src/building_codes_server/server.py
```

### Using with Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "building-codes": {
      "command": "python",
      "args": ["/path/to/diy-helper-mcp-servers/src/building_codes_server/server.py"],
      "env": {
        "CODE_DATABASE_PATH": "/path/to/codes.json"
      }
    }
  }
}
```

### Using Programmatically
```python
from anthropic import Anthropic
from mcp import ClientSession, StdioServerParameters

# Initialize MCP client
server_params = StdioServerParameters(
    command="python",
    args=["src/building_codes_server/server.py"]
)

async with ClientSession(server_params) as session:
    # Initialize connection
    await session.initialize()
    
    # List available tools
    tools = await session.list_tools()
    
    # Call a tool
    result = await session.call_tool(
        "search_building_codes",
        {"query": "outlet spacing in living room", "jurisdiction": "National"}
    )
    print(result)
```

## Development

### Adding New Codes

Edit `src/building_codes_server/codes.json`:
```json
{
  "id": "unique-id",
  "code_ref": "CODE SECTION",
  "title": "Code Title",
  "category": "electrical|plumbing|structural|mechanical|general",
  "jurisdiction": "National|State|City",
  "summary": "Plain English summary",
  "source": "Official source citation",
  "common_questions": ["question 1", "question 2"],
  "notes": "Additional context",
  "related_codes": ["RELATED-1", "RELATED-2"]
}
```

### Running Tests
## Testing

### Run All Tests
```bash
# Run all tests
./run_all_tests.sh

# Or run individually:
python tests/test_building_codes.py
python tests/test_material_server.py
```

### Test Coverage

**Building Codes Server:**
- ✓ Code search functionality
- ✓ Specific section retrieval
- ✓ Category listing
- ✓ Common DIY questions
- ✓ Jurisdiction filtering
- ✓ Edge case handling

**Material Specs Server:**
- ✓ Product search
- ✓ Product details
- ✓ Material calculators (7 types)
- ✓ Alternative products
- ✓ Compatibility checks
- ✓ Shopping list generation

### Quick Tests
```bash
# Test building codes server directly
python src/building_codes_server/server.py

# Test material specs server directly
python src/material_specs_server/server.py
```

## Web Testing Interface

For testing on Linux or without Claude Desktop, use the web interface:

### Prerequisites
```bash
# Install Flask
pip install flask

# Set your Anthropic API key
export ANTHROPIC_API_KEY='your-key-here'
```

### Run the Web Interface
```bash
python test_web_interface.py
```

Then open your browser to: http://localhost:5000

### Features
- Interactive chat with Claude + MCP tools
- Real-time building code lookups
- Material search and pricing
- Project calculators
- Complete conversation history
- Example queries to get started

### Example Queries
Try these in the web interface:
- "What are the outlet spacing requirements for a kitchen?"
- "Search for 12 gauge wire and show me prices"
- "Calculate how much wire I need for a 40-foot circuit"
- "I'm installing a dishwasher 30 feet from the panel. What do I need?"

## Roadmap

- [ ] Vector search integration (Pinecone/pgvector)
- [ ] Material specs server
- [ ] Manufacturer guides server
- [ ] Jurisdictional code amendments
- [ ] Image analysis for code compliance
- [ ] Cost estimation tools

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## License

MIT License - See LICENSE file for details

## Support

- Documentation: [docs/setup.md](docs/setup.md)
- Issues: https://github.com/yourusername/diy-helper-mcp-servers/issues
- Email: support@yourplatform.com