# MCP Quoting System

An MCP (Model Context Protocol) based intelligent quoting system that compares incoming RFPs against historical quotes to generate accurate cost estimates and lead times.

## 🚀 Quick Start (Windows)

**New to the system?** Just double-click **`START.bat`** and choose option [1] for automatic setup!

See these guides:
- **[QUICKSTART.md](QUICKSTART.md)** - Visual guide with workflows and examples
- **[BATCH-FILES-README.md](BATCH-FILES-README.md)** - Complete batch file documentation
- **[TEST-CASES.md](TEST-CASES.md)** - Sample RFQs to test the system

### Available Batch Files
- `START.bat` - Main interactive launcher (recommended) ⭐
- `setup.bat` - First-time installation wizard
- `start-dev.bat` - Start development server
- `start-prod.bat` - Start production server
- `quick-test.bat` - Automated testing
- `stop.bat` - Stop the server
- See [BATCH-FILES-README.md](BATCH-FILES-README.md) for complete list

---

## Features

- **RFP Parsing**: Automatically extracts material, processes, quantities, tolerances, and other key information from text-based RFPs
- **Historical Matching**: Compares new requests against past quotes using intelligent similarity scoring
- **Cost Estimation**: Activity-based costing with material, processing, labor, tooling, and overhead calculations
- **Lead Time Prediction**: Estimates delivery time based on quantity, processes, and historical data
- **Confidence Scoring**: Provides low/medium/high confidence ratings based on data completeness and match quality
- **Human-in-Loop**: Requires approval before sending quotes, with full audit trails
- **Idempotency**: Prevents duplicate processing of the same RFP

## Architecture

The system is built as an MCP server with the following capabilities:

### MCP Functions (Capabilities)

1. **ingestRfp** - Parse RFP text and extract structured information
2. **findSimilarQuotes** - Search historical database for similar past quotes
3. **estimateCostLeadTime** - Calculate cost and lead time estimates
4. **generateQuote** - Create formatted quote documents
5. **approveQuote** - Mark quotes as approved (human-in-loop)
6. **sendQuote** - Send quotes via email (dry-run enabled)

### Coordinator

- **evaluateRfpAndDraftQuote** - Orchestrates all functions to produce a complete quote evaluation

## Installation

```bash
npm install
```

## Configuration

1. Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```

2. Edit `.env` with your settings:
```
PORT=3789
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASS=your-app-password
```

## Usage

### Start the Server

Development mode:
```bash
npm run dev
```

Production mode:
```bash
npm run build
npm start
```

### Load Sample Historical Data

Copy sample quotes to the main database:
```bash
cp data/sample-quotes.json data/quotes.json
```

### Example API Calls

#### 1. Full Quote Evaluation (Coordinator)

```bash
curl -X POST http://localhost:3789/mcp/invoke/evaluateRfpAndDraftQuote \
  -H "Content-Type: application/json" \
  -d '{
    "rfp": {
      "rawText": "We need 200 pcs of a 6061-T6 aluminum widget, CNC machined, anodize finish, tolerance +/-0.005, delivery by 2025-02-28. Contact: buyer@acme.com",
      "qty": 200,
      "contactEmail": "buyer@acme.com",
      "customerName": "Acme Corp"
    }
  }'
```

#### 2. Get Formatted Review

```bash
curl -X POST http://localhost:3789/mcp/utility/formatReview \
  -H "Content-Type: application/json" \
  -d '{
    "result": {<evaluation_result_from_previous_call>}
  }'
```

#### 3. View Historical Quotes

```bash
curl http://localhost:3789/mcp/utility/historicalQuotes
```

#### 4. Add Historical Quote

```bash
curl -X POST http://localhost:3789/mcp/utility/addHistoricalQuote \
  -H "Content-Type: application/json" \
  -d '{
    "id": "Q-NEW",
    "quoteDate": "2024-11-12T10:00:00Z",
    "customerName": "New Customer",
    "normalized": {
      "material": "steel",
      "processes": ["laser", "bend"],
      "qtyRange": [51, 100],
      "tolerances": "+/-0.010"
    },
    "costPerUnit": 25.00,
    "totalCost": 1875.00,
    "leadDays": 14,
    "approved": true
  }'
