# vaibhavgeek/one_inch_mcp architecture

> Architecture diagram of the GitHub repository vaibhavgeek/one_inch_mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vaibhavgeek/one_inch_mcp
- Repository: https://github.com/vaibhavgeek/one_inch_mcp

## Overview

##### 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”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    CLI["CLI / User Interface"]:::cli
    INDEX["index.js"]:::cli
    STATUS["status.js"]:::cli
    MCP["MCP Server"]:::api
    OrderStore["[(Order Store)]"]:::datastore
    Monitor["Monitor Daemon"]:::daemon
    Worker["Worker Process"]:::worker
    RPC["External RPC Nodes"]:::external
    Fusion["1inch Fusion+ API"]:::external

    %% Flow
    CLI -->|"start server"| INDEX
    INDEX -->|"init MCP server"| MCP
    CLI -->|"status check"| STATUS
    STATUS -->|"read orders/status"| OrderStore

    MCP -->|"swap request"| OrderStore
    MCP -->|"portfolio query"| Fusion
    MCP -->|"status query"| RPC

    Monitor -->|"poll for new orders"| OrderStore
    Monitor -->|"fork worker"| Worker

    Worker -->|"read order"| OrderStore
    Worker -->|"submit tx & poll on-chain"| RPC
    Worker -->|"submit tx & poll on-chain"| Fusion
    Worker -->|"update order"| OrderStore

    %% Click Events
    click INDEX "https://github.com/vaibhavgeek/one_inch_mcp/blob/main/index.js"
    click STATUS "https://github.com/vaibhavgeek/one_inch_mcp/blob/main/status.js"
    click MCP "https://github.com/vaibhavgeek/one_inch_mcp/blob/main/mcpServer.js"
    click OrderStore "https://github.com/vaibhavgeek/one_inch_mcp/blob/main/order-status.json"
    click Monitor "https://github.com/vaibhavgeek/one_inch_mcp/blob/main/monitor-service.js"
    click Worker "https://github.com/vaibhavgeek/one_inch_mcp/blob/main/monitor-worker.js"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px;
    classDef api fill:#bbf,stroke:#333,stroke-width:1px;
    classDef daemon fill:#fbf,stroke:#333,stroke-width:1px;
    classDef worker fill:#bfb,stroke:#333,stroke-width:1px;
    classDef datastore fill:#ffb,stroke:#333,stroke-width:1px;
    classDef external fill:#fdd,stroke:#333,stroke-width:1px;
```
