PMS Analysis Reports MCP Server

A Model Context Protocol (MCP) server for Planned Maintenance System (PMS) analysis reports, maintenance tracking, compliance monitoring, and performance analytics.

Features

• Search PMS Analysis Reports: Universal search tool for maintenance records, compliance data, and performance metrics
• AI-Powered Analysis: Generate comprehensive maintenance analysis reports with AI insights
• Equipment Status Tracking: Monitor equipment status and maintenance schedules
• Compliance Monitoring: Track compliance requirements and status
• Performance Analytics: Analyze equipment performance and maintenance trends
• Document parsing and processing
• Casefile management
• Typesense integration for search
• MongoDB integration for data storage

Prerequisites

• Node.js (v18 or higher)
• MongoDB
• Typesense
• OpenAI API key
• LlamaParse API key
• Perplexity API key

Configuration

You can configure the server in three ways:

1. Environment-Specific Configuration Files

The server now supports environment-specific configuration files. Create a file named .env.{environment} where {environment} matches your NODE_ENV value:

.env.development  # Used when NODE_ENV=development (default)
.env.production   # Used when NODE_ENV=production
.env.staging      # Used when NODE_ENV=staging
.env              # Fallback if no environment-specific file is found

To use a specific environment:

NODE_ENV=production node dist/index.js

See the env.production.example file for a template of production environment variables.

2. Environment Variables (.env file)

Create a .env file in the root directory:

MONGO_URI=mongodb://localhost:27017
DB_NAME=mcp_pms
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=your_typesense_api_key
OPENAI_API_KEY=your_openai_api_key
LLAMA_API_KEY=your_llama_api_key
VENDOR_MODEL=gpt-4
S3_API_TOKEN=your_s3_api_token
S3_GENERATE_HTML_URL=your_s3_generate_html_url
LLAMA_PARSE_URL=your_llama_parse_url
PERPLEXITY_API_KEY=your_perplexity_api_key
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=your_google_redirect_uri
GOOGLE_API_KEY=your_google_api_key
GOOGLE_SEARCH_ENGINE_ID=your_google_search_engine_id
COHERE_API_KEY=your_cohere_api_key
COMPANY_NAME=your_company_name
# API Configuration
SNAPSHOT_URL=https://dev-api.siya.com/v1.0/vessel-info/qna-snapshot
JWT_TOKEN=your_jwt_token_here

3. Command Line Arguments

Command line arguments will override values from the .env file:

node dist/index.js \
  --mongo-uri mongodb://localhost:27017 \
  --db-name mcp_pms \
  --typesense-host localhost \
  --typesense-port 8108 \
  --typesense-protocol http \
  --typesense-api-key your_api_key \
  --openai-api-key your_openai_key \
  --llama-api-key your_llama_key \
  --vendor-model gpt-4 \
  --s3-api-token your_s3_token \
  --perplexity-api-key your_perplexity_key \
  --company-name your_company_name

Available Command Line Arguments

| Argument | Environment Variable | Default | Description | |----------|---------------------|---------|-------------| | --mongo-uri | MONGO_URI | mongodb://localhost:27017 | MongoDB connection URI | | --db-name | DB_NAME | mcp_pms | MongoDB database name | | --typesense-host | TYPESENSE_HOST | localhost | Typesense server host | | --typesense-port | TYPESENSE_PORT | 8108 | Typesense server port | | --typesense-protocol | TYPESENSE_PROTOCOL | http | Typesense protocol (http/https) | | --typesense-api-key | TYPESENSE_API_KEY | (empty) | Typesense API key | | --openai-api-key | OPENAI_API_KEY | (empty) | OpenAI API key | | --llama-api-key | LLAMA_API_KEY | (empty) | LlamaParse API key | | --vendor-model | VENDOR_MODEL | gpt-4 | Default LLM model | | --s3-api-token | S3_API_TOKEN | (empty) | S3 API token | | --s3-generate-html-url | S3_GENERATE_HTML_URL | (empty) | S3 HTML generation URL | | --llama-parse-url | LLAMA_PARSE_URL | (empty) | LlamaParse service URL | | --perplexity-api-key | PERPLEXITY_API_KEY | (empty) | Perplexity API key | | --google-client-id | GOOGLE_CLIENT_ID | (empty) | Google OAuth client ID | | --google-client-secret | GOOGLE_CLIENT_SECRET | (empty) | Google OAuth client secret | | --google-redirect-uri | GOOGLE_REDIRECT_URI | (empty) | Google OAuth redirect URI | | --google-api-key | GOOGLE_API_KEY | (empty) | Google API key | | --google-search-engine-id | GOOGLE_SEARCH_ENGINE_ID | (empty) | Google Custom Search Engine ID | | --cohere-api-key | COHERE_API_KEY | (empty) | Cohere API key | | --company-name | COMPANY_NAME | (required) | Company name (mandatory) | | --snapshot-url | SNAPSHOT_URL | https://dev-api.siya.com/v1.0/vessel-info/qna-snapshot | API endpoint for vessel QnA snapshots | | --jwt-token | JWT_TOKEN | (default dev token) | JWT token for API authentication |

