@noditlabs/nodit-mcp-server 1.0.5 → 1.0.7

package/README.md

@@ -17,12 +17,24 @@ Nodit MCP Server simplifies how AI models and applications interact with blockch
 Instead of handling complex node RPCs, raw event logs, or chain-specific data structures, developers can access normalized, multi-chain blockchain data in a format optimized for AI reasoning and decision-making.
 
 With Nodit's MCP, you can:
-- Build AI agents that query, analyze, and act on real-time blockchain data across EVM-compatible and non-EVM networks.
-- Create Web3-integrated applications without requiring specialized blockchain development expertise.
-- Leverage Nodit's reliable node infrastructure, Web3 Data APIs, and GraphQL indexing services through a unified access layer.
+- Build AI agents that **query, analyze, and act on real-time blockchain data** across EVM-compatible and non-EVM networks.
+- **Develope Web3-integrated applications** without requiring specialized blockchain development expertise.
+- Leverage Nodit's **reliable node infrastructure, Web3 Data APIs, and GraphQL indexing services** through a unified access layer.
+- Easily develop with blockchain MCP in **both local and remote integration**, depending on your workflow needs.
 
 Supported networks include Ethereum, Base, Optimism, Arbitrum, Polygon, Aptos, Bitcoin, Dogecoin, TRON, XRPL, and more.
 
