Neo N3 Protocol Integration Server

Advanced MCP Server for Neo N3 DLT Connectivity | Release Candidate v1.6.0

A high-performance, production-grade MCP node designed specifically for interfacing with the Neo N3 virtual machine. Features 34 distinct operational tools and exposes 9 structured resources covering ledger monitoring, transactional processing, identity management, and contract deployment/interaction.

🚀 Initial Deployment Guide

Installation Via NPM Registry

bash

Global installation for command-line utility access

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

Local dependency inclusion for project integration

npm install @r3e/neo-n3-mcp

Execution Primitives

bash

Initiate server utilizing default configuration parameters

npx @r3e/neo-n3-mcp

Or invoke if installed globally

neo-n3-mcp

⚙️ Configuration Paradigms

1. Command-Line Interface (CLI) Overrides

bash

Designate the operational network

neo-n3-mcp --network mainnet

Specify custom endpoint Uniform Resource Locators (URLs)

neo-n3-mcp --mainnet-rpc https://custom.neo.main.endpoint:443 --testnet-rpc https://custom.neo.test.endpoint:443

Activate verbose logging and redirect output

neo-n3-mcp --log-level debug --log-file ./system_trace.log

Comprehensive configuration example

neo-n3-mcp \ --network mainnet \ --mainnet-rpc https://mainnet1.neo.coz.io:443 \ --testnet-rpc https://testnet1.neo.coz.io:443 \ --log-level trace \ --log-file ./logs/neo-node-activity.log

2. Declarative JSON Configuration

Define settings within neo-mcp-configuration.json:

{ "system_network": "mainnet", "rpc_endpoints": { "mainnet": "https://mainnet1.neo.coz.io:443", "testnet": "https://testnet1.neo.coz.io:443" }, "telemetry": { "level": "warn", "output_path": "./logs/server_log.log", "stream_to_console": false }, "server_metadata": { "node_id": "neo-n3-mcp-host-01", "version_tag": "1.6.0" }, "storage": { "wallet_vault_path": "/data/neo-wallets" } }

Execute using the configuration file pointer: bash neo-n3-mcp --config ./neo-mcp-configuration.json

3. Containerized Deployment (Docker)

Pulling from Docker Hub

bash

Standard operational launch, mapping port 3000

docker run -p 3000:3000 r3enetwork/neo-n3-mcp:1.6.0

Utilizing environment variables for runtime configuration

docker run -p 3000:3000 \ -e NEO_NETWORK=mainnet \ -e NEO_MAINNET_RPC=https://mainnet1.neo.coz.io:443 \ -e LOG_LEVEL=error \ r3enetwork/neo-n3-mcp:1.6.0

Ensuring persistence for wallet and log data volumes

docker run -p 3000:3000 \ -v $(pwd)/persistent_wallets:/app/wallets \ -e NEO_NETWORK=testnet \ r3enetwork/neo-n3-mcp:1.6.0

Docker Compose Orchestration

Define infrastructure using docker-compose.yml:

yaml version: '3.8' services: neo-integration-node: image: r3enetwork/neo-n3-mcp:1.6.0 container_name: neo-mcp-service ports: - "3000:3000" environment: - NEO_NETWORK=mainnet - NEO_MAINNET_RPC=https://mainnet1.neo.coz.io:443 - LOG_LEVEL=info - LOG_FILE=/app/logs/node.log volumes: - ./wallets:/app/wallets - ./logs:/app/logs restart: always

Deployment command: bash docker-compose up -d

🐳 Rapid Docker Startup

bash

Clone repository and deploy via Compose

git clone https://github.com/r3e-network/neo-n3-mcp.git cd neo-n3-mcp docker-compose -f docker/production-setup.yml up -d

Build and run manually for quick testing

npm run package:build npm run node:start

Run in development/hot-reload mode

npm run dev:containerized

Optimized Production Deployment

bash

Build custom production artifact tag

./scripts/build.sh --target production --tag stable-v1.6.0

Execute detached production instance

docker run -d \ --name dedicated-neo-node \ -p 3000:3000 \ -e NEO_NETWORK=mainnet \ -v neo-data-volume:/app/wallets \ neo-n3-mcp:stable-v1.6.0

🔧 Configuration Parameters Reference

Environmental Variables Reference

Variable Name	Purpose	Default Setting
NEO_NETWORK	Primary DLT selection (mainnet/testnet)	testnet
NEO_MAINNET_RPC	Mainnet node connection string	https://mainnet1.neo.coz.io:443
NEO_TESTNET_RPC	Testnet node connection string	https://testnet1.neo.coz.io:443
LOG_LEVEL	Verbosity threshold (debug, info, warning, error)	info
WALLET_VAULT_PATH	Absolute path for secure key storage	./wallets

CLI Argument Flags

Flag	Description	Example Value
--network	Overrides the default chain environment	mainnet
--mainnet-rpc	Explicit Mainnet RPC endpoint setting	http://...
--log-level	Runtime console logging verbosity	debug
--config	Path to an external settings JSON file	./config.json
--help	Display command usage information	N/A

