@goplausible/algorand-mcp 3.0.7

package/dist/types.d.ts

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+export declare const CreateAccountResultSchema: z.ZodObject<{
+    address: z.ZodString;
+    privateKey: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    address: string;
+    privateKey: string;
+}, {
+    address: string;
+    privateKey: string;
+}>;
+export type CreateAccountResult = z.infer<typeof CreateAccountResultSchema>;
+export declare const RekeyAccountParamsSchema: z.ZodObject<{
+    sourceAddress: z.ZodString;
+    targetAddress: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sourceAddress: string;
+    targetAddress: string;
+}, {
+    sourceAddress: string;
+    targetAddress: string;
+}>;
+export type RekeyAccountParams = z.infer<typeof RekeyAccountParamsSchema>;
+export declare const RekeyAccountResultSchema: z.ZodObject<{
+    txId: z.ZodString;
+    signedTxn: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    txId: string;
+    signedTxn: string;
+}, {
+    txId: string;
+    signedTxn: string;
+}>;
+export type RekeyAccountResult = z.infer<typeof RekeyAccountResultSchema>;
+export declare const AccountDetailsSchema: z.ZodObject<{
+    address: z.ZodString;
+    amount: z.ZodUnion<[z.ZodNumber, z.ZodBigInt]>;
+    assets: z.ZodArray<z.ZodObject<{
+        assetId: z.ZodUnion<[z.ZodNumber, z.ZodBigInt]>;
+        amount: z.ZodUnion<[z.ZodNumber, z.ZodBigInt]>;
+    }, "strip", z.ZodTypeAny, {
+        assetId: number | bigint;
+        amount: number | bigint;
+    }, {
+        assetId: number | bigint;
+        amount: number | bigint;
+    }>, "many">;
+    authAddress: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    address: string;
+    amount: number | bigint;
+    assets: {
+        assetId: number | bigint;
+        amount: number | bigint;
+    }[];
+    authAddress?: string | undefined;
+}, {
+    address: string;
+    amount: number | bigint;
+    assets: {
+        assetId: number | bigint;
+        amount: number | bigint;
+    }[];
+    authAddress?: string | undefined;
+}>;
+export type AccountDetails = z.infer<typeof AccountDetailsSchema>;
+export declare const TransactionInfoSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    sender: z.ZodString;
+    receiver: z.ZodOptional<z.ZodString>;
+    amount: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodBigInt]>>;
+    assetId: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodBigInt]>>;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sender: string;
+    type: string;
+    id: string;
+    timestamp: string;
+    assetId?: number | bigint | undefined;
+    amount?: number | bigint | undefined;
+    receiver?: string | undefined;
+}, {
+    sender: string;
+    type: string;
+    id: string;
+    timestamp: string;
+    assetId?: number | bigint | undefined;
+    amount?: number | bigint | undefined;
+    receiver?: string | undefined;
+}>;
+export type TransactionInfo = z.infer<typeof TransactionInfoSchema>;
+export declare const AssetHoldingSchema: z.ZodObject<{
+    assetId: z.ZodUnion<[z.ZodNumber, z.ZodBigInt]>;
+    amount: z.ZodUnion<[z.ZodNumber, z.ZodBigInt]>;
+    creator: z.ZodString;
+    frozen: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    assetId: number | bigint;
+    amount: number | bigint;
+    frozen: boolean;
+    creator: string;
+}, {
+    assetId: number | bigint;
+    amount: number | bigint;
+    frozen: boolean;
+    creator: string;
+}>;
+export type AssetHolding = z.infer<typeof AssetHoldingSchema>;
+export declare const ApplicationStateSchema: z.ZodObject<{
+    appId: z.ZodUnion<[z.ZodNumber, z.ZodBigInt]>;
+    globalState: z.ZodRecord<z.ZodString, z.ZodAny>;
+    localState: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    appId: number | bigint;
+    globalState: Record<string, any>;
+    localState?: Record<string, any> | undefined;
+}, {
+    appId: number | bigint;
+    globalState: Record<string, any>;
+    localState?: Record<string, any> | undefined;
+}>;
+export type ApplicationState = z.infer<typeof ApplicationStateSchema>;

