Installation

You can install the Neo N3 MCP Server using npm:

npm install @r3e/neo-n3-mcp

For global installation:

npm install -g @r3e/neo-n3-mcp

Requirements

• Node.js v14 or later
• npm v6 or later

Configuration

The Neo N3 MCP Server can be configured through environment variables or a configuration file.

Environment Variables

Configuration File

You can also provide a configuration file at ~/.neo-n3-mcp/config.json:

{
  "port": 3000,
  "network": "mainnet",
  "mainnetRpcUrl": "https://mainnet1.neo.coz.io:443",
  "testnetRpcUrl": "https://testnet1.neo.coz.io:443",
  "walletPath": "./wallets"
}

Running the Server

Start the server using the following command:

npx neo-n3-mcp

By default, the server will run on port 8080. You can customize this by setting the NEO_MCP_PORT environment variable:

NEO_MCP_PORT=3000 npx neo-n3-mcp

You should see output similar to:

Neo N3 MCP Server started on port 8080
Mainnet RPC: https://mainnet1.neo.coz.io:443
Testnet RPC: https://testnet1.neo.coz.io:443
Log level: info

LangChain Integration

LangChain is a framework for developing applications powered by language models. You can integrate the Neo N3 MCP Server with LangChain to create AI applications that can interact with the Neo N3 blockchain.

Installation

npm install langchain @modelcontextprotocol/sdk @r3e/neo-n3-mcp

Basic Integration

import { ChatOpenAI } from 'langchain/chat_models/openai';
import { Client } from '@modelcontextprotocol/sdk/client';
import { createMcpAgent } from '@langchain/mcp';

// Initialize the LLM
const llm = new ChatOpenAI({
  modelName: 'gpt-4',
  temperature: 0
});

// Initialize the MCP client
const mcpClient = new Client({
  url: 'http://localhost:8080'
});

// Create an agent with MCP tools
const agent = createMcpAgent({
  llm,
  mcpClient,
  tools: ['get_blockchain_info', 'get_balance', 'list_famous_contracts']
});

// Run the agent
const result = await agent.invoke({
  input: 'What is the current block height of the Neo N3 mainnet?'
});

console.log(result.output);

Advanced Integration

For more advanced integration, you can create custom tools that combine multiple MCP tools:

import { ChatOpenAI } from 'langchain/chat_models/openai';
import { Client } from '@modelcontextprotocol/sdk/client';
import { createMcpAgent } from '@langchain/mcp';
import { DynamicTool } from 'langchain/tools';

// Initialize the LLM
const llm = new ChatOpenAI({
  modelName: 'gpt-4',
  temperature: 0
});

// Initialize the MCP client
const mcpClient = new Client({
  url: 'http://localhost:8080'
});

// Create a custom tool that combines multiple MCP tools
const getAccountInfoTool = new DynamicTool({
  name: 'get_account_info',
  description: 'Get detailed information about a Neo N3 account, including balances for NEO, GAS, and bNEO',
  func: async (address) => {
    // Get NEO balance
    const neoBalance = await mcpClient.callTool('get_balance', {
      address,
      asset: 'NEO',
      network: 'mainnet'
    });
    
    // Get GAS balance
    const gasBalance = await mcpClient.callTool('get_balance', {
      address,
      asset: 'GAS',
      network: 'mainnet'
    });
    
    // Get bNEO balance
    const bNeoBalance = await mcpClient.callTool('neoburger_get_balance', {
      address,
      network: 'mainnet'
    });
    
    return JSON.stringify({
      address,
      balances: {
        neo: neoBalance.amount,
        gas: gasBalance.amount,
        bNeo: bNeoBalance.amount
      }
    });
  }
});

// Create an agent with MCP tools and custom tools
const agent = createMcpAgent({
  llm,
  mcpClient,
  tools: ['get_blockchain_info', 'list_famous_contracts'],
  additionalTools: [getAccountInfoTool]
});

// Run the agent
const result = await agent.invoke({
  input: 'What are the balances for the account NXV7ZhHaLY2GNjp6R1AYBV9FqrVnGLfQcz?'
});

console.log(result.output);

LlamaIndex Integration

