algorand-remote-mcp

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #typescript #golang #go #linux #docker #cli #kubernetes #awesome-list #pytorch #mcp

algorand-remote-mcp

(★ 15)

Algorand remote (SSE) MCP Server Cloudflare Worker

algorand-remote-mcp 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Algorand Remote MCP

A Model Context Protocol (MCP) server that provides tools and resources for AI agents to interact with the Algorand blockchain. Built on Cloudflare Workers with HashiCorp Vault-based wallet management and multi-provider OAuth authentication.

## Overview

Algorand Remote MCP bridges AI agents and the Algorand blockchain ecosystem through a standardized MCP interface. It enables AI systems to manage wallets, create and submit transactions, swap tokens via DEX aggregators, and access blockchain data — all without requiring deep blockchain expertise.

This is a **remote MCP** implementation running on Cloudflare Workers with:

- **HashiCorp Vault** for secure Ed25519 key storage and transaction signing
- **Multi-provider OAuth** (Google, GitHub, Twitter, LinkedIn) for user authentication
- **algosdk v3.5.2** for Algorand SDK operations
- **Haystack Router** for best-price DEX aggregation across Tinyman, Pact, Folks, and LST protocols
- **Tinyman SDK** for direct DEX swap operations
- **Alpha Arcade SDK** for prediction market trading (orderbooks, limit/market orders, positions)

## Quick Start

**Prerequisites:** Node.js v16+, an OAuth account (Google, GitHub, Twitter, or LinkedIn)

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "algorand-remote-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://algorandmcp.goplausible.xyz/sse"
      ]
    }
  }
}
```

Restart your LLM agent and prompt:
```
Read Algorand MCP skill.
```

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              AI Agents / LLM Clients                       │
│                    (Claude, GPT, Cursor, Windsurf, etc.)                    │
└─────────────────────────────┬───────────────────────────────────────────────┘
                              │ MCP Protocol (SSE / Streamable HTTP)
                              ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                     Cloudflare Workers — Edge Runtime                       │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                        OAuthProvider Layer                            │  │
│  │          Google · GitHub · Twitter · LinkedIn (Multi-provider)        │  │
│  └───────────────────────────┬───────────────────────────────────────────┘  │
│                              ▼                                              │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │              AlgorandRemoteMCP (McpAgent / McpServer)                 │  │
│  │                                                                       │  │
│  │  ┌─────────────── Tool Managers ───────────────────────────────────┐  │  │
│  │  │                                                                 │  │  │
│  │  │  walletManager ─── accountManager ─── utilityManager            │  │  │
│  │  │  transactionManager/                                            │  │  │
│  │  │    ├── generalTransaction   (pay, sign, submit, keyreg)         │  │  │
│  │  │    ├── assetTransactions    (ASA create, optin, transfer)       │  │  │
│  │  │    ├── appTransactions      (create, update, delete, call)      │  │  │
│  │  │    └── groupTransactions    (atomic groups)                     │  │  │
│  │  │  algodManager ─── knowledgeManager                              │  │  │
│  │  │  arc26Manager ─── receiptManager ─── ap2Manager                 │  │  │
│  │  │  tinymanManager ─── alphaArcadeManager                          │  │  │
│  │  │  apiManager/                                                    │  │  │
│  │  │    ├── algod/       (account, application, asset, txn queries)  │  │  │
│  │  │    ├── indexer/     (search & lookup across all data types)     │  │  │
│  │  │    ├── hayrouter/   (DEX aggregator — quote, swap, optin)      │  │  │
│  │  │    └── nfd/         (Algorand Name Service lookups)            │  │  │
│  │  └─────────────────────────────────────────────────────────────────┘  │  │
│  │                                                                       │  │
│  │  ┌─────────────── Resources ───────────────────────────────────────┐  │  │
│  │  │  algorand://remote-mcp-skill         (Skill definition)        │  │  │
│  │  │  algorand://knowledge/taxonomy       (Knowledge base)          │  │  │
│  │  │  algorand://knowledge/taxonomy/{cat} (Category docs)           │  │  │
│  │  └─────────────────────────────────────────────────────────────────┘  │  │
│  │                                                                       │  │
│  │  ┌─────────────── Utils ───────────────────────────────────────────┐  │  │
│  │  │  ResponseProcessor (pagination, BigInt-safe JSON)               │  │  │
│  │  │  vaultManager (Vault API client)                                │  │  │
│  │  │  Skill.js (skill content)                                       │  │  │
│  │  └─────────────────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│                                                                             │
│  ┌─────────────── Cloudflare Bindings ────────────────────────────────────┐ │
│  │  Durable Objects (session state)  ·  KV (OAuth tokens, client reg)    │ │
│  │  R2 Bucket (knowledge documents)  ·  Service Bindings (Vault worker)  │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
└──────────┬──────────────────┬──────────────────┬──────────────────┬─────────┘
           │                  │                  │                  │
           ▼                  ▼                  ▼                  ▼
┌──────────────────┐ ┌────────────────┐ ┌────────────────┐ ┌───────────────┐
│  HashiCorp Vault │ │  Algorand Node │ │  DEX & Markets │ │  External APIs│
│  (CF Worker)     │ │  (Algod +      │ │                │ │               │
│                  │ │   Indexer)     │ │  Haystack      │ │  NFD API      │
│  Ed25519 keypair │ │                │ │  Router        │ │  Pera API     │
│  generation      │ │  Nodely.io /   │ │  ┌──────────┐  │ │  Alpha Arcade │
│  Transit engine  │ │  AlgoNode      │ │  │ Tinyman  │  │ │  API          │
│  signing         │ │                │ │  │ Pact     │  │ │               │
│  No private key  │ │  MainNet /     │ │  │ Folks    │  │ │               │
│  exposure        │ │  TestNet       │ │  │ LST      │  │ │               │
│                  │ │                │ │  └──────────┘  │ │               │
└──────────────────┘ └────────────────┘ │                │ └───────────────┘
                                        │  Tinyman SDK   │
                                        │  Alpha Arcade  │
                                        │  SDK           │
                                        └────────────────┘
```

