MCP Prospect365 - Business Intelligence Server

🎯 Purpose

This MCP server provides conversational business intelligence capabilities for Prospect365 data, allowing users to ask natural language questions about their sales, customers, and products.

🚀 Features

Smart Analytics Tools

• searchProducts - Find exact product codes by name/description (NEW!)
• analyzeCustomers - Customer performance metrics and rankings
• analyzeProducts - Product sales analysis and customer purchasing patterns

Key Capabilities

• Real-time data analysis (no ETL lag)
• Natural language business questions
• Pre-aggregated responses (no memory overload)
• Customer name resolution built-in
• Product-level sales insights
• 100% accurate product analytics - Search products first, then analyze by code

📊 Example Questions You Can Ask

Customer Analytics

• "Who was my top customer in August 2025?"
• "Show me customer revenue trends"
• "What's my average order value by customer?"

Product Analytics (NEW: Use searchProducts first!)

• "Find product code for Sweetbird Dark Chocolate Sauce" → Use searchProducts
• "How many ZDCS2L have we sold this month?" → Use product code from searchProducts
• "Which customer bought the most iced tea in July 2025?" → Search for "iced tea" first
• "What were my top 5 products last quarter?"
• "Which products haven't sold in 30 days?"

🔧 Technical Architecture

Data Flow

User Question → MCP Server → Prospect365 API (with $expand) → Aggregated Results → Human-Readable Answer

For product analytics:

User: "How many Sweetbird Dark Chocolate sold?"
  ↓
searchProducts("sweetbird dark chocolate")  → Product Code: ZDCS2L
  ↓
analyzeProducts({ productCodeFilter: "ZDCS2L" })  → 78 units (100% accurate!)

Design Principles

1. Tools return ANSWERS, not RAW DATA - Always aggregated, never overwhelming
2. Smart defaults - Sensible limits and time ranges
3. Business-aligned - Tools think like analysts, not databases
4. Performance-first - Single API calls when possible
5. Accuracy-first - Product codes over descriptions (avoids 30% data loss)

📁 Project Structure

mcp-prospect365/
├── README.md                   # This file
├── requirements.md             # Tool specifications and requirements
├── src/
│   ├── index.ts               # MCP server entry point
│   ├── tools/
│   │   ├── analyze-customers.ts
│   │   ├── analyze-products.ts
│   │   └── search-products.ts  # NEW: Product search tool
│   └── utils/
│       ├── api-client.ts      # Prospect365 API wrapper
│       └── aggregations.ts    # Data aggregation utilities
├── research/                   # Research and discovery work
│   ├── data-analysis/         # SQLite database and extractions
│   ├── api-docs/              # API documentation and TypeScript clients
│   └── ai-learning-guides/    # Solved challenges and guides
└── package.json

🔑 Configuration

Environment Variables Required

PROSPECT365_API_URL=https://crm-odata-v1-westeurope.prospect365.com/
PROSPECT365_API_TOKEN=your_bearer_token_here

🚀 Installation & Usage

Development Setup

# Clone and install
git clone <repository-url>
cd mcp-prospect365
npm install

# Set up environment
cp .env.example .env
# Edit .env with your Prospect365 API token

# Run in development mode
npm run dev

Production Build & Deployment

# Build the server
npm run build

# Test the built server
npm run test:server

# Start production server
npm start

# Or use the binary directly
npx mcp-prospect365

Claude Desktop Integration

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "prospect365": {
      "command": "npx",
      "args": ["mcp-prospect365"],
      "env": {
        "PROSPECT365_API_TOKEN": "your_token_here"
      }
    }
  }
}

📈 Performance Considerations

• All tools enforce result limits (default: 10-20 rows max)
• Server-side aggregation reduces data transfer
• Intelligent caching for frequently asked questions
• Rate limiting: 1200 requests per 10 minutes

🎉 Breakthrough Discoveries

Customer Name Resolution

• Solution: $expand=SalesLedger parameter on SalesOrderHeaders
• Result: 50,031+ orders with fully resolved customer names

Product-Level Analysis

• Solution: SalesTransaction entity with product details
• Result: Complete product sales data with quantities and customer links

Product Code Accuracy (NEW! v7.3.0)

• Problem: Single product (ZDCS2L) had 2 different descriptions, causing 30% data loss
• Solution: searchProducts tool finds exact product codes from ProductItems catalog
• Result: 100% accurate analytics using product codes instead of descriptions
• Example: ZDCS2L query returns 78 units (not 55) - capturing all transaction variations

📚 Documentation

• Requirements & Specifications
• API Learning Guides
• Data Analysis Documentation

🚦 Status

Phase 1: ✅ Research & Discovery Complete Phase 2: 🔄 Building MCP Tools (In Progress) Phase 3: ⏳ Production Deployment (Pending)

Built for real-time business intelligence without the complexity of traditional BI tools.