iTop MCP Server

Um servidor MCP para interagir com sistemas iTop ITSM via sua API REST.

Documentação

Servidor iTop MCP

Um servidor Model Context Protocol (MCP) para integração com sistemas iTop ITSM (Gerenciamento de Serviços de TI). Este servidor fornece aos assistentes de IA a capacidade de interagir com o iTop por meio de sua API REST, permitindo operações como gerenciamento de chamados, gerenciamento de ICs (Itens de Configuração) e muito mais.

🚀 Recursos

O servidor iTop MCP fornece as seguintes ferramentas:

🧠 Processador de Consultas Inteligentes V2 (Nova Versão Aprimorada):

smart_query_v2: Processador revolucionário de consultas em linguagem natural com inteligência específica por classe
- Detecção Automática de Classe: Detecta inteligentemente a classe iTop alvo a partir da linguagem natural
- 12+ Manipuladores Especializados: Processadores dedicados para UserRequest, Ticket, Change, Incident, Problem, Server, PC, VirtualMachine, NetworkDevice, Person, Team, Organization
- Recursos Avançados de Consulta: Agrupamento, filtragem, análise de SLA, acompanhamento de prazos e detalhamentos estatísticos
- Mapeamento Inteligente de Campos: Aliases de campos amigáveis mapeados automaticamente para o esquema iTop
- Correspondência Difusa: Correspondência inteligente de nomes para servidores, pessoas e outras entidades
- Descoberta de Esquema em Tempo Real: Usa campos *+ para detecção automática de campos
- Formatação Aprimorada: Saída específica por classe com ícones, modos detalhado/resumido e resultados agrupados

Operações Principais do iTop:

list_operations: Lista todas as operações disponíveis da API REST do iTop
smart_query_v2: Processa consultas em linguagem natural com detecção inteligente de classe e manipuladores especializados

Suporte Legado (Obsoleto):

Nota: Versões anteriores incluíam ferramentas adicionais (get_objects, create_object, update_object, delete_object, apply_stimulus, get_related_objects, check_credentials) que foram simplificadas em favor da abordagem mais poderosa do smart_query_v2

Instalação

Opção 1: Instalar a partir do PyPI (Recomendado)

# Install from PyPI
pip install itop-mcp

# Or using uv
uv add itop-mcp

Implementação 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

🔧 Configuração do MCP

Pré-requisitos

Instância iTop: Acesso a uma instância iTop com API REST habilitada
Conta de Usuário iTop: Conta de usuário com perfil "REST Services User"

Variáveis de Ambiente: Defina as seguintes variáveis de ambiente:

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

Configuração do Claude Desktop

Adicione ao seu arquivo de configuração do Claude Desktop:

Para implementação 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 pacote 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 implementação 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"
      }
    }
  }
}

Outros Clientes MCP

Para outros clientes MCP, use configuração semelhante com o comando e as variáveis de ambiente apropriados.

🧠 Processador de Consultas Inteligentes V2

O Processador de Consultas Inteligentes V2 representa um grande avanço no processamento de consultas em linguagem natural para o iTop. Ele apresenta manipuladores específicos por classe que entendem as características e relacionamentos únicos dos diferentes tipos de objetos iTop.

Classes e Manipuladores Suportados

🎫 Gerenciamento de Chamados

UserRequest: Solicitações de serviço do usuário com acompanhamento de SLA
Ticket: Operações genéricas de chamados
Change: Chamados de gerenciamento de mudanças
Incident: Gerenciamento de incidentes
Problem: Gerenciamento de problemas

🖥️ Infraestrutura

Server: Servidores físicos com detalhes de hardware
PC: Computadores pessoais e estações de trabalho
VirtualMachine: Gerenciamento de máquinas virtuais
NetworkDevice: Equipamentos de rede (switches, roteadores, firewalls)

👥 Pessoas e Organização

Person: Contatos individuais e usuários
Team: Gerenciamento de equipes e atribuições
Organization: Estrutura organizacional

Recursos Principais

🎯 Detecção Automática de Classe

O sistema detecta inteligentemente qual classe iTop você 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

🔍 Recursos Avançados de Consulta

