@goplausible/algorand-mcp 3.0.7

package/dist/tools/apiManager/tinyman/swap.js

@@ -0,0 +1,147 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { Swap, poolUtils, SwapType } from '@tinymanorg/tinyman-js-sdk';
+import { getAlgodClient, extractNetwork } from '../../../algorand-client.js';
+import { withCommonParams } from '../../commonParams.js';
+export const swapTools = [
+    {
+        name: 'api_tinyman_get_swap_quote',
+        description: 'Get quote for swapping assets',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                assetIn: {
+                    type: 'integer',
+                    description: 'ID of the input asset'
+                },
+                assetOut: {
+                    type: 'integer',
+                    description: 'ID of the output asset'
+                },
+                amount: {
+                    type: 'integer',
+                    description: 'Amount to swap'
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['fixedInput', 'fixedOutput'],
+                    description: 'Mode of swap'
+                },
+                version: {
+                    type: 'string',
+                    enum: ['v1_1', 'v2'],
+                    description: 'Tinyman protocol version',
+                    default: 'v2'
+                }
+            },
+            required: ['assetIn', 'assetOut', 'amount', 'mode']
+        })
+    }
+];
+export async function handleSwapTools(args) {
+    const { name, assetIn, assetOut, amount, mode, version = 'v2' } = args;
+    const network = extractNetwork(args);
+    const algodClient = getAlgodClient(network);
+    if (network === 'localnet') {
+        throw new McpError(ErrorCode.InvalidRequest, 'Tinyman is not available on localnet');
+    }
+    const tinymanNetwork = network;
+    async function getAssetDecimals(assetId) {
+        try {
+            if (assetId === 0)
+                return 6; // Algo has 6 decimals
+            const assetInfo = await algodClient.getAssetByID(assetId).do();
+            return assetInfo.params.decimals;
+        }
+        catch (error) {
+            console.error(`Failed to get decimals for asset ${assetId}:`, error);
+            return 6; // Default to 6 decimals if we can't get the info
+        }
+    }
+    if (name === 'api_tinyman_get_swap_quote') {
+        try {
+            // Get pool information first
+            const poolInfo = await (version === 'v2'
+                ? poolUtils.v2.getPoolInfo({
+                    client: algodClient,
+                    network: tinymanNetwork,
+                    asset1ID: assetIn,
+                    asset2ID: assetOut
+                })
+                : poolUtils.v1_1.getPoolInfo({
+                    client: algodClient,
+                    network: tinymanNetwork,
+                    asset1ID: assetIn,
+                    asset2ID: assetOut
+                }));
+            // Get asset decimals
+            const [assetInDecimals, assetOutDecimals] = await Promise.all([
+                getAssetDecimals(assetIn),
+                getAssetDecimals(assetOut)
+            ]);
+            let quote;
+            if (version === 'v2') {
+                if (mode === 'fixedInput') {
+                    quote = await Swap.v2.getQuote({
+                        assetIn: {
+                            id: assetIn,
+                            decimals: assetInDecimals
+                        },
+                        assetOut: {
+                            id: assetOut,
+                            decimals: assetOutDecimals
+                        },
+                        pool: poolInfo,
+                        amount: BigInt(amount),
+                        type: SwapType.FixedInput,
+                        network: tinymanNetwork,
+                        slippage: 0.01 // 1% slippage
+                    });
+                }
+                else {
+                    quote = await Swap.v2.getQuote({
+                        assetIn: {
+                            id: assetIn,
+                            decimals: assetInDecimals
+                        },
+                        assetOut: {
+                            id: assetOut,
+                            decimals: assetOutDecimals
+                        },
+                        pool: poolInfo,
+                        amount: BigInt(amount),
+                        type: SwapType.FixedOutput,
+                        network: tinymanNetwork,
+                        slippage: 0.01
+                    });
+                }
+            }
+            else {
+                // Get pool reserves for v1.1
+                const reserves = await poolUtils.v1_1.getPoolReserves(algodClient, poolInfo);
+                if (mode === 'fixedInput') {
+                    quote = Swap.v1_1.getQuote(SwapType.FixedInput, poolInfo, reserves, {
+                        id: assetIn,
+                        amount: BigInt(amount)
+                    }, {
+                        assetIn: assetInDecimals,
+                        assetOut: assetOutDecimals
+                    });
+                }
+                else {
+                    quote = Swap.v1_1.getQuote(SwapType.FixedOutput, poolInfo, reserves, {
+                        id: assetOut,
+                        amount: BigInt(amount)
+                    }, {
+                        assetIn: assetInDecimals,
+                        assetOut: assetOutDecimals
+                    });
+                }
+            }
+            return quote;
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to get swap quote: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    throw new McpError(ErrorCode.MethodNotFound, `Unknown swap tool: ${name}`);
+}

package/dist/tools/arc26Manager.d.ts

@@ -0,0 +1,37 @@
+interface Arc26ToolInput {
+    address: string;
+    label?: string;
+    amount?: number;
+    asset?: number;
+    note?: string;
+    xnote?: string;
+}
+export declare class Arc26Manager {
+    arc26Tools: {
+        name: string;
+        description: string;
+        inputSchema: any;
+    }[];
+    /**
+     * Constructs an Algorand URI according to ARC-26 specification and generates a QR code
+     * @param params The parameters for constructing the URI
+     * @returns Object containing the URI and QR code as base64 data URL
+     */
+    generateUriAndQr(params: Arc26ToolInput): Promise<{
+        uri: string;
+        qrCode: string;
+    }>;
+    handleTool(name: string, args: Record<string, unknown>): Promise<{
+        content: ({
+            type: string;
+            text: string;
+            mimeType?: undefined;
+        } | {
+            type: string;
+            text: string;
+            mimeType: string;
+        })[];
+    }>;
+}
+export declare const arc26Manager: Arc26Manager;
+export {};

package/dist/tools/arc26Manager.js

@@ -0,0 +1,131 @@
+import * as QRCode from 'qrcode';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { withCommonParams } from './commonParams.js';
+export class Arc26Manager {
+    constructor() {
+        this.arc26Tools = [
+            {
+                name: 'generate_algorand_uri',
+                description: 'Generate an Algorand URI and QR code according to ARC-26 specification',
+                inputSchema: withCommonParams({
+                    type: 'object',
+                    properties: {
+                        address: {
+                            type: 'string',
+                            description: 'Algorand address in standard format (58 characters)'
+                        },
+                        label: {
+                            type: 'string',
+                            description: 'Label for the address (e.g. name of receiver)',
+                            optional: true
+                        },
+                        amount: {
+                            type: 'number',
+                            description: 'Amount in microAlgos (must be non-negative)',
+                            optional: true
+                        },
+                        asset: {
+                            type: 'number',
+                            description: 'Asset ID for ASA transfers',
+                            optional: true
+                        },
+                        note: {
+                            type: 'string',
+                            description: 'URL-encoded note that can be modified by user',
+                            optional: true
+                        },
+                        xnote: {
+                            type: 'string',
+                            description: 'URL-encoded note that must not be modified by user',
+                            optional: true
+                        }
+                    },
+                    required: ['address']
+                })
+            }
+        ];
+    }
+    /**
+     * Constructs an Algorand URI according to ARC-26 specification and generates a QR code
+     * @param params The parameters for constructing the URI
+     * @returns Object containing the URI and QR code as base64 data URL
+     */
+    async generateUriAndQr(params) {
+        // Validate address format (base32 string)
+        if (!params.address || !/^[A-Z2-7]{58}$/.test(params.address)) {
+            throw new McpError(ErrorCode.InvalidParams, 'Invalid Algorand address format');
+        }
+        // Start building the URI with the scheme and address
+        let uri = `algorand://${params.address}`;
+        // Build query parameters
+        const queryParams = [];
+        // Add optional parameters if provided
+        if (params.label) {
+            queryParams.push(`label=${encodeURIComponent(params.label)}`);
+        }
+        if (typeof params.amount === 'number') {
+            if (params.amount < 0) {
+                throw new McpError(ErrorCode.InvalidParams, 'Amount must be non-negative');
+            }
+            // Convert to microAlgos and ensure no decimals
+            const microAlgos = Math.floor(params.amount);
+            queryParams.push(`amount=${microAlgos}`);
+        }
+        if (typeof params.asset === 'number') {
+            if (params.asset < 0) {
+                throw new McpError(ErrorCode.InvalidParams, 'Asset ID must be non-negative');
+            }
+            queryParams.push(`asset=${params.asset}`);
+        }
+        if (params.note) {
+            queryParams.push(`note=${encodeURIComponent(params.note)}`);
+        }
+        if (params.xnote) {
+            queryParams.push(`xnote=${encodeURIComponent(params.xnote)}`);
+        }
+        // Add query parameters to URI if any exist
+        if (queryParams.length > 0) {
+            uri += '?' + queryParams.join('&');
+        }
+        // Generate QR code as SVG
+        const qrCode = await QRCode.toString(uri, {
+            type: 'svg',
+            errorCorrectionLevel: 'H',
+            margin: 1,
+            width: 300
+        });
+        return {
+            uri,
+            qrCode
+        };
+    }
+    async handleTool(name, args) {
+        // Cast args to Arc26ToolInput after validation
+        const toolArgs = {
+            address: args.address,
+            label: args.label,
+            amount: typeof args.amount === 'number' ? args.amount : undefined,
+            asset: typeof args.asset === 'number' ? args.asset : undefined,
+            note: args.note,
+            xnote: args.xnote
+        };
+        if (name === 'generate_algorand_uri') {
+            const { uri, qrCode } = await this.generateUriAndQr(toolArgs);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ uri }, null, 2)
+                    },
+                    {
+                        type: "text",
+                        text: qrCode,
+                        mimeType: "image/svg+xml"
+                    }
+                ]
+            };
+        }
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+    }
+}
+export const arc26Manager = new Arc26Manager();

