S&P Global Financial Data Analytics

naftiko: "1.0.0-alpha1"

info:
  label: "S&P Global Financial Data Analytics"
  description: "Unified financial data analytics workflow combining S&P Global Commodity Insights market data with Kensho entity resolution. Used by financial analysts, quant teams, energy traders, and data scientists to integrate commodity pricing with entity identification across S&P Global data assets."
  tags:
    - S&P Global
    - Financial Data
    - Commodity Insights
    - Entity Resolution
    - Market Data
    - Analytics
    - Trading
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SPG_CI_ACCESS_TOKEN: SPG_CI_ACCESS_TOKEN
      KENSHO_LINK_TOKEN: KENSHO_LINK_TOKEN

capability:
  consumes:
    - import: spg-commodity-insights
      location: ./shared/commodity-insights.yaml
    - import: kensho-link
      location: ./shared/kensho-link.yaml

  exposes:
    - type: rest
      port: 8081
      namespace: financial-data-analytics-api
      description: "Unified REST API for S&P Global financial data analytics combining commodity market data and entity resolution."
      resources:
        - path: /v1/prices/current
          name: current-prices
          description: "Current commodity price assessments"
          operations:
            - method: GET
              name: get-current-prices
              description: "Get current price assessments for specified commodity symbols"
              call: "spg-commodity-insights.get-current-market-data"
              with:
                symbol: "rest.symbol"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/prices/history
          name: price-history
          description: "Historical commodity price assessments"
          operations:
            - method: GET
              name: get-price-history
              description: "Get historical price assessments over a date range"
              call: "spg-commodity-insights.get-historical-market-data"
              with:
                symbol: "rest.symbol"
                startDate: "rest.startDate"
                endDate: "rest.endDate"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/symbols
          name: symbols
          description: "Commodity symbol reference data"
          operations:
            - method: GET
              name: list-symbols
              description: "List available commodity symbols"
              call: "spg-commodity-insights.list-symbols"
              with:
                commodityName: "rest.commodityName"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/entities/link
          name: entity-link
          description: "Entity resolution and linking"
          operations:
            - method: POST
              name: link-entity
              description: "Resolve entity mentions to canonical KEIDs"
              call: "kensho-link.link-entity"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/entities/{keid}
          name: entity
          description: "Canonical entity record"
          operations:
            - method: GET
              name: get-entity
              description: "Get entity record by KEID with cross-references"
              call: "kensho-link.get-entity"
              with:
                keid: "rest.keid"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/entities/search
          name: entity-search
          description: "Entity search by name or identifier"
          operations:
            - method: GET
              name: search-entities
              description: "Search for financial entities"
              call: "kensho-link.search-entities"
              with:
                q: "rest.q"
                entityType: "rest.entityType"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9091
      namespace: financial-data-analytics-mcp
      transport: http
      description: "MCP server for AI-assisted financial data analysis combining commodity pricing and entity intelligence."
      tools:
        - name: get-current-commodity-prices
          description: "Get the latest price assessments for Platts commodity symbols (e.g., PCAAS00 for Dated Brent crude oil). Returns current value, unit of measure, currency, and assessment date."
          hints:
            readOnly: true
            openWorld: false
          call: "spg-commodity-insights.get-current-market-data"
          with:
            symbol: "tools.symbol"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-historical-commodity-prices
          description: "Get historical commodity price assessments for a date range. Use for time series analysis, backtesting, and trend analysis in energy and commodity markets."
          hints:
            readOnly: true
            openWorld: false
          call: "spg-commodity-insights.get-historical-market-data"
          with:
            symbol: "tools.symbol"
            startDate: "tools.startDate"
            endDate: "tools.endDate"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-commodity-symbols
          description: "List available Platts commodity symbols with descriptions, units, and assessment frequency. Filter by commodity name (Crude Oil, Natural Gas, LNG, etc.)."
          hints:
            readOnly: true
            openWorld: false
          call: "spg-commodity-insights.list-symbols"
          with:
            commodityName: "tools.commodityName"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-modified-commodity-symbols
          description: "Get list of commodity symbols with updated price assessments since a given date. Use for incremental data sync."
          hints:
            readOnly: true
            openWorld: false
          call: "spg-commodity-insights.get-modified-symbols"
          with:
            modifiedDate: "tools.modifiedDate"
          outputParameters:
            - type: object
              mapping: "$."
        - name: link-financial-entity
          description: "Resolve a financial entity mention (company name, ticker, CUSIP, ISIN) to its canonical Kensho Entity Identifier (KEID) with confidence scores and cross-references."
          hints:
            readOnly: true
            openWorld: false
          call: "kensho-link.link-entity"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-entity-by-keid
          description: "Get the full canonical entity record for a KEID including aliases, cross-references (ticker, CUSIP, ISIN, LEI, S&P Global Company ID)."
          hints:
            readOnly: true
            openWorld: false
          call: "kensho-link.get-entity"
          with:
            keid: "tools.keid"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-financial-entities
          description: "Search for financial entities (companies, instruments, funds, indices) by name or identifier. Returns ranked candidates with confidence scores."
          hints:
            readOnly: true
            openWorld: false
          call: "kensho-link.search-entities"
          with:
            q: "tools.q"
            entityType: "tools.entityType"
          outputParameters:
            - type: object
              mapping: "$."