Nodit MCP Server

Instructions

Implementation Reference

• src/tools/aptos-indexer.ts:132-207 (handler)

  The complete server.tool registration block defining the 'call_nodit_aptos_indexer_api' tool, including its name, description, Zod input schema, and the full handler function that executes the GraphQL API call to the Nodit Aptos Indexer with authentication, timeout handling, detailed error responses for common status codes, and JSON response parsing.

  server.tool(
    "call_nodit_aptos_indexer_api",
    "Calls a Nodit Aptos Indexer API. Returns the API response. Before making the call, it's recommended to verify the detailed API specifications using the 'get_nodit_aptos_indexer_api_spec' tool. Please note that using this tool will consume your API quota.",
    {
        network: z.string().describe("Nodit network to call. e.g. 'mainnet' or 'testnet'."),
        requestBody: z.record(z.any()).describe("Graphql request body matching the API's spec."),
    },
    async ({ network, requestBody }) => {
      const toolName = "call_nodit_aptos_indexer_api";
      const apiKey = process.env.NODIT_API_KEY;
      if (!apiKey) {
        return createErrorResponse(`NODIT_API_KEY environment variable is not set. It is required to call nodit api. Please check your mcp server configuration.`, toolName);
      }
  
      const apiUrl = `https://aptos-${network}.nodit.io/v1/graphql`;
      const { signal, cleanup } = createTimeoutSignal(TIMEOUT_MS);
  
      try {
        const apiOptions: RequestInit = {
          method: 'POST',
          headers: {
            'X-API-KEY': apiKey,
            'Accept': 'application/json',
            'Content-Type': 'application/json',
            'User-Agent': 'nodit-mcp-server',
          },
          body: JSON.stringify(requestBody),
          signal,
        };
  
        log(`Calling Aptos Indexer GraphQL API: ${apiUrl}, apiOptions: ${JSON.stringify(apiOptions, null, 2)}`);
  
        const response = await fetch(apiUrl, apiOptions);
        const responseBodyText = await response.text();
  
        if (!response.ok) {
          const statusMessages: Record<number, string> = {
            400: `${responseBodyText}. Help the user identify what went wrong in their request. Explain the likely issue based on the error message, and provide a corrected example if possible.`,
            403: `${responseBodyText}. Let the user know that this API is only available to paid plan users. Explain that their current plan does not include access, and suggest upgrading to a paid tier via https://nodit.io/pricing .`,
            404: `${responseBodyText}. Let the user know that no data was found for the provided ID or address. This usually means the resource doesn't exist or hasn't been indexed yet. Suggest double-checking the input or trying again later.`,
            429: `${responseBodyText}. Inform the user that they've reached their current plan's usage limit. Recommend reviewing their usage or upgrading via https://nodit.io/pricing. Optionally mention the Referral Program: https://developer.nodit.io/docs/referral-program.`,
            500: `${responseBodyText}. This is not the user's fault. Let them know it's likely a temporary issue. Suggest retrying soon or contacting support at https://developer.nodit.io/discuss if the problem continues.`,
            503: `${responseBodyText}. Inform the user that the service may be under maintenance or experiencing high load. Suggest retrying shortly, and checking the Notice section in the Nodit Developer Portal (https://developer.nodit.io).`
          };
  
          if (statusMessages[response.status]) {
            return createErrorResponse(statusMessages[response.status], toolName);
          }
  
          let errorDetails = `Raw error response: ${responseBodyText}`;
          try {
            const errorJson = JSON.parse(responseBodyText);
            errorDetails = `Error Details (JSON):\n${JSON.stringify(errorJson, null, 2)}`;
          } catch (e) { /* ignore parsing error, use raw text */ }
          return createErrorResponse(`API Error (Status ${response.status}). ${errorDetails}`, toolName);
        }
  
        try {
          JSON.parse(responseBodyText);
          log(`Tool (${toolName}): API Success (${response.status})`);
          return { content: [{ type: "text", text: responseBodyText }] };
        } catch (parseError) {
          return createErrorResponse(`API returned OK status but body was not valid JSON. Raw response: ${responseBodyText}`, toolName);
        }
  
      } catch (error) {
        let message = (error as Error).message;
        if (error instanceof Error && error.name === 'AbortError') {
          message = `The request took longer than expected and has been terminated. This may be due to high server load or because the requested data is taking longer to process. Please try again later.`;
        }
        return createErrorResponse(`Network/fetch error calling API: ${message}`, toolName);
      } finally {
        cleanup()
      }
    }
  );

• src/tools/aptos-indexer.ts:135-138 (schema)

  Zod schema defining the input parameters for the tool: 'network' (string, e.g., 'mainnet' or 'testnet') and 'requestBody' (arbitrary record for GraphQL query/mutation).

  {
      network: z.string().describe("Nodit network to call. e.g. 'mainnet' or 'testnet'."),
      requestBody: z.record(z.any()).describe("Graphql request body matching the API's spec."),
  },

• src/tools/index.ts:15-15 (registration)

  Registration call within registerAllTools that invokes registerAptosIndexerTools(server), thereby registering the 'call_nodit_aptos_indexer_api' tool among others.

  registerAptosIndexerTools(server);

• src/index.ts:16-16 (registration)

  Top-level server registration call to registerAllTools(server), which chains to the aptos indexer tools registration including the target tool.

  registerAllTools(server);