TMDB MCP Server

Instructions

Implementation Reference

• src/tools.ts:116-126 (handler)

  The MCP tool handler for 'get-movie-details', which invokes the TMDB API wrapper function getMovieDetails.

  "get-movie-details": async ({ movieId }: { movieId: string }) => {
    try {
      const result = await getMovieDetails(movieId);
      return result;
    } catch (error: unknown) {
      if (error instanceof Error) {
        return { text: `Failed to get movie details: ${error.message}` };
      }
      return { text: "Failed to get movie details: Unknown error" };
    }
  },

• src/tools.ts:56-69 (schema)

  The input schema definition for the 'get-movie-details' tool.

  "get-movie-details": {
    name: "get-movie-details",
    description: "Get detailed information about a specific movie",
    inputSchema: {
      type: "object",
      properties: {
        movieId: {
          type: "string",
          description: "ID of the movie to get details for",
        },
      },
      required: ["movieId"],
    },
  },

• src/handlers.ts:57-59 (registration)

  Registration of the list tools endpoint, exposing the tool schemas including 'get-movie-details'.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: Object.values(tools),
  }));

• src/handlers.ts:62-98 (registration)

  Registration of the call tool endpoint, which dispatches calls to the appropriate tool handler including 'get-movie-details'.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    try {
      const { name, arguments: args } = request.params;
      // Using type assertion to tell TypeScript this is a valid key
      const handler = toolHandlers[name as keyof typeof toolHandlers];
  
      if (!handler) throw new Error(`Tool not found: ${name}`);
  
      // Execute the handler but wrap the response in the expected format
      const result = await handler(args as any);
      
      // Return in the format expected by the SDK
      return {
        tools: [{
          name,
          inputSchema: {
            type: "object",
            properties: {} // This would ideally be populated with actual schema
          },
          description: `Tool: ${name}`,
          result
        }]
      };
    } catch (error) {
      // Properly handle errors
      if (error instanceof Error) {
        return {
          tools: [],
          error: error.message
        };
      }
      return {
        tools: [],
        error: "An unknown error occurred"
      };
    }
  });

• src/tmdb-api.ts:115-129 (helper)

  The underlying helper function that fetches movie details from TMDB API using axios, called by the tool handler.

  export async function getMovieDetails(movieId: number | string): Promise<MovieDetailsResponse> {
    try {
      const response = await axiosWithRetry<MovieDetailsResponse>({
        url: `/movie/${movieId}`,
        params: {
          append_to_response: 'credits,videos,images'
        }
      });
      return response.data;
    } catch (error) {
      const err = error as Error;
      console.error('Error getting movie details:', err.message);
      throw new Error(`Failed to get movie details: ${err.message}`);
    }
  }