```

## Similarity Matching

The system uses rule-based similarity scoring with weighted components:

- **Material** (35%): Exact, family, or partial matches
- **Processes** (30%): Overlap of required processes
- **Quantity** (20%): Same range or adjacent ranges
- **Tolerances** (10%): Matching precision requirements
- **Finish** (5%): Surface treatment matching

### Confidence Thresholds

- **High confidence** (≥85%): Very similar to past work, reliable estimate
- **Medium confidence** (70-85%): Similar family, adjust with caution
- **Low confidence** (<70%): New type of work, requires engineer review

## Cost Estimation

Activity-based costing model:

```
Total Cost = Material + Processing + Labor + Tooling + Overhead + Margin
```

### Components

- **Material Cost**: Unit price × quantity (from material price list)
- **Processing Cost**: Sum of process times × machine hour rate
- **Labor Cost**: Operator time × labor rate
- **Tooling Amortization**: Setup cost / quantity
- **Overhead**: 15% of direct costs
- **Margin**: 20% profit margin
- **Contingency**: 10% for low-confidence quotes

### Lead Time Calculation

```
Lead Time = Procurement + Setup + Run Time + QA + Shipping
```

Adjustments based on:
- Quantity (higher volume = longer lead time)
- Process complexity (heat treat, plating add time)
- Historical actual lead times from similar quotes

## Data Storage

Currently uses JSON files in the `data/` directory:

- `quotes.json` - Historical quotes database
- `evaluations.json` - Recent RFP evaluations (last 100)

For production, consider migrating to:
- PostgreSQL for relational data
- Vector database (Pinecone, Weaviate) for semantic similarity search
- Redis for caching and idempotency

## Safety Features

1. **Human-in-Loop**: All quotes default to "draft" status
2. **Dry-Run Email**: Email sending requires explicit enablement
3. **Idempotency**: Duplicate RFPs return cached results
4. **Audit Trails**: All evaluations logged with timestamps
5. **Confidence Scoring**: Flags uncertain estimates for review

## Extending the System

### Add New Materials

Edit `src/config.ts`:
```typescript
materials: {
  'titanium-grade-5': 18.0,
  // Add more...
}
```

### Add New Processes

Edit `src/config.ts`:
```typescript
processes: {
  'EDM': 40,  // minutes per part
  'Grinding': 25,
  // Add more...
}
```

### Integrate Vector Search

Replace the rule-based matcher in `src/matcher.ts` with:
1. OpenAI embeddings for RFP text
2. Vector DB (Pinecone, Weaviate, FAISS)
3. Cosine similarity search
4. Metadata filtering (material, process)

### Add Database Backend

Replace `src/storage.ts` with database adapters:
- Use Prisma or TypeORM for PostgreSQL
- Implement connection pooling
- Add transactions for data integrity

## Testing

Create test RFPs:

```javascript
// Test 1: High similarity match
{
  "rawText": "Need 250 units of 6061-T6 aluminum, CNC milled and anodized, +/-0.005 tolerance",
  "qty": 250
}

// Test 2: New material
{
  "rawText": "100 titanium brackets, laser cut and polished",
  "qty": 100
}

// Test 3: Low detail (low confidence)
{
  "rawText": "We need some metal parts",
  "qty": 50
}
```

## API Documentation

See full API documentation in the console output when starting the server.

## Troubleshooting

### No historical matches found
- Check that `data/quotes.json` exists and has content
- Verify material names match (case-insensitive)
- Lower similarity threshold in `src/config.ts`

### Costs seem incorrect
- Review material prices in `src/config.ts`
- Adjust machine hour rate and labor rate
- Check overhead and margin percentages

### Lead times too short/long
- Adjust `defaultLeadDays` in config
- Review process time estimates
- Check quantity-based scaling logic

## Future Enhancements

1. **ML-based similarity**: Train model on historical quote-to-win patterns
2. **Drawing analysis**: Extract features from CAD/PDF drawings
3. **Supplier integration**: Real-time material lead times from vendors
4. **CRM integration**: Auto-populate customer info
5. **Dashboard UI**: React frontend for engineers to review/approve
6. **Analytics**: Win/loss tracking, pricing optimization
7. **Multi-currency**: International quote support
8. **Revision tracking**: Quote version history

## License

MIT

## Support

For issues or questions, please contact your system administrator.