### Component Summary

- **AlgorandRemoteMCP**: Main MCP agent extending McpAgent on Cloudflare Workers
- **OAuthProvider**: Multi-provider authentication layer (Google, GitHub, Twitter, LinkedIn)
- **Tool Managers**: 15 specialized managers covering accounts, wallets, transactions, assets, applications, APIs, DEX operations, prediction markets, ARC-26 URIs, receipts, AP2 protocol, and knowledge
- **Resource Providers**: URI-based access to skill definition and knowledge base via R2
- **ResponseProcessor**: Standardized response formatting with pagination and BigInt-safe serialization
- **HashiCorp Vault**: Ed25519 keypair generation and secure signing via Transit engine — no private key exposure
- **Cloudflare Bindings**: Durable Objects for session state, KV for OAuth, R2 for knowledge docs, Service Bindings for Vault worker

## Tools

### Account Management
| Tool | Description |
|------|-------------|
| `sdk_create_algorand_keypair` | Create a new Algorand keypair (not wallet-linked) |
| `sdk_mnemonic_to_address_and_secretkey` | Get address and secret key from a mnemonic |
| `sdk_address_to_public_key` | Get the public key for an Algorand address |
| `sdk_check_account_balance` | Check account balance in ALGO |

### Wallet Management
| Tool | Description |
|------|-------------|
| `wallet_get_info` | Get account information including address, publicKey, balance, and assets (replaces `wallet_get_address` and `wallet_get_publickey`) |
| `wallet_get_role` | Get the role UUID for the configured wallet to be used to login into Hashicorp Vault with OIDC |
| `wallet_get_assets` | Get assets held by the wallet |
| `wallet_reset_account` | Reset wallet and generate new keys (destructive) |
| `wallet_logout` | Logout from OAuth provider |

### Transaction Operations
| Tool | Description |
|------|-------------|
| `sdk_txn_payment_transaction` | Create a payment transaction |
| `wallet_sign_transaction` | Sign a transaction using vault keys |
| `sdk_sign_transaction` | Sign a transaction using a mnemonic |
| `sdk_submit_transaction` | Submit a signed transaction to the network |
| `sdk_txn_key_registration_transaction` | Create a key registration transaction |
| `sdk_assign_group_id` | Assign group ID for atomic execution |
| `sdk_create_atomic_group` | Create an atomic transaction group (pay, axfer, acfg, appl, afrz, keyreg) |
| `wallet_sign_atomic_group` | Sign an atomic group using vault keys |
| `sdk_sign_atomic_group` | Sign an atomic group using a mnemonic |
| `sdk_submit_atomic_group` | Submit a signed atomic group |
| `sdk_send_raw_transaction` | Submit raw signed transactions |