Installation

1. Clone the repository:

git clone https://github.com/syia-ai/pms_mcp_server.git
cd pms_mcp_server

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Start the server:

npm start

Development

For development with hot reload:

npm run dev

Testing

Test the server with MCP Inspector:

npm test

MCP Tools and Resources

PMS Analysis Tools

• search_pms_analysis_reports: Universal search tool for PMS analysis reports, maintenance records, compliance data, and performance metrics
• generate_maintenance_analysis_report: Generate comprehensive maintenance analysis reports using AI-powered insights

Document Tools

• parse_document_link: Parse documents from URLs or local files
• write_casefile_data: Create and update casefiles
• retrieve_casefile_data: Search and retrieve casefiles

Search Tools

• google_search: Perform Google searches
• smart_pms_table_search: Advanced PMS maintenance search with filters
• smart_equipment_search: Advanced equipment search with filters
• smart_compliance_search: Advanced compliance search with filters
• vessel_info_search: Search for vessel information
• mongodb_find: Direct MongoDB queries

Maintenance Management Tools

• get_all_vessel_maintenance_records: Get vessel maintenance records
• get_equipment_status_data: Retrieve equipment status information
• get_complete_vessel_pms_data: Get comprehensive vessel PMS information
• get_maintenance_task_details: Get detailed maintenance task information
• get_equipment_inspection_details: Get detailed equipment inspection information
• list_maintenance_tasks_by_status: List maintenance tasks filtered by status
• list_equipment_inspections_by_status: List equipment inspections by status
• list_overdue_maintenance_tasks: Find overdue maintenance tasks
• list_recent_vessel_maintenance_activities: Get recent vessel maintenance activities
• list_top_equipment_by_category: Get top equipment by category

Equipment & Vendor Tools

• find_relevant_equipment_vendors: Search for equipment vendors by name, service, or location
• get_equipment_vendor_contact_details: Retrieve equipment vendor contact information

Project Structure

src/
├── tools/
│   ├── handlers/
│   │   ├── pmsTools.ts        # PMS analysis and maintenance management
│   │   ├── equipmentTools.ts  # Equipment status and inspection management
│   │   ├── complianceTools.ts # Compliance tracking and reporting
│   │   ├── exportTools.ts     # Data export functionality
│   │   └── universalTools.ts  # Universal search and utility tools
│   ├── schema.ts          # Tool schema definitions
│   └── index.ts          # Main tool handler
├── config/
│   └── index.ts          # Configuration management
├── types/
│   └── index.ts          # TypeScript type definitions
├── prompts/
│   └── index.ts          # Prompt management
├── resources/
│   └── index.ts          # Resource management
└── index.ts              # Main application entry point

Key Features

PMS Analysis

• Search and analyze maintenance records
• Generate AI-powered maintenance reports
• Monitor equipment status and compliance
• Track performance metrics and trends

Document Processing

• Parse documents from URLs or local files
• Generate markdown and JSON outputs
• Support for various document formats

Casefile Management

• Create and update casefiles
• Track casefile status and importance
• Manage casefile pages and indexes
• Generate casefile URLs

Maintenance Data

• Track maintenance tasks and schedules
• Monitor equipment performance and status
• Manage maintenance budgets and costs
• Link maintenance data to vessels by IMO

Search Integration

• Full-text search using Typesense
• Vector search for semantic matching
• Filtering and pagination support

Error Handling

The application implements comprehensive error handling:

• Input validation
• Database operation error handling
• API integration error handling
• Proper error logging
• User-friendly error messages

Logging

Logging is implemented using Winston that:

• Logs to console with timestamps
• Includes different log levels (debug, info, error)
• Provides detailed error information
• Supports structured logging

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.