TMDB MCP Server

Instructions

Implementation Reference

• src/tools.ts:105-115 (handler)

  MCP tool handler for 'get-similar' that invokes getSimilarMovies with error handling.

  "get-similar": async ({ movieId }: { movieId: string }) => {
    try {
      // Return the raw results directly
      return await getSimilarMovies(movieId);
    } catch (error: unknown) {
      if (error instanceof Error) {
        throw new Error(`Failed to get similar movies: ${error.message}`);
      }
      throw new Error("Failed to get similar movies: Unknown error");
    }
  },

• src/tools.ts:42-55 (schema)

  JSON Schema definition for the input parameters of the 'get-similar' tool.

  "get-similar": {
    name: "get-similar",
    description: "Get similar movies to a given movie",
    inputSchema: {
      type: "object",
      properties: {
        movieId: {
          type: "string",
          description: "ID of the movie to find similar movies for",
        },
      },
      required: ["movieId"],
    },
  },

• src/tmdb-api.ts:144-155 (helper)

  Helper function that fetches similar movies from TMDB API using axios.

  export async function getSimilarMovies(movieId: number | string): Promise<SearchMoviesResponse> {
    try {
      const response = await axiosWithRetry<SearchMoviesResponse>({
        url: `/movie/${movieId}/similar`
      });
      return response.data;
    } catch (error) {
      const err = error as Error;
      console.error('Error getting similar movies:', err.message);
      throw new Error(`Failed to get similar movies: ${err.message}`);
    }
  }

• src/handlers.ts:13-72 (registration)

  Import of toolHandlers and tools (schemas) in the MCP server handlers setup.

  import { toolHandlers, tools } from "./tools.js";
  import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
  
  export const setupHandlers = (server: Server): void => {
    // Resource handlers
    server.setRequestHandler(
      ListResourcesRequestSchema,
      async () => ({ resources }),
    );
    
    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
      resourceTemplates,
    }));
    
    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
      const { uri } = request.params;
      // Using type assertion to tell TypeScript this is a valid key
      const resourceHandler = resourceHandlers[uri as keyof typeof resourceHandlers];
      if (resourceHandler) return await resourceHandler();
      
      const resourceTemplateHandler = await getResourceTemplate(uri);
      if (resourceTemplateHandler) return await resourceTemplateHandler();
      
      throw new Error(`Resource not found: ${uri}`);
    });
  
    // Prompt handlers
    server.setRequestHandler(ListPromptsRequestSchema, async () => ({
      prompts: Object.values(prompts),
    }));
    
    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;
      // Using type assertion to tell TypeScript this is a valid key
      const promptHandler = promptHandlers[name as keyof typeof promptHandlers];
      
      if (promptHandler) {
        return promptHandler(args as any);
      }
      
      throw new Error(`Prompt not found: ${name}`);
    });
  
    // Tool handlers
    server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools: Object.values(tools),
    }));
  
    // This is the key fix - we need to format the response properly
    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);

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

  MCP CallTool request handler that dispatches to specific toolHandlers including 'get-similar'.

  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"
      };
    }
  });