Squid Proxy Management

naftiko: "1.0.0-alpha1"

info:
  label: "Squid Proxy Management"
  description: >-
    Unified workflow capability for managing and monitoring a Squid caching proxy.
    Combines cache statistics, connection monitoring, configuration management,
    and operational commands into a single workflow interface for network administrators
    and DevOps engineers managing proxy infrastructure.
  tags:
    - Squid
    - Caching Proxy
    - HTTP Proxy
    - Network Administration
    - Cache Management
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SQUID_CACHEMGR_PASSWORD: SQUID_CACHEMGR_PASSWORD

capability:
  consumes:
    - import: squid-cache-manager
      location: ./shared/cache-manager.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: squid-proxy-management-api
      description: "Unified REST API for Squid proxy management and monitoring."
      resources:
        - path: /v1/cache/info
          name: cache-info
          description: "Cache information and general statistics"
          operations:
            - method: GET
              name: get-cache-info
              description: "Get general Squid cache information"
              call: "squid-cache-manager.get-cache-info"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/cache/counters
          name: cache-counters
          description: "Performance counters"
          operations:
            - method: GET
              name: get-cache-counters
              description: "Get detailed cache performance counters"
              call: "squid-cache-manager.get-cache-counters"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/cache/statistics/5min
          name: statistics-5min
          description: "5-minute rolling statistics"
          operations:
            - method: GET
              name: get-5min-statistics
              description: "Get 5-minute rolling cache statistics"
              call: "squid-cache-manager.get-5min-statistics"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/cache/statistics/60min
          name: statistics-60min
          description: "60-minute rolling statistics"
          operations:
            - method: GET
              name: get-60min-statistics
              description: "Get 60-minute rolling cache statistics"
              call: "squid-cache-manager.get-60min-statistics"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/cache/utilization
          name: cache-utilization
          description: "Cache utilization metrics"
          operations:
            - method: GET
              name: get-cache-utilization
              description: "Get cache utilization and capacity"
              call: "squid-cache-manager.get-cache-utilization"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/cache/memory
          name: memory
          description: "Memory usage statistics"
          operations:
            - method: GET
              name: get-memory-usage
              description: "Get memory allocation statistics"
              call: "squid-cache-manager.get-memory-usage"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/connections
          name: connections
          description: "Active connections"
          operations:
            - method: GET
              name: get-connections
              description: "Get all active connections"
              call: "squid-cache-manager.get-connections"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/requests
          name: active-requests
          description: "Active HTTP requests"
          operations:
            - method: GET
              name: get-active-requests
              description: "List active HTTP requests being processed"
              call: "squid-cache-manager.get-active-requests"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/config
          name: configuration
          description: "Cache configuration"
          operations:
            - method: GET
              name: get-cache-config
              description: "Get current Squid configuration"
              call: "squid-cache-manager.get-cache-config"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/acls
          name: acl-list
          description: "Access control lists"
          operations:
            - method: GET
              name: get-acl-list
              description: "Get all ACLs and their membership"
              call: "squid-cache-manager.get-acl-list"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/objects
          name: cached-objects
          description: "Cached objects"
          operations:
            - method: GET
              name: get-cache-objects
              description: "List cached objects"
              call: "squid-cache-manager.get-cache-objects"
              with:
                pattern: "rest.pattern"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/operations/reconfigure
          name: reconfigure
          description: "Reconfigure Squid"
          operations:
            - method: POST
              name: reconfigure-squid
              description: "Reload Squid configuration"
              call: "squid-cache-manager.reconfigure-squid"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/operations/rotate-logs
          name: rotate-logs
          description: "Rotate log files"
          operations:
            - method: POST
              name: rotate-log-files
              description: "Rotate Squid log files"
              call: "squid-cache-manager.rotate-log-files"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: squid-proxy-management-mcp
      transport: http
      description: "MCP server for AI-assisted Squid proxy management and troubleshooting."
      tools:
        - name: get-cache-info
          description: "Get general Squid cache information including version, uptime, and basic statistics"
          hints:
            readOnly: true
            idempotent: true
          call: "squid-cache-manager.get-cache-info"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-cache-counters
          description: "Get detailed Squid performance counters including hit rates and byte counts"
          hints:
            readOnly: true
            idempotent: true
          call: "squid-cache-manager.get-cache-counters"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-5min-statistics
          description: "Get 5-minute rolling averages for cache activity"
          hints:
            readOnly: true
            idempotent: true
          call: "squid-cache-manager.get-5min-statistics"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-60min-statistics
          description: "Get 60-minute rolling averages for cache activity"
          hints:
            readOnly: true
            idempotent: true
          call: "squid-cache-manager.get-60min-statistics"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-cache-utilization
          description: "Get current cache utilization, object count, and capacity"
          hints:
            readOnly: true
            idempotent: true
          call: "squid-cache-manager.get-cache-utilization"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-memory-usage
          description: "Get Squid memory pool and allocation statistics"
          hints:
            readOnly: true
            idempotent: true
          call: "squid-cache-manager.get-memory-usage"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-active-requests
          description: "List all currently active HTTP requests being processed by Squid"
          hints:
            readOnly: true
            idempotent: false
          call: "squid-cache-manager.get-active-requests"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-connections
          description: "Get all active client and server connections with state and bytes"
          hints:
            readOnly: true
            idempotent: false
          call: "squid-cache-manager.get-connections"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-cache-config
          description: "Get current Squid runtime configuration"
          hints:
            readOnly: true
            idempotent: true
          call: "squid-cache-manager.get-cache-config"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-acl-list
          description: "Get all defined Squid ACLs for access control auditing"
          hints:
            readOnly: true
            idempotent: true
          call: "squid-cache-manager.get-acl-list"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-cache-objects
          description: "List objects stored in the Squid cache with optional URL pattern filter"
          hints:
            readOnly: true
            idempotent: true
          call: "squid-cache-manager.get-cache-objects"
          with:
            pattern: "tools.pattern"
          outputParameters:
            - type: object
              mapping: "$."
        - name: reconfigure-squid
          description: "Trigger Squid to reload its configuration file without restart"
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "squid-cache-manager.reconfigure-squid"
          outputParameters:
            - type: object
              mapping: "$."
        - name: rotate-log-files
          description: "Trigger Squid log file rotation"
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "squid-cache-manager.rotate-log-files"
          outputParameters:
            - type: object
              mapping: "$."