# goplausible/algorand-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/goplausible/algorand-mcp
- Repository: https://github.com/goplausible/algorand-mcp

## Overview

##### Project Type and Purpose
- This is an open-source, monorepo toolset implementing a Model Context Protocol (MCP) for Algorand.
- It consists of two co-located packages:
- **Server** – a Node.js microservice exposing MCP-compliant HTTP/JSON endpoints to LLM hosts (Claude, Cursor).
- **Client** – a TypeScript library for wallet management and transaction signing (browser & Node.js).

##### High-Level File Structure & Architectural Patterns
- **Monorepo layout**
- Root: package.json, tsconfig.json, shared tooling/config.
- /packages/client: LocalWallet.ts, index.ts, env.ts – client entry, wallet abstraction, environment config.
- /packages/server:
– **API specs** (OpenAPI/JSON files) + smithery.yaml – endpoint definitions, request/response schemas
– **src/index.ts** – service bootstrap (reads env, registers resources, starts HTTP server)
– **src/env.ts** – central environment/config loader
– **src/resources** – “controllers” or resource handlers (knowledge docs, wallet endpoints)
– **src/tools** – “services” layer: accountManager, algodManager, utilityManager, transactionManager and sub-modules (apiManager for Algod/Indexer/NFD/Tinyman/Ultrade/Vestige)
– **tests** covering resources and tools
– Dockerfile, jest.config, tsconfig

- **Layered modular architecture**
- **Resource Layer** (HTTP handlers) → **Tools/Service Layer** (business logic) → **External Systems** (Algorand nodes, DEX APIs, NFD service).
- **Design patterns**
- Separation of concerns: docs vs. wallet vs. transaction vs. API tools
- Standardized response envelope (data + metadata / error)
- Environment-driven feature toggles for optional DeFi integrations