LlamaIndex is a data framework for LLM applications. You can integrate the Neo N3 MCP Server with LlamaIndex to create AI applications that can retrieve and process blockchain data.

Installation

npm install llamaindex openai @modelcontextprotocol/sdk @r3e/neo-n3-mcp

Basic Integration

import { VectorStoreIndex, SimpleDirectoryReader } from 'llamaindex';
import { OpenAI } from 'llamaindex/llms/openai';
import { Client } from '@modelcontextprotocol/sdk/client';

// Initialize the LLM
const llm = new OpenAI({
  model: 'gpt-4',
  temperature: 0
});

// Initialize the MCP client
const mcpClient = new Client({
  url: 'http://localhost:8080'
});

// Create custom Neo N3 tools
const neoTools = {
  getBlockchainInfo: async () => {
    return await mcpClient.callTool('get_blockchain_info', {
      network: 'mainnet'
    });
  },
  
  getBalance: async (address, asset = 'NEO') => {
    return await mcpClient.callTool('get_balance', {
      address,
      asset,
      network: 'mainnet'
    });
  }
};

// Create a query engine with our tools
const queryEngine = await VectorStoreIndex.fromDocuments(
  await new SimpleDirectoryReader().loadData('./docs'),
  { llm }
);

// Augment the query engine with Neo N3 tools
const augmentedQueryEngine = queryEngine.asQueryEngine({
  tools: [
    {
      name: 'neo_get_blockchain_info',
      description: 'Get blockchain information from Neo N3',
      func: neoTools.getBlockchainInfo
    },
    {
      name: 'neo_get_balance',
      description: 'Get asset balance for a Neo N3 address',
      func: neoTools.getBalance
    }
  ]
});

// Query the engine
const response = await augmentedQueryEngine.query(
  'What is the current block height of Neo N3 and the NEO balance of address NXV7ZhHaLY2GNjp6R1AYBV9FqrVnGLfQcz?'
);

console.log(response.toString());

Custom Integration

You can also integrate the Neo N3 MCP Server directly into your custom AI systems using the MCP SDK.

Installation

npm install @modelcontextprotocol/sdk @r3e/neo-n3-mcp

Basic Integration

import { Client } from '@modelcontextprotocol/sdk/client';

// Initialize the MCP client
const mcpClient = new Client({
  url: 'http://localhost:8080'
});

// List available tools
const tools = await mcpClient.listTools();
console.log('Available tools:', tools);

// Call a tool
async function callNeoTool(toolName, params) {
  try {
    const result = await mcpClient.callTool(toolName, params);
    return result;
  } catch (error) {
    console.error(`Error calling tool ${toolName}:`, error);
    throw error;
  }
}

// Example: Get blockchain info
const blockchainInfo = await callNeoTool('get_blockchain_info', {
  network: 'mainnet'
});
console.log('Blockchain info:', blockchainInfo);

// Example: Get balance
const balance = await callNeoTool('get_balance', {
  address: 'NXV7ZhHaLY2GNjp6R1AYBV9FqrVnGLfQcz',
  asset: 'NEO',
  network: 'mainnet'
});
console.log('Balance:', balance);

Integrating into a Custom AI System

Here's an example of integrating the Neo N3 MCP Server into a custom AI system:

import { Client } from '@modelcontextprotocol/sdk/client';
import { OpenAI } from 'openai';

// Initialize the OpenAI API
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

// Initialize the MCP client
const mcpClient = new Client({
  url: 'http://localhost:8080'
});

// Function to handle blockchain queries
async function handleBlockchainQuery(query) {
  // Use the LLM to identify the intent
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [
      {
        role: 'system',
        content: 'You are a helpful assistant that answers questions about the Neo N3 blockchain.'
      },
      {
        role: 'user',
        content: `Identify the intent and parameters from this blockchain query: "${query}"`
      }
    ],
    response_format: { type: 'json_object' }
  });
  
  const intent = JSON.parse(response.choices[0].message.content);
  
  // Based on the intent, call the appropriate MCP tool
  switch (intent.action) {
    case 'get_blockchain_info':
      return await mcpClient.callTool('get_blockchain_info', {
        network: intent.network || 'mainnet'
      });
      
    case 'get_balance':
      return await mcpClient.callTool('get_balance', {
        address: intent.address,
        asset: intent.asset || 'NEO',
        network: intent.network || 'mainnet'
      });
      
    case 'get_contract_info':
      return await mcpClient.callTool('get_contract_info', {
        contractName: intent.contractName,
        network: intent.network || 'mainnet'
      });
      
    default:
      throw new Error(`Unknown intent: ${intent.action}`);
  }
}

