# MENTORR

MCP server for lutherie — build management, physics calculations, tonewood inventory, diagnostics, and education.

29 tools across 4 domains, packaged as a single MCP server for Claude Code.

## Install

```bash
pip install mentorr

# With optional integrations:
pip install mentorr[openai]    # semantic search + lab inbox vision
pip install mentorr[sheets]    # Google Sheets inventory sync
pip install mentorr[all]       # everything
```

## Register with Claude Code

```bash
claude mcp add --transport stdio mentorr -- mentorr-server
```

## Tools

### Luthier Physics (15 tools)
Build management, engineering calculations, knowledge retrieval.

| Tool | Description |
|------|-------------|
| `register_project` | Add a project to the Master Schedule |
| `generate_work_day` | Create a prioritized daily schedule |
| `forecast_materials` | List materials needed for upcoming steps |
| `start_build` | Initialize a build with a template checklist |
| `get_build_status` | View checklist progress |
| `update_build_step` | Mark a step as Done/In Progress/Pending |
| `customize_build` | Add a custom step to a build |
| `consult_library` | Semantic search the knowledge base |
| `save_project_specs` | Save measurements and design specs |
| `get_project_specs` | Retrieve saved specs |
| `get_wood_specs` | Look up wood physical properties |
| `calculate_fret_layout` | Generate fret slotting table |
| `calculate_string_tension` | Compute string tension |
| `calculate_saddle_placement` | Calculate saddle compensation |
| `calculate_neck_angle_geometry` | Calculate bridge thickness |

### Shelley Inventory (6 tools)
Tonewood inventory scraping, search, and analytics.

| Tool | Description |
|------|-------------|
| `update_shelley_inventory` | Scrape Shelley Hardwoods catalog |
| `update_exotic_inventory` | Scrape Exotic Wood Zone catalog |
| `update_stewmac_inventory` | Scrape StewMac catalog |
| `process_lab_inbox` | Extract items from receipt photos (AI vision) |
| `get_inventory_stats` | Inventory summary statistics |
| `search_inventory` | Full-text search across inventory |

### Luthier Logic (5 tools)
Diagnostics, verification, design validation.

| Tool | Description |
|------|-------------|
| `verify_truth_table` | Generate truth table for a logic formula |
| `diagnose` | Diagnose guitar issues using logic trees |
| `recommend_wood` | Suggest tonewoods for a tonal goal |
| `verify_design` | Validate project specs against constraints |
| `explain_rule` | Explain lutherie rules of thumb |

### MENTORR Guide (3 tools)
MCP protocol education and system documentation.

| Tool | Description |
|------|-------------|
| `explain_mcp_architecture` | Deep-dive into MCP architecture topics |
| `get_mentorr_capabilities` | Reference of all MENTORR tools |
| `start_tutorial` | 6-lesson MCP server development course |

## Environment Variables

| Variable | Required | Purpose |
|----------|----------|---------|
| `MENTORR_DATA_DIR` | No | User data directory (default: `~/.mentorr`) |
| `OPENAI_API_KEY` | No | Enables semantic search + lab inbox processing |
| `OPENAI_EMBEDDING_MODEL` | No | Embedding model (default: `text-embedding-3-small`) |
| `OPENAI_MODEL` | No | Vision model for lab inbox (default: `gpt-4o`) |
| `GOOGLE_SHEETS_CREDENTIALS` | No | Path to service account JSON |
| `GOOGLE_SHEETS_SHEET_ID` | No | Google Sheet ID for inventory sync |
| `GOOGLE_SHEETS_WORKSHEET` | No | Worksheet name (default: `Sheet1`) |

## Architecture

MENTORR runs as a single FastMCP server over stdio. All 29 tools are registered on one `FastMCP("MENTORR")` instance, organized into 4 domain modules:

```
mentorr-server (stdio)
  |-- physics.py    (15 tools)
  |-- inventory.py  (6 tools)
  |-- logic.py      (5 tools)
  |-- guide.py      (3 tools + 1 resource)
  |-- helpers.py    (shared utilities)
  |-- pipeline/     (scraper modules)
  +-- data/         (bundled knowledge base)
```

User data (projects, inventory) is stored in `~/.mentorr/` by default.

## Built by

XZA (Magus) & CZA (Cipher). Wu-Tang style.
