naftiko: 1.0.0-alpha2
info:
  label: RunSignup Race Event Management
  description: Comprehensive race event management capability for RunSignup. Enables race directors, timing companies, and
    integration partners to discover races, manage participant registrations, retrieve bib/chip assignments, submit and retrieve
    race results, manage divisions and teams, and access fundraising data. Covers the full lifecycle from race discovery through
    results publication.
  tags:
  - RunSignup
  - Race Registration
  - Event Management
  - Running
  - Sports
  - Timing
  - Results
  - Fundraising
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    RUNSIGNUP_API_KEY: RUNSIGNUP_API_KEY
    RUNSIGNUP_API_SECRET: RUNSIGNUP_API_SECRET
capability:
  consumes:
  - type: http
    namespace: runsignup
    baseUri: https://runsignup.com/Rest
    description: RunSignup REST API for race event management
    authentication:
      type: apikey
      key: api_key
      value: '{{env.RUNSIGNUP_API_KEY}}'
      placement: query
    resources:
    - name: races
      path: /races
      description: Search and list races
      operations:
      - name: get-races
        method: GET
        description: List upcoming races
        inputParameters:
        - name: api_secret
          in: query
          type: string
          required: true
          description: API secret
        - name: format
          in: query
          type: string
          required: false
          description: Response format (json/xml)
        - name: search_term
          in: query
          type: string
          required: false
          description: Search by race name
        - name: state
          in: query
          type: string
          required: false
          description: Filter by state
        - name: results_per_page
          in: query
          type: integer
          required: false
          description: Results per page (max 1000)
        - name: events
          in: query
          type: string
          required: false
          description: Include events (T/F)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: race
      path: /race/{race_id}
      description: Get detailed race information
      operations:
      - name: get-race
        method: GET
        description: Get race details by ID
        inputParameters:
        - name: race_id
          in: path
          type: integer
          required: true
          description: Race ID
        - name: api_secret
          in: query
          type: string
          required: true
          description: API secret
        - name: format
          in: query
          type: string
          required: false
          description: Response format
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: participants
      path: /race/{race_id}/participants
      description: Manage race participants
      operations:
      - name: get-participants
        method: GET
        description: Get registered participants for a race
        inputParameters:
        - name: race_id
          in: path
          type: integer
          required: true
          description: Race ID
        - name: api_secret
          in: query
          type: string
          required: true
          description: API secret
        - name: event_id
          in: query
          type: integer
          required: false
          description: Filter by event ID
        - name: results_per_page
          in: query
          type: integer
          required: false
          description: Results per page
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: bib-chip
      path: /race/{race_id}/get-bib-chip
      description: Get bib and chip assignments
      operations:
      - name: get-bib-chip
        method: GET
        description: Get bib number and chip assignments for a race event
        inputParameters:
        - name: race_id
          in: path
          type: integer
          required: true
          description: Race ID
        - name: api_secret
          in: query
          type: string
          required: true
          description: API secret
        - name: event_id
          in: query
          type: integer
          required: false
          description: Event ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: results
      path: /race/{race_id}/results/get-results
      description: Retrieve race results
      operations:
      - name: get-results
        method: GET
        description: Get all results for a race
        inputParameters:
        - name: race_id
          in: path
          type: integer
          required: true
          description: Race ID
        - name: api_secret
          in: query
          type: string
          required: true
          description: API secret
        - name: event_id
          in: query
          type: integer
          required: false
          description: Filter by event ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: post-results
      path: /race/{race_id}/results/full-results
      description: Submit race results
      operations:
      - name: post-full-results
        method: POST
        description: Submit complete race results for an event
        inputParameters:
        - name: race_id
          in: path
          type: integer
          required: true
          description: Race ID
        body:
          type: json
          data:
            api_key: '{{env.RUNSIGNUP_API_KEY}}'
            api_secret: '{{env.RUNSIGNUP_API_SECRET}}'
            event_id: '{{tools.event_id}}'
            results: '{{tools.results}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: divisions
      path: /race/{race_id}/divisions/divisions
      description: Race age group divisions
      operations:
      - name: get-divisions
        method: GET
        description: Get race divisions
        inputParameters:
        - name: race_id
          in: path
          type: integer
          required: true
          description: Race ID
        - name: api_secret
          in: query
          type: string
          required: true
          description: API secret
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: teams
      path: /race/{race_id}/teams
      description: Race team management
      operations:
      - name: get-teams
        method: GET
        description: Get teams registered for a race
        inputParameters:
        - name: race_id
          in: path
          type: integer
          required: true
          description: Race ID
        - name: api_secret
          in: query
          type: string
          required: true
          description: API secret
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: donations
      path: /race/{race_id}/donations/list
      description: Race donation data
      operations:
      - name: get-donations
        method: GET
        description: Get donations for a race
        inputParameters:
        - name: race_id
          in: path
          type: integer
          required: true
          description: Race ID
        - name: api_secret
          in: query
          type: string
          required: true
          description: API secret
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: race-event-api
    description: Unified REST API for RunSignup race event management.
    resources:
    - path: /v1/races
      name: races
      description: Race discovery and search
      operations:
      - method: GET
        name: get-races
        description: Search and list upcoming races
        call: runsignup.get-races
        with:
          search_term: rest.search_term
          state: rest.state
          results_per_page: rest.results_per_page
          events: rest.events
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/races/{race_id}
      name: race
      description: Individual race details
      operations:
      - method: GET
        name: get-race
        description: Get full race information including events
        call: runsignup.get-race
        with:
          race_id: rest.race_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/races/{race_id}/participants
      name: participants
      description: Participant registration management
      operations:
      - method: GET
        name: get-participants
        description: List registered participants
        call: runsignup.get-participants
        with:
          race_id: rest.race_id
          event_id: rest.event_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/races/{race_id}/bib-chip
      name: bib-chip
      description: Bib and chip assignment data
      operations:
      - method: GET
        name: get-bib-chip
        description: Get bib number and chip assignments
        call: runsignup.get-bib-chip
        with:
          race_id: rest.race_id
          event_id: rest.event_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/races/{race_id}/results
      name: results
      description: Race results retrieval and submission
      operations:
      - method: GET
        name: get-results
        description: Get race results
        call: runsignup.get-results
        with:
          race_id: rest.race_id
          event_id: rest.event_id
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: post-results
        description: Submit race results
        call: runsignup.post-full-results
        with:
          race_id: rest.race_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/races/{race_id}/divisions
      name: divisions
      description: Age and gender division management
      operations:
      - method: GET
        name: get-divisions
        description: Get race divisions
        call: runsignup.get-divisions
        with:
          race_id: rest.race_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/races/{race_id}/teams
      name: teams
      description: Team registration management
      operations:
      - method: GET
        name: get-teams
        description: Get registered teams
        call: runsignup.get-teams
        with:
          race_id: rest.race_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/races/{race_id}/donations
      name: donations
      description: Fundraising and donation data
      operations:
      - method: GET
        name: get-donations
        description: Get race donations
        call: runsignup.get-donations
        with:
          race_id: rest.race_id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: race-event-mcp
    transport: http
    description: MCP server for AI-assisted race event management and results processing.
    tools:
    - name: search-races
      description: Search and discover upcoming races on RunSignup by name, location, or state
      hints:
        readOnly: true
        openWorld: true
      call: runsignup.get-races
      with:
        search_term: tools.search_term
        state: tools.state
        results_per_page: tools.results_per_page
      outputParameters:
      - type: object
        mapping: $.
    - name: get-race-details
      description: Get comprehensive details about a specific race including all events, registration status, and settings
      hints:
        readOnly: true
        openWorld: true
      call: runsignup.get-race
      with:
        race_id: tools.race_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-race-participants
      description: Retrieve registered participants for a race, optionally filtered by event
      hints:
        readOnly: true
        openWorld: false
      call: runsignup.get-participants
      with:
        race_id: tools.race_id
        event_id: tools.event_id
        results_per_page: tools.results_per_page
      outputParameters:
      - type: object
        mapping: $.
    - name: get-bib-chip-assignments
      description: Get bib number and RFID chip assignments for timing operations
      hints:
        readOnly: true
        openWorld: false
      call: runsignup.get-bib-chip
      with:
        race_id: tools.race_id
        event_id: tools.event_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-race-results
      description: Retrieve official race results including finish times and placements
      hints:
        readOnly: true
        openWorld: true
      call: runsignup.get-results
      with:
        race_id: tools.race_id
        event_id: tools.event_id
      outputParameters:
      - type: object
        mapping: $.
    - name: submit-race-results
      description: Submit official race results with finish times and placements for participants
      hints:
        readOnly: false
        openWorld: false
      call: runsignup.post-full-results
      with:
        race_id: tools.race_id
        event_id: tools.event_id
        results: tools.results
      outputParameters:
      - type: object
        mapping: $.
    - name: get-race-divisions
      description: Get age and gender divisions configured for race results scoring
      hints:
        readOnly: true
        openWorld: true
      call: runsignup.get-divisions
      with:
        race_id: tools.race_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-race-teams
      description: Get teams registered for a race event
      hints:
        readOnly: true
        openWorld: true
      call: runsignup.get-teams
      with:
        race_id: tools.race_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-race-donations
      description: Get donation and fundraising data for a race
      hints:
        readOnly: true
        openWorld: false
      call: runsignup.get-donations
      with:
        race_id: tools.race_id
      outputParameters:
      - type: object
        mapping: $.