iTop MCP Server

Un servidor MCP para interactuar con sistemas iTop ITSM a través de su API REST.

GitHub
19

Documentación

iTop MCP Server

Un servidor de Model Context Protocol (MCP) para integrarse con sistemas iTop ITSM (IT Service Management). Este servidor proporciona a los asistentes de IA la capacidad de interactuar con iTop a través de su API REST, permitiendo operaciones como gestión de tickets, gestión de CI (Configuration Item) y más.

🚀 Características

El servidor iTop MCP proporciona las siguientes herramientas:

🧠 Smart Query Processor V2 (Nueva versión mejorada):

  • smart_query_v2: Procesador revolucionario de consultas en lenguaje natural con inteligencia específica por clase
    • Detección automática de clase: Detecta inteligentemente la clase iTop objetivo a partir del lenguaje natural
    • Más de 12 manejadores especializados: Procesadores dedicados para UserRequest, Ticket, Change, Incident, Problem, Server, PC, VirtualMachine, NetworkDevice, Person, Team, Organization
    • Funciones avanzadas de consulta: Agrupación, filtrado, análisis de SLA, seguimiento de plazos y desgloses estadísticos
    • Mapeo inteligente de campos: Alias de campos fáciles de usar mapeados automáticamente al esquema de iTop
    • Coincidencia difusa: Coincidencia inteligente de nombres para servidores, personas y otras entidades
    • Descubrimiento de esquema en tiempo real: Utiliza los campos *+ para la detección automática de campos
    • Formato mejorado: Salida específica por clase con iconos, modos detallado/resumen y resultados agrupados

Operaciones principales de iTop:

  • list_operations: Lista todas las operaciones disponibles de la API REST de iTop
  • smart_query_v2: Procesa consultas en lenguaje natural con detección inteligente de clase y manejadores especializados

Soporte heredado (obsoleto):

  • Nota: Las versiones anteriores incluían herramientas adicionales (get_objects, create_object, update_object, delete_object, apply_stimulus, get_related_objects, check_credentials) que se han simplificado en favor del enfoque más potente de smart_query_v2

Instalación

Opción 1: Instalar desde PyPI (Recomendado)

# Install from PyPI
pip install itop-mcp

# Or using uv
uv add itop-mcp

Implementación en Node.js

# Install from npm (coming soon)
npm install itop-mcp-nodejs

# Or clone and build locally
git clone https://github.com/roneydsilva/itop-mcp.git
cd itop-mcp/nodejs
npm install
npm run build

🔧 Configuración de MCP

Requisitos previos

  1. Instancia de iTop: Acceso a una instancia de iTop con la API REST habilitada
  2. Cuenta de usuario de iTop: Cuenta de usuario con el perfil "REST Services User"
  3. Variables de entorno: Establezca las siguientes variables de entorno: 
    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

Configuración de Claude Desktop

Añada a su archivo de configuración de Claude Desktop:

Para la implementación en Python:

{
  "mcpServers": {
    "itop": {
      "command": "python",
      "args": ["-m", "main"],
      "cwd": "/path/to/itop-mcp",
      "env": {
        "ITOP_BASE_URL": "https://your-itop-instance.com",
        "ITOP_USER": "your-username", 
        "ITOP_PASSWORD": "your-password",
        "ITOP_VERSION": "1.4"
      }
    }
  }
}

Para el paquete instalado:

{
  "mcpServers": {
    "itop": {
      "command": "itop-mcp",
      "env": {
        "ITOP_BASE_URL": "https://your-itop-instance.com",
        "ITOP_USER": "your-username",
        "ITOP_PASSWORD": "your-password", 
        "ITOP_VERSION": "1.4"
      }
    }
  }
}

Para la implementación en Node.js:

{
  "mcpServers": {
    "itop": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/itop-mcp/nodejs",
      "env": {
        "ITOP_BASE_URL": "https://your-itop-instance.com",
        "ITOP_USER": "your-username",
        "ITOP_PASSWORD": "your-password",
        "ITOP_VERSION": "1.4"
      }
    }
  }
}

Otros clientes MCP

Para otros clientes MCP, utilice una configuración similar con el comando y las variables de entorno adecuados.

🧠 Smart Query Processor V2

El Smart Query Processor V2 representa un gran avance en el procesamiento de consultas en lenguaje natural para iTop. Cuenta con manejadores específicos por clase que comprenden las características y relaciones únicas de los diferentes tipos de objetos de iTop.

Clases y manejadores compatibles

🎫 Gestión de tickets

  • UserRequest: Solicitudes de servicio de usuario con seguimiento de SLA
  • Ticket: Operaciones genéricas de tickets
  • Change: Tickets de gestión de cambios
  • Incident: Gestión de incidentes
  • Problem: Gestión de problemas

🖥️ Infraestructura

  • Server: Servidores físicos con detalles de hardware
  • PC: Computadoras personales y estaciones de trabajo
  • VirtualMachine: Gestión de máquinas virtuales
  • NetworkDevice: Equipos de red (switches, routers, firewalls)

👥 Personas y organización

  • Person: Contactos y usuarios individuales
  • Team: Gestión de equipos y asignaciones
  • Organization: Estructura organizativa

