# Install globally
npm install -g fluid-mcp-server

# Or run directly with npx
npx fluid-mcp-server

{
  "mcpServers": {
    "fluid": {
      "command": "npx",
      "args": ["fluid-mcp-server"]
    }
  }
}

claude mcp add fluid -- npx fluid-mcp-server

git clone https://github.com/ahmadmardeni1/fluid-mcp-server.git
cd fluid-mcp-server
npm install
npm run build
npm start

graph TB
    subgraph "AI Agent Layer"
        Agent[AI Agent / LLM]
        MCP[MCP Client]
    end

    subgraph "Fluid MCP Server"
        Server[MCP Server Entry Point]

        subgraph "READ Tools"
            LR[Liquidity Read]
            LendR[Lending Read]
            VR[Vault Read]
            DR[DEX Read]
        end

        subgraph "WRITE Tools"
            LendW[Lending Write]
            VW[Vault Write]
            DW[DEX Write]
        end

        Config[Chain Config]
        ABIs[ABI Definitions]
        Provider[Provider Manager]
    end

    subgraph "Fluid Protocol (On-Chain)"
        LL[Liquidity Layer]
        LP[Lending Protocol / fTokens]
        VP[Vault Protocol]
        DEX[DEX Protocol]

        subgraph "Resolvers"
            LiqR[LiquidityResolver]
            LendRes[LendingResolver]
            VaultRes[VaultResolver]
            DexRes[DexReservesResolver]
        end
    end

    Agent --> MCP
    MCP --> Server
    Server --> LR & LendR & VR & DR
    Server --> LendW & VW & DW
    LR & LendR & VR & DR --> Provider
    LendW & VW & DW --> Provider
    Provider --> Config & ABIs
    Provider --> LiqR & LendRes & VaultRes & DexRes
    LiqR --> LL
    LendRes --> LP
    VaultRes --> VP
    DexRes --> DEX

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCP Server
    participant Chain as Blockchain
    participant fToken as fToken Contract
    participant LL as Liquidity Layer

    Note over Agent,LL: Step 1: Research
    Agent->>MCP: fluid_get_all_ftokens_details(chain)
    MCP->>Chain: LendingResolver.getAllFTokensDetails()
    Chain-->>MCP: [fToken details with rates]
    MCP-->>Agent: Best APY opportunities

    Note over Agent,LL: Step 2: Approve (if ERC20)
    Agent->>MCP: fluid_build_token_approve(token, fToken)
    MCP-->>Agent: Unsigned approval tx
    Agent->>Chain: Sign & send approval

    Note over Agent,LL: Step 3: Deposit
    Agent->>MCP: fluid_build_lending_deposit(fToken, amount, receiver)
    MCP-->>Agent: Unsigned deposit tx + preview shares
    Agent->>Chain: Sign & send deposit tx
    Chain->>fToken: deposit(assets, receiver)
    fToken->>LL: Supply to Liquidity Layer
    fToken-->>Agent: fToken shares minted

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCP Server
    participant Chain as Blockchain
    participant Vault as Vault Contract
    participant LL as Liquidity Layer

    Note over Agent,LL: Step 1: Find a vault
    Agent->>MCP: fluid_get_all_vaults_data(chain)
    MCP->>Chain: VaultResolver.getAllVaultsEntireData()
    Chain-->>MCP: [All vaults with rates, limits, LTV]
    MCP-->>Agent: Available vaults + collateral factors

    Note over Agent,LL: Step 2: Open position
    Agent->>MCP: fluid_build_vault_open(vault, collateral, borrow, receiver)
    MCP-->>Agent: Unsigned operate() tx
    Agent->>Chain: Sign & send tx
    Chain->>Vault: operate(0, +col, +debt, to)
    Vault->>LL: Deposit collateral + borrow from Liquidity
    Vault-->>Agent: NFT minted (position ID)

    Note over Agent,LL: Step 3: Monitor health
    Agent->>MCP: fluid_get_vault_position(nftId)
    MCP->>Chain: VaultResolver.positionByNftId()
    Chain-->>MCP: Position data
    MCP-->>Agent: Supply, borrow, LTV, health

    Note over Agent,LL: Step 4: Repay & close
    Agent->>MCP: fluid_build_vault_close(vault, nftId, receiver)
    MCP-->>Agent: Unsigned close tx
    Agent->>Chain: Sign & send tx
    Chain->>Vault: operate(nftId, MIN, MIN, to)
    Vault-->>Agent: All collateral returned

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCP Server
    participant Chain as Blockchain
    participant Pool as DEX Pool
    participant Res as DexReservesResolver

    Note over Agent,Res: Step 1: Discover pools
    Agent->>MCP: fluid_get_all_pools_reserves(chain)
    MCP->>Chain: DexResolver.getAllPoolsReserves()
    Chain-->>MCP: [All pools with token pairs & reserves]
    MCP-->>Agent: Available trading pairs

    Note over Agent,Res: Step 2: Get quote
    Agent->>MCP: fluid_estimate_swap_in(pool, direction, amountIn)
    MCP->>Chain: Fetch adjusted reserves + estimate
    Chain-->>MCP: Estimated output
    MCP-->>Agent: Quote with price impact

    Note over Agent,Res: Step 3: Execute swap
    Agent->>MCP: fluid_build_swap_exact_input(pool, direction, amountIn, slippage, receiver)
    MCP->>Chain: Fetch reserves + calculate minOutput
    MCP-->>Agent: Unsigned swap tx with slippage protection
    Agent->>Chain: Sign & send swap tx
    Chain->>Pool: swapIn(direction, amountIn, minOut, to)
    Pool-->>Agent: Output tokens received