### Asset Operations
| Tool | Description |
|------|-------------|
| `sdk_txn_create_asset` | Create a new Algorand Standard Asset (ASA) |
| `sdk_txn_asset_optin` | Opt-in to an ASA |
| `wallet_usdc_optin` | Opt-in agent wallet to USDC (vault-signed) |
| `sdk_txn_transfer_asset` | Transfer an ASA |

### Application (Smart Contract) Operations
| Tool | Description |
|------|-------------|
| `sdk_txn_create_application` | Create a new smart contract |
| `sdk_txn_update_application` | Update an existing smart contract |
| `sdk_txn_delete_application` | Delete a smart contract |
| `sdk_txn_closeout_application` | Close out from an application |
| `sdk_txn_clear_application` | Clear application state |
| `sdk_txn_call_application` | Call a smart contract (noop, optin, closeout, clear, delete) |
| `sdk_optin_application` | Opt-in to an application |

### DEX — Haystack Router (DEX Aggregator)
| Tool | Description |
|------|-------------|
| `haystack_get_swap_quote` | Get best-price swap quote across multiple DEXes and LST protocols |
| `haystack_execute_swap` | Execute an optimized swap: quote, vault-sign, submit, confirm |
| `haystack_needs_optin` | Check if an address needs to opt-in to an asset before swapping |

### DEX — Tinyman
| Tool | Description |
|------|-------------|
| `tinyman_fixed_input_swap` | Execute a swap with a fixed input amount |
| `tinyman_fixed_output_swap` | Execute a swap with a fixed output amount |

### Algod API
| Tool | Description |
|------|-------------|
| `algod_get_account_info` | Get account balance, assets, and auth address |
| `algod_get_account_application_info` | Get account-specific application info |
| `algod_get_account_asset_info` | Get account-specific asset info |
| `algod_get_application_info` | Get application details |
| `algod_get_application_box_value` | Get application box contents |
| `algod_get_application_boxes` | List application boxes |
| `algod_get_application_state` | Get application global state |
| `algod_get_asset_info` | Get asset details |
| `algod_get_asset_holding` | Get asset holding for an account |
| `algod_get_pending_txn_info` | Get pending transaction details |
| `algod_get_pending_transactions` | Get pending transactions from mempool |

### Pera Wallet Asset Verification
| Tool | Description |
|------|-------------|
| `pera_asset_verification_status` | Get verification status of an asset |
| `pera_verified_asset_details` | Get detailed asset information from Pera |
| `pera_verified_asset_search` | Search verified assets by name, unit name, or creator |

### Indexer API
| Tool | Description |
|------|-------------|
| `indexer_lookup_account_assets` | Get account assets |
| `indexer_lookup_account_app_local_states` | Get account app local states |
| `indexer_lookup_account_created_apps` | Get applications created by an account |
| `indexer_lookup_account_transactions` | Get transactions for an account |
| `indexer_search_for_accounts` | Search accounts with filters |
| `indexer_lookup_application_logs` | Get application log messages |
| `indexer_search_for_applications` | Search applications |
| `indexer_lookup_asset_balances` | Get holders of a specific asset |
| `indexer_search_for_assets` | Search assets |
| `indexer_lookup_transaction_by_id` | Get transaction details |
| `indexer_search_for_transactions` | Search transactions |

### NFD (Algorand Name Service)
| Tool | Description |
|------|-------------|
| `api_nfd_get_nfd` | Get NFD domain information by name |
| `api_nfd_get_nfds_for_address` | Get all NFD domains owned by an address |

### TEAL Operations
| Tool | Description |
|------|-------------|
| `sdk_compile_teal` | Compile TEAL source code |
| `sdk_disassemble_teal` | Disassemble TEAL bytecode |

