naftiko: 1.0.0-alpha2
info:
  label: Spiceworks IT Management
  description: Workflow capability for IT professionals using Spiceworks to manage help desk ticketing, device inventory,
    and user administration. Combines ticket lifecycle management with device inventory lookup for unified IT operations workflows.
    Suitable for IT managers, technicians, and help desk administrators who need to correlate support requests with asset
    information.
  tags:
  - Spiceworks
  - Help Desk
  - IT Management
  - Ticketing
  - Inventory
  - IT Operations
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    SPICEWORKS_OAUTH_TOKEN: SPICEWORKS_OAUTH_TOKEN
capability:
  consumes:
  - type: http
    namespace: spiceworks
    baseUri: https://community.spiceworks.com
    description: Spiceworks Cloud Apps REST API for IT management and Help Desk
    authentication:
      type: bearer
      token: '{{SPICEWORKS_OAUTH_TOKEN}}'
    resources:
    - name: tickets
      path: /api/v1/tickets
      description: Help Desk ticket management
      operations:
      - name: list-tickets
        method: GET
        description: Retrieve a list of Help Desk tickets
        inputParameters:
        - name: status
          in: query
          type: string
          required: false
          description: Filter tickets by status (open, closed, in_progress)
        - name: assigned_to
          in: query
          type: integer
          required: false
          description: Filter by assigned technician ID
        - name: page
          in: query
          type: integer
          required: false
          description: Page number for pagination
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-ticket
        method: POST
        description: Create a new Help Desk ticket
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            summary: '{{tools.summary}}'
            description: '{{tools.description}}'
            priority: '{{tools.priority}}'
    - name: ticket
      path: /api/v1/tickets/{id}
      description: Individual Help Desk ticket operations
      operations:
      - name: get-ticket
        method: GET
        description: Retrieve full details of a specific ticket
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: The ticket ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: update-ticket
        method: PUT
        description: Update an existing Help Desk ticket
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: The ticket ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            status: '{{tools.status}}'
            priority: '{{tools.priority}}'
            assignee_id: '{{tools.assignee_id}}'
    - name: ticket-comments
      path: /api/v1/tickets/{ticket_id}/comments
      description: Ticket comment management
      operations:
      - name: list-comments
        method: GET
        description: Retrieve all comments for a ticket
        inputParameters:
        - name: ticket_id
          in: path
          type: integer
          required: true
          description: The ticket ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: add-comment
        method: POST
        description: Add a comment to a ticket
        inputParameters:
        - name: ticket_id
          in: path
          type: integer
          required: true
          description: The ticket ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            body: '{{tools.body}}'
            is_public: '{{tools.is_public}}'
    - name: devices
      path: /api/v1/devices
      description: IT device inventory management
      operations:
      - name: list-devices
        method: GET
        description: Retrieve a list of managed IT devices
        inputParameters:
        - name: type
          in: query
          type: string
          required: false
          description: Filter by device type
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: device
      path: /api/v1/devices/{id}
      description: Individual device inventory operations
      operations:
      - name: get-device
        method: GET
        description: Retrieve details of a specific device
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: The device ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users
      path: /api/v1/users
      description: User and technician management
      operations:
      - name: list-users
        method: GET
        description: Retrieve a list of platform users
        inputParameters:
        - name: role
          in: query
          type: string
          required: false
          description: Filter by user role
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: user
      path: /api/v1/users/{id}
      description: Individual user profile operations
      operations:
      - name: get-user
        method: GET
        description: Retrieve a specific user profile
        inputParameters:
        - name: id
          in: path
          type: integer
          required: true
          description: The user ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: spiceworks-it-management-api
    description: Unified REST API for Spiceworks IT management workflows.
    resources:
    - path: /v1/tickets
      name: tickets
      description: Help Desk ticket management
      operations:
      - method: GET
        name: list-tickets
        description: List all Help Desk tickets
        call: spiceworks.list-tickets
        with:
          status: rest.status
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: create-ticket
        description: Create a new Help Desk ticket
        call: spiceworks.create-ticket
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tickets/{id}
      name: ticket
      description: Individual ticket operations
      operations:
      - method: GET
        name: get-ticket
        description: Get full ticket details including comments
        call: spiceworks.get-ticket
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: update-ticket
        description: Update ticket status, priority, or assignee
        call: spiceworks.update-ticket
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tickets/{id}/comments
      name: ticket-comments
      description: Ticket comment management
      operations:
      - method: GET
        name: list-comments
        description: List all comments on a ticket
        call: spiceworks.list-comments
        with:
          ticket_id: rest.id
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: add-comment
        description: Add a comment to a ticket
        call: spiceworks.add-comment
        with:
          ticket_id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/devices
      name: devices
      description: IT device inventory
      operations:
      - method: GET
        name: list-devices
        description: List all managed IT devices
        call: spiceworks.list-devices
        with:
          type: rest.type
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/devices/{id}
      name: device
      description: Individual device details
      operations:
      - method: GET
        name: get-device
        description: Get device hardware, software, and network details
        call: spiceworks.get-device
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users
      name: users
      description: User and technician management
      operations:
      - method: GET
        name: list-users
        description: List platform users and technicians
        call: spiceworks.list-users
        with:
          role: rest.role
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: spiceworks-it-management-mcp
    transport: http
    description: MCP server for AI-assisted IT help desk and inventory management.
    tools:
    - name: list-tickets
      description: List Help Desk tickets, optionally filtered by status or assignee
      hints:
        readOnly: true
        openWorld: true
      call: spiceworks.list-tickets
      outputParameters:
      - type: object
        mapping: $.
    - name: get-ticket
      description: Get full details of a Help Desk ticket including all comments
      hints:
        readOnly: true
      call: spiceworks.get-ticket
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: create-ticket
      description: Create a new Help Desk support ticket
      hints:
        readOnly: false
      call: spiceworks.create-ticket
      outputParameters:
      - type: object
        mapping: $.
    - name: update-ticket
      description: Update ticket status, priority, or assignee
      hints:
        readOnly: false
        idempotent: true
      call: spiceworks.update-ticket
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: add-ticket-comment
      description: Add a public or internal comment to a Help Desk ticket
      hints:
        readOnly: false
      call: spiceworks.add-comment
      with:
        ticket_id: tools.ticket_id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-devices
      description: List all managed IT devices from the Spiceworks inventory
      hints:
        readOnly: true
        openWorld: true
      call: spiceworks.list-devices
      outputParameters:
      - type: object
        mapping: $.
    - name: get-device
      description: Get hardware specs, software inventory, and network details for a device
      hints:
        readOnly: true
      call: spiceworks.get-device
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-users
      description: List Spiceworks users and technicians
      hints:
        readOnly: true
        openWorld: true
      call: spiceworks.list-users
      outputParameters:
      - type: object
        mapping: $.