🛠️ MCP Client Interfacing

Integration with Claude Desktop Environment

Configure your MCP broker manifest (~/.cursor/mcp.json):

{ "mcpServers": { "neo-n3-interface": { "command": "npx", "args": [ "@r3e/neo-n3-mcp", "--network", "testnet", "--log-level", "warn" ], "disabled": false, "env": { "NEO_NETWORK": "testnet" } } } }

Utilizing Custom Client SDK (TypeScript/Node.js)

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

const transportChannel = new StdioTransport({ command: 'npx', args: ['@r3e/neo-n3-mcp', '--network', 'mainnet', '--log-level', 'error'] });

const clientInstance = new Client( { name: 'my-app-connector', version: '2.1.0' }, { capabilities: { feature_set: ['wallets', 'contracts'] } } );

await clientInstance.establishConnection(transportChannel);

📊 Functionality Map: Tools & Data Resources

🛠️ Available Operational Tools (Total: 34)

• Network Management: get_network_mode, update_network_settings
• Ledger Traversal: fetch_block_by_height, retrieve_transaction_details, get_current_block_number
• Account & Key Management: provision_new_wallet, load_wallet_from_pem, export_public_key
• Token Operations: query_token_balance, execute_asset_transfer, calculate_transaction_cost
• Smart Contract Interface: invoke_script_function, get_deployed_contract_metadata, list_standard_contracts
• Advanced Utilities: claim_network_rewards, pre_calculate_invocation_gas

📁 Exposed Data Streams (Total: 9)

• Network Health: neo://system/status, neo://mainnet/heartbeat, neo://testnet/heartbeat
• Chain State: neo://mainnet/chain_digest, neo://testnet/chain_digest
• Contract Index: neo://mainnet/registry, neo://testnet/registry
• Token Index: neo://mainnet/asset_definitions, neo://testnet/asset_definitions

🛡️ Security Posture

• Data Integrity: Rigorous validation schema enforced on all incoming payloads.
• Transactional Safety: Critical functions mandate explicit user confirmation signals.
• Key Protection: Private cryptographic material utilizes AES-256 encryption at rest.
• Network Segregation: Strict isolation maintained between mainnet and testnet processing contexts.
• Throttling: Highly configurable request-per-second governors for distributed denial-of-service (DDoS) mitigation.

⚡ Performance & Uptime Guarantees

• Concurrency: Optimized asynchronous I/O handling for high throughput RPC interactions.
• Fault Tolerance: Implemented circuit-breaker patterns for transient RPC failures.
• Production Readiness: Configuration templates provided for systemd service management and Prometheus metric exposition.

🔄 Software Lifecycle and Release Cadence

Current Software Iteration: v1.6.0

Release strategy adheres strictly to SemVer 2.0.0. Refer to the accompanying documentation for detailed pipeline specifications.

🚀 Initiating the Next Formal Release

Option A: Automated Release Orchestrator (Preferred Method)

bash

Simulate the release process with a dry run

./scripts/release_prep.sh --increment minor --dry-run

Execute the standard minor version bump and artifact creation

./scripts/release_prep.sh --increment minor

Final step: Tagging and pushing sources, which initiates CI/CD

git push origin develop && gh release create v1.7.0 --draft

Option B: Manual NPM Version Control

bash

Check existing version

npm version

Increment patch level (e.g., 1.6.0 -> 1.6.1)

npm version patch -m "fix: Resolve RPC connection instability"

Publish after committing version bump

git push --follow-tags

⚙️ CI/CD Pipeline Workflow Stages

Upon a successful tag push, the automated system executes:

1. Pre-Flight Checks: Compatibility testing across Node LTS versions (18, 20, 22).
2. Code Verification: Static analysis (ESLint) and strict TypeScript compilation.
3. Artifact Generation: Compilation, bundling, and creation of deployment containers.
4. Registry Push: Publishing to NPM and pushing tagged images to Docker Hub.

📋 Release Categorization Matrix

Increment Type	SemVer Impact	Primary Use Case	Script Invocation
patch	1.6.0 → 1.6.1	Hotfixes, critical vulnerability patching	--increment patch
minor	1.6.0 → 1.7.0	New features, non-breaking functional additions	--increment minor
major	1.6.0 → 2.0.0	API contract modifications, schema changes	--increment major

📚 Auxiliary Resources

• API Specification
• System Architecture Overview
• Deployment Configuration Guide
• Security Audit Log

📄 Legal Information

Distribution governed under the MIT License. See the LICENSE file.

🔗 External References

• Neo N3 Protocol Docs: https://docs.neo.org/
• MCP Specification: https://modelcontextprotocol.io/

FOOTNOTE: The accompanying text regarding the Tron network (WIKIPEDIA extract) is retained here for contextual comparison of DLT service documentation styles but is irrelevant to the Neo N3 MCP implementation.