Características principales

🎯 Detección automática de clase

El sistema detecta inteligentemente qué clase de iTop está consultando:

"Show me all critical servers" → Detects: Server class
"List user requests from last week" → Detects: UserRequest class
"Find network switches in production" → Detects: NetworkDevice class

🔍 Capacidades avanzadas de consulta

  • Agrupación y desglose: "Muestra servidores agrupados por organización"
  • Análisis de SLA: "Encuentra tickets con incumplimientos de SLA"
  • Filtrado por estado: "Lista servidores de producción"
  • Multi-criterio: "VMs críticas propiedad del equipo de base de datos"
  • Coincidencia difusa: Maneja errores tipográficos y variaciones en los nombres

📊 Formato de salida mejorado

Cada manejador de clase proporciona:

  • Iconos específicos por clase (🖥️ para servidores, 🎫 para tickets, etc.)
  • Selección de campos relevantes según el contexto de la consulta
  • Resúmenes estadísticos para consultas de agrupación
  • Modos detallado vs resumen según el tipo de consulta
  • Metadatos enriquecidos que incluyen filtros aplicados y detalles de la consulta

🔧 Mapeo inteligente de campos

Los términos fáciles de usar se mapean automáticamente a los campos del esquema de iTop:

"organization" → "org_name"
"owner" → "owner_friendlyname"  
"critical" → "business_criticity = critical"
"production" → "status = production"

Consultas de ejemplo

Consultas de infraestructura

"Show all production servers"
"List critical VMs by organization" 
"Find network switches in Datacenter A"
"Count PCs by location"
"Show servers with Windows OS"

Gestión de tickets

"Show high priority user requests"
"List incidents created this week"
"Find changes scheduled for next month"
"Group tickets by status"
"Show SLA breached requests"

Personas y organización

"List active people in IT department"
"Show teams by organization"
"Find managers in Engineering"
"Count users by location"

Funciones avanzadas

🎯 Modo de enfoque de software

Para consultas de infraestructura, detección automática de intención relacionada con software:

"Show software on Server2" → Returns installed applications
"List applications on production servers" → Software-focused output

📈 Análisis estadístico

Agrupación automática y desgloses estadísticos:

"Servers by organization" → Groups servers and shows counts per org
"Ticket status breakdown" → Shows distribution across statuses
"SLA compliance by team" → Analyzes SLA performance by team

🔄 Soporte de respaldo

  • Manejador genérico para clases sin implementaciones específicas
  • Detección inteligente de campos para clases desconocidas
  • Degradación elegante con mensajes de error útiles

🧪 Desarrollo y pruebas

Ejecución de pruebas

# Run all tests
python tests/run_tests.py

# Run specific test types
python tests/run_tests.py --unit        # Unit tests only
python tests/run_tests.py --live        # Live tests only (requires iTop instance)
python tests/run_tests.py --nodejs      # Node.js tests only
python tests/run_tests.py --lint        # Linting only

# Auto-fix linting issues
python tests/run_tests.py --fix

Calidad del código

El proyecto incluye linting y formato exhaustivos:

  • Black: Formato de código
  • isort: Ordenación de importaciones
  • Flake8: Linting de código
  • mypy: Verificación de tipos (Python)
  • ESLint: Linting de TypeScript (Node.js)

Pruebas en vivo

Establezca las variables de entorno y ejecute pruebas en vivo contra su instancia de iTop:

export ITOP_BASE_URL="https://your-itop-instance.com"
export ITOP_USER="your-username"
export ITOP_PASSWORD="your-password"

python tests/test_live.py

🤝 Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios
  4. Ejecute las pruebas: python tests/run_tests.py
  5. Envíe un pull request

📋 Ejemplo de uso

Una vez configurado, puede preguntar a Claude:

  • "Muéstrame todos los tickets de soporte nuevos con estado de SLA"
  • "Obtén las solicitudes de usuario que han incumplido el SLA"
  • "Lista los incidentes por prioridad en formato de tabla"
  • "Encuentra tickets asignados a John Smith"
  • "Crea una nueva solicitud de usuario para problemas de impresora"

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para más detalles.

🔗 Enlaces

  1. Configure iTop connection:

    # Copy the example configuration
cp .env.example .env

