Nodit MCP Server

Instructions

Implementation Reference

• src/tools/node-apis.ts:10-85 (handler)

  The core handler function for the 'list_nodit_node_apis' tool. It loads the API spec map, extracts operationIds from POST paths, categorizes them into common methods (eth_, net_, web3_) and chain-specific, formats a detailed text response listing all available operations with usage notes, and handles errors.

    server.tool("list_nodit_node_apis", "Lists available Nodit API operations.", {}, async () => {
      const toolName = "list_nodit_node_apis";
      try {
        const apiList = Array.from(noditNodeApiSpecMap.entries())
          .filter(([, spec]) => spec?.paths)
          .flatMap(([, spec]) =>
            Object.entries(spec.paths)
              .filter(([, pathItem]) => pathItem?.post?.operationId)
              .map(([pathKey, pathItem]) => ({
                operationId: pathItem!.post!.operationId!,
                path: pathKey
              }))
          )
  
        const commonMethods: typeof apiList = [];
        const chainSpecificMethods: typeof apiList = [];
        const chainsWithCommonMethods = new Set<string>();
  
        apiList.forEach(api => {
          const operationId = api.operationId;
          const methodName = operationId.includes('-') ? operationId.split('-')[1] : operationId;
  
          let chain = 'ethereum';
          if (operationId.includes('-')) {
            chain = operationId.split('-')[0];
          }
  
          if (methodName.startsWith('eth_') || methodName.startsWith('net_') || methodName.startsWith('web3_')) {
            chainsWithCommonMethods.add(chain);
  
            if (!commonMethods.some(item => {
              const itemMethod = item.operationId.includes('-') ? item.operationId.split('-')[1] : item.operationId;
              return itemMethod === methodName;
            })) {
              commonMethods.push(api);
            }
          } else {
            chainSpecificMethods.push(api);
          }
        });
  
        const formattedCommonList = commonMethods
          .map(api => {
            const methodName = api.operationId.includes('-') ? api.operationId.split('-')[1] : api.operationId;
            return `  - operationId: ${methodName}`;
          })
          .join("\n");
  
        const formattedSpecificList = chainSpecificMethods
          .map(api => `  - operationId: ${api.operationId}`)
          .join("\n");
  
        const supportedChains = Array.from(chainsWithCommonMethods).sort().join(', ');
  
        const content = `Nodit Blockchain Context has endpoints with patterns like https://{chain}-{network}.nodit.io. For example, Ethereum mainnet uses an endpoint like https://ethereum-mainnet.nodit.io
  and accepts input in the form of widely known requestBody argument such as { "jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": [] }.
  **Important: To ensure the tool 'call_nodit_api' works correctly and to avoid errors, you should first use the tool 'get_nodit_api_spec' to obtain detailed API specifications. Depending on the situation, you may omit using the get_nodit_api_spec tool, but it is recommended to use it on the first call.**
  The API list is as follows.
  **Important: Nodit Blockchain Context's operationId format rules**
  - Ethereum network: No prefix (e.g., operationId="eth_blockNumber")
  - All other chains: Use the format {chain}-{operationId} (e.g., operationId="polygon-eth_blockNumber")
  - Make sure to use 'call_nodit_api' with the correct chain, network, and operationId.
  - These operationId format rules are relevant only when using the tool, not when directly using the API.
  - Common Methods (supported by most chains, use with appropriate chain name):
  ${formattedCommonList}
  - Chains supporting common methods: ${supportedChains}
  - Chain-Specific Methods (use with the specified chain):
  ${formattedSpecificList}
  Note: You can use these APIs with any supported chain by simply replacing the chain name in the endpoint URL.
  `
  
        return { content: [{ type: "text", text: content }] };
      } catch (error) {
        return createErrorResponse(`Failed to list APIs: ${(error as Error).message}`, toolName);
      }
    });

