graph TB
    subgraph "User Interface Layer"
        A[Web Browser]
        B[Stacks AI Frontend<br/>Next.js Chat Interface]
        C[Wallet Connection<br/>Leather/Xverse]
    end

    subgraph "AI Processing Layer"
        D[Claude Desktop]
        E[AI Agent Processing]
        F[Natural Language<br/>Understanding]
    end

    subgraph "Backend Layer"
        G[Stacks AI MCP Server<br/>144+ Tools]
        H[Plugin System<br/>6 DeFi Protocols]
        I[Wallet Authentication<br/>Transaction Signing]
    end

    subgraph "Blockchain Layer"
        J[Stacks Network<br/>Bitcoin L2]
        K[Smart Contracts<br/>Clarity]
        L[Protocol APIs<br/>REST/SDK]
    end

    A --> B
    B --> C
    B --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I
    I --> J
    I --> K
    I --> L

    C --> I

    style A fill:#e1f5ff
    style B fill:#e1f5ff
    style D fill:#ffe1f5
    style G fill:#fff4e1
    style H fill:#e1ffe1
    style J fill:#f5e1ff

graph TB
    subgraph "AI Layer"
        A[Claude Desktop/Cursor/VS Code]
        B[Natural Language Input]
    end

    subgraph "MCP Server"
        C[MCP Protocol Handler]
        D[Plugin Manager]
        E[Wallet Client]
        F[Config Manager]
    end

    subgraph "Protocol Plugins"
        G1[ALEX Plugin<br/>34 Tools]
        G2[Bitflow Plugin<br/>29 Tools]
        G3[Arkadiko Plugin<br/>28 Tools]
        G4[Charisma Plugin<br/>14 Tools]
        G5[Velar Plugin<br/>18 Tools]
        G6[Granite Plugin<br/>21 Tools]
        G7[Stacks Core Plugin<br/>40+ Tools]
    end

    subgraph "Blockchain Layer"
        H1[Stacks Network]
        H2[ALEX API]
        H3[Velar SDK]
        H4[Protocol Contracts]
        H5[Hiro API]
    end

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F

    D --> G1
    D --> G2
    D --> G3
    D --> G4
    D --> G5
    D --> G6
    D --> G7

    G1 --> H2
    G1 --> H1
    G2 --> H1
    G3 --> H1
    G4 --> H1
    G5 --> H3
    G5 --> H1
    G6 --> H1
    G7 --> H5
    G7 --> H4

    style A fill:#e1f5ff
    style C fill:#fff4e1
    style D fill:#ffe1f5
    style G1 fill:#e1ffe1
    style G2 fill:#e1ffe1
    style G3 fill:#e1ffe1
    style G4 fill:#e1ffe1
    style G5 fill:#e1ffe1
    style G6 fill:#e1ffe1
    style G7 fill:#e1ffe1
    style H1 fill:#f5e1ff

graph TB
    subgraph "Stacks AI MCP Server"
        Core[Core Engine]
    end

    subgraph "DeFi Protocols"
        ALEX[ALEX Protocol<br/>AMM & DEX<br/>34 Tools]
        Bitflow[Bitflow Protocol<br/>Stable DEX<br/>29 Tools]
        Arkadiko[Arkadiko Protocol<br/>Lending & USDA<br/>28 Tools]
        Charisma[Charisma Protocol<br/>Composable Vaults<br/>14 Tools]
        Velar[Velar Protocol<br/>Multi-chain DEX<br/>18 Tools]
        Granite[Granite Protocol<br/>BTC Lending<br/>21 Tools]
    end

    subgraph "Core Operations"
        Contracts[Smart Contracts<br/>Deploy & Interact]
        Transactions[Transactions<br/>Query & Track]
        PoX[PoX Stacking<br/>STX Rewards]
        Tokens[Token Operations<br/>Transfer & Balance]
        NFT[NFT Operations<br/>Mint & Transfer]
        Blocks[Blockchain Data<br/>Blocks & Events]
    end

    Core --> ALEX
    Core --> Bitflow
    Core --> Arkadiko
    Core --> Charisma
    Core --> Velar
    Core --> Granite
    Core --> Contracts
    Core --> Transactions
    Core --> PoX
    Core --> Tokens
    Core --> NFT
    Core --> Blocks

    ALEX --> |Swaps, Liquidity| StacksNet[Stacks Network]
    Bitflow --> |Stable Swaps, DCA| StacksNet
    Arkadiko --> |Vaults, Loans| StacksNet
    Charisma --> |Blaze Intents| StacksNet
    Velar --> |Cross-chain Swaps| StacksNet
    Granite --> |sBTC Lending| StacksNet

    Contracts --> StacksNet
    Transactions --> StacksNet
    PoX --> StacksNet
    Tokens --> StacksNet
    NFT --> StacksNet
    Blocks --> StacksNet

    style Core fill:#e1f5ff
    style ALEX fill:#e1ffe1
    style Bitflow fill:#e1ffe1
    style Arkadiko fill:#e1ffe1
    style Charisma fill:#e1ffe1
    style Velar fill:#e1ffe1
    style Granite fill:#e1ffe1
    style StacksNet fill:#f5e1ff