package/dist/types.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export const CreateAccountResultSchema = z.object({
+    address: z.string(),
+    privateKey: z.string(),
+});
+export const RekeyAccountParamsSchema = z.object({
+    sourceAddress: z.string(),
+    targetAddress: z.string(),
+});
+export const RekeyAccountResultSchema = z.object({
+    txId: z.string(),
+    signedTxn: z.string(), // Base64 encoded signed transaction
+});
+export const AccountDetailsSchema = z.object({
+    address: z.string(),
+    amount: z.union([z.number(), z.bigint()]),
+    assets: z.array(z.object({
+        assetId: z.union([z.number(), z.bigint()]),
+        amount: z.union([z.number(), z.bigint()]),
+    })),
+    authAddress: z.string().optional(),
+});
+export const TransactionInfoSchema = z.object({
+    id: z.string(),
+    type: z.string(),
+    sender: z.string(),
+    receiver: z.string().optional(),
+    amount: z.union([z.number(), z.bigint()]).optional(),
+    assetId: z.union([z.number(), z.bigint()]).optional(),
+    timestamp: z.string(),
+});
+export const AssetHoldingSchema = z.object({
+    assetId: z.union([z.number(), z.bigint()]),
+    amount: z.union([z.number(), z.bigint()]),
+    creator: z.string(),
+    frozen: z.boolean(),
+});
+export const ApplicationStateSchema = z.object({
+    appId: z.union([z.number(), z.bigint()]),
+    globalState: z.record(z.any()),
+    localState: z.record(z.any()).optional(),
+});

package/dist/utils/responseProcessor.d.ts

@@ -0,0 +1,31 @@
+export interface PaginationMetadata {
+    totalItems: number;
+    itemsPerPage: number;
+    currentPage: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    pageToken?: string;
+}
+export interface PaginatedResponse<T> {
+    data: T;
+    metadata: PaginationMetadata & {
+        arrayField?: string;
+    };
+}
+export interface ProcessedResponse {
+    [key: string]: any;
+    content?: any[];
+    metadata?: PaginationMetadata & {
+        arrayField?: string;
+    };
+}
+export declare class ResponseProcessor {
+    private static generateNextPageToken;
+    private static decodePageToken;
+    private static shouldPaginateArray;
+    private static shouldPaginateObject;
+    private static paginateObject;
+    private static paginateArray;
+    static processResponse(response: any, pageToken?: string, itemsPerPage?: number): any;
+    static wrapResourceHandler<T extends (...args: any[]) => Promise<any>>(handler: T): T;
+}

package/dist/utils/responseProcessor.js

