survey-mcp-server/build/tools/schemas.js

import { z } from "zod";
export const toolDefinitions = {
    universal_certificate_survey_search: {
        name: "universal_certificate_survey_search",
        description: `Query the certificate database using structured parameters to retrieve and analyze vessel certificates, surveys, and compliance documents 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

    ## PARAMETER USAGE
    - **query_by**: Comma-separated field names for full-text search (e.g., "certificateSurveyEquipmentName,certificateNumber,issuingAuthority")
    - **q**: Search query string for full-text search (e.g., "safety equipment")
    - **filter_by**: Filtering conditions using Typesense syntax (e.g., "currentStatus:IN ORDER && imo:>9000000")
    - **sort_by**: Field name with direction for sorting (e.g., "expiryDate:desc,issueDate:asc")
    - **page**: Page number for pagination (default: 1)
    - **per_page**: Results per page, up to 250 (default: 50)

    ## DATE HANDLING
    **IMPORTANT**: For date fields (issueDate, expiryDate, windowStartDate, windowEndDate, extensionDate), always use **yyyy-mm-dd** format in filter_by parameter. The function automatically converts these to Unix timestamps for querying.

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

    ## COMMON MISTAKES TO AVOID
    ❌ WRONG: Using non-existent fields
    ❌ 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 - CERTIFICATE TABLE
    The certificate table contains comprehensive vessel certificate and survey data with 20+ fields organized into the following categories:

    ### 1. VESSEL INFORMATION (3 fields)
    Information about the vessel associated with certificates and surveys.

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

    ### 2. CERTIFICATE/SURVEY INFORMATION (8 fields)
    Core certificate and survey details.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | certificateSurveyEquipmentName | string | Name of the certificate/survey/Continuous machinery survey(CSM, CMS, Machinery Survey)/IHM. Try to expand the abbreviation and give the abbreviation in bracket. CoC means condition of class |
    | certificateNumber | string | Unique certificate number identifier |
    | certificateLink | string | URL or hyperlink to supporting resource |
    | type | string | Type of record. Values: CERTIFICATE, CMS, COC, IHM, SURVEY. Continuous machinery survey(CSM, CMS, Machinery Survey) are all same terms |
    | issuingAuthority | string | Name of the authority that issued the certificate/survey (e.g., 'DNV', 'ABS', 'LR', 'BV') |
    | currentStatus | string | Current lifecycle status. Values: IN ORDER, IN WINDOW, EXPIRED |
    | dataSource | string | Data source. Values: CLASS, SHIPPALM, MMPL |
    | isExtended | bool | Whether the certificate or survey is extended or not. Values: true, false |

    ### 3. DATE INFORMATION (6 fields)
    Important dates for certificate lifecycle management.

    | Field Name | Data Type | Description |
    |------------|-----------|-------------|
    | issueDate | int64 | Certificate/survey/CMS/IHM issue date (Unix timestamp). When filtering use yyyy-mm-dd format |
    | expiryDate | int64 | Expiry date for certificate and due date for survey (Unix timestamp). When filtering use yyyy-mm-dd format |
    | windowStartDate | int64 | Start date of the survey/certificate validity window (Unix timestamp). When filtering use yyyy-mm-dd format |
    | windowEndDate | int64 | End date of the survey/certificate validity window (Unix timestamp). When filtering use yyyy-mm-dd format |
    | extensionDate | int64 | Date to which a certificate or survey is postponed (Unix timestamp). When filtering use yyyy-mm-dd format |
    | daysToExpiry | int64 | Number of days remaining for certificate, survey, CMS or COC to expire. Use > < = operators |

    ## USAGE EXAMPLES

    **Basic Search Queries:**
    - universal_certificate_survey_search(query_by="certificateSurveyEquipmentName,certificateNumber", q="safety equipment", per_page=100)
    - universal_certificate_survey_search(filter_by="currentStatus:IN ORDER", sort_by="expiryDate:desc")

    **Advanced Filtering:**
    - universal_certificate_survey_search(filter_by="imo:>9000000 && currentStatus:IN ORDER", sort_by="daysToExpiry:asc")
    - universal_certificate_survey_search(filter_by="type:CERTIFICATE && isExtended:true", query_by="vesselName", q="*")

    **Date Range Filtering:**
    - universal_certificate_survey_search(filter_by="issueDate:>=2024-01-01 && issueDate:<=2024-12-31")
    - universal_certificate_survey_search(filter_by="expiryDate:<2024-08-15 && currentStatus:IN WINDOW")

    **Complex Queries:**
    - universal_certificate_survey_search(query_by="issuingAuthority,certificateSurveyEquipmentName", q="DNV", filter_by="daysToExpiry:>30 && type:CERTIFICATE", sort_by="expiryDate:asc")

    **Expiry Management:**
    - universal_certificate_survey_search(filter_by="daysToExpiry:<=30 && currentStatus:IN WINDOW")
    - universal_certificate_survey_search(filter_by="daysToExpiry:<0 && currentStatus:EXPIRED")

    **Extended Certificates:**
    - universal_certificate_survey_search(filter_by="isExtended:true && type:CERTIFICATE")

    ## 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 advanced analytics, reporting, and compliance monitoring for vessel certificates and surveys.`,
        schema: {
            query_by: z.string().optional().describe("Comma-separated list of field names to search in for full-text search. Only use string fields that are useful for text-based queries. Available fields - vesselName, certificateSurveyEquipmentName, certificateNumber, issuingAuthority, type, currentStatus, dataSource"),
            q: z.string().default("*").describe("Search query string for full-text search. Use '*' for wildcard searches or specific terms. Example: 'safety equipment' or 'certificate*'"),
            filter_by: z.string().optional().describe("Filter conditions using Typesense syntax. Use field:value format with operators like :, :>, :<, :>=, :<=. Combine with && (AND) or || (OR). Example: 'currentStatus:IN ORDER && imo:9000000'"),
            sort_by: z.string().default("relevance").describe("Comma-separated list of fields with sort direction. Format: 'field:asc' or 'field:desc'. Example: 'expiryDate:desc,issueDate:asc'"),
            page: z.number().min(1).default(1).describe("Page number for pagination. Default: 1"),
            per_page: z.number().min(1).max(250).default(50).describe("Number of results per page"),
        }
    },
    get_fleet_dry_docking_status: {
        name: "get_fleet_dry_docking_status",
        description: "Use this tool to get the information on dry docking status of all vessels in the fleet",
        schema: {
            imo: z.number().describe("The IMO number of the fleet."),
        }
    },
    get_fleet_annual_survey_status: {
        name: "get_fleet_annual_survey_status",
        description: "Use this tool to get the information on annual survey status of all vessels in the fleet",
        schema: {
            imo: z.number().describe("The IMO number of the fleet."),
        }
    },
    get_fleet_ihm_certificate_status: {
        name: "get_fleet_ihm_certificate_status",
        description: "Use this tool to get the information on IHM Certificate status of all vessels in the fleet",
        schema: {
            imo: z.number().describe("The IMO number of the fleet."),
        }
    },
    get_fleet_lsa_ffa_certificate_status: {
        name: "get_fleet_lsa_ffa_certificate_status",
        description: "Use this tool to get the information on LSA/FFA Certificate status of all vessels in the fleet",
        schema: {
            imo: z.number().describe("The IMO number of the fleet."),
        }
    },
    export_fleet_surveys: {
        name: "export_fleet_surveys",
        description: "Export ALL survey and certificate records for an entire fleet in CSV format. This tool is ideal for comprehensive fleet-wide survey analysis, compliance reporting, and bulk data export. The fleet IMO should be obtained from another MCP server that handles fleet name lookups.",
        schema: {
            fleet_imo: z.number().describe("IMO number of the fleet or group"),
        }
    },
    get_vessel_survey_certificate_information: {
        name: "get_vessel_survey_certificate_information",
        description: `Retrieves vessel survey and certificate information organized by functional categories from MongoDB curated data.

      ### When to Use This Tool:
      - When users ask about vessel certificate status and compliance
      - For class society survey reports and upcoming survey schedules
      - When checking LSA/FFA equipment service status and requirements
      - For IHM (Inventory of Hazardous Materials) compliance tracking
      - When monitoring dry docking schedules and periodical surveys
      - For CoC (Conditions of Class) and class notes management
      - When generating compliance reports for regulatory authorities

      ### Data Freshness:
      - Data reflects latest information from class society websites
      - Real-time certificate status from ERP systems
      - Current survey schedules and compliance tracking
      - Updated equipment service records and maintenance status

      ### Certificate Categories & Available Certificates:

      **class_society_compliance:**
      - Q19: Class Survey Status Report (Latest downloadable reports from class website)
      - Q20: Status of Statutory Class Certificates (Current certificate validity status)
      - Q21: Status of Statutory Class Surveys (Due/overdue surveys in next 90 days)
      - Q22: Status of CoC/Notes/Memo (Conditions of Class and class notes)
      - Q23: Dry Docking Schedule (Next docking due dates and remaining days)
      - Q24: Next Periodical Survey (Annual/intermediate survey windows and timing)
      - Q25: CMS Items (Continuous Machinery Survey items status)

      **hazardous_materials_management:**
      - Q87: IHM Certificate Status (Certificate validity and expiration tracking)
      - Q88: IHM Maintenance Procedures (How IHM is maintained and managed)
      - Q89: IHM Records and Documents (Part 1 manual versions and revisions)
      - Q90: Outstanding IHM Tasks (Pending tasks and purchase orders)

      **safety_equipment_compliance:**
      - Q106: LSA/FFA Certificate Status (Life saving and fire fighting equipment status)
      - Q107: Flag LSA/FFA Requirements (Flag state specific requirements and circulars)
      - Q108: LSA/FFA Service History (Comprehensive equipment service records)

      **erp_certificate_tracking:**
      - Q115: ERP Certificate Management (Expired certificates in ShipPalm system)

      ### Usage Examples:
      - category='class_society_compliance', question_no=19 → Class Survey Status Report
      - category='safety_equipment_compliance', question_no=null → All LSA/FFA certificates
      - category='hazardous_materials_management' → All IHM certificates and procedures
      - category='erp_certificate_tracking' → All ERP certificate management

      ### Output Includes:
      - Certificate validity status with color-coded indicators
      - Survey schedules with remaining days and window periods
      - Equipment service history with due dates
      - Downloadable reports and documentation links
      - Compliance status summaries with action items
      - Detailed tables with filtering and sorting capabilities`,
        schema: {
            imo: z.number().describe("Vessel IMO number (7-digit unique identifier)"),
            category: z.enum(["class_society_compliance", "hazardous_materials_management", "safety_equipment_compliance", "erp_certificate_tracking"]).describe("Certificate category selector"),
            question_no: z.union([z.literal(19), z.literal(20), z.literal(21), z.literal(22), z.literal(23), z.literal(24), z.literal(25), z.literal(87), z.literal(88), z.literal(89), z.literal(90), z.literal(106), z.literal(107), z.literal(108), z.literal(115)]).optional().describe("Specific certificate within category (optional - if not provided, returns all certificates in category)"),
        }
    }
};