tiktok_search

Instructions

Implementation Reference

• index.ts:200-252 (handler)

  The performSearch function is the core handler for the tiktok_search tool. It calls the TikNeuron API endpoint (https://tikneuron.com/api/mcp/search), formats the results into a human-readable string with video details (description, creator, hashtags, engagement metrics, etc.) and pagination metadata.

  async function performSearch(query: string, cursor?: string, search_uid?: string) {
      const url = new URL('https://tikneuron.com/api/mcp/search');
      url.searchParams.set('query', query);
      
      if (cursor) {
          url.searchParams.set('cursor', cursor);
      }
      
      if (search_uid) {
          url.searchParams.set('search_uid', search_uid);
      }
  
      const response = await fetch(url, {
          headers: {
              'Accept': 'application/json',
              'Accept-Encoding': 'gzip',
              'MCP-API-KEY': TIKNEURON_MCP_API_KEY,
          }
      });
  
      if (!response.ok) {
          throw new Error(`TikNeuron API error: ${response.status} ${response.statusText}\n${await response.text()}`);
      }
  
      const data = await response.json() as SearchResult;
  
      if (data.videos && data.videos.length > 0) {
          const videosList = data.videos.map((video, index) => {
              return `Video ${index + 1}:
  Description: ${video.description || 'N/A'}
  Video ID: ${video.video_id || 'N/A'}
  Creator: ${video.creator || 'N/A'}
  Hashtags: ${Array.isArray(video.hashtags) ? video.hashtags.join(', ') : 'N/A'}
  Likes: ${video.likes || '0'}
  Shares: ${video.shares || '0'}
  Comments: ${video.comments || '0'}
  Views: ${video.views || '0'}
  Bookmarks: ${video.bookmarks || '0'}
  Created at: ${video.created_at || 'N/A'}
  Duration: ${video.duration || 0} seconds
  Available subtitles: ${video.available_subtitles?.map(sub => `${sub.language || 'Unknown'} (${sub.source || 'Unknown source'})`).join(', ') || 'None'}`;
          }).join('\n\n');
  
          const metadata = `\nSearch Metadata:
  Cursor: ${data.metadata?.cursor || 'N/A'}
  Has more results: ${data.metadata?.has_more ? 'Yes' : 'No'}
  Search UID: ${data.metadata?.search_uid || 'N/A'}`;
  
          return videosList + metadata;
      } else {
          return 'No videos found for the search query';
      }
  }

• index.ts:143-167 (schema)

  The SearchResult interface defines the response schema for the tiktok_search tool, including video details and pagination metadata (cursor, has_more, search_uid).

  interface SearchResult {
      success: boolean;
      videos: Array<{
          description: string;
          video_id: string;
          creator: string;
          hashtags: string[];
          likes: string;
          shares: string;
          comments: string;
          views: string;
          bookmarks: string;
          created_at: string;
          duration: number;
          available_subtitles: Array<{
              language?: string;
              source?: string;
          }>;
      }>;
      metadata: {
          cursor: string;
          has_more: boolean;
          search_uid: string;
      };
  }

• index.ts:63-90 (schema)

  The SEARCH Tool constant defines the tool's name ('tiktok_search'), description, and inputSchema (query required; cursor and search_uid optional).

  const SEARCH: Tool = {
      name: "tiktok_search",
      description:
          "Search for TikTok videos based on a query." +
          "This is used for searching TikTok videos by keywords, hashtags, or other search terms." +
          "Supports search query as input and optional cursor and search_uid for pagination." +
          "Returns a list of videos matching the search criteria with their details including" +
          " - Description, video ID, creator, hashtags, engagement metrics, date of creation, duration of the video and available subtitles with language and source information" +
          " - Pagination metadata for continuing the search",
      inputSchema: {
          type: "object",
          properties: {
              query: {
                  type: "string",
                  description: "Search query for TikTok videos, e.g., 'funny cats', 'dance', 'cooking tutorial'",
              },
              cursor: {
                  type: "string",
                  description: "Pagination cursor for getting more results (optional)",
              },
              search_uid: {
                  type: "string",
                  description: "Search session identifier for pagination (optional)",
              },
          },
          required: ["query"],
      },
  };

• index.ts:189-198 (handler)

  The isSearchArgs type guard validates arguments for the tiktok_search tool, ensuring query is a string and optionally cursor and search_uid are strings.

  function isSearchArgs(args: unknown): args is { query: string, cursor?: string, search_uid?: string } {
      return (
          typeof args === "object" &&
          args !== null &&
          "query" in args &&
          typeof (args as { query: string }).query === "string" &&
          ("cursor" in args ? typeof (args as { cursor?: string }).cursor === "string" : true) &&
          ("search_uid" in args ? typeof (args as { search_uid?: string }).search_uid === "string" : true)
      );
  }

• index.ts:318-320 (registration)

  The ListToolsRequestSchema handler registers the SEARCH tool (along with GET_SUBTITLE and GET_POST_DETAILS) by including it in the tools array.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools: [GET_SUBTITLE, GET_POST_DETAILS, SEARCH],
  }));

• index.ts:357-368 (registration)

  The CallToolRequestSchema handler dispatches to performSearch when the tool name is 'tiktok_search', validates args via isSearchArgs, calls performSearch, and returns the result.

  case "tiktok_search": {
      if (!isSearchArgs(args)) {
          throw new Error("Invalid arguments for tiktok_search");
      }
      const { query, cursor, search_uid } = args;
  
      const results = await performSearch(query, cursor, search_uid);
      return {
          content: [{ type: "text", text: results }],
          isError: false,
      };
  }