jpl_cad

Instructions

Implementation Reference

• src/handlers/jpl/cad.ts:14-80 (handler)

  The main handler function cadHandler that implements the JPL Close Approach Data (CAD) API call, parameter transformation, resource creation, and error handling.

  export async function cadHandler(args: Record<string, any>) {
    try {
      // Base URL for the CAD API
      const baseUrl = 'https://ssd-api.jpl.nasa.gov/cad.api';
      
      // Validate parameters if needed
      // Parameters are fairly flexible in this API, so minimal validation is needed
      
      // Transform parameter names from underscore to hyphenated format
      const transformedParams = transformParamsToHyphenated(args);
      
      // Make the API request
      const response = await axios.get(baseUrl, { params: transformedParams });
      const data = response.data;
      
      // Create a resource URI that represents this query
      let resourceUri: string;
      let resourceName: string;
      
      if (args.des) {
        // Query for a specific object
        resourceUri = `jpl://cad/object/${args.des}`;
        resourceName = `Close approaches for object ${args.des}`;
      } else if (args.spk) {
        // Query for a specific object by SPK-ID
        resourceUri = `jpl://cad/object/${args.spk}`;
        resourceName = `Close approaches for object ${args.spk}`;
      } else {
        // Query for close approaches with constraints
        const constraints = Object.entries(args)
          .map(([key, value]) => `${key}=${value}`)
          .join('&');
        
        resourceUri = `jpl://cad/list${constraints ? '?' + constraints : ''}`;
        
        // Create a readable name based on date range and body
        const dateMin = args['date_min'] || 'now';
        const dateMax = args['date_max'] || '+60';
        const body = args.body || 'Earth';
        
        resourceName = `Close approaches to ${body} from ${dateMin} to ${dateMax}`;
      }
      
      // Add response to resources
      addResource(resourceUri, {
        name: resourceName,
        mimeType: "application/json",
        text: JSON.stringify(data, null, 2)
      });
      
      // Format the response
      return {
        content: [{
          type: "text",
          text: JSON.stringify(data, null, 2)
        }]
      };
    } catch (error: any) {
      return {
        content: [{
          type: "text",
          text: `Error accessing JPL SB Close Approach API: ${error.message}`
        }],
        isError: true
      };
    }
  }

• src/index.ts:1132-1180 (schema)

  Input schema and parameter descriptions for the jpl_cad tool as defined in the tools/list handler response.

  {
    name: "jpl_cad",
    description: "Asteroid and comet close approaches to the planets in the past and future",
    inputSchema: {
      type: "object",
      properties: {
        "dist_max": {
          type: "string",
          description: "Maximum approach distance (e.g., 0.05, 10LD). Default: 0.05 au"
        },
        "dist_min": {
          type: "string",
          description: "Minimum approach distance. Default: none"
        },
        "date_min": {
          type: "string",
          description: "Start date for search (YYYY-MM-DD). Default: now"
        },
        "date_max": {
          type: "string",
          description: "End date for search (YYYY-MM-DD). Default: +60 days"
        },
        "body": {
          type: "string",
          description: "Body to find close approaches to (e.g., Earth, Mars, ALL). Default: Earth"
        },
        "sort": {
          type: "string",
          description: "Sort field: date, dist, dist-min, v-inf, v-rel, h, object. Default: date"
        },
        "des": {
          type: "string",
          description: "Object designation (e.g., '2000 SG344' or '433')"
        },
        "spk": {
          type: "string",
          description: "Object SPK-ID (e.g., '2000433')"
        },
        "neo": {
          type: "boolean",
          description: "Limit to NEOs. Default: true"
        },
        "fullname": {
          type: "boolean",
          description: "Include full object name in result. Default: false"
        }
      }
    }
  },

• src/index.ts:522-526 (registration)

  Tool registration entry for jpl_cad in the tools/manifest response.

  {
    name: "jpl_cad",
    id: "jpl/cad",
    description: "Asteroid and comet close approaches to the planets in the past and future"
  },

• src/index.ts:1896-1932 (registration)

  Dynamic dispatch logic in handleToolCall that imports and executes the JPL cad handler for tool name 'jpl_cad' (internal 'jpl/cad').

  } else if (internalToolId.startsWith("jpl/")) {
    // Extract the JPL API endpoint name
    const endpoint = internalToolId.split("/")[1];
    serverInstance?.sendLoggingMessage({
      level: "info",
      data: `JPL Endpoint: ${endpoint}`,
    });
    
    try {
      // Dynamic import for JPL handlers using the original slash format path
      serverInstance?.sendLoggingMessage({
        level: "info",
        data: `Importing handler module: ./handlers/jpl/${endpoint}.js`,
      });
      const handlerModule = await import(`./handlers/jpl/${endpoint}.js`);
      
      // Try to find the handler function in various export formats
      const handlerFunction = handlerModule.default || 
                             handlerModule[`jpl${endpoint.charAt(0).toUpperCase() + endpoint.slice(1)}Handler`] ||
                             handlerModule[`${endpoint}Handler`];
      
      if (typeof handlerFunction === 'function') {
        return await handlerFunction(args);
      } else {
        throw new Error(`Handler for ${endpoint} not found in module`);
      }
    } catch (error: unknown) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [{
          type: "text",
          text: `Error executing JPL tool '${toolName}': ${errorMessage}`
        }],
        isError: true
      };
    }
  }

• src/index.ts:2126-2132 (registration)

  Global MCP tool registration for mcp__jplcad that routes to the jpl/cad handler.

  registerGlobalTool('mcp__jplcad', async (args: Record<string, any>) => {
    serverInstance?.sendLoggingMessage({
      level: "info",
      data: `MCP JPL CAD called with args: ${JSON.stringify(args)}`,
    });
    return await handleToolCall('jpl/cad', args);
  });