// Example usage
const query = 'What is the current block height of Neo N3 mainnet?';
const result = await handleBlockchainQuery(query);
console.log(result);

Blockchain Chatbot

Create a chatbot that can answer questions about the Neo N3 blockchain.

import { ChatOpenAI } from 'langchain/chat_models/openai';
import { Client } from '@modelcontextprotocol/sdk/client';
import { createMcpAgent } from '@langchain/mcp';

// Initialize the LLM
const llm = new ChatOpenAI({
  modelName: 'gpt-4',
  temperature: 0
});

// Initialize the MCP client
const mcpClient = new Client({
  url: 'http://localhost:8080'
});

// Create an agent with MCP tools
const agent = createMcpAgent({
  llm,
  mcpClient,
  tools: [
    'get_blockchain_info',
    'get_block',
    'get_transaction',
    'get_balance',
    'list_famous_contracts',
    'get_contract_info'
  ]
});

// Create a chatbot interface
async function handleChatMessage(message) {
  try {
    const result = await agent.invoke({
      input: message
    });
    
    return result.output;
  } catch (error) {
    console.error('Error handling chat message:', error);
    return 'Sorry, I encountered an error while processing your request.';
  }
}

// Example usage
const response = await handleChatMessage(
  'What is the current block height and when was the last block mined?'
);
console.log(response);

NFT Creation Assistant

Create an assistant that helps users create and list NFTs on GhostMarket.

import { ChatOpenAI } from 'langchain/chat_models/openai';
import { Client } from '@modelcontextprotocol/sdk/client';
import { createMcpAgent } from '@langchain/mcp';

// Initialize the LLM
const llm = new ChatOpenAI({
  modelName: 'gpt-4',
  temperature: 0
});

// Initialize the MCP client
const mcpClient = new Client({
  url: 'http://localhost:8080'
});

// Create an agent with MCP tools
const agent = createMcpAgent({
  llm,
  mcpClient,
  tools: [
    'ghostmarket_create_nft',
    'ghostmarket_list_nft',
    'ghostmarket_get_token_info'
  ]
});

// Create a function to handle NFT creation
async function createAndListNFT(walletPath, walletPassword, tokenURI, properties, price, paymentToken) {
  try {
    // Create the NFT
    const nftResult = await mcpClient.callTool('ghostmarket_create_nft', {
      walletPath,
      walletPassword,
      tokenURI,
      properties,
      network: 'mainnet'
    });
    
    const tokenId = nftResult.tokenId;
    
    // List the NFT for sale
    const listingResult = await mcpClient.callTool('ghostmarket_list_nft', {
      walletPath,
      walletPassword,
      tokenId,
      price,
      paymentToken,
      network: 'mainnet'
    });
    
    return {
      nft: nftResult,
      listing: listingResult
    };
  } catch (error) {
    console.error('Error creating and listing NFT:', error);
    throw error;
  }
}

// Example usage
const result = await createAndListNFT(
  '/path/to/wallet.json',
  'your-password',
  'https://example.com/nft/metadata.json',
  [
    { key: 'artist', value: 'ExampleArtist' },
    { key: 'edition', value: '1/1' }
  ],
  '100',
  '0xd2a4cff31913016155e38e474a2c06d08be276cf'
);
console.log(result);

DeFi Advisor

Create an advisor that helps users optimize their DeFi investments on Neo N3.

import { ChatOpenAI } from 'langchain/chat_models/openai';
import { Client } from '@modelcontextprotocol/sdk/client';
import { createMcpAgent } from '@langchain/mcp';

// Initialize the LLM
const llm = new ChatOpenAI({
  modelName: 'gpt-4',
  temperature: 0
});

// Initialize the MCP client
const mcpClient = new Client({
  url: 'http://localhost:8080'
});

