MCP Payment Distribution System

A comprehensive Model Context Protocol (MCP) based payment distribution system for open source projects using stablecoins. This system enables fair and transparent compensation for contributors based on various contribution metrics.

Features

Core Features

• MCP-based Architecture: Intelligent payment distribution using Model Context Protocol
• Multiple Payment Models:
  • Contribution-based payments (commits, PRs, issues)
  • Time-based compensation
  • Milestone-based rewards
  • Reputation-weighted distributions
• Blockchain Integration: Secure stablecoin payments via smart contracts
• Real-time Notifications: Stay updated on payments and contributions
• Analytics Dashboard: Comprehensive insights and trends

Frontend Features

• Modern React 18 with TypeScript
• Web3 Integration with MetaMask support
• Real-time Data with React Query
• Interactive Charts using Recharts and D3.js
• Responsive Design with Tailwind CSS
• Enhanced UX with multi-step forms and notifications

Backend Features

• FastAPI with async support
• Smart Contract Integration via Web3.py
• Database Models with SQLAlchemy
• Contribution Tracking from GitHub
• Payment Processing with batch operations
• Notification System for real-time updates

Setup

Quick Start

1. Clone the repository:

git clone <repository-url>
cd mcp-payment-system

2. Run the setup script:

./scripts/setup.sh

3. Access the application:
   • Frontend: http://localhost:5173
   • Backend API: http://localhost:8000
   • API Docs: http://localhost:8000/docs

Manual Setup

Backend

1. Install dependencies:

pip install -r requirements.txt

2. Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

3. Run the application:

uvicorn app.main:app --reload

Frontend

1. Navigate to frontend directory:

cd frontend

2. Install dependencies:

npm install

3. Set up environment:

cp .env.example .env
# Edit with your configuration

4. Start development server:

npm run dev

5. For production build:

npm run build

Smart Contracts

1. Install Foundry (if not already installed):

curl -L https://foundry.paradigm.xyz | bash
foundryup

2. Install dependencies:

forge install

3. Compile contracts:

forge build

4. Deploy contracts:

forge script script/Deploy.s.sol --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast

Usage

For Contributors

1. Connect Wallet: Use MetaMask to connect your Ethereum wallet
2. Browse Projects: Explore active projects seeking contributions
3. Submit Contributions: Add your work and track approval status
4. Receive Payments: Get compensated automatically based on contribution value

For Project Owners

1. Create Project: Set up your project with GitHub integration
2. Configure Payment Rules: Choose contribution-based, time-based, or milestone payments
3. Review Contributions: Approve or reject submitted work
4. Distribute Payments: Create batch payments for approved contributions

For Administrators

1. Monitor Analytics: Track system-wide metrics and trends
2. Manage Projects: Oversee project health and activity
3. Review Payments: Monitor payment distribution and success rates

Configuration

Environment Variables

Backend (.env):

DATABASE_URL=postgresql://user:password@localhost:5432/mcp_payment
WEB3_PROVIDER_URI=https://mainnet.infura.io/v3/your-project-id
PAYMENT_DISTRIBUTOR_ADDRESS=0x...
SIGNER_PRIVATE_KEY=your-private-key
GITHUB_TOKEN=your-github-token

Frontend (.env):

VITE_API_URL=http://localhost:8000
VITE_PAYMENT_DISTRIBUTOR_ADDRESS=0x...
VITE_CHAIN_ID=1337

API Documentation

The API provides comprehensive endpoints for:

• Projects: CRUD operations for project management
• Payments: Create and track payment distributions
• Contributions: Submit and manage contributions
• Analytics: System-wide metrics and insights
• Notifications: Real-time user notifications

Access interactive API documentation at: http://localhost:8000/docs

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │  Smart Contract │
│   (React)       │◄──►│   (FastAPI)     │◄──►│  (Solidity)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web3 Wallet   │    │   Database      │    │   Blockchain    │
│   (MetaMask)    │    │   (PostgreSQL)  │    │   (Ethereum)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Tech Stack

Frontend

• React 18 with TypeScript
• Vite for build tooling and development
• Web3 Integration with ethers.js and web3-react
• UI Framework with Tailwind CSS and Headless UI
• Data Visualization using Recharts and D3.js
• State Management with React Query
• Routing with React Router

Backend

• FastAPI with async/await support
• SQLAlchemy ORM with PostgreSQL
• Web3.py for blockchain interaction
• Alembic for database migrations
• Redis for caching and sessions
• Celery for background tasks

Smart Contracts

• Solidity 0.8.19
• Foundry for development and testing
• OpenZeppelin for security standards
• ERC20 token support (USDC)

Infrastructure

• Docker and Docker Compose
• PostgreSQL database
• Redis for caching
• GitHub Actions for CI/CD

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Code Style

• Python: Follow PEP 8, use Black for formatting
• TypeScript: Use Prettier and ESLint
• Solidity: Follow Solidity style guide

Testing

Backend Tests

pytest

Frontend Tests

cd frontend
npm test

Smart Contract Tests

forge test

Deployment

Production Deployment

1. Set up production environment variables
2. Deploy smart contracts to mainnet
3. Build and deploy backend services
4. Build and deploy frontend
5. Configure monitoring and logging

Docker Deployment

docker-compose up -d

Security

• Smart Contract Security: Audited contracts with OpenZeppelin standards
• API Security: JWT authentication and rate limiting
• Database Security: Encrypted connections and parameterized queries
• Frontend Security: Content Security Policy and XSS protection

License

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

Support

• Documentation: Check the /docs folder for detailed guides
• Issues: Report bugs and request features via GitHub Issues
• Community: Join our Discord server for discussions

Roadmap

• Multi-chain Support: Expand beyond Ethereum
• Advanced Analytics: ML-powered contribution analysis
• Mobile App: React Native mobile application
• DAO Integration: Governance token and voting
• API Integrations: GitLab, Bitbucket support
• Advanced Notifications: Email, Slack, Discord