Architecture - Neo N3 MCP Server

System shape

MCP client --stdio--> src/index.ts -----------+
                                                |
HTTP client --HTTP--> src/http-server.ts ------+--> NeoService --> Neo RPC
                                                +--> ContractService --> Neo RPC / optional N3Index lookup
                                                +--> WalletService --> WALLETS_DIR
                                                +--> validation, rate limiting, logging

The MCP entrypoint uses the Model Context Protocol SDK over stdio. The HTTP entrypoint exposes a REST-style adapter but reuses the same core services.

Core modules

MCP server

src/index.ts registers tools, resources, schemas, service selection, and stdio lifecycle handling.

HTTP entrypoint

src/http.ts resolves one network, validates host security, constructs services, and handles shutdown.

HTTP router

src/http-server.ts implements routes, bearer authentication, CORS allowlisting, JSON limits, health, and metrics.

Neo service

src/services/neo-service.ts owns deadline-bounded RPC queries, transaction construction, fees, transfer history, and application-log enrichment.

Contract service

src/contracts/contract-service.ts resolves generic references, verifies deployment, inspects manifests, and executes contract calls.

Wallet service

src/services/wallet-service.ts creates, imports, encrypts, persists, and sanitizes wallet records.

Delegated handlers

src/handlers/ implements tool and resource behavior shared by registrations and transports.

Cross-cutting utilities

src/utils/ contains validation, errors, structured logging, log rotation, and process-local rate limiting.

Request flow

MCP tool call

The SDK validates the registered Zod input schema.
The shared MCP client rate limit is checked.
The server selects the configured Neo service for the requested network.
A direct handler or delegated tool handler calls the service layer.
The result is serialized into MCP text content.

HTTP request

Security and cache-control response headers are applied.
The client IP rate limit is checked.
Bearer authentication runs for every route except /live and /health when a key is configured.
POST and PUT bodies are limited and parsed as JSON objects.
The route calls the corresponding service and emits a JSON or metrics response.

Security boundaries

HTTP defaults to loopback; non-loopback startup requires an API key of at least 32 bytes.
MCP write paths require an explicit network and confirm as the JSON boolean true.
Signed transactions are rejected when combined system and network fees exceed the configured cap.
Wallet records are stored under WALLETS_DIR with restrictive directory and file modes.
Persisted private-key material is NEP-2 encrypted; stateless import does not write a wallet file.
Contract metadata is resolved separately from on-chain deployment checks.
Rate limiting is process-local and must be complemented by deployment-level network controls.

Technology baseline

Component	Current baseline
Node.js	22 or newer; CI also tests 24
TypeScript	5.9
MCP SDK	1.29
Neo SDK	`@cityofzion/neon-js` 5.9
Validation	Zod 3.25 plus project validation helpers
Testing	Jest 29 with ts-jest
Containers	Node.js 22 Alpine, multi-stage production build

Operational boundary

The application exposes /live, RPC-aware /health, and a small Prometheus-text-compatible /metrics response. It does not include a collector, dashboard, alerting system, tracing backend, cache layer, connection pool, circuit breaker, or cloud orchestration manifest.