How hatif03/algorand-mcp works
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.