naftiko: 1.0.0-alpha2
info:
  label: TikTok Social Research
  description: Workflow capability for academic and institutional research on TikTok public data. Uses the Research API to
    query videos, analyze user profiles, examine comment threads, and map social networks. Designed for data scientists, academic
    researchers, and policy analysts.
  tags:
  - TikTok
  - Research
  - Analytics
  - Social Media
  - Data Science
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    TIKTOK_RESEARCH_ACCESS_TOKEN: TIKTOK_RESEARCH_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: tiktok-research
    baseUri: https://open.tiktokapis.com
    description: TikTok Research API for academic data access
    authentication:
      type: bearer
      token: '{{TIKTOK_RESEARCH_ACCESS_TOKEN}}'
    resources:
    - name: research-videos
      path: /v2/research/video
      description: Research video data
      operations:
      - name: query-research-videos
        method: POST
        description: Query TikTok videos using boolean filters
        inputParameters:
        - name: fields
          in: query
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            query: '{{tools.query}}'
            start_date: '{{tools.start_date}}'
            end_date: '{{tools.end_date}}'
            max_count: '{{tools.max_count}}'
            cursor: '{{tools.cursor}}'
      - name: list-video-comments
        method: POST
        description: Retrieve all comments on a specific video
        inputParameters:
        - name: fields
          in: query
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            video_id: '{{tools.video_id}}'
            max_count: '{{tools.max_count}}'
      - name: list-user-liked-videos
        method: POST
        description: Retrieve videos liked by a user
        inputParameters:
        - name: fields
          in: query
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            username: '{{tools.username}}'
            max_count: '{{tools.max_count}}'
      - name: list-user-pinned-videos
        method: POST
        description: Retrieve videos pinned by a user
        inputParameters:
        - name: fields
          in: query
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            username: '{{tools.username}}'
            max_count: '{{tools.max_count}}'
      - name: list-user-reposted-videos
        method: POST
        description: Retrieve videos reposted by a user
        inputParameters:
        - name: fields
          in: query
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            username: '{{tools.username}}'
            max_count: '{{tools.max_count}}'
    - name: research-users
      path: /v2/research/user
      description: Research user data
      operations:
      - name: query-research-user-info
        method: POST
        description: Retrieve public TikTok account information by handle
        inputParameters:
        - name: fields
          in: query
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            username: '{{tools.username}}'
      - name: list-user-followers
        method: POST
        description: Retrieve follower list for a user
        inputParameters:
        - name: fields
          in: query
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            username: '{{tools.username}}'
            max_count: '{{tools.max_count}}'
      - name: list-user-following
        method: POST
        description: Retrieve following list for a user
        inputParameters:
        - name: fields
          in: query
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            username: '{{tools.username}}'
            max_count: '{{tools.max_count}}'
  exposes:
  - type: rest
    port: 8081
    namespace: tiktok-social-research-api
    description: Unified REST API for TikTok social research workflows.
    resources:
    - path: /v1/research/videos
      name: research-videos
      description: Query and analyze TikTok video data
      operations:
      - method: POST
        name: query-research-videos
        description: Query TikTok videos with boolean filters
        call: tiktok-research.query-research-videos
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/research/users/{username}
      name: research-users
      description: Research user profile data
      operations:
      - method: GET
        name: query-research-user-info
        description: Get public user account information
        call: tiktok-research.query-research-user-info
        with:
          username: rest.username
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/research/videos/{video_id}/comments
      name: video-comments
      description: Video comment data
      operations:
      - method: GET
        name: list-video-comments
        description: Get all comments on a TikTok video
        call: tiktok-research.list-video-comments
        with:
          video_id: rest.video_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/research/users/{username}/followers
      name: user-followers
      description: User follower social graph
      operations:
      - method: GET
        name: list-user-followers
        description: List followers of a TikTok user
        call: tiktok-research.list-user-followers
        with:
          username: rest.username
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/research/users/{username}/following
      name: user-following
      description: User following social graph
      operations:
      - method: GET
        name: list-user-following
        description: List accounts a user follows
        call: tiktok-research.list-user-following
        with:
          username: rest.username
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/research/users/{username}/liked-videos
      name: liked-videos
      description: Videos liked by a user
      operations:
      - method: GET
        name: list-user-liked-videos
        description: List videos liked by a user
        call: tiktok-research.list-user-liked-videos
        with:
          username: rest.username
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/research/users/{username}/pinned-videos
      name: pinned-videos
      description: Videos pinned by a user
      operations:
      - method: GET
        name: list-user-pinned-videos
        description: List videos pinned by a user
        call: tiktok-research.list-user-pinned-videos
        with:
          username: rest.username
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/research/users/{username}/reposted-videos
      name: reposted-videos
      description: Videos reposted by a user
      operations:
      - method: GET
        name: list-user-reposted-videos
        description: List videos reposted by a user
        call: tiktok-research.list-user-reposted-videos
        with:
          username: rest.username
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9091
    namespace: tiktok-social-research-mcp
    transport: http
    description: MCP server for AI-assisted TikTok social research and analysis.
    tools:
    - name: query-research-videos
      description: Query TikTok public videos using boolean filters for research analysis
      hints:
        readOnly: true
        idempotent: true
      call: tiktok-research.query-research-videos
      outputParameters:
      - type: object
        mapping: $.
    - name: query-research-user-info
      description: Get public TikTok account information by username for research
      hints:
        readOnly: true
        idempotent: true
      call: tiktok-research.query-research-user-info
      with:
        username: tools.username
      outputParameters:
      - type: object
        mapping: $.
    - name: list-video-comments
      description: Retrieve all comments on a TikTok video for sentiment analysis
      hints:
        readOnly: true
        idempotent: true
      call: tiktok-research.list-video-comments
      with:
        video_id: tools.video_id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-user-followers
      description: List followers of a TikTok user for social network analysis
      hints:
        readOnly: true
        idempotent: true
      call: tiktok-research.list-user-followers
      with:
        username: tools.username
      outputParameters:
      - type: object
        mapping: $.
    - name: list-user-following
      description: List accounts a TikTok user follows for network mapping
      hints:
        readOnly: true
        idempotent: true
      call: tiktok-research.list-user-following
      with:
        username: tools.username
      outputParameters:
      - type: object
        mapping: $.
    - name: list-user-liked-videos
      description: List videos liked by a TikTok user for engagement research
      hints:
        readOnly: true
        idempotent: true
      call: tiktok-research.list-user-liked-videos
      with:
        username: tools.username
      outputParameters:
      - type: object
        mapping: $.
    - name: list-user-pinned-videos
      description: List videos pinned by a TikTok user
      hints:
        readOnly: true
        idempotent: true
      call: tiktok-research.list-user-pinned-videos
      with:
        username: tools.username
      outputParameters:
      - type: object
        mapping: $.
    - name: list-user-reposted-videos
      description: List videos reposted by a TikTok user for sharing behavior analysis
      hints:
        readOnly: true
        idempotent: true
      call: tiktok-research.list-user-reposted-videos
      with:
        username: tools.username
      outputParameters:
      - type: object
        mapping: $.