// Create an agent with MCP tools
const agent = createMcpAgent({
  llm,
  mcpClient,
  tools: [
    'get_balance',
    'neoburger_get_balance',
    'flamingo_get_balance',
    'neocompound_get_balance'
  ]
});

// Create a function to get a user's portfolio
async function getUserPortfolio(address) {
  try {
    // Get NEO balance
    const neoBalance = await mcpClient.callTool('get_balance', {
      address,
      asset: 'NEO',
      network: 'mainnet'
    });
    
    // Get GAS balance
    const gasBalance = await mcpClient.callTool('get_balance', {
      address,
      asset: 'GAS',
      network: 'mainnet'
    });
    
    // Get bNEO balance
    const bNeoBalance = await mcpClient.callTool('neoburger_get_balance', {
      address,
      network: 'mainnet'
    });
    
    // Get FLM balance
    const flmBalance = await mcpClient.callTool('flamingo_get_balance', {
      address,
      network: 'mainnet'
    });
    
    return {
      address,
      balances: {
        neo: neoBalance.amount,
        gas: gasBalance.amount,
        bNeo: bNeoBalance.amount,
        flm: flmBalance.amount
      }
    };
  } catch (error) {
    console.error('Error getting user portfolio:', error);
    throw error;
  }
}

// Create a function to recommend DeFi strategies
async function recommendDeFiStrategies(address) {
  const portfolio = await getUserPortfolio(address);
  
  // Use the LLM to generate recommendations
  const response = await llm.invoke([
    {
      role: 'system',
      content: 'You are a DeFi advisor for Neo N3. Generate investment recommendations based on the user\'s portfolio.'
    },
    {
      role: 'user',
      content: `Here is the user's portfolio: ${JSON.stringify(portfolio, null, 2)}\n\nWhat DeFi strategies would you recommend?`
    }
  ]);
  
  return response.content;
}

// Example usage
const recommendations = await recommendDeFiStrategies('NXV7ZhHaLY2GNjp6R1AYBV9FqrVnGLfQcz');
console.log(recommendations);

Local Deployment

The simplest deployment option is to run the Neo N3 MCP Server locally.

Running as a Background Process

You can use tools like PM2 to run the server as a background process:

# Install PM2
npm install -g pm2

# Start the server
pm2 start "npx neo-n3-mcp" --name neo-n3-mcp

# Check status
pm2 status

# View logs
pm2 logs neo-n3-mcp

# Stop the server
pm2 stop neo-n3-mcp

Cloud Deployment

You can deploy the Neo N3 MCP Server to cloud platforms like AWS, Azure, or GCP.

AWS Deployment

Here's an example of deploying to AWS EC2:

1. Launch an EC2 instance with Node.js installed
2. Clone your Neo N3 MCP Server repository
3. Install dependencies: npm install
4. Start the server: npm start

Heroku Deployment

Here's an example of deploying to Heroku:

1. Create a Procfile with the content: web: npm start
2. Create a Heroku app: heroku create
3. Set environment variables: heroku config:set NEO_MAINNET_RPC_URL=https://mainnet1.neo.coz.io:443
4. Deploy to Heroku: git push heroku main

Containerization

You can containerize the Neo N3 MCP Server using Docker.

Dockerfile

FROM node:16-alpine

WORKDIR /app

# Copy package.json and package-lock.json
COPY package*.json ./

# Install dependencies
RUN npm install

# Copy source code
COPY . .

# Set environment variables
ENV NEO_MAINNET_RPC_URL=https://mainnet1.neo.coz.io:443
ENV NEO_TESTNET_RPC_URL=https://testnet1.neo.coz.io:443
ENV NEO_MCP_PORT=8080

# Expose port
EXPOSE 8080

# Start the server
CMD ["npm", "start"]

Docker Compose

version: '3'

services:
  neo-n3-mcp:
    build: .
    ports:
      - "8080:8080"
    environment:
      - NEO_MAINNET_RPC_URL=https://mainnet1.neo.coz.io:443
      - NEO_TESTNET_RPC_URL=https://testnet1.neo.coz.io:443
      - NEO_MCP_PORT=8080
    volumes:
      - ./wallets:/app/wallets