feat(mcp): Implement supplier_performance_review prompt (#109)

* feat(mcp): implement supplier_performance_review prompt

Implement comprehensive supplier performance review prompt with:
- Optional supplier_code parameter (defaults to None for all suppliers)
- period_days parameter (defaults to 90 days)
- Dynamic current date injection
- Comprehensive system instructions for supply chain analysis
- Guided multi-step workflow (overview, analysis, trends, recommendations)
- Full test coverage (10 tests passing)
- Token size validation (under 5KB)

Author: Copilot

stocktrim_mcp_server/src/stocktrim_mcp_server/prompts/workflows.py

@@ -4,11 +4,164 @@
 inventory management tasks.
 """
 
-from fastmcp import FastMCP
+from datetime import datetime
 
-from stocktrim_mcp_server.logging_config import get_logger
+from fastmcp import Context, FastMCP
+from fastmcp.prompts.prompt import Message
+from pydantic import Field
 
-logger = get_logger(__name__)
+
+async def _supplier_performance_review(
+    supplier_code: str | None,
+    period_days: int,
+    context: Context | None = None,
+) -> list[Message]:
+    """Comprehensive supplier performance review and analysis.
+
+    This prompt guides the AI through:
+    1. Supplier overview and details
+    2. Performance analysis (PO history, delivery times, costs)
+    3. Trend analysis (improving/declining performance)
+    4. Recommendations (consolidation, risk mitigation, contracts)
+
+    Expected duration: 3-5 minutes
+
+    Tools used:
+    - list_purchase_orders
+    - get_supplier
+
+    Resources:
+    - stocktrim://reports/supplier-directory
+    - stocktrim://suppliers/{code}
+    """
+    # Get current date for context
+    current_date = datetime.now().strftime("%Y-%m-%d")
+
+    # Determine supplier scope
+    supplier_specific_or_all = (
+        f"Specific supplier: {supplier_code}" if supplier_code else "All suppliers"
+    )
+
+    prompt_content = f"""You are an expert supply chain analyst conducting a comprehensive supplier performance review.
+
+# Analysis Parameters
+
+- {supplier_specific_or_all}
+- Analysis period: {period_days} days
+- Review date: {current_date}
+
+# Your Task
+
+Conduct a thorough supplier performance review by:
+
+1. Analyzing supplier performance metrics
+2. Identifying optimization opportunities
+3. Providing actionable recommendations
+4. Highlighting risk mitigation strategies
+
+# Process Steps
+
+## Step 1: Supplier Overview
+- Use stocktrim://reports/supplier-directory resource to get supplier list
+- If specific supplier, use stocktrim://suppliers/{{code}} for details
+- Review supplier basic information (contact, terms, lead times)
+- Identify active vs inactive suppliers
+
+## Step 2: Performance Analysis
+- Use list_purchase_orders tool filtered by supplier and time period
+- Calculate key performance indicators:
+  - On-time delivery rate
+  - Order accuracy
+  - Average lead time vs promised lead time
+  - Cost trends over time
+  - Order frequency and consistency
+
+## Step 3: Trend Analysis
+- Identify improving performance patterns
+- Identify declining performance patterns
+- Compare suppliers against each other (if reviewing all)
+- Flag any concerning trends (cost increases, delays)
+- Note seasonal patterns if evident
+
+## Step 4: Recommendations
+- **Consolidation Opportunities**: Identify suppliers that could be consolidated
+- **Risk Mitigation**: Flag suppliers with declining performance or single-source risks
+- **Contract Renegotiation**: Suggest where better terms could be negotiated
+- **Supplier Development**: Identify suppliers worth investing in
+- **Alternative Sources**: Recommend backup suppliers for critical items
+
+# Metrics to Analyze
+
+## Delivery Performance
+- On-time delivery rate (% of orders delivered on or before promised date)
+- Average delay in days for late orders
+- Lead time consistency (standard deviation)
+
+## Cost Performance
+- Price trends over analysis period
+- Cost per unit trends
+- Total spend by supplier
+- Cost competitiveness compared to alternatives
+
+## Order Accuracy
+- Correct quantities received
+- Correct products received
+- Quality issues or returns
+
+## Relationship Quality
+- Communication responsiveness
+- Problem resolution effectiveness
+- Flexibility with urgent orders
+- Payment terms favorability
+
+# Best Practices
+
+- Always analyze data for the full period specified
+- Compare current performance to historical baselines
+- Provide quantitative metrics whenever possible
+- Be objective in assessments
+- Prioritize recommendations by impact and feasibility
+- Consider both cost and risk in recommendations
+
+# Tools Available
+
+- **list_purchase_orders**: Get PO history filtered by supplier and date range
+- **get_supplier**: Get detailed supplier information
+
+# Resources Available
+
+- **stocktrim://reports/supplier-directory**: Complete supplier directory
+- **stocktrim://suppliers/{{code}}**: Individual supplier details
+
+# Output Format
+
+Provide a structured markdown report with:
+
+1. **Executive Summary** (2-3 sentences)
+2. **Supplier Overview Section**
+   - Number of suppliers reviewed
+   - Total spend in period
+   - Key statistics
+3. **Performance Analysis Section**
+   - Top performers (with metrics)
+   - Bottom performers (with metrics)
+   - Detailed metrics by supplier
+4. **Trend Analysis Section**
+   - Improving suppliers
+   - Declining suppliers
+   - Emerging patterns
+5. **Recommendations Section** (prioritized bulleted list)
+   - Consolidation opportunities
+   - Risk mitigation actions
+   - Contract renegotiation targets
+   - Supplier development investments
+6. **Action Items** (specific next steps)
+
+Use tables for metrics, bullets for recommendations, and clear sections for easy scanning.
+
+Start with the supplier overview step."""
+
+    return [Message(content=prompt_content, role="user")]
 
 
 def register_workflow_prompts(mcp: FastMCP) -> None:
@@ -17,5 +170,17 @@ def register_workflow_prompts(mcp: FastMCP) -> None:
     Args:
         mcp: FastMCP server instance
     """
-    # Individual prompts will be added here in follow-up PRs
-    pass
+
+    @mcp.prompt()
+    async def supplier_performance_review(
+        supplier_code: str | None = Field(
+            default=None,
+            description="Specific supplier to review (optional, if None reviews all)",
+        ),
+        period_days: int = Field(
+            default=90, description="Historical period to analyze (default: 90 days)"
+        ),
+        context: Context | None = None,
+    ) -> list[Message]:
+        """Comprehensive supplier performance review and analysis."""
+        return await _supplier_performance_review(supplier_code, period_days, context)

stocktrim_mcp_server/tests/test_prompts/test_workflows.py

@@ -1,5 +1,9 @@
 """Tests for workflow prompts."""
 
+import pytest
+
+from stocktrim_mcp_server.prompts.workflows import _supplier_performance_review
+
 
 class TestWorkflowPrompts:
     """Tests for workflow prompt registration and structure."""
@@ -15,3 +19,103 @@ def test_workflow_prompts_module_exists(self):
         from stocktrim_mcp_server.prompts.workflows import register_workflow_prompts
 
         assert callable(register_workflow_prompts)
+
+
+class TestSupplierPerformanceReview:
+    """Tests for supplier_performance_review prompt."""
+
+    @pytest.mark.asyncio
+    async def test_supplier_performance_review_structure(self):
+        """Test prompt returns correct message structure."""
+        messages = await _supplier_performance_review(None, 90, None)
+
+        assert len(messages) == 1
+        assert messages[0].role == "user"
+        assert hasattr(messages[0].content, "text")
+
+    @pytest.mark.asyncio
+    async def test_supplier_performance_review_content(self):
+        """Test prompt contains expected content."""
+        messages = await _supplier_performance_review(None, 90, None)
+
+        content = messages[0].content.text.lower()
+        assert "supply chain analyst" in content
+        assert "supplier performance review" in content
+        assert "list_purchase_orders" in content
+        assert "get_supplier" in content
+        assert "stocktrim://reports/supplier-directory" in content
+        assert "stocktrim://suppliers/{code}" in content
+
+        # Check for key process steps
+        assert "supplier overview" in content
+        assert "performance analysis" in content
+        assert "trend analysis" in content
+        assert "recommendations" in content
+
+        # Check for key metrics
+        assert "on-time delivery" in content
+        assert "cost" in content or "costs" in content
+        assert "lead time" in content
+
+        # Check for parameters
+        assert "90" in content
+        assert "all suppliers" in content
+
+    @pytest.mark.asyncio
+    async def test_supplier_performance_review_specific_supplier(self):
+        """Test prompt correctly uses specific supplier parameter."""
+        messages = await _supplier_performance_review("SUP-001", 90, None)
+
+        content = messages[0].content.text
+        assert "SUP-001" in content
+        assert "Specific supplier: SUP-001" in content
+
+    @pytest.mark.asyncio
+    async def test_supplier_performance_review_all_suppliers(self):
+        """Test prompt correctly handles all suppliers mode."""
+        messages = await _supplier_performance_review(None, 90, None)
+
+        content = messages[0].content.text
+        assert "All suppliers" in content
+
+    @pytest.mark.asyncio
+    async def test_supplier_performance_review_parameters(self):
+        """Test prompt correctly uses parameters."""
+        messages = await _supplier_performance_review("SUP-002", 60, None)
+
+        content = messages[0].content.text
+        assert "SUP-002" in content
+        assert "60" in content
+
+    @pytest.mark.asyncio
+    async def test_supplier_performance_review_token_size(self):
+        """Test prompt stays within token budget."""
+        messages = await _supplier_performance_review(None, 90, None)
+
+        content_size = len(messages[0].content.text)
+
+        # Keep under 5KB total
+        assert content_size < 5000, f"Prompt too large: {content_size} bytes"
+
+    @pytest.mark.asyncio
+    async def test_supplier_performance_review_contains_metrics(self):
+        """Test prompt mentions key performance metrics."""
+        messages = await _supplier_performance_review(None, 90, None)
+
+        content = messages[0].content.text.lower()
+        # Check for important metrics
+        assert "delivery" in content
+        assert "accuracy" in content
+        assert "consolidation" in content
+        assert "risk" in content
+
+    @pytest.mark.asyncio
+    async def test_supplier_performance_review_output_format(self):
+        """Test prompt specifies output format."""
+        messages = await _supplier_performance_review(None, 90, None)
+
+        content = messages[0].content.text.lower()
+        # Check for output format guidance
+        assert "executive summary" in content
+        assert "markdown" in content or "report" in content
+        assert "recommendations" in content