TikTok Social Research

naftiko: "1.0.0-alpha1"

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-03"

binds:
  - namespace: env
    keys:
      TIKTOK_RESEARCH_ACCESS_TOKEN: TIKTOK_RESEARCH_ACCESS_TOKEN

capability:
  consumes:
    - import: tiktok-research
      location: ./shared/research-api.yaml

  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: "$."