trakt_search

Instructions

Implementation Reference

• src/trakt/mcp-functions.ts:412-452 (handler)

  The main handler function `traktSearch()` that executes the tool logic. It calls `this.traktClient.search(query, type, year)`, maps results (movies/shows), truncates overviews, and returns a success/error response.

  /**
   * MCP Function: trakt_search
   * Search for content on Trakt
   */
  async traktSearch(query: string, type?: 'movie' | 'show', year?: number, limit?: number): Promise<Record<string, unknown>> {
    if (!this.isInitialized) {
      this.initializeTraktClient();
    }
  
    const effectiveLimit = limit || TRAKT_PREVIEW_LIMIT;
    try {
      const results = await this.traktClient.search(query, type, year);
  
      return {
        success: true,
        query,
        type: type || 'all',
        year,
        results: results.slice(0, effectiveLimit).map(result => {
          const media = result.type === 'movie' ? result.movie : result.show;
          return {
            type: result.type,
            score: result.score,
            [result.type]: {
              title: media?.title,
              year: media?.year,
              ids: media?.ids,
              overview: media?.overview ? truncate(media.overview, SUMMARY_PREVIEW_LENGTH) : undefined
            }
          };
        }),
        totalResults: results.length,
        showing: Math.min(effectiveLimit, results.length)
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Search failed'
      };
    }
  }

• src/trakt/tool-schemas.ts:80-93 (schema)

  Input schema definition for trakt_search tool. Defines properties: query (string, required), type (enum: movie|show, optional), year (number, optional), limit (number, optional, default: 100).

  {
    name: "trakt_search",
    description: "Search for movies and shows on Trakt.tv",
    inputSchema: {
      type: "object" as const,
      properties: {
        query: { type: "string", description: "Search query" },
        type: { type: "string", enum: ["movie", "show"], description: "Optional media type filter" },
        year: { type: "number", description: "Optional year filter" },
        limit: { type: "number", description: "Max results to return (default: 100)", default: 100 },
      },
      required: ["query"],
    },
  },

• src/trakt/tool-registry.ts:54-61 (registration)

  Registration of the 'trakt_search' tool in the registry, wiring up args to the traktFunctions.traktSearch() call.

  registry.register("trakt_search", (args) =>
    traktFunctions.traktSearch(
      args.query as string,
      args.type as "movie" | "show" | undefined,
      args.year as number | undefined,
      args.limit as number | undefined,
    ).then(wrapResponse)
  );

• src/trakt/client.ts:32-37 (helper)

  Type definition `TraktSearchResult` interface with type, score, movie (optional TraktMovie), show (optional TraktShow) used by the client search method.

  export interface TraktSearchResult {
    type: string;
    score: number;
    movie?: TraktMovie;
    show?: TraktShow;
  }

• src/trakt/client.ts:299-306 (helper)

  The TraktClient.search() method that makes the HTTP GET request to the Trakt API /search endpoint.

  async search(query: string, type?: 'movie' | 'show', year?: number): Promise<TraktSearchResult[]> {
    const params = new URLSearchParams({ query });
    if (type) params.append('type', type);
    if (year) params.append('year', year.toString());
  
    const response = await this.http.get(`/search/${type || 'movie,show'}?${params.toString()}`);
    return response.data;
  }