# Edit the .env file with your iTop details
nano .env

    Variables de entorno requeridas:

    • ITOP_BASE_URL: La URL de su instancia de iTop (p. ej., https://itop.yourcompany.com)
    • ITOP_USER: Nombre de usuario con perfil REST Services User
    • ITOP_PASSWORD: Contraseña del usuario
    • ITOP_VERSION: Versión de la API (opcional, predeterminado: 1.4)

Uso

Ejecución del servidor

# Activate the virtual environment
source .venv/bin/activate

# Run the server
uv run main.py

Conexión a Claude Desktop

Opción 1: Usando la instalación desde PyPI

Para usar este servidor con Claude Desktop, añada lo siguiente a su claude_desktop_config.json:

{
  "mcpServers": {
    "itop": {
      "command": "itop-mcp",
      "env": {
        "ITOP_BASE_URL": "https://your-itop-instance.com",
        "ITOP_USER": "your_username",
        "ITOP_PASSWORD": "your_password"
      }
    }
  }
}

Opción 2: Usando la instalación desde el código fuente

{
  "mcpServers": {
    "itop": {
        "command": "uv",
        "args": [
            "run",
            "--directory",
            "/path/to/itop-mcp",
            "itop-mcp"
        ],
        "env": {
            "ITOP_BASE_URL": "https://your-itop-instance.com",
            "ITOP_USER": "your_username",
            "ITOP_PASSWORD": "your_password",
            "ITOP_VERSION": "1.3"
        }
    }
  }
}

Nota: Esto funciona porque hemos configurado itop-mcp como punto de entrada en pyproject.toml. Debe ejecutar esto desde el directorio del proyecto donde se encuentra pyproject.toml, o uv debe poder encontrar el proyecto.


### Example Operations

Once connected, you can ask your AI assistant to perform operations like:

**Basic Operations:**
- "List all open user requests in iTop"
- "Create a new incident ticket for server downtime"
- "Find all CIs related to the mail server"
- "Update the priority of ticket #123 to high"
- "Resolve ticket #456 with resolution details"

**Enhanced Queries:**
- "Get the latest 5 tickets created today"
- "Show me all tickets assigned to John Smith"
- "Find all tickets reported by Jane Doe"
- "Get detailed information for ticket R-000123"
- "List organizations containing 'Tech' in their name"

**Smart Ticket Creation:**
- "Create a new user request for printer issues reported by John from IT Department"

**AI-Powered Smart Queries:**
- "Get me PC count"
- "Give me status-based stats for the PCs"
- "Get me active tickets generated by PC-wise"
- "Change requests completed vs not completed on time"
- "Tickets closed vs not closed on time based on SLA"
- "List all servers in the production environment"
- "Show me all virtual machines running"

## iTop Class Examples

Common iTop classes you can work with:

- **UserRequest**: User requests/tickets
- **Incident**: Incident tickets
- **Person**: Users and contacts
- **Organization**: Organizations/companies
- **Server**: Server configuration items
- **Application**: Application configuration items
- **Service**: IT services
- **Contract**: Contracts and SLAs

## Advanced Features (Updated July 2025)

This server now supports advanced, AI-powered natural language queries and smart schema discovery. Key features include:

- **Smart Query Processor**: Use natural language to ask for any iTop data (e.g., "Show all virtual machines running", "List all servers in production", "Tickets closed vs not closed on time based on SLA").
- **Automatic Class & Field Detection**: The server dynamically discovers iTop classes and fields, so you don't need to hardcode field names.
- **Flexible Output**: Results can be formatted as tables, summaries, JSON, or detailed views.
- **SLA & Time Analysis**: Supports queries about SLA compliance, overdue tickets, and on-time completion.
- **Multi-Query Comparison**: Easily compare stats (e.g., closed vs not closed, completed on time vs not on time).
- **Relationship & Grouping**: Group results by status, organization, or any field, and link related objects (e.g., network devices with locations).
- **Extensible Tools**: Add new tools by decorating async functions with `@mcp.tool()`.

### Example Smart Queries

- "Get me PC count"
- "Give me status-based stats for the PCs"
- "Get me active tickets generated by PC-wise"
- "Change requests completed vs not completed on time"
- "Tickets closed vs not closed on time based on SLA"
- "List all servers in the production environment"
- "Show me all virtual machines running"

### How it Works

- The main server logic is in `main.py`.
- Uses a class taxonomy and dynamic schema discovery to map natural language to iTop REST API queries.
- Handles errors gracefully and provides suggestions if a query returns no results.
- Supports both simple and complex queries, including grouping, filtering, and comparisons.

---

## Security Notes

- Always use HTTPS for your iTop instance in production
- Store credentials securely (use environment variables, not hardcoded values)
- The user account should have minimal necessary permissions
- Test operations in a development environment first
- Use simulation mode for delete operations until you're confident

## Troubleshooting

### Common Issues

1. **Authentication errors**: Ensure your user has the "REST Services User" profile in iTop
2. **Connection errors**: Verify the ITOP_BASE_URL is correct and accessible
3. **Permission errors**: Check that the user has appropriate rights on the objects you're trying to access

### Testing the Connection

Use the `check_credentials` tool to verify your configuration:

```python
# The server will automatically test credentials on startup
# You can also ask the AI assistant: "Check my iTop credentials"

Desarrollo

Para ampliar el servidor:

  1. Añada nuevas herramientas creando funciones decoradas con @mcp.tool()
  2. Siga la documentación de la API REST de iTop para las operaciones disponibles
  3. Maneje los errores con elegancia y proporcione mensajes informativos
  4. Pruebe exhaustivamente en un entorno de desarrollo
  5. Utilice el procesador de consultas inteligente para la creación rápida de prototipos y pruebas de nuevos tipos de consultas

Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios
  4. Pruebe exhaustivamente
  5. Envíe un pull request

Licencia

Este proyecto es de código abierto. Consulte el archivo LICENSE para más detalles.

Referencias