"Transfer 100 STX to ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM"
"Check my STX balance"
"Send 50 ALEX tokens to alice.btc"
"What's my USDA balance?"

"Deploy a new Clarity contract from /path/to/contract.clar"
"Call the transfer function on contract SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.arkadiko-token"
"Get contract info for ALEX token"
"Read the get-balance function for my address"

"Stack 1000 STX for 6 cycles"
"Check my current stacking status"
"What's the minimum STX to stack?"
"Show me the current PoX cycle information"
"Delegate 500 STX to pool SP000..."

"Swap 100 STX for ALEX on ALEX DEX"
"Get the best price for 1000 ALEX to USDA"
"What's the current STX/ALEX exchange rate?"
"Add liquidity to the STX-ALEX pool"
"Check my liquidity positions on ALEX"

"Open a vault with 1000 STX collateral"
"Mint 500 USDA from my vault"
"Check my vault health and liquidation price"
"Repay 100 USDA to my vault"
"Close vault #123 and withdraw collateral"

"Create a new composable vault for STX-ALEX yield"
"Deposit 1000 STX into vault #456"
"Check my vault balance and APY"
"Execute Blaze intent: swap STX for best stablecoin"

"Swap 500 STX for USDA on Velar"
"Add liquidity to STX-USDA pool on Velar"
"Check Velar pool statistics for STX pairs"
"What's the TVL on Velar protocol?"

"Supply 0.1 sBTC to Granite lending pool"
"Borrow USDA against my sBTC collateral"
"Check my borrowing capacity on Granite"
"Repay my USDA loan on Granite"

"Mint an NFT with metadata from ipfs://QmHash"
"Transfer my NFT #123 from collection SP2C2Y... to SP3D03X..."
"Show me all NFTs in my wallet"
"Get NFT collection info for Megapont"

"Show me the latest Stacks block"
"What's the current mempool fee rate?"
"Get transaction details for 0x..."
"Show network statistics for the last 24 hours"
"Check the current Bitcoin block height"

pnpm dev

pnpm build
pnpm start

pnpm test

pnpm test:clarinet

pnpm test:watch

pnpm type-check

pnpm lint

src/plugins/
├── alex/          # ALEX Protocol integration
├── bitflow/       # Bitflow Protocol integration
├── arkadiko/      # Arkadiko Protocol integration
├── charisma/      # Charisma Protocol integration
├── velar/         # Velar Protocol integration
├── granite/       # Granite Protocol integration
├── contracts/     # Smart contract operations
├── transactions/  # Transaction management
├── pox/           # PoX stacking operations
├── tokens/        # Token operations
├── nft/           # NFT operations
└── ...            # Additional core plugins

graph LR
    subgraph "Plugin Base"
        A[PluginBase<br/>Abstract Class]
        B[Tool Factory]
        C[Validation Layer]
    end

    subgraph "Protocol Plugin"
        D[Plugin Implementation]
        E[Service Layer]
        F[API Integration]
        G[Contract Interface]
    end

    subgraph "Tool Registration"
        H[Tool Definition]
        I[Parameter Schema]
        J[Tool Handler]
    end

    A --> D
    B --> H
    C --> I
    D --> E
    E --> F
    E --> G
    H --> J
    I --> J

    style A fill:#e1f5ff
    style D fill:#ffe1e1
    style E fill:#e1ffe1
    style H fill:#fff4e1

