# hatif03/algorand-mcp architecture

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

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

## Overview

##### Project type and purpose
- This is a backend MCP (Model Context Protocol) server written in TypeScript/Node.js that exposes 47+ Algorand‐specific “tools” for AI assistants (VSCode, Claude Desktop, Cursor, etc.).
- Its sole responsibility is to listen for MCP calls (JSON-RPC over stdin/stdout), dispatch them to the appropriate tool handler in your codebase, and interact with Algorand network endpoints or other services.

##### File structure
- Top-level files:
- package.json / tsconfig.json / .env.example → build & environment config
- README, TESTING, TEST_QUERIES, MCP_SETUP → docs & usage
- src/ directory (the heart of the architecture):
- index.ts → MCP server bootstrap, tool registration & dispatch
- algorand.ts → core Algorand blockchain operations
- apiTools.ts → wrappers around Algod, Indexer & NFD REST APIs
- utilityTools.ts → address validation, TEAL compile/disassemble, msgpack encode/decode
- advancedTransactionTools.ts → atomic groups & smart-contract calls
- arc26Tools.ts → ARC-26 URI & QRCode generation
- knowledgeTools.ts → semantic search (Qdrant + OpenAI embeddings)
- Build output: dist/ (JavaScript)
- Dev config: .vscode/mcp.json

##### Key insights from README
- Modular design: each file defines a “tool category” with a list of Zod‐validated schemas and handler methods.
- Security: AES-256-GCM encryption for mnemonic storage (wallet management), environment‐driven network endpoints (ALGORAND_ALGOD, ALGORAND_INDEXER, NFD_API_URL), optional Qdrant/OpenAI for embeddings.
- Interaction pattern: client → MCP server (index.ts) → tool module → service method → external API or local crypto logic → response.

##### Main components & their relationships
A. MCP Client(s) (VSCode / Claude / Cursor / custom)
B. MCP Server (your code)
1. EntryPoint (index.ts)
- Registers all tools (Basic, Core, Utility, API, Advanced, ARC-26, Knowledge)
- Parses incoming MCP requests → tool name + args
- Delegates to the matching module & service method
- CoreAlgorandModule
- UtilityModule
- ApiModule
- AdvancedTxModule
- Arc26Module
- KnowledgeModule
3. Services & Helpers inside each module (business logic + Zod validation)
4. Encryption Layer (AES-256-GCM) for wallet storage
C. External Services (cloud endpoints):
- Algod REST API (node / indexer)
- Indexer REST API
- NFD API
- Qdrant vector store (optional)
- OpenAI API (for embedding + semantic search)
D. Environment Configuration & Secrets
- .env or process.env drives network URLs, tokens, API keys

