Algorand MCP Server

<div align="center"> # Contributing to Algorand MCP Server **Thank you for your interest in contributing to the Algorand MCP Server!** This document provides guidelines and instructions for contributing to this project. </div> ## Code of Conduct Please be respectful and considerate of others when contributing to this project. We aim to foster an inclusive and welcoming community for all developers in the Algorand ecosystem. ## How to Contribute ### Reporting Bugs If you find a bug, please create an issue on GitHub with the following information: - A clear, descriptive title - A detailed description of the bug - Steps to reproduce the bug - Expected behavior - Actual behavior - Any relevant logs or screenshots - Your environment (OS, Node.js version, npm version) - Transaction IDs on Algorand if applicable - Network used (mainnet/testnet) ### Suggesting Enhancements If you have an idea for an enhancement, please create an issue on GitHub with the following information: - A clear, descriptive title - A detailed description of the enhancement - Any relevant examples or mockups - Why this enhancement would be useful for Algorand developers - Potential implementation approach ### Pull Requests 1. Fork the repository 2. Create a new branch for your feature or bugfix (`git checkout -b feature/amazing-feature`) 3. Make your changes 4. Run tests to ensure your changes don't break existing functionality 5. Commit your changes (`git commit -m 'feat: add amazing feature'`) 6. Push to the branch (`git push origin feature/amazing-feature`) 7. Open a Pull Request. Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as your PR's title ## Development Setup 1. Clone your fork of the repository 2. Install dependencies: `npm install` 3. Create a `.env` file with your configuration (see README.md) 4. Test the server: `npm start` 5. Test the MCP server: `npm run mcp` ## Coding Standards - Follow the existing code style (JavaScript/Node.js conventions) - Write clear, descriptive commit messages - Add JSDoc comments to your code where necessary - Write tests for new features when applicable - Update documentation when necessary - Use meaningful variable and function names - Keep functions small and focused on a single responsibility ## Adding New MCP Tools If you want to add a new tool to the Algorand MCP server, follow these steps: ### 1. Create the Tool Handler Add your tool to the TOOLS array in `mcp/index.js`: ```javascript // Add to TOOLS array { name: 'your_tool_name', description: 'Clear description of what your tool does', inputSchema: { type: 'object', properties: { address: { type: 'string', description: 'Algorand account address', }, parameter_one: { type: 'string', description: 'Description of parameter', }, parameter_two: { type: 'number', description: 'Optional parameter', default: 10, }, }, required: ['address', 'parameter_one'], }, }, // Add case in switch statement case 'your_tool_name': result = await algorandAPI.yourMethod( args.address, args.parameter_one, args.parameter_two || 10 ); break; ``` ### 2. Handle Algorand-Specific Features When adding tools that interact with Algorand: ```javascript // Initialize Algorand API client const algorandAPI = new AlgorandAPI({ network: process.env.ALGORAND_NETWORK || 'mainnet' }); // Validate Algorand addresses if (!algosdk.isValidAddress(address)) { throw new Error('Invalid Algorand address'); } // Handle transactions const txn = await algorandAPI.sendPayment(from, to, amount, note, privateKey); // Wait for confirmation const confirmed = await algorandAPI.waitForConfirmation(txn.txId); // Handle smart contracts const result = await algorandAPI.callContract(appId, sender, privateKey, appArgs); ``` ### 3. Add Tests Create test cases for your new tool: ```javascript // test-your-tool.js const testYourTool = async () => { // Test the tool directly const algorandAPI = new AlgorandAPI({ network: 'testnet' }); try { const result = await algorandAPI.yourMethod( 'TESTNET_ADDRESS', 'parameter_value', 10 ); console.log('Tool result:', result); } catch (error) { console.error('Test failed:', error); } }; ``` ### 4. Update Documentation - Add your tool to the README.md tools section with proper category - Include example usage in the Examples section - Document supported networks (mainnet/testnet) - Add example prompts that would use your tool - Update the tool count in README.md features ## Testing Guidelines ### Running Tests ```bash # Run all tests npm test # Test MCP server with specific tool node mcp/index.js # In another terminal, test with curl curl -X POST http://localhost:3000 \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "your_tool_name", "arguments": {"address": "ALGORAND_ADDRESS", "parameter_one": "value"}}, "id": 1}' ``` ### Writing Tests - Test both success and failure cases - Include edge cases (invalid addresses, insufficient balance) - Test with various parameter combinations - Verify error messages are helpful - Test on both mainnet and testnet - Test transaction confirmation - Mock API responses for consistent testing ## Algorand Integration When adding features that interact with Algorand: 1. Validate addresses using algosdk 2. Handle minimum balance requirements (0.1 ALGO) 3. Implement proper error handling for transactions 4. Respect network rate limits 5. Test on testnet before mainnet ## Smart Contract Operations When adding smart contract features: 1. Support TEAL, Python, and TypeScript contracts 2. Handle global and local state properly 3. Implement proper ABI encoding/decoding 4. Test contract deployment and calls 5. Document state schema requirements ## Asset Operations When adding ASA (Algorand Standard Asset) functionality: 1. Validate asset parameters (decimals, total supply) 2. Handle opt-in requirements 3. Implement freeze/clawback logic if needed 4. Test asset creation and transfers 5. Consider ARC standards (ARC-3, ARC-69 for NFTs) ## Algorand SDK Integration When using Algorand SDK: ```javascript // Import the Algorand SDK const algosdk = require('algosdk'); // Initialize clients const algodClient = new algosdk.Algodv2('', 'https://mainnet-api.algonode.cloud', ''); const indexerClient = new algosdk.Indexer('', 'https://mainnet-idx.algonode.cloud', ''); // Create transaction const txn = algosdk.makePaymentTxnWithSuggestedParams( from, to, amount, undefined, note, params ); // Sign transaction const signedTxn = txn.signTxn(privateKey); // Send transaction const { txId } = await algodClient.sendRawTransaction(signedTxn).do(); ``` ## Environment Variables When adding new environment variables: 1. Update the `.env.example` file with clear comments 2. Document in README.md environment section 3. Add validation in `algorand-api.js` 4. Provide sensible defaults where appropriate Example: ```javascript // In algorand-api.js constructor this.network = process.env.ALGORAND_NETWORK || 'mainnet'; this.apiKey = process.env.ALGORAND_API_KEY || ''; // Network validation if (!['mainnet', 'testnet', 'betanet'].includes(this.network)) { throw new Error('Invalid network specified'); } ``` ## Documentation - Keep README.md up to date with all changes - Use clear, concise language - Include JavaScript code examples for tools - Document Algorand-specific concepts - Add comments in code where necessary - Document supported networks and requirements - Include response examples where helpful - Update prompts section if adding new capabilities ## Security Considerations - **Never commit private keys or mnemonics** - Validate all Algorand addresses - Check minimum balance requirements - Implement proper transaction validation - Follow Algorand security best practices - Review dependencies for vulnerabilities - Handle private keys securely - Don't log sensitive information - Use HTTPS for all API calls ## Performance Guidelines - Use batch operations where possible - Implement caching for frequently accessed data - Use indexer for historical queries - Monitor API rate limits - Profile code for bottlenecks - Consider response time requirements - Cache network status for short periods - Optimize transaction grouping ## Algorand-Specific Considerations ### Network Support - Support mainnet, testnet, and betanet - Handle network-specific parameters - Implement proper network validation - Use appropriate endpoints for each network ### Transaction Management - Validate transaction parameters - Handle atomic transactions - Support transaction notes - Implement proper fee calculation ### Asset Standards - Support ARC-3 for NFTs - Support ARC-69 for enhanced NFTs - Handle fungible tokens properly - Implement proper metadata handling ### Smart Contract Standards - Support ABI for contract interaction - Handle state schema properly - Implement proper argument encoding - Support all transaction types ## Submitting Your Contribution Before submitting: 1. Ensure all tests pass 2. Update README.md with new tools 3. Check for linting issues 4. Verify no private keys are included 5. Write a clear PR description with examples 6. Test on Algorand testnet 7. Include sample responses in PR 8. Update tool count in README if adding new tools ## Getting Help If you need help with your contribution: - Check existing issues and PRs on GitHub - Ask questions in the issue tracker - Review [Algorand Developer Documentation](https://developer.algorand.org/) - Check [AlgoKit Documentation](https://github.com/algorandfoundation/algokit-cli) - Join [Algorand Discord](https://discord.gg/algorand) for support - Review [Algorand Forum](https://forum.algorand.org/) ## Recognition Contributors will be recognized in: - The project README contributors section - GitHub release notes - Special thanks in major version releases Thank you for helping improve the Algorand MCP Server! --- <div align="center"> **Built by [Tairon.ai](https://tairon.ai/) team with help from Claude** </div>