##### Key Concepts from README
- Exposes ~125 “tools & resources” grouped by category (account, asset, application, transactions, key management, docs taxonomy).
- Integrates with Algorand network via algosdk, plus optional external services:
- NFDomains for name service
- Tinyman, Ultrade, Vestige for DeFi analytics/AMM/DEX
- Client package is WIP: provides LocalWallet, external wallet connectors (Pera, Defly, Daffi).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Agent Layer
    LLM["LLM Host / Agent\n(Claude, Cursor)"]:::external
    CLIENT["MCP Client Library\n(packages/client)"]:::client

    LLM -->|"MCP Protocol Calls"| HTTP
    CLIENT -->|"Library Usage"| HTTP

    %% Server Package
    subgraph "Algorand MCP Server" 
        direction TB
        HTTP["HTTP Listener\n(src/index.ts)"]:::resource
        ENV["Env Config Loader\n(src/env.ts)"]:::resource

        subgraph "Resource Layer" 
            direction TB
            KNOW["Knowledge Handlers\n(resources/knowledge)"]:::resource
            WALLET["Wallet Endpoints\n(resources/wallet/index.ts)"]:::resource
        end

        subgraph "Tools / Service Layer"
            direction TB
            ACC["Account Manager Service\n(tools/accountManager.ts)"]:::service
            ARC26["Arc26 Manager\n(tools/arc26Manager.ts)"]:::service
            ALGODM["Algod Manager\n(tools/algodManager.ts)"]:::service
            KNOWM["Knowledge Manager\n(tools/knowledgeManager.ts)"]:::service
            UTIL["Utility Manager\n(tools/utilityManager.ts)"]:::service
            TX["Transaction Manager\n(tools/transactionManager)"]:::service
            subgraph "API Managers"
                direction TB
                APIA["Algod API Manager\n(tools/apiManager/algod)"]:::service
                APII["Indexer API Manager\n(tools/apiManager/indexer)"]:::service
                APINFD["NFD API Manager\n(tools/apiManager/nfd)"]:::service
                APITINY["Tinyman API Manager\n(tools/apiManager/tinyman)"]:::service
                APIULTRA["Ultrade API Manager\n(tools/apiManager/ultrade)"]:::service
                APIVEST["Vestige API Manager\n(tools/apiManager/vestige)"]:::service
            end
            UTIL -->|calls| APINFD
            UTIL -->|calls| APITINY
            UTIL -->|calls| APIULTRA
            UTIL -->|calls| APIVEST
        end

        UTILUTIL["Response Processor\n(utils/responseProcessor.ts)"]:::utility
        TYPES["Type Definitions\n(src/types.ts)"]:::utility

        %% Connections within server
        HTTP -->|"routes"| KNOW
        HTTP -->|"routes"| WALLET
        HTTP -->|"uses config"| ENV
        KNOW -->|"calls"| ACC
        KNOW -->|"calls"| ARC26
        WALLET -->|"calls"| TX
        TX -->|"calls algosdk"| ALGODM
        ACC -->|"calls indexer"| APII
        ARC26 -->|"calls algod"| APIA
        TX -->|"uses utils"| UTILUTIL
        HTTP -->|"response envelope"| UTILUTIL
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        ALGODNODE["Algod Node(s)"]:::externalSys
        INDEXERNODE["Indexer Node(s)"]:::externalSys
        NFDAPI["NFD API"]:::externalSys
        TINY["Tinyman AMM"]:::externalSys
        ULTRA["Ultrade DEX"]:::externalSys
        VEST["Vestige Analytics"]:::externalSys
    end

    %% Data flow to externals
    APIA -->|"HTTP"| ALGODNODE
    APII -->|"HTTP"| INDEXERNODE
    APINFD -->|"HTTP"| NFDAPI
    APITINY -->|"HTTP"| TINY
    APIULTRA -->|"HTTP"| ULTRA
    APIVEST -->|"HTTP"| VEST

    %% Response flow
    UTILUTIL -->|"standardized response"| LLM

    %% Click Events
    click HTTP "https://github.com/goplausible/algorand-mcp/blob/main/packages/server/src/index.ts"
    click ENV "https://github.com/goplausible/algorand-mcp/blob/main/packages/server/src/env.ts"
    click KNOW "https://github.com/goplausible/algorand-mcp/blob/main/packages/server/src/resources/knowledge/index.ts"
    click WALLET "https://github.com/goplausible/algorand-mcp/blob/main/packages/server/src/resources/wallet/index.ts"
    click ACC "https://github.com/goplausible/algorand-mcp/blob/main/packages/server/src/tools/accountManager.ts"
    click ARC26 "https://github.com/goplausible/algorand-mcp/blob/main/packages/server/src/tools/arc26Manager.ts"
    click ALGODM "https://github.com/goplausible/algorand-mcp/blob/main/packages/server/src/tools/algodManager.ts"
    click KNOWM "https://github.com/goplausible/algorand-mcp/blob/main/packages/server/src/tools/knowledgeManager.ts"
    click UTIL "https://github.com/goplausible/algorand-mcp/blob/main/packages/server/src/tools/utilityManager.ts"
    click TX "https://github.com/goplausible/algorand-mcp/tree/main/packages/server/src/tools/transactionManager"
    click APIA "https://github.com/goplausible/algorand-mcp/tree/main/packages/server/src/tools/apiManager/algod"
    click APII "https://github.com/goplausible/algorand-mcp/tree/main/packages/server/src/tools/apiManager/indexer"
    click APINFD "https://github.com/goplausible/algorand-mcp/tree/main/packages/server/src/tools/apiManager/nfd"
    click APITINY "https://github.com/goplausible/algorand-mcp/tree/main/packages/server/src/tools/apiManager/tinyman"
    click APIULTRA "https://github.com/goplausible/algorand-mcp/tree/main/packages/server/src/tools/apiManager/ultrade"
    click APIVEST "https://github.com/goplausible/algorand-mcp/tree/main/packages/server/src/tools/apiManager/vestige"
    click UTILUTIL "https://github.com/goplausible/algorand-mcp/blob/main/packages/server/src/utils/responseProcessor.ts"

    click CLIENT "https://github.com/goplausible/algorand-mcp/blob/main/packages/client/src/index.ts"
    click CLIENT "https://github.com/goplausible/algorand-mcp/blob/main/packages/client/src/LocalWallet.ts"
    click CLIENT "https://github.com/goplausible/algorand-mcp/blob/main/packages/client/src/env.ts"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef client fill:#d0b,stroke:#333,stroke-width:1px
    classDef resource fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef service fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef utility fill:#fff9c4,stroke:#fbc02d,stroke-width:1px
    classDef externalSys fill:#ffe0b2,stroke:#f57c00,stroke-width:1px
```