##### Architecture patterns & design principles
- Modular plugin-style: each tool category lives in its own file with an exportable array of “Tools.”
- Single dispatch point (index.ts) using a switch or map of tool names → service calls.
- Zod schemas for input validation at the boundary of each tool.
- Clear separation:
- Protocol layer (MCP request/response)
- Tool definition & validation
- Core business logic & external calls
- Encryption / security
- No persistent database (stateless server); all stateful data handled via secure in-memory or file storage if implemented.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "MCP Clients"
        VSCode["VSCode"]:::client
        Claude["Claude Desktop"]:::client
        Cursor["Cursor"]:::client
    end

    subgraph "MCP Server"
        EntryPoint["EntryPoint\n(index.ts)"]:::protocol
        shield[/"AES-256-GCM Encryption"/]:::security
        subgraph "Tool Modules"
            Core["CoreAlgorandModule"]:::module
            Utility["UtilityModule"]:::module
            API["ApiModule"]:::module
            Advanced["AdvancedTxModule"]:::module
            ARC26["Arc26Module"]:::module
            Knowledge["KnowledgeModule"]:::module
        end
    end

    subgraph "External Services"
        Algod[(Algod REST API)]:::external
        Indexer[(Indexer REST API)]:::external
        NFD[(NFD API)]:::external
        Qdrant[(Qdrant & OpenAI)]:::external
    end

    VSCode -->|"MCP JSON-RPC request"| EntryPoint
    Claude -->|"MCP JSON-RPC request"| EntryPoint
    Cursor -->|"MCP JSON-RPC request"| EntryPoint

    EntryPoint -->|"invokeTool(name,args)"| Core
    EntryPoint -->|"invokeTool(name,args)"| Utility
    EntryPoint -->|"invokeTool(name,args)"| API
    EntryPoint -->|"invokeTool(name,args)"| Advanced
    EntryPoint -->|"invokeTool(name,args)"| ARC26
    EntryPoint -->|"invokeTool(name,args)"| Knowledge

    Core --> shield
    Utility --> shield

    Core -->|"HTTP REST"| Algod
    API -->|"HTTP REST"| Indexer
    API -->|"HTTP REST"| NFD
    Knowledge -->|"HTTP REST"| Qdrant

    Algod -->|"response"| Core
    Indexer -->|"response"| API
    NFD -->|"response"| API
    Qdrant -->|"response"| Knowledge

    Core -->|"MCP response"| EntryPoint
    Utility -->|"MCP response"| EntryPoint
    API -->|"MCP response"| EntryPoint
    Advanced -->|"MCP response"| EntryPoint
    ARC26 -->|"MCP response"| EntryPoint
    Knowledge -->|"MCP response"| EntryPoint

    EntryPoint -->|"MCP JSON-RPC response"| VSCode
    EntryPoint -->|"MCP JSON-RPC response"| Claude
    EntryPoint -->|"MCP JSON-RPC response"| Cursor

    subgraph "Configuration & Documentation"
        pkg["package.json"]:::config
        tsconfig["tsconfig.json"]:::config
        env[".env.example"]:::config
        readme["README.md"]:::docs
        setup["MCP_SETUP.md"]:::docs
        testing["TESTING.md / TEST_QUERIES.md"]:::docs
    end

    click EntryPoint "https://github.com/hatif03/algorand-mcp/blob/main/src/index.ts"
    click Core "https://github.com/hatif03/algorand-mcp/blob/main/src/algorand.ts"
    click API "https://github.com/hatif03/algorand-mcp/blob/main/src/apiTools.ts"
    click Utility "https://github.com/hatif03/algorand-mcp/blob/main/src/utilityTools.ts"
    click Advanced "https://github.com/hatif03/algorand-mcp/blob/main/src/advancedTransactionTools.ts"
    click ARC26 "https://github.com/hatif03/algorand-mcp/blob/main/src/arc26Tools.ts"
    click Knowledge "https://github.com/hatif03/algorand-mcp/blob/main/src/knowledgeTools.ts"
    click pkg "https://github.com/hatif03/algorand-mcp/blob/main/package.json"
    click tsconfig "https://github.com/hatif03/algorand-mcp/blob/main/tsconfig.json"
    click env "https://github.com/hatif03/algorand-mcp/blob/main/.env.example"
    click readme "https://github.com/hatif03/algorand-mcp/blob/main/README.md"
    click setup "https://github.com/hatif03/algorand-mcp/blob/main/MCP_SETUP.md"
    click testing "https://github.com/hatif03/algorand-mcp/blob/main/TESTING.md"

    classDef client fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef protocol fill:#85C1E9,stroke:#1B4F72,color:#1B2631
    classDef module fill:#D5DBDB,stroke:#566573,color:#1B2631
    classDef security fill:#F1948A,stroke:#943126,color:#641E16
    classDef external fill:#7DCEA0,stroke:#145A32,color:#145A32
    classDef config fill:#F9E79F,stroke:#7D6608,color:#7D6608
    classDef docs fill:#E8DAEF,stroke:#6C3483,color:#4A235A
```
