NASA MCP Server

Instructions

Implementation Reference

• src/handlers/jpl/horizons_file.ts:14-100 (handler)

  The core handler function `horizonsFileHandler` that executes the `jpl_horizons_file` tool. It formats input parameters into a Horizons-compatible text file, submits via multipart POST to the JPL API, processes the response, adds it as a resource, and returns formatted output.
  export async function horizonsFileHandler(args: Record<string, any>) { try { // Base URL for the Horizons File API (POST) const baseUrl = 'https://ssd.jpl.nasa.gov/api/horizons_file.api'; // Format arguments into the key='value' text format for the input file // DO NOT include format here, it's a separate form field. const formattedArgs = { ...args }; delete formattedArgs.format; // Remove format if present let fileContent = '!$$SOF\n'; // Add !SOF marker for (const [key, value] of Object.entries(formattedArgs)) { let formattedValue: string | number; const upperKey = key.toUpperCase(); // Leave numbers unquoted if (typeof value === 'number') { formattedValue = value; } // Quote ALL other values (strings, including YES/NO) else { formattedValue = `'${String(value).replace(/'/g, "\'")}'`; } fileContent += `${upperKey}=${formattedValue}\n`; } fileContent += '!$$EOF\n'; // Correct !EOF marker // Create FormData payload const form = new FormData(); // Add format as a separate field form.append('format', args.format || 'json'); // Add the file content under the 'input' field name form.append('input', fileContent, { filename: 'horizons_input.txt', // Required filename, content doesn't matter contentType: 'text/plain', }); // Make the API request using POST with multipart/form-data const response = await axios.post(baseUrl, form, { headers: { ...form.getHeaders(), // Important for correct boundary }, }); const data = response.data; // Assume response is JSON based on 'format=json' // Create a resource URI that represents this query (similar to GET handler) let resourceUri = 'jpl://horizons-file'; // Distinguish from GET let resourceName = 'JPL Horizons file-based ephemeris data'; if (args.COMMAND) { resourceUri += `/object/${encodeURIComponent(args.COMMAND)}`; resourceName = `${args.COMMAND} ephemeris data (file input)`; if (args.START_TIME && args.STOP_TIME) { resourceName += ` (${args.START_TIME} to ${args.STOP_TIME})`; } } // Add response to resources addResource(resourceUri, { name: resourceName, mimeType: "application/json", // Assuming JSON response text: JSON.stringify(data, null, 2) }); // Format the response return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] }; } catch (error: any) { let errorMessage = `Error accessing JPL Horizons File API: ${error.message}`; if (error.response) { // Include more detail from the API response if available errorMessage += `\nStatus: ${error.response.status}\nData: ${JSON.stringify(error.response.data)}`; } return { content: [{ type: "text", text: errorMessage }], isError: true }; } }
• src/index.ts:1290-1347 (schema)

  Input schema and metadata definition for the `jpl_horizons_file` tool provided in the `tools/list` MCP endpoint response.
  name: "jpl_horizons_file", description: "JPL Horizons - Solar system objects ephemeris data (File Input)", inputSchema: { type: "object", properties: { format: { type: "string", description: "Response format (json, text)", enum: ["json", "text"] }, COMMAND: { type: "string", description: "Target object identifier (e.g., '499' for Mars, '1' for Ceres, 'C/2020 F3' for Comet NEOWISE)" }, OBJ_DATA: { type: "string", description: "Include object data", enum: ["YES", "NO"] }, MAKE_EPHEM: { type: "string", description: "Generate ephemeris", enum: ["YES", "NO"] }, EPHEM_TYPE: { type: "string", description: "Type of ephemeris (OBSERVER, VECTORS, ELEMENTS)", enum: ["OBSERVER", "VECTORS", "ELEMENTS"] }, CENTER: { type: "string", description: "Coordinate center (e.g., '500@399' for Earth)" }, START_TIME: { type: "string", description: "Start time for ephemeris (e.g., '2023-01-01')" }, STOP_TIME: { type: "string", description: "Stop time for ephemeris (e.g., '2023-01-02')" }, STEP_SIZE: { type: "string", description: "Step size for ephemeris points (e.g., '1d' for daily, '1h' for hourly)" }, QUANTITIES: { type: "string", description: "Observable quantities to include (e.g., 'A' for all, or '1,2,20,23' for specific ones)" }, OUT_UNITS: { type: "string", description: "Output units for vector tables", enum: ["KM-S", "AU-D", "KM-D"] } }, required: ["COMMAND"] } },
• src/index.ts:1896-1932 (registration)

  Dynamic registration and dispatch logic in `handleToolCall` for JPL tools. Dynamically imports `./handlers/jpl/horizons_file.js` (endpoint='horizons_file') and executes its default export handler function.
  } 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:2151-2157 (registration)

  Global MCP tool registration for `mcp__jplhorizons_file` that routes calls to the `jpl/horizons_file` handler via `handleToolCall`.
  registerGlobalTool('mcp__jplhorizons_file', async (args: Record<string, any>) => { serverInstance?.sendLoggingMessage({ level: "info", data: `MCP JPL Horizons File called with args: ${JSON.stringify(args)}`, }); return await handleToolCall('jpl/horizons_file', args); });