voyage-and-consumption-mcp-server/dist/tools/schema.js

Voyage and consumption management server handling vessel position tracking, ETA monitoring, fuel consumption, lube oil consumption, fresh water production and weather data

export const listToolsRequestSchema = {
    type: "object",
    properties: {
        category: {
            type: "string",
            description: "Optional category to filter tools by",
            enum: ["voyage", "consumption", "performance", "vessel", "user"]
        },
        search: {
            type: "string",
            description: "Optional search term to filter tools by name or description"
        },
        include_deprecated: {
            type: "boolean",
            description: "Whether to include deprecated tools in the response",
            default: false
        }
    },
    additionalProperties: false
};
export const toolDefinitions = [
    {
        name: "get_live_position_from_navtor",
        description: "Use this tool to obtain through Navtor API a vessel's current live position (latitude/longitude) and its estimated time of arrival (ETA) to the next scheduled port. Supply the vessel's IMO number to get real-time tracking data including GPS position, next port of call, and calculated ETA.",
        inputSchema: {
            type: "object",
            properties: {
                imo: {
                    type: "string",
                    description: "IMO number of the vessel"
                }
            },
            required: ["imo"]
        }
    },
    {
        name: "get_vessel_fresh_water_history",
        description: "Use this tool to retrieve historical fresh water consumption and production data for a vessel from the MongoDB database. Provides comprehensive fresh water records including daily consumption, water maker production rates, tank levels. Optionally filter by date range for analyzing consumption patterns and water maker performance.",
        inputSchema: {
            type: "object",
            properties: {
                imo: {
                    type: "string",
                    description: "IMO number of the vessel"
                },
                start_date: {
                    type: "string",
                    description: "Optional start date for filtering fresh water records (YYYY-MM-DD format). Filter will include data from this date onwards"
                },
                end_date: {
                    type: "string",
                    description: "Optional end date for filtering fresh water records (YYYY-MM-DD format). Filter will include data up to this date"
                }
            },
            required: ["imo"]
        }
    },
    {
        name: "get_vessel_mecc_history",
        description: "Use this tool to retrieve historical Main Engine Crankcase Oil (MECC) consumption data for a vessel from the MongoDB database for data analysis. Optionally filter by date range for specific time periods. Use this for main engine crankcase lube oil consumption trend analysis based on time.",
        inputSchema: {
            type: "object",
            properties: {
                imo: {
                    type: "string",
                    description: "IMO number of the vessel"
                },
                start_date: {
                    type: "string",
                    description: "Optional start date for filtering MECC records (YYYY-MM-DD format). Filter will include data from this date onwards"
                },
                end_date: {
                    type: "string",
                    description: "Optional end date for filtering MECC records (YYYY-MM-DD format). Filter will include data up to this date"
                }
            },
            required: ["imo"]
        }
    },
    {
        name: "meclo_historical_data",
        description: "Use this tool to retrieve historical cylinder oil consumption and performance data for a vessel from the MongoDB database. Provides comprehensive cylinder oil records including daily consumption rates. Optionally filter by date range for analyzing consumption patterns and cylinder oil efficiency trends.",
        inputSchema: {
            type: "object",
            properties: {
                imo: {
                    type: "string",
                    description: "IMO number of the vessel"
                },
                start_date: {
                    type: "string",
                    description: "Optional start date for filtering cylinder oil records (YYYY-MM-DD format). Filter will include data from this date onwards"
                },
                end_date: {
                    type: "string",
                    description: "Optional end date for filtering cylinder oil records (YYYY-MM-DD format). Filter will include data up to this date"
                }
            },
            required: ["imo"]
        }
    },
    {
        name: "get_vessel_aecc_history",
        description: "Use this tool to retrieve historical Auxiliary Engine Crankcase Oil (AECC) consumption data for a vessel from the MongoDB database for data analysis. Optionally filter by date range for specific time periods. Use this for auxiliary engine crankcase lube oil consumption trend analysis based on time.",
        inputSchema: {
            type: "object",
            properties: {
                imo: {
                    type: "string",
                    description: "IMO number of the vessel"
                },
                start_date: {
                    type: "string",
                    description: "Optional start date for filtering AECC records (YYYY-MM-DD format). Filter will include data from this date onwards"
                },
                end_date: {
                    type: "string",
                    description: "Optional end date for filtering AECC records (YYYY-MM-DD format). Filter will include data up to this date"
                }
            },
            required: ["imo"]
        }
    },
    {
        name: "get_live_weather_by_coordinates",
        description: "Use this tool to retrieve the current (or nearest-in-time) weather conditions at a specific geographic position. Required workflow: 1) Call get_live_position_from_navtor with vessel's IMO to get latitude, longitude, and timestamp. 2) Pass all three values to this tool to get weather data for that exact time and location. Response includes air temperature, wind speed, wind direction, pressure, humidity, and time (UTC).",
        inputSchema: {
            type: "object",
            required: ["latitude", "longitude", "timestamp"],
            properties: {
                latitude: {
                    type: "number",
                    description: "Latitude extracted from the information given by get_live_position_from_navtor tool"
                },
                longitude: {
                    type: "number",
                    description: "Longitude extracted from the information given by get_live_position_from_navtor tool"
                },
                timestamp: {
                    type: "string",
                    description: "ISO UTC timestamp of the position fix extracted from the information given by get_live_position_from_navtor tool"
                }
            }
        }
    },
    {
        name: "universal_voyage_search",
        description: `Query the voyage database using structured parameters to retrieve and analyze vessel voyage data, operational reports, fuel consumption, cargo operations, and performance analytics from Typesense. This tool constructs search queries internally with predefined field validation for security and consistency.

        ## KEY FEATURES
        ✅ **STRUCTURED PARAMETERS**: Separate fields for query, filter, and sort operations
        ✅ **FIELD VALIDATION**: Only accepts fields from the documented schema below
        ✅ **FLEXIBLE SEARCH**: Supports full-text search across indexed fields
        ✅ **DATE FILTERING**: Supports date range filtering with yyyy-mm-dd format
        ✅ **COMPREHENSIVE DATA**: Covers voyage operations, fuel consumption, cargo, and performance

        ## PARAMETER USAGE
        - **query_by**: Comma-separated field names for full-text search (e.g., "vesselName,event,fromport,toport"). Use ONLY string fields suitable for text search.
        - **q**: Search query string for full-text search (e.g., "bunkering operations")
        - **filter_by**: Filtering conditions using Typesense syntax (e.g., "imo:9123456 && reportdate:>=2024-01-01"). Use ONLY for imo and reportdate fields.
        - **sort_by**: Field name with direction for sorting (e.g., "reportdate:desc")
        - **page**: Page number for pagination (default: 1)
        - **per_page**: Results per page, up to 250 (default: 50)

        ## IMPORTANT FIELD USAGE RULES
        **query_by parameter** - Use these fields for full-text search:
        - vesselName, fromport, toport, event, eventtype

        **filter_by parameter** - Use ONLY these fields for filtering:
        - imo (integer field - e.g., "imo:9123456")
        - reportdate (date field - use yyyy-mm-dd format, e.g., "reportdate:>=2024-01-01")

        ## DATE HANDLING
        **IMPORTANT**: For the reportdate field, always use **yyyy-mm-dd** format in filter_by parameter. The function automatically converts these to Unix timestamps for querying.

        **Examples**:
        - ✅ CORRECT: "reportdate:>=2024-01-01"
        - ✅ CORRECT: "reportdate:<=2024-12-31"
        - ✅ CORRECT: "reportdate:2024-06-15"
        - ❌ WRONG: "reportdate:>=01-01-2024" (dd-mm-yyyy format)
        - ❌ WRONG: "reportdate:>=1704067200" (Unix timestamp format - use yyyy-mm-dd instead)

        ## COMMON MISTAKES TO AVOID
        ❌ WRONG: Using fields other than imo and reportdate in filter_by
        ❌ WRONG: Using imo or reportdate in query_by (these are not text-searchable)
        ❌ WRONG: Incorrect date format (use yyyy-mm-dd for date filters, NOT dd-mm-yyyy)
        ❌ WRONG: Using SQL syntax instead of Typesense syntax for filters

        ## TYPESENSE DATABASE SCHEMA - VOYAGE TABLE
        The voyage table contains comprehensive vessel operational data with 20+ fields organized into the following categories:

        ### 1. VESSEL INFORMATION (3 fields)
        Basic vessel identification and metadata.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | imo | int64 | IMO number of the vessel (only use for filter, not in query_by argument) |
        | vesselName | string | Name of the vessel |
        | voyageNumber | string | Current voyage number |

        ### 2. VOYAGE OPERATIONS (7 fields)
        Core voyage and operational details.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | event | string | Operational event onboard (e.g., NOON AT SEA, NOON, END OF SEA PASSAGE, Commencement Of Sea Passage, ARRIVAL, DEPARTURE, BUNKERING, LOADING, DISCHARGING) |
        | eventtype | string | Report category (e.g., REPORT, CORRECTION, NOON_REPORT, POSITION_REPORT) |
        | fromport | string | Port of departure for current voyage leg |
        | toport | string | Destination port for current voyage leg |
        | location | string | Current geographical location or position of vessel |
        | vesselActivity | string | Current activity status (e.g., steaming, at anchor, loading, discharging, drifting) |
        | vesselstatus | string | Current operational status of the vessel |
        | atPort | string | Indicates if vessel is currently at port (true/false) |

        ### 3. DATE AND TIME (4 fields)
        Important dates and time information for voyage tracking.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | createdAt | string | Date and time when the report was created |
        | createdAtIst | string | Date and time in IST timezone |
        | reportdate | int64 | Date when the report was generated (Unix timestamp). When filtering use yyyy-mm-dd format |
        | timeZone | string | Time zone of the vessel location during reporting |

        ### 4. OPERATIONAL METRICS (2 fields)
        Performance and operational measurements.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | steamingTime | int64 | Hours spent steaming during reporting period |
        | steaminghours | int64 | Total steaming hours (alternative field) |

        ### 5. COMMERCIAL INFORMATION (2 fields)
        Charter and commercial details.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | chartererpartyspeed | int64 | Charter party agreed speed in knots |
        | chartererpartyconsumption | int64 | Charter party agreed consumption in MT/day |

        ### 6. CARGO AND OPERATIONS DATA (3 fields)
        Cargo and operational data in structured format.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | cargoData | string | Cargo information including type, quantity, and status (JSON string) |
        | freshWaterData | string | Fresh water production, consumption, and ROB data (JSON string) |
        | machineryWiseFuelOilConsumptionData | string | Fuel oil consumption breakdown by machinery (JSON string) |

        ### 7. FUEL AND LUBE OIL DATA (2 fields)
        Fuel oil and lubricating oil consumption and ROB information.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | fuelOilConsumptionRobData | string | Fuel oil consumption and remaining on board data (JSON string) |
        | lubeOilConsumptionRobData | string | Lube oil consumption and remaining on board data (JSON string) |

        ### 8. SYSTEM AND IDENTIFIERS (2 fields)
        System-generated identifiers and metadata.

        | Field Name | Data Type | Description |
        |------------|-----------|-------------|
        | ownerId | string[] | Array of owner identifiers |
        | fleetId | string | Fleet identifier |

        ## RETURNED FIELDS
        Each search result will include the following fields:

        **Core Vessel & Voyage Information:**
        - vesselName, voyageNumber, imo
        - event, eventtype
        - fromport, toport, location
        - vesselActivity, vesselstatus, atPort

        **Dates & Time:**
        - createdAt, reportdate
        - steamingTime, steaminghours

        **Commercial Details:**
        - chartererpartyspeed, chartererpartyconsumption

        **Structured Data (JSON strings):**
        - cargoData - Cargo type, quantity, loading/discharging details
        - freshWaterData - Fresh water production, consumption, ROB levels
        - machineryWiseFuelOilConsumptionData - Fuel consumption breakdown by machinery/equipment
        - fuelOilConsumptionRobData - Fuel oil consumption rates and remaining on board quantities
        - lubeOilConsumptionRobData - Lubricating oil consumption rates and remaining on board quantities

        ## USAGE EXAMPLES

        **Basic Search Queries:**
        - universal_voyage_search(query_by="vesselName", q="Atlantic Star", per_page=100)
        - universal_voyage_search(query_by="vesselName,event", q="bunkering", per_page=50)

        **Filtering by IMO:**
        - universal_voyage_search(filter_by="imo:9123456", sort_by="reportdate:desc")
        - universal_voyage_search(filter_by="imo:9123456", query_by="event", q="DEPARTURE")

        **Date Range Filtering:**
        - universal_voyage_search(filter_by="reportdate:>=2024-01-01 && reportdate:<=2024-12-31")
        - universal_voyage_search(filter_by="imo:9123456 && reportdate:>=2024-06-01")

        **Port Search:**
        - universal_voyage_search(query_by="fromport,toport", q="Singapore")
        - universal_voyage_search(query_by="fromport", q="Rotterdam")

        **Event Type Queries:**
        - universal_voyage_search(query_by="event", q="LOADING")
        - universal_voyage_search(query_by="event,eventtype", q="BUNKERING")

        ## SECURITY NOTES
        - Results are filtered based on company restrictions
        - Queries have timeout limits
        - Maximum 250 results per page
        - All date filters must use yyyy-mm-dd format

        This tool enables comprehensive voyage analysis, operational reporting, performance monitoring, and compliance tracking for maritime operations.`,
        inputSchema: {
            type: "object",
            properties: {
                query_by: {
                    type: "string",
                    description: "Comma-separated list of field names to search in for full-text search. ONLY use these fields: vesselName, fromport, toport, event, eventtype",
                    enum: [
                        "vesselName",
                        "fromport",
                        "toport",
                        "event",
                        "eventtype"
                    ]
                },
                q: {
                    type: "string",
                    description: "Search query string for full-text search. Use '*' for wildcard searches or specific terms. Example: 'bunkering operations' or 'loading*'",
                    default: "*"
                },
                filter_by: {
                    type: "string",
                    description: "Filter conditions using Typesense syntax. Use field:value format with operators like :, :>, :<, :>=, :<=. Combine with && (AND) or || (OR). Example: 'vesselActivity:steaming && imo:>9000000'"
                },
                sort_by: {
                    type: "string",
                    description: "Comma-separated list of fields with sort direction. Format: 'field:asc' or 'field:desc'. Example: 'reportdate:desc,steamingTime:asc'",
                    default: "relevance"
                },
                page: {
                    type: "number",
                    description: "Page number for pagination. Default: 1",
                    minimum: 1,
                    default: 1
                },
                per_page: {
                    type: "number",
                    description: "Number of results per page. Maximum: 250, Default: 50",
                    minimum: 1,
                    maximum: 250,
                    default: 50
                }
            },
            required: [],
            additionalProperties: false
        }
    },
    {
        name: "get_fleet_eta_cargo_activity",
        description: "Use this tool to get the fleet vessels itinerary and cargo activity details from vessel Noon report emails. The answer is table will indicate whether the vessels belonging to the fleet are sailing, at anchorage/drifting, or in port, along with next port of call and ETA/ETB/ETD information.",
        inputSchema: {
            type: "object",
            properties: {
                fleet_imo: {
                    type: "string",
                    description: "IMO number of the fleet"
                }
            },
            required: ["fleet_imo"]
        }
    },
    {
        name: "get_fleet_vessels_cii_rating",
        description: "Use this tool to retrieve CII rating for all vessel's in the fleet from the MongoDB database. Provide the fleet's IMO number to get the full structured CII rating of the vessels in the fleet",
        inputSchema: {
            type: "object",
            properties: {
                fleet_imo: {
                    type: "string",
                    description: "IMO number of the fleet"
                }
            },
            required: ["fleet_imo"]
        }
    },
    {
        name: "get_fleet_charter_party_compliance_status",
        description: "Use this tool to retrieve latest charter-party compliance assessment for all vessel's in the fleet from the MongoDB database. Provide the fleet's IMO number to get the full structured compliance status and charter-party terms assessment.",
        inputSchema: {
            type: "object",
            properties: {
                fleet_imo: {
                    type: "string",
                    description: "IMO number of the fleet"
                }
            },
            required: ["fleet_imo"]
        }
    },
    {
        name: "get_vessel_voyage_operations_information",
        description: `Retrieves comprehensive vessel voyage operations data organized by functional categories from MongoDB curated data.
      
      ### When to Use This Tool:
      - When users ask about vessel voyage schedules, ETA, and cargo activities
      - For charter party compliance monitoring and performance analysis
      - When checking fuel oil consumption, ROB levels, and tank distributions
      - For lubricating oil consumption tracking and tank capacity management
      - When monitoring fresh water production, consumption, and tank levels
      - For environmental compliance reporting (CII ratings, EEOI calculations)
      - When generating voyage performance reports and efficiency analysis
      
      ### Data Freshness:
      - Real-time voyage data from ShipPalm ERP and AIS systems
      - Current tank levels and consumption data from noon reports
      - Up-to-date charter party performance metrics
      - Latest environmental compliance calculations and ratings
      - Synchronized data with timestamps for accuracy verification
      
      ### Voyage Operations Categories & Available Information:
      
      **voyage_planning_operations:**
      - Q31: Voyage Details from ShipPalm (Current voyage, charterer, cargo, vessel status, instructed speed/consumption)
      - Q32: Vessel Schedule, ETA and Cargo Activity (Interactive dashboard with position data, AIS, and interpretation guidelines)
      - Q33: Charter Party Compliance (Performance vs terms, consumption/speed requirements, weather-adjusted metrics)
      
      **fuel_oil_management:**
      - Q34: Fuel Oil Consumption and ROB (Consumption by grade/equipment, ROB quantities, safety margins, estimated days remaining)
      - Q86: Fuel Oil Tankwise Bunker Distribution (Tank-by-tank breakdown with visual charts and distribution tables)
      
      **lubricating_oil_management:**
      - Q35: ME CLO Consumption and ROB (Cylinder lube oil consumption, ROB for different viscosity grades, 90-day averages)
      - Q36: MECC and AECC Consumption and ROB (System oil consumption, ROB quantities, 6-month consumption trends)
      - Q104: Lube Oil Tank Distribution & Capacities (Tank distribution and capacity information)
      
      **fresh_water_management:**
      - Q37: Fresh Water Status (Tank levels, consumption data, production rates)
      
      **environmental_emissions_compliance:**
      - Q61: Last or Ongoing Voyage EEOI (Energy Efficiency Operational Indicator, CO2 emissions, cargo/distance data)
      - Q63: Current CII Rating (Carbon Intensity Indicator A-E rating, YTD performance, projected ratings, calculation methodology)
      
      ### Usage Examples:
      - category='voyage_planning_operations', question_no=32 → Vessel Schedule and ETA Information
      - category='fuel_oil_management' → All fuel consumption and tank distribution data
      - category='environmental_emissions_compliance', question_no=63 → Current CII Rating
      - category='lubricating_oil_management' → Complete lube oil consumption and tank status
      
      ### Output Includes:
      - Interactive dashboards with visual charts and graphs
      - Real-time consumption trends and ROB calculations
      - Charter party performance metrics with deviation analysis
      - Tank distribution visualizations with capacity utilization
      - Environmental compliance ratings with regulatory context
      - Predictive analytics for consumption and tank management
      - Weather-adjusted performance comparisons
      - Historical trend analysis over multiple time periods
      - Links to detailed voyage data and performance graphs`,
        inputSchema: {
            type: "object",
            properties: {
                imo: {
                    type: "string",
                    description: "Vessel IMO number (7-digit unique identifier)"
                },
                category: {
                    type: "string",
                    description: "Voyage operations category selector",
                    enum: [
                        "voyage_planning_operations",
                        "fuel_oil_management",
                        "lubricating_oil_management",
                        "fresh_water_management",
                        "environmental_emissions_compliance"
                    ]
                },
                question_no: {
                    type: "integer",
                    description: "Specific information within category (optional - if not provided, returns all information in category)",
                    enum: [31, 32, 33, 34, 35, 36, 37, 61, 63, 86, 104]
                }
            },
            required: ["imo", "category"],
            additionalProperties: false
        }
    },
    // {
    //   name: "get_tank_distribution_information",
    //   description: `Retrieves comprehensive tank distribution information for vessels from MongoDB curated data.
    //   ### When to Use This Tool:
    //   - When users ask about fuel oil tank distribution and bunker planning
    //   - For lube oil tank capacity and distribution analysis
    //   - When checking tank-wise bunker distribution with visual charts
    //   - For fuel oil and lube oil tank management queries
    //   - When generating tank distribution reports and analysis
    //   ### Data Freshness:
    //   - Real-time tank level data from ShipPalm ERP systems
    //   - Current ROB (Remaining On Board) quantities
    //   - Tank capacity utilization and distribution charts
    //   - All data is updated daily with latest consumption logs
    //   ### Question Reference Table:
    //   | Question No. | Question | Information Provided |
    //   |--------------|----------|---------------------|
    //   | 86 | Fuel Oil Tankwise Bunker Distribution | Tank-by-tank breakdown with visual charts and distribution tables for fuel oil |
    //   | 104 | Lube Oil Tank Distribution & Capacities | Tank distribution and capacity information for lube oil grades |
    //   ### Output Includes:
    //   - Tank-by-tank breakdown with current levels
    //   - Visual charts and distribution tables
    //   - ROB quantities and capacity utilization
    //   - Bunker intake calculations for optimal levels
    //   - Tank distribution analysis and recommendations`,
    //   inputSchema: {
    //       type: "object",
    //       properties: {
    //           imo: {
    //               type: "string",
    //               description: "Vessel IMO number."
    //           },
    //           questionNo: {
    //               type: "integer",
    //               description: "Tank distribution information type selector",
    //               enum: [86, 104]
    //           }
    //       },
    //       required: ["imo", "questionNo"],
    //       additionalProperties: false
    //   }
    // }
];
//# sourceMappingURL=schema.js.map