mcp-vessel-accounts/dist/prompts/index.js

MCP server for vessel account management including EyeShare API integration, vessel expenses, and purchase orders

import { logger } from "../utils/logger.js";
export class PromptHandler {
    constructor(server) {
        this.server = server;
    }
    // List of available prompts
    getPromptList() {
        return [
            {
                name: "committed_cost_detailed_report_guide",
                description: "Comprehensive guide for generating committed cost detailed reports with complete PO lines integration",
                arguments: []
            }
        ];
    }
    async handleGetPrompt(name, arguments_) {
        try {
            switch (name) {
                case "committed_cost_detailed_report_guide":
                    return this.getCommittedCostDetailedReportGuide(arguments_);
                default:
                    throw new Error(`Unknown prompt: ${name}`);
            }
        }
        catch (error) {
            logger.error(`Error calling prompt ${name}:`, error);
            throw error;
        }
    }
    getCommittedCostDetailedReportGuide(arguments_) {
        const committedCostGuide = `# Committed Cost Detailed Report with Complete PO Lines Integration

## CRITICAL IMPORTANCE - 100% DATA ACCURACY REQUIREMENT

### MANDATORY DATA INTEGRITY STANDARDS
- 100% DATA EXTRACTION: ALL available data from MCP tools MUST be processed - NO LIMITATIONS
- 100% ACCURACY GUARANTEE: Every record, every field, every data point must be preserved
- NO DATASET LIMITING: Never use limits, filters, or restrictions that could exclude data
- COMPLETE TOOL UTILIZATION: Use ALL available MCP vessel account tools to their full capacity
- ZERO DATA LOSS: Every transaction, every line item, every expense must be captured

### CRITICAL SUCCESS FACTORS
FAILURE TO FOLLOW THESE REQUIREMENTS WILL RESULT IN INCOMPLETE FINANCIAL REPORTING
- Always set limit: 10000 or higher in MCP calls to ensure complete data extraction
- Process ALL unique EyeShare IDs without exception
- Include ALL purchase order lines regardless of status or amount
- Capture ALL vessel expenses across all time periods
- Preserve ALL original data fields plus enhanced details

## Overview
This document provides comprehensive instructions for generating detailed vessel committed cost reports that integrate purchase orders, vessel expenses, and complete purchase order line details with financial matching capabilities. This report GUARANTEES 100% accuracy for committed cost analysis through any specified date with COMPLETE data coverage.

## Prerequisites
- Access to MCP vessel account tools
- Python environment with required libraries (pandas, openpyxl)
- Purchase order data from ShipPalm systems
- Vessel expenses data from ShipNet systems
- Purchase order line details from EyeShare API

## Data Sources
- Purchase Orders: ShipPalm V2 and V3 systems (purchase_order collection)
- Vessel Expenses: ShipNet systems (budget_expenses_raw_data and budget_expenses_previous_year_raw_data collections)
- PO Line Details: EyeShare API via get_purchase_order_by_invoice tool
- Access Method: MCP vessel accounts tools

## Complete Process Flow

### Phase 1: Basic Purchase Order and Expenses Integration

#### Step 1: Data Extraction - CRITICAL: 100% DATA REQUIREMENT

USER CONFIDENCE BUILDING: Show extraction progress and results

Example MCP calls:
- purchase_orders tool with vesselCode and limit: 10000
- vessel_expenses tool with vesselCode and limit: 10000  
- vessel_expenses_previous_year tool with vesselCode and limit: 10000

### Phase 2: Complete PO Lines Integration

#### Step 3: Extract Unique EyeShare IDs - SHOW USER PROGRESS

Extract unique EyeShare IDs from the existing PO expenses report for processing.

#### Step 4: Get Complete PO Lines Data - CRITICAL: 100% COVERAGE REQUIRED

Use get_purchase_order_by_invoice tool with:
- invoiceConfigs: ALL EyeShare IDs as configurations
- maxWorkers: 500 (maximum parallel processing)
- extractPurchaseOrdersOnly: true

## Enhanced Output Fields (73+ Columns)

### Original Purchase Order Fields (16)
- vesselName, purchaseOrderNo, purchaseOrderIssueDate
- exchangeRate, TCD, purchaseOrderValue, currencyCode
- vendorName, purchaseOrderStatus, itemName
- quantity, unitprice, intaccountcode, ItemLineNo
- vesselCode, PO_Amount_USD

### Expense Fields (6)
- expense_baseAmount, expense_eyeshareId, expense_postingDate
- expense_accountNo, expense_accountDescription, expense_comments

### Detailed PO Lines Fields (48+)
- Basic Info: eyeshareId, purchaseOrderNo, poNumber, vesselCode
- Supplier Info: supplierCode, invoiceSupplierCode, purchaser
- Dates & Status: orderDate, poStatus, lineMatchStatus
- Currencies: currency, invoiceCurrency
- Line Details: line, itemName, itemDescription
- Quantities: quantity_ordered, quantity_received, quantity_invoiced
- Pricing: originalPrice, invoicedUnitPrice, totalLineAmount
- Financial: discountAmount, vatAmount, totalGrossAmount
- Codes: accountCode, costCentre, unitOfMeasure
- Technical: tcd_quotation, tcd_description, extra4
- System: lineId, gtin, prNo, crewId

### NEW: Committed Cost Analysis Fields (3)
- quantity_difference: quantity - quantity_ordered (shows over/under delivery)
- committed_cost_quantity_wise: quantity_difference × unitprice (local currency)
- committed_cost_amount_usd: committed_cost_quantity_wise × exchangeRate (USD)

## Enhanced Key Features

### MANDATORY 100% ACCURACY GUARANTEES
- COMPLETE DATA EXTRACTION: ALL available data sources processed without exception
- NO DATASET LIMITATIONS: Never apply limits that could exclude data
- MAXIMUM PARALLEL PROCESSING: Use full capacity with 500 concurrent workers
- ABSOLUTE DATA INTEGRITY: ALL joins preserve original data - ZERO data loss
- COMPREHENSIVE ERROR HANDLING: Every error checked, logged, and resolved
- COMPLETE VALIDATION: Data type consistency and format validation for every field
- FULL COVERAGE VERIFICATION: Validate that 100% of records are processed
- MANDATORY COMPLETENESS CHECKS: Ensure no missing transactions, expenses, or line items

### NEW: Advanced Committed Cost Analysis
- ACCURATE QUANTITY ANALYSIS: Correct calculation of quantity differences
- FINANCIAL IMPACT ASSESSMENT: USD-converted committed cost amounts
- STATUS-BASED FILTERING: Exclude cancelled and short-closed orders
- ZERO-VALUE EXCLUSION: Clean summary reports with only meaningful commitments
- COMPREHENSIVE GROUPING: Summary by vessel, PO, vendor, status, and account
- BOLD TOTAL FORMATTING: Professional Excel formatting with highlighted totals

### Financial Analysis Capabilities
- Committed vs Actual: Compare purchase order commitments with actual expenses
- Line-Level Detail: Granular analysis at individual line item level
- Multi-Currency Support: Handle different currencies with exchange rates
- Account Matching: Link expenses to specific account codes
- Date Range Flexibility: Configurable reporting periods
- Quantity Variance Analysis: Identify over/under deliveries against orders

### Generic Implementation
- Vessel Agnostic: Works for any vessel code
- Date Configurable: Any end date specification
- Scalable: Handles large datasets efficiently
- Reusable: Consistent process for all vessels
- User-Friendly: Interactive prompts for vessel code and date inputs

## Enhanced File Outputs
1. Basic Report: {VESSEL_CODE}_enhanced_vessel_po_expenses_report_{DATE}.xlsx
2. Intermediate Files: unique_eyeshare_ids.json, extracted_po_lines.json
3. Detailed Report: {VESSEL_CODE}_COMMITTED_COST_DETAILED_REPORT_{DATE}.xlsx
4. NEW: Enhanced Report: {VESSEL_CODE}_COMMITTED_COST_ENHANCED_REPORT_{DATE}.xlsx
5. NEW: Summary Report: Committed Cost Summary.xlsx

## ENHANCED DATA QUALITY ASSURANCE - 100% ACCURACY STANDARDS
- ZERO MISSING DATA TOLERANCE: ALL null/missing values must be handled without data loss
- COMPLETE TYPE CONVERSION: Automatic data type standardization for ALL fields
- ABSOLUTE DUPLICATE PREVENTION: Unique record identification with 100% accuracy
- COMPREHENSIVE VALIDATION CHECKS: Data consistency verification for EVERY record
- COMPLETE AUDIT TRAIL: Full processing log with verification at each step
- MANDATORY COMPLETENESS VERIFICATION: Ensure 100% of source data is processed
- CRITICAL ERROR DETECTION: Immediate failure if ANY data integrity issues detected
- FULL DATASET VALIDATION: Verify complete extraction from ALL MCP tools
- NEW: QUANTITY CALCULATION VALIDATION: Verify committed cost formulas are correct
- NEW: ZERO VALUE VERIFICATION: Confirm all zero values are properly excluded

## ENHANCED TROUBLESHOOTING - 100% SUCCESS REQUIREMENT
- MCP Connection Issues: MUST verify server connectivity and credentials - NO PARTIAL CONNECTIONS
- Memory Limitations: NEVER compromise on data completeness - increase resources if needed
- Date Format Issues: MUST ensure ISO 8601 compliance for ALL date fields
- Missing Matches: MANDATORY verification of EyeShare ID and line number consistency
- Performance Issues: Optimize maxWorkers but NEVER reduce data coverage
- DATA EXTRACTION FAILURES: If ANY MCP tool fails, MUST retry until 100% success
- INCOMPLETE RESPONSES: If response limit reached, MUST increase limits and re-extract
- VALIDATION FAILURES: ANY data integrity issue MUST be resolved before proceeding
- PARTIAL PROCESSING: NEVER accept partial results - 100% completion required
- NEW: CALCULATION ERRORS: Verify quantity difference formulas produce expected results
- NEW: SUMMARY DISCREPANCIES: Ensure summary totals match detailed report totals

## FINAL ENHANCED REQUIREMENTS SUMMARY

### ABSOLUTE MANDATES FOR 100% ACCURACY:
1. COMPLETE DATA EXTRACTION: Use ALL available MCP tools with maximum limits
2. ZERO DATA LOSS: Every record, field, and transaction MUST be preserved
3. 100% TOOL UTILIZATION: Never limit, filter, or restrict tool capabilities
4. COMPREHENSIVE VALIDATION: Verify data completeness at every processing step
5. FULL PARALLEL PROCESSING: Use maximum workers for ALL EyeShare IDs
6. COMPLETE ERROR HANDLING: Resolve ALL issues before proceeding
7. ABSOLUTE DATA INTEGRITY: Maintain 100% accuracy throughout entire process
8. NEW: ACCURATE QUANTITY CALCULATIONS: Use correct formula (quantity - quantity_ordered)
9. NEW: ZERO VALUE EXCLUSION: Remove all zero committed cost values from summaries
10. NEW: COMPREHENSIVE FORMATTING: Professional Excel formatting with bold totals

### SUCCESS CRITERIA:
✅ ALL purchase orders extracted and processed  
✅ ALL vessel expenses captured completely  
✅ ALL EyeShare IDs processed with PO lines data  
✅ ALL records preserved through join operations  
✅ ALL 73+ fields populated with complete information  
✅ ZERO data loss or exclusions  
✅ 100% accuracy verification completed  
✅ NEW: Committed cost calculations verified and accurate
✅ NEW: Summary reports contain only non-zero commitments
✅ NEW: Enhanced reports with professional formatting

### FAILURE IS NOT AN OPTION:
❌ Any data limitation or restriction  
❌ Partial dataset processing  
❌ Incomplete MCP tool utilization  
❌ Missing records or fields  
❌ Unresolved data integrity issues  
❌ NEW: Incorrect quantity difference calculations
❌ NEW: Zero values in summary reports
❌ NEW: Unformatted or unprofessional Excel outputs

---
This comprehensive enhanced documentation GUARANTEES 100% accuracy and complete reproducibility for committed cost detailed reporting across ALL vessels with ZERO data loss, COMPLETE tool utilization, and ADVANCED committed cost analysis capabilities.`;
        const messages = [
            {
                role: "user",
                content: {
                    type: "text",
                    text: committedCostGuide
                }
            }
        ];
        return {
            description: "Comprehensive guide for generating committed cost detailed reports with complete PO lines integration",
            messages
        };
    }
}
//# sourceMappingURL=index.js.map