npm package: @iflow-mcp/cdmx-in-itop-mcp
Description: Model Context Protocol server for iTop ITSM integration with advanced analytics (Node.js)
Author: Roney Dsilva
Latest version: 1.1.0

# @cdmx/itop-mcp

A Model Context Protocol (MCP) server for integrating with iTop ITSM (IT Service Management) systems. This is the Node.js/TypeScript implementation.

## 🚀 Features

- **Complete iTop API Integration**: All core iTop REST API operations
- **Enhanced Support Ticket Management**: Optimized for ITSM workflows with SLA tracking
- **Advanced Analytics**: PC status stats, change request analytics, SLA compliance reporting
- **TypeScript Support**: Full type safety and IntelliSense support
- **Comprehensive Testing**: Unit tests with Jest and TypeScript

## 📦 Installation

```bash
npm install @cdmx/itop-mcp
# or
yarn add @cdmx/itop-mcp
```

## 🔧 MCP Configuration

### Prerequisites

1. **iTop Instance**: Access to an iTop instance with REST API enabled
2. **iTop User Account**: User account with "REST Services User" profile
3. **Environment Variables**: Set the following environment variables:

```bash
export ITOP_BASE_URL="https://your-itop-instance.com"
export ITOP_USER="your-username"
export ITOP_PASSWORD="your-password"
export ITOP_VERSION="1.4"  # Optional, defaults to 1.4
```

### Claude Desktop Configuration

Add to your Claude Desktop configuration file:

```json
{
  "mcpServers": {
    "itop": {
      "command": "npx",
      "args": ["@cdmx/itop-mcp"],
      "env": {
        "ITOP_BASE_URL": "https://your-itop-instance.com",
        "ITOP_USER": "your-username",
        "ITOP_PASSWORD": "your-password",
        "ITOP_VERSION": "1.4"
      }
    }
  }
}
```

## 🧪 Development

### Setup

```bash
git clone https://github.com/roneydsilva/itop-mcp.git
cd itop-mcp/nodejs
npm install
```

### Scripts

```bash
# Development
npm run dev          # Run in development mode with hot reload
npm run build        # Build TypeScript to JavaScript
npm run start        # Start the built server

# Code Quality
npm run lint         # Run ESLint
npm run lint:fix     # Auto-fix ESLint issues
npm run type-check   # Run TypeScript type checking

# Testing
npm test             # Run tests
npm run test:watch   # Run tests in watch mode
```

### Environment Setup

Create a `.env` file in the nodejs directory:

```env
ITOP_BASE_URL=https://your-itop-instance.com
ITOP_USER=your-username
ITOP_PASSWORD=your-password
ITOP_VERSION=1.4
```

## 🎯 Available Tools

### Support Ticket Management
- `get_support_tickets`: Get support tickets with SLA tracking
- `get_pc_count`: Get count of PCs/computers
- `get_pc_status_stats`: Get status-based statistics for PCs
- `get_active_tickets_by_pc`: Get active tickets generated by PCs
- `get_tickets_with_null_service`: Get tickets with null service fields
- `get_tickets_sla_closure_stats`: Get SLA closure statistics

### Change Management
- `get_change_requests_completion_stats`: Get change request completion analytics
- `get_change_management_completion_stats`: Get ChangeManagement class analytics

### Core Operations
- `list_operations`: List all available iTop REST API operations
- `get_objects`: Search and retrieve iTop objects
- `check_credentials`: Verify iTop API credentials

## 📊 Analytics Features

### SLA Tracking
- ✅ **On Time**: SLA target met
- ❌ **Breached**: SLA target exceeded  
- ➖ **N/A**: SLA not applicable

### Output Formats
1. **detailed**: Full information with SLA status
2. **summary**: Condensed view with statistics
3. **table**: Tabular format for easy scanning

### Change Request Analytics
- Completion rates (on-time vs late)
- Status breakdown
- Category analysis

## 🧪 Testing

The package includes comprehensive test coverage:

```bash
# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run tests in watch mode
npm run test:watch
```

### Test Structure
- **Unit Tests**: Core functionality and API client
- **Integration Tests**: End-to-end workflow testing
- **Mock Tests**: API response handling

## 📝 Example Usage

Once configured, you can ask Claude:

```
"Show me PC count and status statistics"
"Get active tickets generated by PCs"
"Show change requests completion stats"
"Get tickets with null service fields"
"Show SLA closure statistics"
```

## 🔧 API Reference

### ITopClient Class

```typescript
class ITopClientImpl {
  constructor(baseUrl: string, username: string, password: string, version?: string)
  async makeRequest(operationData: Record<string, any>): Promise<ITopResponse>
}
```

### Support Ticket Configuration

```typescript
const SUPPORT_TICKET_FIELDS = {
  UserRequest: {
    defaultFields: "ref,title,status,start_date,close_date,sla_tto_passed,sla_ttr_passed",
    priorityFields: ["ref", "title", "status", "org_name", "caller_name", "agent_name"],
    slaFields: ["sla_tto_passed", "sla_ttr_passed", "sla_tto_deadline", "sla_ttr_deadline"],
    timeFields: ["start_date", "close_date", "last_update", "creation_date"]
  },
  // ... more configurations
}
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `npm test`
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.

## 🔗 Links

- **Repository**: https://github.com/roneydsilva/itop-mcp
- **npm Package**: https://www.npmjs.com/package/@cdmx/itop-mcp
- **Issues**: https://github.com/roneydsilva/itop-mcp/issues
- **Python Version**: https://pypi.org/project/itop-mcp/
- **iTop Documentation**: https://www.itophub.io/wiki/page?id=latest%3Aadvancedtopics%3Arest_json