Agrupamento e Detalhamento: "Mostrar servidores agrupados por organização"
Análise de SLA: "Encontrar chamados com violações de SLA"
Filtragem por Status: "Listar servidores de produção"
Multicritério: "VMs críticas pertencentes à equipe de Banco de Dados"
Correspondência Difusa: Lida com erros de digitação e variações em nomes

📊 Formatação Aprimorada de Saída

Cada manipulador de classe fornece:

Ícones específicos por classe (🖥️ para servidores, 🎫 para chamados, etc.)
Seleção de campos relevantes com base no contexto da consulta
Resumos estatísticos para consultas de agrupamento
Modos detalhado vs. resumido com base no tipo de consulta
Metadados ricos incluindo filtros aplicados e detalhes da consulta

🔧 Mapeamento Inteligente de Campos

Termos amigáveis são mapeados automaticamente para o esquema iTop:

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

Exemplos de Consultas

Consultas de Infraestrutura

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

Gerenciamento de Chamados

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

Pessoas e Organização

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

Recursos Avançados

🎯 Modo de Foco em Software

Para consultas de infraestrutura, detecção automática de intenção relacionada a software:

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

📈 Análise Estatística

Agrupamento automático e detalhamentos estatí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

🔄 Suporte de Fallback

Manipulador genérico para classes sem implementações específicas
Detecção inteligente de campos para classes desconhecidas
Degradação graciosa com mensagens de erro úteis

🧪 Desenvolvimento e Testes

Executando Testes

# 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

Qualidade de Código

O projeto inclui linting e formatação abrangentes:

Black: Formatação de código
isort: Ordenação de imports
Flake8: Linting de código
mypy: Verificação de tipos (Python)
ESLint: Linting TypeScript (Node.js)

Testes ao Vivo

Defina variáveis de ambiente e execute testes ao vivo contra sua instância 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

🤝 Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça suas alterações
Execute os testes: python tests/run_tests.py
Envie um pull request

📋 Exemplo de Uso

Uma vez configurado, você pode perguntar ao Claude:

"Mostre-me todos os novos chamados de suporte com status de SLA"
"Obtenha solicitações de usuário que violaram o SLA"
"Liste incidentes por prioridade em formato de tabela"
"Encontre chamados atribuídos a João Silva"
"Crie uma nova solicitação de usuário para problemas de impressora"

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🔗 Links

Repositório: https://github.com/roneydsilva/itop-mcp
Pacote PyPI: https://pypi.org/project/itop-mcp/
Problemas: https://github.com/roneydsilva/itop-mcp/issues
Documentação do iTop: https://www.itophub.io/wiki/page?id=latest%3Aadvancedtopics%3Arest_json curl -LsSf https://astral.sh/uv/install.sh | sh

Clone e instale

git clone https://github.com/roneydsilva/itop-mcp.git cd itop-mcp uv sync

Configure iTop connection:
```
# Copy the example configuration
cp .env.example .env

# Edit the .env file with your iTop details
nano .env
```
Variáveis de ambiente necessárias:
- ITOP_BASE_URL: URL da sua instância iTop (ex.: https://itop.yourcompany.com)
- ITOP_USER: Nome de usuário com perfil REST Services User
- ITOP_PASSWORD: Senha do usuário
- ITOP_VERSION: Versão da API (opcional, padrão: 1.4)

Uso

Executando o Servidor

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

# Run the server
uv run main.py

Conectando ao Claude Desktop

Opção 1: Usando Instalação via PyPI

Para usar este servidor com o Claude Desktop, adicione o seguinte ao seu 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"
      }
    }
  }
}

Opção 2: Usando Instalação a partir do Código Fonte

{
  "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: Isso funciona porque configuramos itop-mcp como um ponto de entrada em pyproject.toml. Você precisa executar isso a partir do diretório do projeto onde pyproject.toml está localizado, ou o uv precisa conseguir encontrar o projeto.


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

Desenvolvimento

Para estender o servidor:

Adicione novas ferramentas criando funções decoradas com @mcp.tool()
Siga a documentação da API REST do iTop para operações disponíveis
Trate erros com elegância e forneça mensagens informativas
Teste minuciosamente em um ambiente de desenvolvimento
Use o processador de consultas inteligentes para prototipagem rápida e teste de novos tipos de consulta

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça suas alterações
Teste minuciosamente
Envie um pull request

Licença

Este projeto é de código aberto. Consulte o arquivo LICENSE para obter detalhes.