graph TB
    subgraph "Core Layer"
        A[PluginBase<br/>Abstract base class]
        B[ToolBase<br/>Tool factory]
        C[StacksWalletClient<br/>Wallet interface]
        D[Config Manager<br/>Environment config]
    end

    subgraph "Service Layer"
        E[Protocol Services<br/>Business logic]
        F[API Clients<br/>External APIs]
        G[Contract Handlers<br/>Smart contracts]
    end

    subgraph "Integration Layer"
        H[Hiro API<br/>Blockchain data]
        I[Protocol APIs<br/>ALEX, Velar, etc.]
        J[Stacks Network<br/>Contract calls]
    end

    A --> E
    B --> E
    C --> E
    D --> E

    E --> F
    E --> G

    F --> H
    F --> I
    G --> J

    style A fill:#e1f5ff
    style B fill:#e1f5ff
    style C fill:#e1f5ff
    style D fill:#e1f5ff
    style E fill:#e1ffe1
    style F fill:#e1ffe1
    style G fill:#e1ffe1
    style H fill:#ffe1f5
    style I fill:#ffe1f5
    style J fill:#ffe1f5

sequenceDiagram
    participant AI as AI Agent
    participant MCP as MCP Server
    participant Plugin as Protocol Plugin
    participant Service as Service Layer
    participant Wallet as Wallet Client
    participant Network as Stacks Network

    AI->>MCP: Natural Language Request
    MCP->>Plugin: Route to Tool Handler
    Plugin->>Service: Validate & Prepare
    Service->>Service: Build Contract Call
    Service->>Plugin: Return Contract Call Data
    Plugin->>MCP: Return Unsigned Transaction
    MCP->>AI: Transaction Details

    Note over AI,Wallet: User/Client Signs Transaction

    AI->>Wallet: Sign Transaction
    Wallet->>Network: Broadcast Transaction
    Network->>Wallet: Transaction ID
    Wallet->>AI: Confirmation
    AI->>MCP: Query Transaction Status
    MCP->>Network: Check Status
    Network->>MCP: Transaction Result
    MCP->>AI: Final Status

graph LR
    subgraph "Input"
        A[Natural Language] --> B[MCP Request]
    end

    subgraph "Processing"
        B --> C[Tool Router]
        C --> D[Parameter Validation]
        D --> E[Service Execution]
        E --> F[API/Contract Call]
    end

    subgraph "Output"
        F --> G[Response Formatting]
        G --> H[MCP Response]
        H --> I[AI-Readable Result]
    end

    style A fill:#e1f5ff
    style C fill:#ffe1e1
    style E fill:#e1ffe1
    style F fill:#fff4e1
    style I fill:#f5e1ff

graph TB
    subgraph "MCP Server"
        A[Tool Handler]
        B[Service Layer]
    end

    subgraph "External APIs"
        C[Hiro API<br/>Blockchain Data]
        D[ALEX API<br/>DEX Analytics]
        E[Velar SDK<br/>Multi-chain DEX]
        F[Bitflow SDK<br/>Stable DEX]
    end

    subgraph "Blockchain"
        G[Stacks Network<br/>Contract Calls]
        H[Protocol Contracts<br/>Read/Write]
        I[Pyth Oracles<br/>Price Feeds]
    end

    A --> B
    B --> C
    B --> D
    B --> E
    B --> F
    B --> G
    G --> H
    G --> I

    style A fill:#e1f5ff
    style B fill:#ffe1e1
    style C fill:#e1ffe1
    style D fill:#e1ffe1
    style E fill:#e1ffe1
    style F fill:#e1ffe1
    style G fill:#fff4e1
    style H fill:#f5e1ff
    style I fill:#f5e1ff

sequenceDiagram
    participant Tool as MCP Tool
    participant Service as Protocol Service
    participant API as External API
    participant Contract as Smart Contract
    participant Cache as Response Cache

    Tool->>Service: Execute Operation
    Service->>Service: Validate Parameters

    alt Read Operation
        Service->>Cache: Check Cache
        alt Cache Hit
            Cache->>Service: Return Cached Data
        else Cache Miss
            Service->>API: Fetch Data
            API->>Service: Return Data
            Service->>Cache: Update Cache
        end
    else Write Operation
        Service->>Contract: Build Contract Call
        Contract->>Service: Return Call Data
    end

    Service->>Tool: Return Result

graph LR
    subgraph "Development"
        A[Write Plugin Code] --> B[Add Unit Tests]
        B --> C[Type Check]
        C --> D[Run Tests]
    end

    subgraph "Integration"
        D --> E[Register Plugin]
        E --> F[Build Server]
        F --> G[Test with MCP Client]
    end

    subgraph "Deployment"
        G --> H[Configure AI App]
        H --> I[Test End-to-End]
        I --> J[Deploy to Production]
    end

    style A fill:#e1f5ff
    style D fill:#e1ffe1
    style F fill:#fff4e1
    style I fill:#ffe1f5
    style J fill:#f5e1ff