@@ -0,0 +1,152 @@
+/**
+ * Global BigInt JSON serialization support.
+ * algosdk v3 returns BigInt for numeric fields; JSON.stringify cannot handle them natively.
+ * This patch ensures all JSON.stringify calls throughout the codebase work with BigInt values.
+ */
+BigInt.prototype.toJSON = function () {
+    return Number(this);
+};
+const DEFAULT_ITEMS_PER_PAGE = 10;
+export class ResponseProcessor {
+    static generateNextPageToken(page) {
+        return btoa(`page_${page}`);
+    }
+    static decodePageToken(token) {
+        try {
+            const decoded = atob(token);
+            const page = parseInt(decoded.replace('page_', ''));
+            return isNaN(page) ? 1 : page;
+        }
+        catch {
+            return 1;
+        }
+    }
+    static shouldPaginateArray(array, itemsPerPage) {
+        return array.length > itemsPerPage;
+    }
+    static shouldPaginateObject(obj, itemsPerPage) {
+        return Object.keys(obj).length > itemsPerPage;
+    }
+    static paginateObject(obj, itemsPerPage, pageToken) {
+        const entries = Object.entries(obj);
+        const totalItems = entries.length;
+        const totalPages = Math.ceil(totalItems / itemsPerPage);
+        const currentPage = pageToken ? this.decodePageToken(pageToken) : 1;
+        const startIndex = (currentPage - 1) * itemsPerPage;
+        const endIndex = startIndex + itemsPerPage;
+        const hasNextPage = endIndex < totalItems;
+        const paginatedEntries = entries.slice(startIndex, endIndex);
+        const paginatedObject = Object.fromEntries(paginatedEntries);
+        return {
+            items: paginatedObject,
+            metadata: {
+                totalItems,
+                itemsPerPage,
+                currentPage,
+                totalPages,
+                hasNextPage,
+                ...(hasNextPage && {
+                    pageToken: this.generateNextPageToken(currentPage + 1),
+                }),
+            }
+        };
+    }
+    static paginateArray(array, itemsPerPage, pageToken) {
+        const totalItems = array.length;
+        const totalPages = Math.ceil(totalItems / itemsPerPage);
+        const currentPage = pageToken ? this.decodePageToken(pageToken) : 1;
+        const startIndex = (currentPage - 1) * itemsPerPage;
+        const endIndex = startIndex + itemsPerPage;
+        const hasNextPage = endIndex < totalItems;
+        const paginatedItems = array.slice(startIndex, endIndex);
+        return {
+            items: paginatedItems,
+            metadata: {
+                totalItems,
+                itemsPerPage,
+                currentPage,
+                totalPages,
+                hasNextPage,
+                ...(hasNextPage && {
+                    pageToken: this.generateNextPageToken(currentPage + 1),
+                }),
+            }
+        };
+    }
+    static processResponse(response, pageToken, itemsPerPage) {
+        const perPage = itemsPerPage || DEFAULT_ITEMS_PER_PAGE;
+        // Handle array responses
+        if (Array.isArray(response)) {
+            const { items, metadata } = this.paginateArray(response, perPage, pageToken);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ data: items, metadata }, null, 2)
+                    }]
+            };
+        }
+        // Handle object responses with array values
+        if (typeof response === 'object' && response !== null) {
+            const processed = JSON.parse(JSON.stringify(response));
+            let paginatedField;
+            let paginationMetadata;
+            for (const key in processed) {
+                if (Array.isArray(processed[key])) {
+                    if (this.shouldPaginateArray(processed[key], perPage)) {
+                        const result = this.paginateArray(processed[key], perPage, pageToken);
+                        processed[key] = result.items;
+                        if (result.metadata) {
+                            paginatedField = key;
+                            paginationMetadata = result.metadata;
+                        }
+                    }
+                }
+                else if (typeof processed[key] === 'object' && processed[key] !== null) {
+                    if (this.shouldPaginateObject(processed[key], perPage)) {
+                        const result = this.paginateObject(processed[key], perPage, pageToken);
+                        processed[key] = result.items;
+                        if (result.metadata) {
+                            paginatedField = key;
+                            paginationMetadata = result.metadata;
+                        }
+                    }
+                    const nestedResult = this.processResponse(processed[key], pageToken, perPage);
+                    if (nestedResult.content?.[0]?.text) {
+                        try {
+                            processed[key] = JSON.parse(nestedResult.content[0].text);
+                        }
+                        catch {
+                            processed[key] = nestedResult.content[0].text;
+                        }
+                    }
+                }
+            }
+            if (paginationMetadata) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                data: processed,
+                                metadata: { ...paginationMetadata, arrayField: paginatedField }
+                            }, null, 2)
+                        }]
+                };
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ data: processed }, null, 2)
+                    }]
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ data: response }, null, 2)
+                }]
+        };
+    }
+    static wrapResourceHandler(handler) {
+        return ((...args) => handler(...args));
+    }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@goplausible/algorand-mcp",
+  "version": "3.0.7",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Algorand Model Context Protocol Local Implementation",
+  "type": "module",
+  "keywords": [
+    "algorand",
+    "mcp",
+    "blockchain",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "MIT",
+  "bin": {
+    "algorand-mcp": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "@types/jest": "29.5.12",
+    "@types/node": "^20.0.0",
+    "@types/qrcode": "^1.5.5",
+    "@types/sql.js": "^1.4.9",
+    "jest": "29.7.0",
+    "ts-jest": "29.1.2",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@cf-wasm/photon": "^0.1.31",
+    "@juit/qrcode": "^1.0.59",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@napi-rs/keyring": "^1.2.0",
+    "@noble/curves": "^2.0.1",
+    "@tinymanorg/tinyman-js-sdk": "^5.1.2",
+    "algo-msgpack-with-bigint": "^2.1.1",
+    "algosdk": "^3.5.2",
+    "hi-base32": "^0.5.1",
+    "just-pick": "^4.2.0",
+    "qrcode": "^1.5.4",
+    "sql.js": "^1.14.0",
+    "zod": "^3.25.61"
+  },
+  "scripts": {
+    "build": "tsc && cp -r src/resources/knowledge/taxonomy src/resources/knowledge/taxonomy-categories dist/resources/knowledge/ && chmod +x dist/index.js",
+    "clean": "rm -rf dist",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "test:e2e": "NODE_OPTIONS='--experimental-vm-modules' jest --config tests/jest.config.e2e.js",
+    "test:all": "npm test && npm run test:e2e",
+    "typecheck": "tsc --noEmit"
+  }
+}