How vaibhavgeek/one_inch_mcp works
Project type and purpose
• This is a backend Node.js tool (CommonJS) for orchestrating cross-chain token swaps via 1inch Fusion+ and exposing those capabilities as MCP (Model Context Protocol) tools.
• It provides:
• an MCP server to accept “swap” and portfolio-related commands
• a background monitoring daemon that watches swap orders
• per-order worker processes to track and finalize each cross-chain transaction
File structure
• Top-level files:
• index.js – entry point (starts MCP server)
• mcpServer.js – defines and registers MCP tools (swap, swap-status, portfolio-* commands)
• monitor-service.js – the monitor daemon that polls order-status.json and spawns workers
• monitor-worker.js – code for a single order watcher/worker process
• status.js – CLI status checker for orders and for the monitor daemon itself
• order-status.json – simple JSON store of pending/in-progress/completed orders
• No frontend—pure service-oriented architecture.
• Config via .env, external RPC endpoints and 1inch API keys in env variables.
• Uses 1inch Fusion SDK and MCP framework libraries.
Insights from README
• The MCP server listens on a configurable port and exposes four categories of tools: cross-chain swap, swap-status, portfolio-protocols-value, portfolio-tokens-details, etc.
• The monitoring subsystem is decoupled: orders are written to a JSON file, a long-running daemon polls that file, and for each new order it forks a worker process to watch on-chain events and complete the swap.
a. Main components
1. CLI / User Interface
– npm start (spins up MCP server)
– npm run monitor:start, monitor:stop, status
2. MCP Server
– index.js & mcpServer.js
– exposes HTTP (or local IPC) endpoints for swap & portfolio tools
3. Order Store
– order-status.json (persistent queue of swap orders)
4. Monitor Daemon
– monitor-service.js (polls store, forks workers)
5. Worker Processes
– monitor-worker.js (per-order watcher)
6. External Services
– Ethereum, Arbitrum, Base, Polygon RPC nodes (RPC_URL_*)
– 1inch Fusion+ API (INCH_API_KEY)
b. Relationships & data flow
• User/Assistant → MCP Server → Business Logic →
– Initiate swap: writes new order entry to order-status.json
– Query status / portfolio: direct calls to Fusion SDK + RPC
• Monitor Daemon (separate process) ↔ order-status.json
– detects new orders → launches Worker
• Worker → Fusion SDK + RPC → polls on-chain state & submits secrets → updates order-status.json
• MCP Server status queries read from order-status.json or call Fusion RPC directly
c. Architectural patterns & principles
– Command pattern (MCP tools encapsulate each action)
– Producer/Consumer via file-based queue
– Forked worker processes for isolation & concurrency
– Externalize configuration via environment variables
d. Key technologies
– Node.js (CommonJS)
– 1inch Fusion SDK
– Model Context Protocol (MCP) framework
– JSON file persistence (order-status.json)
– Spawn/fork child processes in monitor-service
Elements
• Clear labels:
• MCP Server, Order Store, Monitor Daemon, Worker, External RPC, 1inch API
• “swap request → order store → worker → blockchain → update store → completion”