naftiko: 1.0.0-alpha2
info:
  label: Stack Exchange Knowledge Discovery
  description: Workflow capability for discovering and retrieving programming knowledge from the Stack Exchange network. Enables
    developers, AI agents, and tools to search for questions, find answers, explore tags, and identify experts across Stack
    Overflow and other Stack Exchange sites.
  tags:
  - Stack Exchange
  - Knowledge Discovery
  - Q&A
  - Developer Tools
  - Search
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    STACK_EXCHANGE_ACCESS_TOKEN: STACK_EXCHANGE_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: stack-exchange-api
    baseUri: https://api.stackexchange.com/2.3
    description: Stack Exchange network Q&A API v2.3
    authentication:
      type: apikey
      key: access_token
      value: '{{STACK_EXCHANGE_ACCESS_TOKEN}}'
      placement: query
    resources:
    - name: questions
      path: /questions
      description: Stack Exchange questions
      operations:
      - name: get-questions
        method: GET
        description: Get questions from a Stack Exchange site
        inputParameters:
        - name: site
          in: query
          type: string
          required: true
          description: Stack Exchange site identifier
        - name: tagged
          in: query
          type: string
          required: false
          description: Semicolon-delimited tags to filter by
        - name: sort
          in: query
          type: string
          required: false
          description: Sort field (activity, creation, votes, hot, week, month)
        - name: order
          in: query
          type: string
          required: false
          description: Sort order (asc, desc)
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        - name: pagesize
          in: query
          type: integer
          required: false
          description: Items per page (max 100)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-unanswered-questions
        method: GET
        description: Get unanswered questions from a Stack Exchange site
        inputParameters:
        - name: site
          in: query
          type: string
          required: true
          description: Stack Exchange site identifier
        - name: tagged
          in: query
          type: string
          required: false
          description: Filter by tags
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: questions-by-id
      path: /questions/{ids}
      description: Stack Exchange questions by ID
      operations:
      - name: get-questions-by-ids
        method: GET
        description: Get specific questions by semicolon-delimited IDs
        inputParameters:
        - name: ids
          in: path
          type: string
          required: true
          description: Semicolon-delimited question IDs
        - name: site
          in: query
          type: string
          required: true
          description: Stack Exchange site identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: answers
      path: /answers
      description: Stack Exchange answers
      operations:
      - name: get-answers
        method: GET
        description: Get all answers from a Stack Exchange site
        inputParameters:
        - name: site
          in: query
          type: string
          required: true
          description: Stack Exchange site identifier
        - name: sort
          in: query
          type: string
          required: false
          description: Sort field
        - name: order
          in: query
          type: string
          required: false
          description: Sort order
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: search
      path: /search
      description: Search Stack Exchange questions
      operations:
      - name: search-questions
        method: GET
        description: Search questions by title text and tags
        inputParameters:
        - name: site
          in: query
          type: string
          required: true
          description: Stack Exchange site identifier
        - name: intitle
          in: query
          type: string
          required: false
          description: Text to search in question titles
        - name: tagged
          in: query
          type: string
          required: false
          description: Filter by tags
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: search-advanced
      path: /search/advanced
      description: Advanced search of Stack Exchange questions
      operations:
      - name: search-advanced
        method: GET
        description: Advanced question search with filtering by accepted status, body, tags, and user
        inputParameters:
        - name: site
          in: query
          type: string
          required: true
          description: Stack Exchange site identifier
        - name: q
          in: query
          type: string
          required: false
          description: Full-text search query
        - name: tagged
          in: query
          type: string
          required: false
          description: Filter by tags
        - name: accepted
          in: query
          type: boolean
          required: false
          description: Filter for questions with accepted answers
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users
      path: /users
      description: Stack Exchange users
      operations:
      - name: get-users
        method: GET
        description: Get users from a Stack Exchange site
        inputParameters:
        - name: site
          in: query
          type: string
          required: true
          description: Stack Exchange site identifier
        - name: inname
          in: query
          type: string
          required: false
          description: Filter by display name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: tags
      path: /tags
      description: Stack Exchange tags
      operations:
      - name: get-tags
        method: GET
        description: Get tags from a Stack Exchange site
        inputParameters:
        - name: site
          in: query
          type: string
          required: true
          description: Stack Exchange site identifier
        - name: inname
          in: query
          type: string
          required: false
          description: Filter by tag name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: sites
      path: /sites
      description: Stack Exchange network sites
      operations:
      - name: get-sites
        method: GET
        description: Get all sites in the Stack Exchange network
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: knowledge-discovery-api
    description: Unified REST API for Stack Exchange knowledge discovery and Q&A retrieval.
    resources:
    - path: /v1/questions
      name: questions
      description: Browse and filter questions
      operations:
      - method: GET
        name: get-questions
        description: Get questions from Stack Exchange sorted by activity, creation, or votes
        call: stack-exchange-api.get-questions
        with:
          site: rest.site
          tagged: rest.tagged
          sort: rest.sort
          order: rest.order
          page: rest.page
          pagesize: rest.pagesize
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/unanswered
      name: unanswered
      description: Questions that need answers
      operations:
      - method: GET
        name: get-unanswered-questions
        description: Get unanswered questions to identify knowledge gaps
        call: stack-exchange-api.get-unanswered-questions
        with:
          site: rest.site
          tagged: rest.tagged
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/search
      name: search
      description: Search questions by keyword
      operations:
      - method: GET
        name: search-questions
        description: Search Stack Exchange questions by title text and tags
        call: stack-exchange-api.search-questions
        with:
          site: rest.site
          intitle: rest.intitle
          tagged: rest.tagged
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/search/advanced
      name: advanced-search
      description: Advanced question search with multiple filters
      operations:
      - method: GET
        name: advanced-search
        description: Advanced search with acceptance status, body, and view count filters
        call: stack-exchange-api.search-advanced
        with:
          site: rest.site
          q: rest.q
          tagged: rest.tagged
          accepted: rest.accepted
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tags
      name: tags
      description: Browse tags
      operations:
      - method: GET
        name: get-tags
        description: Get tags used to categorize questions on Stack Exchange
        call: stack-exchange-api.get-tags
        with:
          site: rest.site
          inname: rest.inname
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users
      name: users
      description: Find community experts
      operations:
      - method: GET
        name: get-users
        description: Find Stack Exchange users and community experts
        call: stack-exchange-api.get-users
        with:
          site: rest.site
          inname: rest.inname
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/sites
      name: sites
      description: Stack Exchange network sites
      operations:
      - method: GET
        name: get-sites
        description: List all Stack Exchange network sites
        call: stack-exchange-api.get-sites
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: knowledge-discovery-mcp
    transport: http
    description: MCP server for AI-assisted knowledge discovery on the Stack Exchange network.
    tools:
    - name: search-programming-questions
      description: Search Stack Overflow and Stack Exchange for programming questions by keyword, topic, or technology tag
      hints:
        readOnly: true
        openWorld: true
        idempotent: true
      call: stack-exchange-api.search-questions
      with:
        site: tools.site
        intitle: tools.intitle
        tagged: tools.tagged
      outputParameters:
      - type: object
        mapping: $.
    - name: advanced-search-questions
      description: Perform advanced search of Stack Exchange with acceptance, vote, and tag filters
      hints:
        readOnly: true
        openWorld: true
        idempotent: true
      call: stack-exchange-api.search-advanced
      with:
        site: tools.site
        q: tools.q
        tagged: tools.tagged
        accepted: tools.accepted
      outputParameters:
      - type: object
        mapping: $.
    - name: get-top-questions
      description: Get top-voted or most-active questions on a Stack Exchange site optionally filtered by tag
      hints:
        readOnly: true
        idempotent: true
      call: stack-exchange-api.get-questions
      with:
        site: tools.site
        tagged: tools.tagged
        sort: tools.sort
      outputParameters:
      - type: object
        mapping: $.
    - name: get-unanswered-questions
      description: Find unanswered questions on Stack Exchange that need community attention
      hints:
        readOnly: true
        idempotent: true
      call: stack-exchange-api.get-unanswered-questions
      with:
        site: tools.site
        tagged: tools.tagged
      outputParameters:
      - type: object
        mapping: $.
    - name: get-question-details
      description: Get full details of specific Stack Exchange questions by ID
      hints:
        readOnly: true
        idempotent: true
      call: stack-exchange-api.get-questions-by-ids
      with:
        ids: tools.ids
        site: tools.site
      outputParameters:
      - type: object
        mapping: $.
    - name: browse-tags
      description: Browse tags on a Stack Exchange site to understand topic taxonomy
      hints:
        readOnly: true
        idempotent: true
      call: stack-exchange-api.get-tags
      with:
        site: tools.site
        inname: tools.inname
      outputParameters:
      - type: object
        mapping: $.
    - name: find-experts
      description: Find high-reputation users and experts on a Stack Exchange site by name
      hints:
        readOnly: true
        idempotent: true
      call: stack-exchange-api.get-users
      with:
        site: tools.site
        inname: tools.inname
      outputParameters:
      - type: object
        mapping: $.
    - name: list-stack-exchange-sites
      description: List all sites in the Stack Exchange network to find the right community
      hints:
        readOnly: true
        idempotent: true
      call: stack-exchange-api.get-sites
      outputParameters:
      - type: object
        mapping: $.