NASA MCP Server

Instructions

Implementation Reference

• src/handlers/jpl/periodic_orbits.ts:30-89 (handler)

  Main handler function that validates inputs, transforms parameters, queries JPL SSD Periodic Orbits API, stores result as resource, and returns MCP-formatted response.

  export async function periodicOrbitsHandler(args: PeriodicOrbitParams) {
    try {
      // Validate required parameters
      if (!args.sys || !args.family) {
        throw new Error('Missing required parameters: sys and family must be provided.');
      }
      
      // Base URL for the Periodic Orbits API
      const baseUrl = 'https://ssd-api.jpl.nasa.gov/periodic_orbits.api';
      
      // Transform parameter names from underscore to hyphenated format
      const transformedParams = transformParamsToHyphenated(args);
      
      // Make the API request using GET with parameters
      const response = await axios.get(baseUrl, { params: transformedParams });
      const data = response.data;
      
      // Create a resource URI 
      // Example: jpl://periodic-orbits?sys=earth-moon&family=halo&libr=1&branch=N
      let resourceUri = `jpl://periodic-orbits?sys=${encodeURIComponent(args.sys)}&family=${encodeURIComponent(args.family)}`;
      let resourceName = `Periodic Orbits: ${args.sys} / ${args.family}`;
      if (args.libr) {
        resourceUri += `&libr=${args.libr}`;
        resourceName += ` / L${args.libr}`;
      }
      if (args.branch) {
        resourceUri += `&branch=${encodeURIComponent(args.branch)}`;
        resourceName += ` / Branch ${args.branch}`;
      }
      // Potentially add filter params to URI/Name if needed for uniqueness
  
      // Add response to resources
      addResource(resourceUri, {
        name: resourceName,
        mimeType: "application/json", 
        text: JSON.stringify(data, null, 2)
      });
      
      // Format the response for MCP
      return {
        content: [{
          type: "text",
          text: JSON.stringify(data, null, 2)
        }]
      };
    } catch (error: any) {
      let errorMessage = `Error accessing JPL Periodic Orbits 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/handlers/jpl/periodic_orbits.ts:8-20 (schema)

  TypeScript interface defining the input parameters for the periodicOrbitsHandler, matching the JPL API parameters.

  interface PeriodicOrbitParams {
    sys: string;
    family: string;
    libr?: number;
    branch?: string;
    periodmin?: number;
    periodmax?: number;
    periodunits?: string;
    jacobimin?: number;
    jacobimax?: number;
    stabmin?: number;
    stabmax?: number;
  }

• src/index.ts:1349-1380 (registration)

  Tool registration in tools/list endpoint defining the tool name 'jpl_periodic_orbits' and its input schema.

    name: "jpl_periodic_orbits",
    description: "JPL Three-Body Periodic Orbits Database",
    inputSchema: {
      type: "object",
      properties: {
        sys: {
          type: "string",
          description: "Three-body system (e.g., earth-moon, sun-earth)"
        },
        family: {
          type: "string",
          description: "Orbit family name (e.g., halo, dro, lyapunov)"
        },
        libr: {
          type: "integer",
          description: "Libration point (1-5, required for some families)"
        },
        branch: {
          type: "string",
          description: "Branch within family (N/S, E/W, etc., required for some families)"
        },
        periodmin: { type: "number", description: "Minimum period" },
        periodmax: { type: "number", description: "Maximum period" },
        periodunits: { type: "string", description: "Units for period (s, h, d, TU)", enum: ["s", "h", "d", "TU"] },
        jacobimin: { type: "number", description: "Minimum Jacobi constant" },
        jacobimax: { type: "number", description: "Maximum Jacobi constant" },
        stabmin: { type: "number", description: "Minimum stability index" },
        stabmax: { type: "number", description: "Maximum stability index" }
      },
      required: ["sys", "family"]
    }
  },

• src/index.ts:2160-2166 (registration)

  Global MCP tool registration for 'mcp__jplperiodic_orbits' that routes to the JPL periodic orbits handler.

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