USFA Fire Incident Data and Analysis

naftiko: "1.0.0-alpha1"

info:
  label: "USFA Fire Incident Data and Analysis"
  description: >-
    Capability for fire incident data research and emergency management
    analysis using the OpenFEMA API. Combines fire disaster declarations,
    FEMA dataset discovery, and summary-level emergency data to support
    fire safety researchers, emergency managers, and public safety analysts.
  tags:
    - Fire Safety
    - Emergency Management
    - Disaster Analysis
    - USFA
    - FEMA
    - Federal Government
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys: {}

capability:
  consumes:
    - import: openfema
      location: ./shared/openfema-fire-data.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: usfa-fire-data-api
      description: "Unified REST API for USFA fire incident data and emergency management analysis."
      resources:
        - path: /v1/datasets
          name: datasets
          description: "Discover available OpenFEMA datasets and their metadata"
          operations:
            - method: GET
              name: list-datasets
              description: "List all available OpenFEMA datasets"
              call: "openfema.list-datasets"
              with:
                $top: "rest.top"
                $select: "rest.select"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/datasets/fields
          name: dataset-fields
          description: "Get field-level data dictionary for a dataset"
          operations:
            - method: GET
              name: list-dataset-fields
              description: "Get field descriptions for a specific dataset"
              call: "openfema.list-dataset-fields"
              with:
                $filter: "rest.datasetName"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/fire-disasters
          name: fire-disasters
          description: "Fire-type FEMA disaster declarations"
          operations:
            - method: GET
              name: list-fire-disasters
              description: "List FEMA fire disaster declarations with optional filters"
              call: "openfema.get-disaster-declarations"
              with:
                $filter: "rest.filter"
                $top: "rest.top"
                $skip: "rest.skip"
                $orderby: "rest.orderby"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/disasters/summaries
          name: disaster-summaries
          description: "Summarized disaster declarations with program details"
          operations:
            - method: GET
              name: list-disaster-summaries
              description: "Get disaster declarations with authorized assistance programs"
              call: "openfema.get-disaster-summaries"
              with:
                $filter: "rest.filter"
                $top: "rest.top"
                $skip: "rest.skip"
                $orderby: "rest.orderby"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: usfa-fire-data-mcp
      transport: http
      description: "MCP server for AI-assisted fire safety research and emergency management analysis."
      tools:
        - name: list-openfema-datasets
          description: "List all available datasets on the OpenFEMA platform with descriptions and last update times"
          hints:
            readOnly: true
            idempotent: true
          call: "openfema.list-datasets"
          with:
            $top: "tools.top"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-dataset-fields
          description: "Get data dictionary and field descriptions for a specific OpenFEMA dataset"
          hints:
            readOnly: true
            idempotent: true
          call: "openfema.list-dataset-fields"
          with:
            $filter: "tools.dataset_name"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-fire-disaster-declarations
          description: "Retrieve FEMA fire disaster declarations filtered by state, date, or other criteria"
          hints:
            readOnly: true
            idempotent: true
          call: "openfema.get-disaster-declarations"
          with:
            $filter: "tools.filter"
            $top: "tools.top"
            $orderby: "tools.orderby"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-disaster-program-summaries
          description: "Get summarized disaster declarations showing which FEMA assistance programs were authorized"
          hints:
            readOnly: true
            idempotent: true
          call: "openfema.get-disaster-summaries"
          with:
            $filter: "tools.filter"
            $top: "tools.top"
            $count: "tools.include_count"
          outputParameters:
            - type: object
              mapping: "$."