# deseti/mcp-moni architecture

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

- Interactive diagram: https://gitdiagram.com/deseti/mcp-moni
- Repository: https://github.com/deseti/mcp-moni

## Overview

##### Project type and purpose
- MCP Moni is a backend‐only, TypeScript-based MCP (Model Context Protocol) server that exposes blockchain tooling to AI assistants (e.g., Claude Desktop).
- Its purpose is to handle natural-language and JSON requests from an AI client, translate those into blockchain operations on the Monad testnet (via Viem and the Monad SDK), and return results or execute transactions.

##### File structure
- Top level:
- package.json / package-lock.json: Node.js project metadata
- tsconfig.json: TypeScript compiler configuration
- .env.example: environment variables template (private key, RPC_URL, CHAIN_ID)
- src/: TypeScript source
- src/index.ts: entry point that spins up the MCP server and registers tools
- src/config.ts & config.d.ts: loads and validates environment variables
- src/utilities.ts: helper functions shared across tools
- src/nft/: NFT-related tools (index.ts ties together types.ts and utils.ts)
- src/staking.ts, src/swap.ts, src/wrapUnwrap.ts: individual modules for staking, swapping, wrapping/unwrapping MON
- src/transfer.ts (embedded in swap? or implicitly in utilities) and src/staking.ts handle token transfers and liquid staking
- No frontend/UI: purely a modular service

##### README for additional insights
- Confirms components: MCP server, Viem library, Monad SDK
- Lists 20+ “tools” (get-mon-balance, execute-transfer, generate-nft-image, etc.)
- Describes flow: Claude Desktop → MCP Moni → blockchain testnet
- No database or caching layer mentioned

##### Detail & essential elements
- Tool module is individually represented, or group by domain with sub-labels
- That all private keys and signing happen locally (config → Viem signer)
- MCP adapter layer that parses natural-language/JSON into module invocations
- Don’t over-fragment: show logical groupings rather than every single TypeScript file

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% AI Client
    ClaudeDesktop["Claude Desktop (AI Client)"]:::client
    click ClaudeDesktop "https://github.com/deseti/mcp-moni/tree/master/n/a"

    %% MCP Server Monolith
    subgraph "MCP Moni Server"
        subgraph "Entry & Orchestration"
            MCPServerEntry["MCP Server\n(index.ts)"]:::entry
            NLP["Natural Language\nProcessor"]:::entry
        end

        subgraph "Config & Utilities"
            Config["Configuration Module\n(config.ts, config.d.ts)"]:::config
            Utilities["Utility Layer\n(utilities.ts)"]:::config
            Env["Environment Variables\n(.env)"]:::config
        end

        subgraph "Tool Modules"
            Balance["Balance & Portfolio\n(get-mon-balance, get-token-portfolio)"]:::tools
            Transfer["Token Transfers\n(transfer-token, execute-transfer)"]:::tools
            Swap["Swapping\n(get-swap-quote, execute-swap)"]:::tools
            Staking["Staking\n(execute-stake, execute-unstake, execute-claim)"]:::tools
            Wrap["Wrapping/Unwrapping\n(execute-wrap, execute-unwrap)"]:::tools
            NFT["NFT Module\n(generate-nft-image, create-nft-collection)"]:::tools
        end
    end

    %% External Systems
    MonadRPC["Monad Testnet RPC Endpoint"]:::external
    MagicEden["Magic Eden Testnet"]:::external

    %% Project Metadata
    Meta["Project Metadata &\nDependencies"]:::meta

    %% Flow
    ClaudeDesktop -->|"JSON/MCP Request"| MCPServerEntry
    MCPServerEntry -->|"parse request"| NLP
    MCPServerEntry -->|"load config"| Config
    MCPServerEntry -->|"init utilities"| Utilities
    MCPServerEntry -->|"route to module"| Balance
    MCPServerEntry -->|"route to module"| Transfer
    MCPServerEntry -->|"route to module"| Swap
    MCPServerEntry -->|"route to module"| Staking
    MCPServerEntry -->|"route to module"| Wrap
    MCPServerEntry -->|"route to module"| NFT

    %% Module RPC calls
    Balance -->|"Viem+SDK RPC call"| MonadRPC
    Transfer -->|"Viem+SDK RPC call"| MonadRPC
    Swap -->|"Viem+SDK RPC call"| MonadRPC
    Staking -->|"Viem+SDK RPC call"| MonadRPC
    Wrap -->|"Viem+SDK RPC call"| MonadRPC
    NFT -->|"RPC call"| MonadRPC
    NFT -.->|"NFT marketplace request"| MagicEden

    %% Responses back
    MonadRPC -->|"RPC response"| MCPServerEntry
    MagicEden -.->|"marketplace response"| MCPServerEntry
    MCPServerEntry -->|"JSON/MCP Response"| ClaudeDesktop

    %% Metadata & Env
    Meta --- MCPServerEntry
    Env --- Config

    %% Click Events
    click MCPServerEntry "https://github.com/deseti/mcp-moni/blob/master/src/index.ts"
    click Config "https://github.com/deseti/mcp-moni/blob/master/src/config.ts"
    click Utilities "https://github.com/deseti/mcp-moni/blob/master/src/utilities.ts"
    click NFT "https://github.com/deseti/mcp-moni/blob/master/src/nft/index.ts"
    click Staking "https://github.com/deseti/mcp-moni/blob/master/src/staking.ts"
    click Swap "https://github.com/deseti/mcp-moni/blob/master/src/swap.ts"
    click Wrap "https://github.com/deseti/mcp-moni/blob/master/src/wrapUnwrap.ts"
    click Meta "https://github.com/deseti/mcp-moni/blob/master/package.json"
    click Meta "https://github.com/deseti/mcp-moni/blob/master/package-lock.json"
    click Meta "https://github.com/deseti/mcp-moni/blob/master/tsconfig.json"
    click Env "https://github.com/deseti/mcp-moni/blob/master/.env.example"
    click Config "https://github.com/deseti/mcp-moni/blob/master/src/config.d.ts"
    click NFT "https://github.com/deseti/mcp-moni/blob/master/src/nft/types.ts"
    click NFT "https://github.com/deseti/mcp-moni/blob/master/src/nft/utils.ts"

    %% Styles
    classDef client fill:#F9E79F,stroke:#B9770E,color:#000
    classDef entry fill:#AED6F1,stroke:#1F618D,color:#000
    classDef config fill:#D5D8DC,stroke:#5D6D7E,color:#000
    classDef tools fill:#A9DFBF,stroke:#196F3D,color:#000
    classDef external fill:#F5B041,stroke:#B9770E,color:#000
    classDef meta fill:#D6DBDF,stroke:#7B7D7D,color:#000
```
