ms-analysis-reports-mcp-server/README.md

PMS analysis reports server handling maintenance reports, equipment analysis, compliance tracking, and performance metrics with ERP access for data extraction

# 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:

```bash
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:

```env
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:

```bash
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:
```bash
git clone https://github.com/syia-ai/pms_mcp_server.git
cd pms_mcp_server
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

4. Start the server:
```bash
npm start
```

## Development

For development with hot reload:
```bash
npm run dev
```

## Testing

Test the server with MCP Inspector:
```bash
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.