graph TB
    subgraph "Unit Tests"
        A[Service Logic Tests]
        B[Parameter Validation]
        C[Mock API Responses]
    end

    subgraph "Integration Tests"
        D[Clarinet Contract Tests]
        E[Plugin Integration]
        F[End-to-End Flows]
    end

    subgraph "Manual Testing"
        G[Claude Desktop Testing]
        H[Real Network Operations]
        I[Protocol Verification]
    end

    A --> D
    B --> D
    C --> D
    D --> G
    E --> G
    F --> G
    G --> I
    H --> I

    style A fill:#e1f5ff
    style B fill:#e1f5ff
    style C fill:#e1f5ff
    style D fill:#e1ffe1
    style E fill:#e1ffe1
    style F fill:#e1ffe1
    style G fill:#fff4e1
    style H fill:#fff4e1
    style I fill:#f5e1ff

export class NewProtocolService {
  async someOperation(params: OperationParams) {
    // Implementation
  }
}

export class NewProtocolPlugin extends PluginBase<StacksWalletClient> {
  async getTools(walletClient: StacksWalletClient) {
    const service = new NewProtocolService();

    return [
      createTool(
        {
          name: 'protocol_operation',
          description: 'Operation description',
          parameters: z.object({
            param: z.string().describe('Parameter description')
          })
        },
        async ({ param }) => {
          return await service.someOperation({ param });
        }
      )
    ];
  }
}

import { newProtocol } from './plugins/new-protocol/index.js';

plugins: [
  // ... existing plugins
  newProtocol(),
]

sequenceDiagram
    participant Client as MCP Client<br/>(Claude/Cursor)
    participant Server as Stacks AI<br/>MCP Server
    participant Plugin as Protocol Plugin
    participant Network as Stacks Network

    Client->>Server: initialize
    Server->>Client: serverInfo + capabilities

    Client->>Server: tools/list
    Server->>Plugin: getAllTools()
    Plugin->>Server: 144+ Tool Definitions
    Server->>Client: Tool List

    Client->>Server: tools/call<br/>(tool: swap_tokens)
    Server->>Plugin: validateParameters()
    Plugin->>Plugin: buildContractCall()
    Plugin->>Server: Contract Call Data
    Server->>Client: Success Response

    Note over Client,Network: Client signs & broadcasts transaction

    Client->>Server: tools/call<br/>(tool: check_transaction)
    Server->>Network: Query Transaction
    Network->>Server: Transaction Status
    Server->>Client: Status Response

graph LR
    subgraph "Tool Definition"
        A[Tool Name] --> B[Description]
        B --> C[Parameter Schema]
        C --> D[Handler Function]
    end

    subgraph "Parameter Schema"
        E[Required Params] --> F[Optional Params]
        F --> G[Type Validation]
        G --> H[Custom Validators]
    end

    subgraph "Handler Execution"
        I[Receive Parameters] --> J[Validate Input]
        J --> K[Execute Service]
        K --> L[Format Response]
    end

    D --> I

    style A fill:#e1f5ff
    style C fill:#e1ffe1
    style D fill:#fff4e1
    style I fill:#ffe1f5
    style L fill:#f5e1ff

pie title "Tool Distribution by Category"
    "ALEX Protocol" : 34
    "Bitflow Protocol" : 29
    "Arkadiko Protocol" : 28
    "Velar Protocol" : 18
    "Granite Protocol" : 21
    "Charisma Protocol" : 14
    "Core Operations" : 40

graph TB
    subgraph "Core Technologies"
        A[TypeScript 5.x]
        B[Node.js 20+]
        C[Model Context Protocol]
        D[Zod Schema Validation]
    end

    subgraph "Stacks Technologies"
        E[Stacks.js SDK]
        F[Clarity Smart Contracts]
        G[Hiro API]
        H[Clarinet Testing]
    end

    subgraph "Protocol SDKs"
        I[Velar SDK]
        J[Bitflow SDK]
        K[BNS SDK]
        L[Protocol APIs]
    end

    subgraph "Development Tools"
        M[pnpm Package Manager]
        N[ESLint + Prettier]
        O[Jest Testing]
        P[Git + GPG Signing]
    end

    A --> E
    B --> E
    C --> E
    D --> E

    E --> I
    E --> J
    E --> K
    F --> G
    G --> H

    style A fill:#e1f5ff
    style C fill:#ffe1f5
    style E fill:#e1ffe1
    style F fill:#fff4e1