### Utility Tools
| Tool | Description |
|------|-------------|
| `sdk_validate_address` | Check if an Algorand address is valid |
| `sdk_encode_address` | Encode a public key to an address |
| `sdk_decode_address` | Decode an address to a public key |
| `sdk_app_address_by_id` | Get the address for an application ID |
| `sdk_verify_bytes` | Verify a signature against bytes |
| `sdk_sign_bytes` | Sign bytes with a secret key |
| `algorand_mcp_skill` | Access comprehensive Algorand MCP skill |

### ARC-26 URI & Receipts
| Tool | Description |
|------|-------------|
| `generate_algorand_uri` | Generate an ARC-26 compliant URI |
| `generate_algorand_qrcode` | Generate a QR code for an Algorand URI |
| `generate_algorand_receipt` | Generate a transaction receipt |

### AP2 Protocol
| Tool | Description |
|------|-------------|
| `generate_ap2_mandate` | Create an AP2 intent, cart, or payment mandate with verifiable credentials |

### Alpha Arcade (Prediction Markets)
| Tool | Description |
|------|-------------|
| `alpha_get_live_markets` | Fetch all live prediction markets (title, prices, volume, multi-choice options) |
| `alpha_get_reward_markets` | Fetch markets with liquidity rewards |
| `alpha_get_market` | Get full details for a single market (on-chain + API) |
| `alpha_get_orderbook` | Unified YES-perspective orderbook with spread calculation |
| `alpha_get_open_orders` | Fetch open orders for a wallet on a specific market |
| `alpha_get_positions` | Fetch all YES/NO token positions across markets |
| `alpha_create_limit_order` | Place a limit order (price & quantity in microunits) |
| `alpha_create_market_order` | Place a market order with auto-matching and slippage |
| `alpha_cancel_order` | Cancel an open order and refund collateral |
| `alpha_amend_order` | Edit an existing unfilled order in-place |
| `alpha_propose_match` | Propose a match between a maker order and your wallet |
| `alpha_split_shares` | Split USDC into equal YES + NO outcome tokens |
| `alpha_merge_shares` | Merge YES + NO tokens back into USDC |
| `alpha_claim` | Claim USDC from a resolved market by redeeming outcome tokens |

### Knowledge Base
| Tool | Description |
|------|-------------|
| `get_knowledge_doc` | Get markdown content for knowledge documents |
| `list_knowledge_docs` | List available knowledge documents by category |

## Resources

### Knowledge Resources
| URI | Description |
|-----|-------------|
| `algorand://knowledge/taxonomy` | Full taxonomy of knowledge resources |
| `algorand://knowledge/taxonomy/{category}` | Category-specific resources (arcs, sdks, algokit, puya, etc.) |

### Skill
| URI | Description |
|-----|-------------|
| `algorand://remote-mcp-skill` | Comprehensive Algorand MCP skill |

## Development

### Prerequisites
- Node.js v16+
- Cloudflare Workers account
- Algorand node access (e.g., Nodely.io / AlgoNode)
- OAuth credentials (Google, GitHub, Twitter, and/or LinkedIn)
- HashiCorp Vault worker for secure key management

### Environment Variables
```
ALGORAND_NETWORK=mainnet
ALGORAND_ALGOD=https://your-algod-node.com
ALGORAND_INDEXER=https://your-indexer-node.com
ALGORAND_TOKEN=your-api-token
NFD_API_URL=https://api.nf.domains
HAYSTACK_API_KEY=your-haystack-api-key
ALPHA_API_KEY=your-alpha-arcade-api-key           # Optional, enables richer market data
ALPHA_API_BASE_URL=https://platform.alphaarcade.com/api  # Optional, default shown
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
HCV_WORKER_URL=https://your-hashicorp-vault-worker.workers.dev
```

### Scripts
```bash
npm run dev          # Start local development server
npm run type-check   # Run TypeScript type checking
npm run deploy       # Deploy to Cloudflare Workers
npm run format       # Format code with Biome
npm run lint:fix     # Lint and auto-fix with Biome
```

### Deployment
1. Clone the repository
2. Install dependencies: `npm install`
3. Configure environment variables in `wrangler.toml`
4. Deploy: `npm run deploy`

## Usage Flows

