jpz129/mcp_quote_server

MCP Quote Server

A Model Context Protocol (MCP) server for generating material quotes with price matching, lead time optimization, and automated quote generation.

Features

• Material Price Search: Find competitive pricing for materials across multiple vendors
• Quote Generation: Create comprehensive quotes with line items, pricing, and lead times
• Markdown Export: Generate professional quote documents in Markdown format
• Email Drafts: Create approval-ready email drafts for quote delivery
• Lead Time Optimization: Filter offers based on maximum lead time requirements
• Tax Calculation: Support for tax rate calculations in quotes

Prerequisites

• Python 3.8 or higher
• pip (Python package installer)

Installation

1. Clone the repository

   git clone https://github.com/jpz129/mcp_quote_server.git
   cd mcp_quote_server
   

2. Create a virtual environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

Configuration

Environment Variables (Optional)

Create a .env file in the project root to customize default values:

COMPANY_NAME="Your Company Name"
CLIENT_NAME="Default Client"
CLIENT_EMAIL="client@example.com"
QUOTE_SCOPE="Default project scope"
QUOTE_ZIP="00000"

Usage

Running the MCP Server

To run the server for use with ChatGPT or other MCP clients:

python server.py

The server will start in stdio mode and wait for JSON-RPC requests.

Local Testing

Run the example script to test functionality locally:

python example_call.py

This will:

1. Search for material prices
2. Generate a completed quote
3. Create a Markdown quote document
4. Generate an email draft

API Reference

Tools Available

find_material_prices(items_json: str, zip: str) -> str

Search for material prices based on line items and ZIP code.

Parameters:

• items_json: JSON string containing array of line items with ref, qty, uom, and query fields
• zip: ZIP code for delivery location

Returns: JSON string with price offers for each line item reference

complete_quote(quote_json: str, tax_rate: float = 0.0) -> str

Generate a completed quote with optimal pricing and totals.

Parameters:

• quote_json: JSON string containing quote details (client, company, scope, items, zip, lead_time_days_max)
• tax_rate: Tax rate as decimal (e.g., 0.0825 for 8.25%)

Returns: JSON string with completed quote including line items, totals, and rationale

render_quote_md(completed_quote_json: str, out_dir: str = ".") -> str

Generate a Markdown quote document.

Parameters:

• completed_quote_json: JSON string from complete_quote
• out_dir: Output directory for the Markdown file

Returns: JSON string with file path of generated Markdown document

email_draft(to: str, subject: str, completed_quote_json: str) -> str

Generate an email draft for quote approval.

Parameters:

• to: Recipient email address
• subject: Email subject line
• completed_quote_json: JSON string from complete_quote

Returns: JSON string with email details (to, subject, body)

Data Models

LineItem

{
  "ref": "L-001",
  "qty": 240,
  "uom": "ea",
  "query": {
    "keyword": "hurricane tie simpson A35"
  }
}

Quote

{
  "client": {"name": "Jane Doe", "email": "jane@example.com"},
  "company": {"name": "Acme Builders"},
  "scope": "Small hardware package",
  "items": [...],
  "zip": "95476",
  "lead_time_days_max": 7
}

PriceOffer

{
  "source": "Vendor Name",
  "vendor_sku": "SKU123",
  "description": "Product description",
  "unit_price": 12.50,
  "uom": "ea",
  "lead_time_days": 5,
  "fees_delivery": 25.00
}

Example Workflow

1. Define line items with material queries
2. Search prices using find_material_prices
3. Create quote with client and project details
4. Complete quote using complete_quote with optimal pricing
5. Generate document using render_quote_md
6. Create email draft using email_draft

Development

Project Structure

mcp_quote_server/
├── server.py              # MCP tools (thin layer) - at root
├── example_call.py        # Local testing script
├── src/
│   ├── models/
│   │   ├── __init__.py
│   │   └── quote_models.py    # Pydantic data models
│   └── services/
│       ├── __init__.py
│       ├── price_service.py   # Price matching logic
│       ├── quote_service.py   # Quote calculation logic
│       └── rendering_service.py  # Markdown & email rendering
├── requirements.txt       # Python dependencies
├── .gitignore            # Git ignore rules
└── README.md             # This file

Architecture

The codebase follows a clean separation of concerns with organized directories:

• server.py (root): MCP tool definitions only - thin wrappers around services
• src/models/: Pure data models (Pydantic) - no business logic
  • quote_models.py: All quote-related data structures
• src/services/: Business logic organized by domain
  • price_service.py: Price matching algorithms and catalog
  • quote_service.py: Quote calculations and optimization
  • rendering_service.py: Markdown generation and email drafts

Adding New Features

1. Define new Pydantic models in src/models/quote_models.py
2. Implement business logic in appropriate src/services/ module
3. Export new functions from src/services/__init__.py and src/models/__init__.py
4. Create new MCP tools in server.py using the @mcp.tool() decorator
5. Update this README with new API documentation
6. Add tests to example_call.py

Deployment

Docker

Build and run the server locally using Docker:

# Build the image
docker build -t mcp-quote-server .

# Run the container
docker run -p 8080:8080 -e PORT=8080 mcp-quote-server

The server will start in HTTP mode when the PORT environment variable is set, or in stdio mode for local MCP clients when not set.

Google Cloud Run

Deploy to Google Cloud Run for production use:

Prerequisites

• Google Cloud SDK (gcloud) installed
• Docker installed (for local testing)
• A Google Cloud project with billing enabled
• Cloud Run API enabled

Quick Deploy

Use the provided deployment script:

./deploy.sh YOUR_PROJECT_ID REGION

Example:

./deploy.sh my-project-123 us-central1

Manual Deploy

1. Set your project:

   gcloud config set project YOUR_PROJECT_ID
   

2. Build and push the container:

   gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/mcp-quote-server
   

3. Deploy to Cloud Run:

   gcloud run deploy mcp-quote-server \
     --image gcr.io/YOUR_PROJECT_ID/mcp-quote-server \
     --platform managed \
     --region us-central1 \
     --allow-unauthenticated \
     --memory 512Mi \
     --cpu 1 \
     --port 8080
   

4. Get the service URL:

   gcloud run services describe mcp-quote-server \
     --platform managed \
     --region us-central1 \
     --format 'value(status.url)'
   

Environment Variables

Configure via Cloud Run console or during deployment:

• COMPANY_NAME - Default company name for quotes
• CLIENT_NAME - Default client name
• CLIENT_EMAIL - Default client email
• QUOTE_SCOPE - Default quote scope
• QUOTE_ZIP - Default ZIP code

Example with environment variables:

gcloud run deploy mcp-quote-server \
  --image gcr.io/YOUR_PROJECT_ID/mcp-quote-server \
  --set-env-vars COMPANY_NAME="Acme Corp",QUOTE_ZIP="94102"

Configuration Files

• Dockerfile - Container image definition
• .dockerignore - Files to exclude from Docker build
• cloud-run.yaml - Cloud Run service configuration (optional)
• deploy.sh - Automated deployment script

License

This project is open source. Please check the repository for license details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions, please create an issue in the GitHub repository.