+## Table of Contents
+- [How Nodit MCP Tools Work](#how-nodit-mcp-tools-work)
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Running Local Nodit MCP Server](#running-local-nodit-mcp-server)
+- [Integrating Nodit Remote MCP Server](#integrating-nodit-remote-mcp-server)
+- [Troubleshooting](#troubleshooting)
+- [Example Prompts with Nodit MCP](#example-prompts-with-nodit-mcp)
+- [Scope & Limitations](#scope--limitations)
+- [License](#license)
+
 ## How Nodit MCP Tools Work
 
 Nodit MCP Server provides tools enabling AI agents to dynamically discover, understand, and interact with Nodit's Web3 APIs and data infrastructure. The tools minimize token consumption and maintain a lightweight context by modularizing API interactions into distinct steps:
@@ -30,10 +42,10 @@ Nodit MCP Server provides tools enabling AI agents to dynamically discover, unde
 - **List API Categories (`list_nodit_api_categories`)**  
   Retrieve a list of high-level API categories available.
 
-- **List API Operations (`list_nodit_node_apis`, `list_nodit_data_apis`, `list_nodit_aptos_indexer_api_query_root`)**  
-  Fetch available operations within a selected category (Node APIs, Data APIs, Aptos Indexer APIs).
+- **List API Operations (`list_nodit_node_apis`, `list_nodit_data_apis`, `list_nodit_aptos_indexer_api_query_root`,`list_nodit_webhook_apis`)**  
+  Fetch available operations within a selected category (Node APIs, Data APIs, Aptos Indexer APIs, Webhook APIs).
 
-- **Get API Specification (`get_nodit_api_spec`)**  
+- **Get API Specification (`get_nodit_api_spec`,`get_nodit_aptos_indexer_api_spec`)**  
   Obtain detailed information for a specific API operation (parameters, request/response schema).
 
 - **Call API (`call_nodit_api`,`call_nodit_aptos_indexer_api`)**  
@@ -130,8 +142,6 @@ echo '{"method":"tools/list","params":{},"jsonrpc":"2.0","id":1}' | node build/i
 echo '{"method":"tools/call","params":{"name":"list_nodit_api_categories","arguments":{}},"jsonrpc":"2.0","id":1}' | node build/index.js
 ```
 
-## Integration 
-
 ### Connecting to Cursor IDE or Claude Desktop
 
 Add the following configuration to your `.cursor/mcp.json` or `claude_desktop_config.json`:
@@ -177,6 +187,121 @@ export NODIT_API_KEY=your-api-key
 # Start Claude with the Nodit MCP server enabled
 claude
 ```
+## Integrating Nodit Remote MCP Server
+If you’re using an AI tool that supports Remote MCP integration, you can connect to Nodit’s Remote MCP Server without running a local MCP server.
+This allows you to use Nodit MCP features directly within your AI environment.
+
+### Endpoint
+Use the following endpoint to connect to the Nodit Remote MCP Server. Make sure to replace INSERT_YOUR_API_KEY with your actual Nodit API Key.
+
+```bash
+https://mcp.nodit.io/sse?apiKey=INSERT_YOUR_API_KEY
+```
+
+### Connecting to Claude (Web)
+If you’re on the Claude Enterprise, Pro, or Max plan, you can integrate the Remote MCP Server. 
+
+1. Go to Settings > Integrations, click the [Add custom integration] button.
+2. Click the [Add more] button to integrate the new Remote MCP.
+3. Insert the endpoint provided above to complete the setup.
+
+Once the integration is complete, you’ll see that Nodit MCP has been added under the Search and Tools section on the Claude main screen.
+
+### Connecting to Cursor IDE
+To connect Nodit MCP to Cursor IDE:
+	1.	Open Preferences > Cursor Settings > MCP Tools.
+	2.	Click [+ New MCP Server] to open the mcp.json configuration file.
+
+You can also open and edit the mcp.json file directly at the following path:
+  - MacOS: `~/.cursor/mcp.json`
+  - Windows: `C:\Users\<Username>\.cursor\mcp.json`
+
+Add the following configuration to the mcpServers object. If you already have other MCP servers configured, separate each entry with a comma.
+```json
+{
+  "mcpServers": {
+    "nodit": {
+      "url": "https://mcp.nodit.io/sse?apiKey=INSERT_YOUR_API_KEY"
+    }
+  }
+}
+```
+Once added, go back to MCP Tools in the Cursor interface and enable the nodit MCP by toggling it on. When the status shows “9 tools enabled” in green, the connection is complete.
+
+## Troubleshooting
+### Trouble running MCP via npx on Claude Desktop
+If you are running the MCP server in combination with **Claude Desktop** or other tools that rely on a local Node.js installation, you may encounter issues due to:
+* Multiple versions of Node.js installed (e.g., via Homebrew and package installer)
+* Conflicting PATH environments
+* Claude Desktop not recognizing the correct Node.js runtime
+
+Follow the steps below to verify that **Node.js 18+** is properly installed and recognized on your system.
+
+#### 1. Check your currently active Node.js version
+Run the following command in your terminal to check the version:
+```
+node --version
+```
+You should see a version number starting with v18 or higher (e.g., v18.19.0).
+
+If not, you may need to install a compatible version or switch to it.
+
+> [!TIP] 
+> Claude Desktop may not use the same Node.js version as your terminal. If you have multiple installations (e.g., via Homebrew, nvm, or direct installer), it may default to an unexpected version.
+> To list all common installation paths:
+> ```
+> # Homebrew installation
+> ls /usr/local/bin/node
+> ls /opt/homebrew/bin/node
+> 
+> # nvm installations
+> ls ~/.nvm/versions/node/
+> 
+> # System installation
+> ls /usr/bin/node
+> ```
+
+#### 2. Install or switch to Node.js 18+ if needed
+If you don’t have a compatible version, install Node.js using one of the following methods:
+
+* Using Node.js official installer: Download from nodejs.org
+* Using Homebrew (macOS):
+```  
+bashbrew install node@20
+```
+* Using nvm (recommended for version management):
+```
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 20
+nvm use 20
+nvm alias default 20
+```
+
+#### 3. Check which Node.js version Claude Desktop uses
+Claude Desktop inherits the PATH from your system environment.
+In your terminal, run:
+```
+which node
+```
+This displays the path of the Node.js binary currently active in your terminal. This is the path that Claude is likely to use when launched from that terminal.
+
+#### 4. Force Claude Desktop to use the correct Node.js version
+* If you’re using nvm:
+```
+nvm use 18  # Set proper version 
+nvm alias default 18
+```
+
+* If you’re using Homebrew, ensure it’s prioritized in your PATH:
+```
+export PATH="/opt/homebrew/bin:$PATH"  # for Apple Silicon
+# or
+export PATH="/usr/local/bin:$PATH"     # for Intel Macs
+```
+We recommend sticking to a single installation method (e.g., either nvm or Homebrew) to avoid version conflicts.
+
+#### 5. Restart Claude Desktop
+After making changes, restart Claude Desktop to ensure it picks up the correct environment variables and Node.js version.
 
 ## Example Prompts with Nodit MCP
 Once Nodit MCP is connected, you can use natural language to directly query blockchain data from multiple networks.

package/build/helper/nodit-apidoc-helper.js

@@ -11,6 +11,10 @@ export function loadNoditDataApiSpec() {
     const specPath = path.resolve(__dirname, '../spec/reference/web3-data-api.yaml');
     return loadOpenapiSpecFile(specPath);
 }
+export function loadNoditWebhookApiSpec() {
+    const specPath = path.resolve(__dirname, '../spec/reference/webhook.yaml');
+    return loadOpenapiSpecFile(specPath);
+}
 export function loadNoditNodeApiSpecMap() {
     const noditApiSpecMap = new Map();
     const specDir = path.resolve(__dirname, '../spec/reference');
@@ -55,6 +59,9 @@ export function isNodeApi(operationId) {
 export function isEthereumNodeApi(operationId) {
     return !operationId.includes("-");
 }
+export function isWebhookApi(operationId) {
+    return operationId.includes("Webhook");
+}
 export function findNoditNodeApiSpec(operationId, noditNodeApiSpecMap) {
     let key = operationId;
     if (isEthereumNodeApi(operationId)) {
@@ -101,14 +108,35 @@ export function findNoditDataApiDetails(operationId, spec) {
 }
 export function findNoditNodeApiDetails(operationId, specMap) {
     const spec = findNoditNodeApiSpec(operationId, specMap);
-    if (!spec) {
-        return null;
+    if (spec && spec.paths['/']?.post) {
+        return {
+            path: '/',
+            method: 'post',
+            details: spec.paths['/']?.post
+        };
+    }
+    return null;
+}
+export function findNoditWebhookApiDetails(operationId, spec) {
+    for (const [path, pathItem] of Object.entries(spec.paths)) {
+        const methods = [
+            { method: 'get', operation: pathItem.get },
+            { method: 'post', operation: pathItem.post },
+            { method: 'put', operation: pathItem.put },
+            { method: 'patch', operation: pathItem.patch },
+            { method: 'delete', operation: pathItem.delete }
+        ];
+        for (const { method, operation } of methods) {
+            if (operation?.operationId === operationId) {
+                return {
+                    path,
+                    method,
+                    details: operation
+                };
+            }
+        }
     }
-    return {
-        path: '/',
-        method: 'post',
-        details: spec.paths['/']?.post
-    };
+    return null;
 }
 export function createErrorResponse(message, toolName) {
     log(`Tool Error (${toolName}): ${message}`);