• src/tools/node-apis.ts:8-87 (registration)

  The registerNodeApiTools function defines and registers the 'list_nodit_node_apis' tool on the MCP server using server.tool.

  export function registerNodeApiTools(server: McpServer) {
    const noditNodeApiSpecMap: Map<string, NoditOpenApiSpecType> = loadNoditNodeApiSpecMap();
    server.tool("list_nodit_node_apis", "Lists available Nodit API operations.", {}, async () => {
      const toolName = "list_nodit_node_apis";
      try {
        const apiList = Array.from(noditNodeApiSpecMap.entries())
          .filter(([, spec]) => spec?.paths)
          .flatMap(([, spec]) =>
            Object.entries(spec.paths)
              .filter(([, pathItem]) => pathItem?.post?.operationId)
              .map(([pathKey, pathItem]) => ({
                operationId: pathItem!.post!.operationId!,
                path: pathKey
              }))
          )
  
        const commonMethods: typeof apiList = [];
        const chainSpecificMethods: typeof apiList = [];
        const chainsWithCommonMethods = new Set<string>();
  
        apiList.forEach(api => {
          const operationId = api.operationId;
          const methodName = operationId.includes('-') ? operationId.split('-')[1] : operationId;
  
          let chain = 'ethereum';
          if (operationId.includes('-')) {
            chain = operationId.split('-')[0];
          }
  
          if (methodName.startsWith('eth_') || methodName.startsWith('net_') || methodName.startsWith('web3_')) {
            chainsWithCommonMethods.add(chain);
  
            if (!commonMethods.some(item => {
              const itemMethod = item.operationId.includes('-') ? item.operationId.split('-')[1] : item.operationId;
              return itemMethod === methodName;
            })) {
              commonMethods.push(api);
            }
          } else {
            chainSpecificMethods.push(api);
          }
        });
  
        const formattedCommonList = commonMethods
          .map(api => {
            const methodName = api.operationId.includes('-') ? api.operationId.split('-')[1] : api.operationId;
            return `  - operationId: ${methodName}`;
          })
          .join("\n");
  
        const formattedSpecificList = chainSpecificMethods
          .map(api => `  - operationId: ${api.operationId}`)
          .join("\n");
  
        const supportedChains = Array.from(chainsWithCommonMethods).sort().join(', ');
  
        const content = `Nodit Blockchain Context has endpoints with patterns like https://{chain}-{network}.nodit.io. For example, Ethereum mainnet uses an endpoint like https://ethereum-mainnet.nodit.io
  and accepts input in the form of widely known requestBody argument such as { "jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": [] }.
  **Important: To ensure the tool 'call_nodit_api' works correctly and to avoid errors, you should first use the tool 'get_nodit_api_spec' to obtain detailed API specifications. Depending on the situation, you may omit using the get_nodit_api_spec tool, but it is recommended to use it on the first call.**
  The API list is as follows.
  **Important: Nodit Blockchain Context's operationId format rules**
  - Ethereum network: No prefix (e.g., operationId="eth_blockNumber")
  - All other chains: Use the format {chain}-{operationId} (e.g., operationId="polygon-eth_blockNumber")
  - Make sure to use 'call_nodit_api' with the correct chain, network, and operationId.
  - These operationId format rules are relevant only when using the tool, not when directly using the API.
  - Common Methods (supported by most chains, use with appropriate chain name):
  ${formattedCommonList}
  - Chains supporting common methods: ${supportedChains}
  - Chain-Specific Methods (use with the specified chain):
  ${formattedSpecificList}
  Note: You can use these APIs with any supported chain by simply replacing the chain name in the endpoint URL.
  `
  
        return { content: [{ type: "text", text: content }] };
      } catch (error) {
        return createErrorResponse(`Failed to list APIs: ${(error as Error).message}`, toolName);
      }
    });
  
  }

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

  Top-level registration where registerNodeApiTools is imported and called as part of registerAllTools to register the tool on the server.

  import { registerNodeApiTools } from "./node-apis.js";
  import { registerDataApiTools } from "./data-apis.js";
  import { registerWebhookApiTools } from "./webhook-apis.js";
  import { registerAptosIndexerTools } from "./aptos-indexer.js";
  import { registerGetNoditApiSpecTool } from "./get-nodit-api-spec.js";
  import { registerCallNoditApiTool } from "./call-nodit-api.js";
  
  export function registerAllTools(server: McpServer) {
    registerApiCategoriesTools(server);
    registerNodeApiTools(server);

• src/helper/nodit-apidoc-helper.ts:69-129 (helper)

  Critical helper function that loads all Nodit node API OpenAPI specifications from YAML files in spec/reference directories (EVM, Sui, Solana), extracts operationIds, and builds a map used by the tool handler to list available APIs.

  export function loadNoditNodeApiSpecMap(): Map<string, NoditOpenApiSpecType> {
    const noditApiSpecMap = new Map<string, NoditOpenApiSpecType>();
    const specDir = path.resolve(__dirname, '../spec/reference');
  
    try {
      const files = fs.readdirSync(specDir);
  
      const evmSpecFiles = files.filter(file => file.startsWith('evm-') && file.endsWith('.yaml'));
  
      for (const file of evmSpecFiles) {
        const parts = file.replace('.yaml', '').split('-');
  
        if (parts.length >= 2) {
          const chain = parts[1];
          const filePath = path.join(specDir, file);
  
          try {
            const spec = loadOpenapiSpecFile(filePath) as NoditOpenApiSpecType;
            const operationId = spec.paths['/']!.post!.operationId;
            if (operationId) {
              const key = chain === 'ethereum' ? `ethereum-${operationId}` : operationId;
              noditApiSpecMap.set(key, spec);
            } else {
              log(`Could not extract operationId from spec file ${file}`);
            }
          } catch (error) {
            log(`Error loading spec file ${file}:`, error);
          }
        }
      }
  
      const suiNodeApiSpecDir = path.resolve(__dirname, '../spec/reference/sui-node-api');
      const suiNodeApiSpecFiles = fs.readdirSync(suiNodeApiSpecDir);
      for (const file of suiNodeApiSpecFiles) {
        if (file.endsWith('.yaml')) {
          const filePath = path.join(suiNodeApiSpecDir, file);
          const suiNodeApiSpecMap = loadMultiPathApiSpec(filePath);
          suiNodeApiSpecMap.forEach((spec, operationId) => {
            noditApiSpecMap.set(operationId, spec);
          });
        }
      }
  
      const solanaNodeApiSpecDir = path.resolve(__dirname, '../spec/reference/solana-node-api/http-methods');
      const solanaNodeApiSpecFiles = fs.readdirSync(solanaNodeApiSpecDir);
      for (const file of solanaNodeApiSpecFiles) {
        if (file.endsWith('.yaml')) {
          const filePath = path.join(solanaNodeApiSpecDir, file);
          const solanaNodeApiSpecMap = loadMultiPathApiSpec(filePath);
          solanaNodeApiSpecMap.forEach((spec, operationId) => {
            noditApiSpecMap.set(operationId, spec);
          });
        }
      }
  
      return noditApiSpecMap;
    } catch (error) {
      log('Error reading spec directory:', error);
      return new Map();
    }
  }

• src/helper/nodit-apidoc-helper.ts:321-324 (helper)

  Helper function used in the tool handler to create standardized error responses.

  export function createErrorResponse(message: string, toolName: string): { content: { type: "text"; text: string }[] } {
    log(`Tool Error (${toolName}): ${message}`);
    return { content: [{ type: "text" as const, text: `Tool Error: ${message}` }] };
  }