verxio-mcp

# Verxio MCP Server A Model Context Protocol (MCP) server implementation for the Verxio Protocol, enabling LLM applications to integrate on-chain loyalty into customer experience in minutes. ## Features - Create and manage loyalty programs - Issue and manage loyalty passes as NFTs - Track user XP and tier progression - Award, revoke, and gift loyalty points - Comprehensive program and pass data resources - Multi-network support (Solana, Sonic) ## Prerequisites - Node.js 18+ - pnpm - Solana CLI (for development) - Access to a Solana RPC endpoint ## Installation 1. Clone the repository: ```bash git clone [repository-url] cd verxio-mcp ``` 2. Install dependencies: ```bash pnpm install ``` 3. Create a `.env` file: ```bash cp .env.example .env ``` 4. Configure environment variables: ```env RPC_URL=your_solana_rpc_url PRIVATE_KEY=your_base-64_private-key NETWORK=mainnet-beta ``` ## Usage ### Development ```bash pnpm dev ``` ### Production ```bash pnpm start ``` ### Testing ```bash pnpm test ``` ## Project Structure ``` src/ ├── index.js # Main server entry point ├── config/ # Configuration files ├── tools/ # MCP tool implementations ├── resources/ # MCP resource implementations └── utils/ # Utility functions ``` ## MCP Tools | Tool Name | Description | Parameters | |-----------|-------------|------------| | `createLoyaltyProgram` | Creates a new loyalty program with customizable tiers and points system | `loyaltyProgramName`: Program name<br>`metadataUri`: Program metadata URI<br>`organizationName`: Organization name<br>`brandColor`: Brand color (optional)<br>`tiers`: Array of tier configurations<br>`pointsPerAction`: Points awarded per action | | `updateLoyaltyProgram` | Updates an existing loyalty program's tiers and points configuration | `collectionAddress`: Program address<br>`newTiers`: Updated tier configurations<br>`newPointsPerAction`: Updated points per action<br>`updateAuthority`: Authority to perform update | | `awardLoyaltyPoints` | Awards points to a loyalty pass for specific actions | `passAddress`: Pass address<br>`action`: Action performed<br>`multiplier`: Points multiplier (optional)<br>`programAuthority`: Authority to award points | | `revokeLoyaltyPoints` | Revokes points from a loyalty pass | `passAddress`: Pass address<br>`pointsToRevoke`: Number of points to revoke<br>`programAuthority`: Authority to revoke points | | `giftLoyaltyPoints` | Gifts points to a loyalty pass | `passAddress`: Pass address<br>`pointsToGift`: Number of points to gift<br>`action`: Gift action description<br>`programAuthority`: Authority to gift points | ## MCP Resources | Resource URI | Description | Response Fields | |--------------|-------------|----------------| | `program://{address}` | Retrieves detailed information about a loyalty program | `name`: Program name<br>`metadata`: Program metadata<br>`tiers`: Tier configurations<br>`pointsPerAction`: Points configuration<br>`updateAuthority`: Update authority | | `pass://{address}` | Retrieves detailed information about a loyalty pass | `owner`: Pass owner<br>`points`: Current points<br>`tier`: Current tier<br>`actions`: Action history<br>`metadata`: Pass metadata | | `wallet://{address}/passes` | Lists all loyalty passes owned by a wallet | `passes`: Array of pass addresses<br>`totalPoints`: Total points across all passes<br>`activePasses`: Number of active passes | ## Documentation - [API Documentation](./docs/api.md) - [Tool Specifications](./docs/tools.md) - [Resource Specifications](./docs/resources.md) - [Security Guidelines](./docs/security.md) ## Contributing 1. Fork the repository 2. Create your feature branch 3. Commit your changes 4. Push to the branch 5. Create a Pull Request ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.