# Maximo Job Plan Management via MCP

This project uses the Model Context Protocol (MCP) to interact with IBM Maximo for job plan management.

## Overview

The Maximo Job Plan MCP Server provides a seamless interface for AI assistants to interact with IBM Maximo's job plan management system. It enables natural language interactions for creating, querying, updating, and deleting job plans.

## Features

- **Import Job Plans**: Bulk import job plans from CSV files
- **List Job Plans**: Query and filter job plans with OSLC queries
- **Get Job Plan Details**: Retrieve detailed information about specific job plans
- **Delete Job Plans**: Remove job plans from the system
- **Natural Language Interface**: Use conversational commands through AI assistants

## Available MCP Tools

The `maximo-jobplan` MCP server provides 4 tools for managing job plans:

### 1. import_jobplans
Import job plans from CSV data into Maximo.

**Example usage:**
```
"Import job plans from jobplanMaximo.csv"
```

**CSV Format:**
```csv
JPNUM,DESCRIPTION,JPDURATION,STATUS,JOBTYPE,PLUSCJPREVNUM
HVAC-PM-001,Quarterly HVAC System Inspection,4.0,ACTIVE,PM,0
```

### 2. list_jobplans
List all job plans from Maximo with optional filtering.

**Example usage:**
```
"List all job plans"
"Show me HVAC job plans"
```

### 3. get_jobplan
Get detailed information about a specific job plan.

**Example usage:**
```
"Get details of job plan HVAC-PM-001"
"Show me the BREAKINSP job plan"
```

### 4. delete_jobplan
Delete a job plan by number.

**Example usage:**
```
"Delete job plan TEST-001"
```

## Installation

### Prerequisites

- Node.js 18 or higher
- npm or yarn
- Access to IBM Maximo instance
- Maximo API key

### Setup Steps

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd maximo-jobplan-mcp
   ```

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

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

4. **Configure environment variables**
   
   Set the following environment variables:
   - `MAXIMO_BASE_URL`: Your Maximo instance URL (e.g., `https://your-maximo-instance.com`)
   - `MAXIMO_API_KEY`: Your Maximo API key

5. **Configure MCP Client**

   For Bob/Claude Desktop, add to your MCP settings:
   ```json
   {
     "mcpServers": {
       "maximo-jobplan": {
         "command": "node",
         "args": ["C:/path/to/maximo-jobplan-server/build/index.js"],
         "env": {
           "MAXIMO_BASE_URL": "https://your-maximo-instance.com",
           "MAXIMO_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   ```

## Project Structure

```
maximo-jobplan-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── build/                # Compiled JavaScript output
├── docs/                 # Documentation files
│   ├── MCP_SETUP_GUIDE.md
│   ├── QUICK_START.md
│   └── README_MAXIMO_CONNECTION.md
├── examples/
│   └── jobplanMaximo.csv # Sample job plans
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md
```

## Usage Examples

### Using with AI Assistants

Simply use natural language commands:

- "List all job plans in Maximo"
- "Show me details of HVAC-PM-001"
- "Import the job plans from the CSV file"
- "Get all PUMP job plans"
- "Delete job plan TEST-001"

### Programmatic Usage

```typescript
// The MCP server handles all interactions through the protocol
// No direct API calls needed when using with MCP clients
```

## Configuration

### Maximo Connection

The server connects to Maximo using:
- **Base URL**: Configured via `MAXIMO_BASE_URL` environment variable
- **Authentication**: API key via `MAXIMO_API_KEY` environment variable
- **API Endpoint**: `/maximo/api/os/MXAPIJOBPLAN`

### CSV Import Format

Job plans CSV must include these columns:
- `JPNUM`: Job plan number (max 12 characters)
- `DESCRIPTION`: Job plan description
- `JPDURATION`: Duration in hours
- `STATUS`: Status (e.g., ACTIVE, INACTIVE)
- `JOBTYPE`: Job type (e.g., PM, CM)
- `PLUSCJPREVNUM`: Revision number

## Development

### Build Commands

```bash
# Build the project
npm run build

# Watch mode for development
npm run watch

# Prepare for distribution
npm run prepare
```

### Testing

Test the MCP server connection:
```bash
node build/index.js
```

## Troubleshooting

### Connection Issues

1. **Verify environment variables** are set correctly
2. **Check Maximo URL** is accessible
3. **Validate API key** has proper permissions
4. **Review SSL certificates** (development mode disables SSL verification)

### Import Failures

1. **Check CSV format** matches required columns
2. **Verify job plan numbers** are 12 characters or less
3. **Ensure required fields** are populated
4. **Check for duplicate** job plan numbers

## Security Considerations

⚠️ **Important Security Notes**:

1. **SSL Verification**: Currently disabled for development. Enable for production:
   ```typescript
   httpsAgent: new https.Agent({
     rejectUnauthorized: true  // Enable SSL verification
   })
   ```

2. **API Key Storage**: Store API keys securely using:
   - Environment variables
   - Secret management systems
   - Encrypted configuration files

3. **Access Control**: Ensure only authorized users can access the MCP server


## License

MIT License - See LICENSE file for details