package/dist/tools/commonParams.d.ts

@@ -0,0 +1,18 @@
+export declare const networkParam: {
+    network: {
+        type: string;
+        enum: string[];
+        description: string;
+    };
+};
+export declare const itemsPerPageParam: {
+    itemsPerPage: {
+        type: string;
+        description: string;
+    };
+};
+/**
+ * Merges network and itemsPerPage into a tool's inputSchema.
+ * Preserves existing properties and required fields.
+ */
+export declare function withCommonParams(schema: any): any;

package/dist/tools/commonParams.js

@@ -0,0 +1,28 @@
+// Common schema fragments added to all tool inputSchemas
+export const networkParam = {
+    network: {
+        type: 'string',
+        enum: ['mainnet', 'testnet', 'localnet'],
+        description: 'Algorand network to use (default: mainnet)',
+    },
+};
+export const itemsPerPageParam = {
+    itemsPerPage: {
+        type: 'integer',
+        description: 'Number of items per page for paginated responses (default: 10)',
+    },
+};
+/**
+ * Merges network and itemsPerPage into a tool's inputSchema.
+ * Preserves existing properties and required fields.
+ */
+export function withCommonParams(schema) {
+    return {
+        ...schema,
+        properties: {
+            ...schema.properties,
+            ...networkParam,
+            ...itemsPerPageParam,
+        },
+    };
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,8 @@
+export { AccountManager } from './accountManager.js';
+export { WalletManager } from './walletManager.js';
+export { KnowledgeManager } from './knowledgeManager.js';
+export { arc26Manager } from './arc26Manager.js';
+export { UtilityManager } from './utilityManager.js';
+export { TransactionManager, AccountTransactionManager, AssetTransactionManager, AppTransactionManager, GeneralTransactionManager, transactionTools } from './transactionManager/index.js';
+export { AlgodManager } from './algodManager.js';
+export { apiManager, handleApiManager } from './apiManager/index.js';

package/dist/tools/index.js

@@ -0,0 +1,8 @@
+export { AccountManager } from './accountManager.js';
+export { WalletManager } from './walletManager.js';
+export { KnowledgeManager } from './knowledgeManager.js';
+export { arc26Manager } from './arc26Manager.js';
+export { UtilityManager } from './utilityManager.js';
+export { TransactionManager, AccountTransactionManager, AssetTransactionManager, AppTransactionManager, GeneralTransactionManager, transactionTools } from './transactionManager/index.js';
+export { AlgodManager } from './algodManager.js';
+export { apiManager, handleApiManager } from './apiManager/index.js';

package/dist/tools/knowledgeManager.d.ts

@@ -0,0 +1,28 @@
+export declare const knowledgeToolSchemas: {
+    getKnowledgeDoc: {
+        type: string;
+        properties: {
+            documents: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare class KnowledgeManager {
+    static readonly knowledgeTools: {
+        name: string;
+        description: string;
+        inputSchema: any;
+    }[];
+    static handleTool(name: string, args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+}

package/dist/tools/knowledgeManager.js

@@ -0,0 +1,73 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { withCommonParams } from './commonParams.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+// Tool schemas
+export const knowledgeToolSchemas = {
+    getKnowledgeDoc: {
+        type: 'object',
+        properties: {
+            documents: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Array of document keys (e.g. ["ARCs:specs:arc-0020.md"])'
+            }
+        },
+        required: ['documents']
+    }
+};
+export class KnowledgeManager {
+    // Tool handlers
+    static async handleTool(name, args) {
+        try {
+            switch (name) {
+                case 'get_knowledge_doc':
+                    if (!Array.isArray(args.documents)) {
+                        throw new McpError(ErrorCode.InvalidParams, 'Documents array is required');
+                    }
+                    const results = await Promise.all(args.documents.map(async (docKey) => {
+                        if (typeof docKey !== 'string') {
+                            throw new McpError(ErrorCode.InvalidParams, 'Document key must be a string');
+                        }
+                        const __dirname = path.dirname(fileURLToPath(import.meta.url));
+                        const twoLevelsUp = path.resolve(__dirname, '../');
+                        console.error('Current directory:', __dirname);
+                        try {
+                            const filePath = path.resolve(twoLevelsUp, 'resources/knowledge/taxonomy', docKey);
+                            const content = await fs.readFile(filePath, 'utf-8');
+                            return content;
+                        }
+                        catch (error) {
+                            console.error(`[MCP Error] Failed to read document ${docKey}:`, error);
+                            throw new McpError(ErrorCode.InternalError, `Failed to read document ${docKey}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+                        }
+                    }));
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({ documents: results }, null, 2)
+                            }]
+                    };
+                default:
+                    console.error(`[MCP Error] Unknown tool requested: ${name}`);
+                    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof McpError) {
+                console.error(`[MCP Error] ${error.code}: ${error.message}`);
+                throw error;
+            }
+            console.error('[MCP Error] Unexpected error:', error);
+            throw new McpError(ErrorCode.InternalError, `Operation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+}
+KnowledgeManager.knowledgeTools = [
+    {
+        name: 'get_knowledge_doc',
+        description: 'Get markdown content for specified knowledge documents',
+        inputSchema: withCommonParams(knowledgeToolSchemas.getKnowledgeDoc),
+    }
+];

package/dist/tools/transactionManager/accountTransactions.d.ts

@@ -0,0 +1,127 @@
+import { Transaction, SuggestedParams } from 'algosdk';
+export declare const accountTransactionSchemas: {
+    makePaymentTxn: {
+        type: string;
+        description: string;
+        properties: {
+            from: {
+                type: string;
+                description: string;
+            };
+            to: {
+                type: string;
+                description: string;
+            };
+            amount: {
+                type: string;
+                description: string;
+            };
+            note: {
+                type: string;
+                optional: boolean;
+                description: string;
+            };
+            closeRemainderTo: {
+                type: string;
+                optional: boolean;
+                description: string;
+            };
+            rekeyTo: {
+                type: string;
+                optional: boolean;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    makeKeyRegTxn: {
+        type: string;
+        properties: {
+            from: {
+                type: string;
+                description: string;
+            };
+            voteKey: {
+                type: string;
+                description: string;
+            };
+            selectionKey: {
+                type: string;
+                description: string;
+            };
+            stateProofKey: {
+                type: string;
+                description: string;
+            };
+            voteFirst: {
+                type: string;
+                description: string;
+            };
+            voteLast: {
+                type: string;
+                description: string;
+            };
+            voteKeyDilution: {
+                type: string;
+                description: string;
+            };
+            nonParticipation: {
+                type: string;
+                optional: boolean;
+                description: string;
+            };
+            note: {
+                type: string;
+                optional: boolean;
+                description: string;
+            };
+            rekeyTo: {
+                type: string;
+                optional: boolean;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare const accountTransactionTools: {
+    name: string;
+    description: string;
+    inputSchema: any;
+}[];
+export declare class AccountTransactionManager {
+    /**
+     * Creates a payment transaction
+     */
+    static makePaymentTxn(txn: {
+        sender: string;
+        receiver: string;
+        amount: number;
+        closeRemainderTo?: string;
+        note?: Uint8Array;
+        rekeyTo?: string;
+        suggestedParams: SuggestedParams;
+    }): Transaction;
+    /**
+     * Creates a key registration transaction
+     */
+    static makeKeyRegTxn(txn: {
+        sender: string;
+        note?: Uint8Array;
+        rekeyTo?: string;
+        suggestedParams: SuggestedParams;
+        voteKey: Uint8Array | string;
+        selectionKey: Uint8Array | string;
+        stateProofKey: Uint8Array | string;
+        voteFirst: number;
+        voteLast: number;
+        voteKeyDilution: number;
+        nonParticipation?: boolean;
+    }): Transaction;
+    static handleTool(name: string, args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+}