System architecture and design patterns for Neo N3 MCP Server
Neo N3 MCP Server is built as a modular, extensible system that bridges the gap between AI applications and the Neo N3 blockchain. The architecture follows industry best practices for security, performance, and maintainability.
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ AI Client │ │ MCP Server │ │ Neo N3 │
│ (Claude, etc) │◄──►│ (This System) │◄──►│ Network │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌──────────────────┐
│ Tool & Resource│
│ Management │
└──────────────────┘
│
┌───────────┼───────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│Blockchain│ │ Wallet │ │ Security │
│ Service │ │ Service │ │ Service │
└──────────┘ └──────────┘ └──────────┘
Manages the Model Context Protocol communication, handling tool calls, resource requests, and maintaining session state.
Core blockchain interaction layer that handles all Neo N3 network communications and operations.
Secure wallet operations including creation, import, and transaction signing with enterprise-grade encryption.
Manages famous contracts and provides standardized interfaces for smart contract interactions.
Comprehensive security controls including input validation, rate limiting, and access control.
Real-time monitoring, metrics collection, and health checks for operational excellence.
1. AI Client Request │ ▼ 2. MCP Protocol Validation │ ▼ 3. Security Checks │ ├─ Input Validation │ ├─ Rate Limiting │ └─ Authorization ▼ 4. Tool Router │ ▼ 5. Service Layer │ ├─ Blockchain Service │ ├─ Wallet Service │ └─ Contract Service ▼ 6. Neo N3 Network │ ▼ 7. Response Processing │ ├─ Data Transformation │ ├─ Error Handling │ └─ Metrics Collection ▼ 8. MCP Response to Client
{
"dependencies": {
"@cityofzion/neon-js": "^5.4.0",
"@neo-project/neo-js": "^3.15.0",
"express": "^4.18.2",
"ws": "^8.13.0",
"crypto": "node:crypto",
"dotenv": "^16.3.1",
"joi": "^17.9.2",
"winston": "^3.10.0",
"prom-client": "^14.2.0"
},
"devDependencies": {
"@types/node": "^20.4.5",
"typescript": "^5.1.6",
"jest": "^29.6.2",
"eslint": "^8.45.0",
"prettier": "^3.0.0"
}
}
Tool creation and service instantiation based on configuration and runtime requirements.
Different network handlers (mainnet/testnet) and encryption strategies for various security levels.
Event-driven architecture for monitoring, logging, and metric collection across components.
Prevents cascading failures when Neo N3 network is unavailable or experiencing issues.
┌─────────────────────────────────────────┐ │ Application Layer │ │ ├─ Input Validation │ │ ├─ Rate Limiting │ │ └─ Request Authentication │ ├─────────────────────────────────────────┤ │ Service Layer │ │ ├─ Business Logic Validation │ │ ├─ Permission Checks │ │ └─ Operation Confirmation │ ├─────────────────────────────────────────┤ │ Data Layer │ │ ├─ Encryption at Rest │ │ ├─ Secure Key Derivation │ │ └─ Audit Logging │ ├─────────────────────────────────────────┤ │ Network Layer │ │ ├─ TLS/SSL Encryption │ │ ├─ Connection Security │ │ └─ Network Isolation │ └─────────────────────────────────────────┘
Efficient Neo N3 RPC connection management with automatic load balancing and failover.
Non-blocking operations with proper error handling and timeout management.
Intelligent caching of blockchain data with appropriate TTL and invalidation strategies.
Memory-efficient operations with garbage collection optimization and leak prevention.