### Authentication
1. User authenticates via OAuth (Google, GitHub, Twitter, or LinkedIn)
2. Server creates or retrieves wallet credentials from HashiCorp Vault
3. User accesses tools and resources through the MCP interface
4. User can logout using `wallet_logout`

### Individual Transactions
1. Create transaction (e.g., `sdk_txn_payment_transaction`)
2. Sign with vault (`wallet_sign_transaction`) or mnemonic (`sdk_sign_transaction`)
3. Submit to network (`sdk_submit_transaction`)

### Atomic Transaction Groups
1. Create group (`sdk_create_atomic_group`)
2. Sign group (`wallet_sign_atomic_group` or `sdk_sign_atomic_group`)
3. Submit group (`sdk_submit_atomic_group`)

### DEX Swaps via Haystack Router
1. Get best-price quote (`haystack_get_swap_quote`)
2. Execute swap — quotes, vault-signs, submits, and confirms in one call (`haystack_execute_swap`)

### DEX Swaps via Tinyman
1. Execute fixed-input or fixed-output swap (`tinyman_fixed_input_swap` / `tinyman_fixed_output_swap`)

### Prediction Markets via Alpha Arcade
1. Browse markets (`alpha_get_live_markets`)
2. Check orderbook (`alpha_get_orderbook`)
3. Place order (`alpha_create_limit_order` or `alpha_create_market_order`)
4. Monitor positions (`alpha_get_positions`) and open orders (`alpha_get_open_orders`)
5. Manage orders — amend (`alpha_amend_order`) or cancel (`alpha_cancel_order`)
6. Claim winnings from resolved markets (`alpha_claim`)

## Project Structure

```
src/
├── index.ts                      # Main entry point
├── types.ts                      # Type definitions
├── oauth-handler.ts              # OAuth authentication handler
├── workers-oauth-utils.ts        # OAuth utilities
├── resources/
│   ├── skill/                    # Skill resource
│   └── knowledge/                # Knowledge base resources
├── tools/
│   ├── accountManager.ts         # Account management
│   ├── algodManager.ts           # Algorand node tools
│   ├── ap2Manager.ts             # AP2 protocol tools
│   ├── arc26Manager.ts           # ARC-26 URI and QR tools
│   ├── knowledgeManager.ts       # Knowledge base tools
│   ├── receiptManager.ts         # Transaction receipt tools
│   ├── tinymanManager.ts         # Tinyman DEX tools
│   ├── alphaArcadeManager.ts     # Alpha Arcade prediction market tools
│   ├── utilityManager.ts         # Utility tools
│   ├── walletManager.ts          # Wallet management tools
│   ├── apiManager/
│   │   ├── algod/                # Algod API tools (account, application, asset, transaction)
│   │   ├── hayrouter/            # Haystack Router DEX aggregator tools
│   │   ├── indexer/              # Indexer API tools (account, application, asset, transaction)
│   │   └── nfd/                  # NFD name service tools
│   └── transactionManager/
│       ├── generalTransaction.ts # Payment, signing, submission, key registration
│       ├── appTransactions.ts    # Application (smart contract) transactions
│       ├── assetTransactions.ts  # Asset create, optin, transfer
│       └── groupTransactions.ts  # Atomic transaction groups
└── utils/
    ├── Skill.js                  # Skill content
    ├── vaultManager.ts           # HashiCorp Vault integration
    └── responseProcessor.ts      # Response formatting and pagination
```

## Key Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| `algosdk` | ^3.5.2 | Algorand JavaScript SDK |
| `@txnlab/haystack-router` | ^2.0.5 | DEX aggregator for best-price swaps |
| `@tinymanorg/tinyman-js-sdk` | ^5.1.2 | Tinyman DEX SDK |
| `@alpha-arcade/sdk` | latest | Prediction market trading SDK |
| `@modelcontextprotocol/sdk` | ^1.12.1 | MCP protocol SDK |
| `agents` | ^0.0.95 | Cloudflare Agents SDK |
| `algo-msgpack-with-bigint` | ^2.1.1 | MessagePack with BigInt support |

## Contributing

1. Fork the repository
2. Create your feature branch: `git checkout -b feature/my-new-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin feature/my-new-feature`
5. Submit a pull request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

algorand-remote-mcp

algorand-remote-mcp 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

algorand-remote-mcp

algorand-remote-mcp 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README