{
  "chain": "ethereum",
  "action": "deposit",
  "to": "0x...",       // Contract to call
  "data": "0x...",     // Encoded calldata
  "value": "0",        // ETH value to send (wei)
  "description": "...",
  "note": "..."
}

import { ethers } from "ethers";

// After receiving tx data from MCP tool:
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);
const tx = await wallet.sendTransaction({
  to: toolResult.to,
  data: toolResult.data,
  value: BigInt(toolResult.value),
});
const receipt = await tx.wait();

{
  "chain": "ethereum",
  "rpc_url": "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
}

fluid-mcp-server/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── config/
│   │   └── chains.ts            # Multi-chain contract addresses
│   ├── abis/
│   │   └── index.ts             # Minimal ABI definitions
│   ├── tools/
│   │   ├── index.ts             # Tool registry
│   │   ├── liquidity-read.ts    # Liquidity Layer queries
│   │   ├── lending-read.ts      # fToken lending queries
│   │   ├── vault-read.ts        # Vault protocol queries
│   │   ├── dex-read.ts          # DEX pool queries + swap estimates
│   │   ├── lending-write.ts     # Lending transaction builders
│   │   ├── vault-write.ts       # Vault transaction builders
│   │   └── dex-write.ts         # DEX swap transaction builders
│   └── utils/
│       ├── provider.ts          # Ethers.js provider management
│       └── formatting.ts        # Data formatting utilities
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

# 1) List all fTokens on Ethereum
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"fluid_get_all_ftokens","arguments":{"chain":"ethereum"}}}' \
  | node dist/index.js

# 2) Get detailed info for a specific fToken (fUSDC on Ethereum)
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"fluid_get_ftoken_details","arguments":{"chain":"ethereum","ftoken_address":"0x9Fb7b4477576Fe5B32be4C1843aFB1e55F251B33"}}}' \
  | node dist/index.js

# 3) Build an unsigned deposit tx into fUSDC (100 USDC, 6 decimals)
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"fluid_build_lending_deposit","arguments":{"chain":"ethereum","ftoken_address":"0x9Fb7b4477576Fe5B32be4C1843aFB1e55F251B33","amount":"100000000","receiver":"0xYOUR_ADDRESS"}}}' \
  | node dist/index.js

# 4) List all vaults on Ethereum with their types (T1–T4)
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"fluid_get_all_vaults","arguments":{"chain":"ethereum"}}}' \
  | node dist/index.js

# 5) Build an unsigned Vault T1 operate() tx (open position)
# Example: ETH/GHO T1 vault on Ethereum
echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"fluid_build_vault_t1_operate","arguments":{"chain":"ethereum","vault_address":"0xD9A7Dcdc57C6e44f00740dC73664fA456B983669","nft_id":0,"new_col":"100000000000000000","new_debt":"200000000000000000000","receiver":"0xYOUR_ADDRESS"}}}' \
  | node dist/index.js