GitHub - AO-protocol/ao

Project Overview

comprehensive blockchain application that demonstrates the integration of x402 payment protocol with 0G Storage through Model Context Protocol (MCP). The project features a multi-package monorepo structure with frontend, backend, MCP server, and AWS CDK infrastructure components.

Architecture (AWS)

Architecture (local)

Project Structure

.
├── docs/ # Project documentation and diagrams
├── pkgs/
│ ├── frontend/ # Next.js 15 frontend application
│ ├── backend/ # Hono-based API server with x402 payment handling
│ ├── mcp/ # Model Context Protocol server for 0G Storage file operations
│ └── cdk/ # AWS CDK infrastructure for cloud deployment
├── .github/workflows/ # CI/CD pipeline configuration
├── biome.json # Code linting and formatting configuration
├── pnpm-workspace.yaml # pnpm monorepo workspace configuration
└── tsconfig.json # TypeScript base configuration

Technologies

Package Manager: pnpm v8+ with workspace support
Monorepo Structure: pnpm workspaces for multi-package management
Frontend: Next.js 15 with React 19, TypeScript, and PWA support
Backend: Hono framework with TypeScript, x402 payment protocol integration
MCP: Model Context Protocol SDK for 0G Storage file operations and blockchain payments
Blockchain: x402-enabled payment interactions
Payment: x402 protocol for USDC payments on Base Sepolia
Storage: 0G Storage modern cloud storage with AI-powered insights
Infrastructure: AWS CDK for cloud deployment and Lambda functions
Code Quality: Biome for linting and formatting
CI/CD: GitHub Actions for automated building and testing

Getting Started

Prerequisites

Node.js (v20+)
pnpm v8+
A wallet with USDC on Base Sepolia for payment functionality

Installation

# Clone the repository
git clone <your_repo_url>
cd <repo_name>

# Install dependencies
pnpm install

Development Commands

# Format code with Biome
pnpm format

# Lint code
pnpm lint

# Check and apply fixes
pnpm check

# Package-specific commands
pnpm frontend <command> # Frontend-specific commands
pnpm backend <command> # Backend-specific commands
pnpm mcp <command> # MCP-specific commands
pnpm cdk <command> # CDK-specific commands

Environment Setup

1. Backend Configuration

Create pkgs/backend/.env file:

FACILITATOR_URL=https://x402.org/facilitator
NETWORK=base-sepolia
ADDRESS=<your_wallet_address>

2. MCP Configuration

Create pkgs/mcp/.env file:

RESOURCE_SERVER_URL=http://localhost:4021
ENDPOINT_PATH=/download
PRIVATE_KEY=<your_private_key_with_usdc_on_base_sepolia>

3. Frontend Configuration

Create pkgs/frontend/.env.local file:

OPENAI_API_KEY=<your_openai_api_key>
GOOGLE_GENERATIVE_AI_API_KEY=<your_google_ai_key>
ANTHROPIC_API_KEY=<your_anthropic_key>
PATH_TO_MCP=<absolute_path_to_repo>/pkgs/mcp/dist/index.js

4. CDK Configuration (Optional for AWS deployment)

Create pkgs/cdk/.env file:

FACILITATOR_URL=https://facilitator.x402.io
NETWORK=base-sepolia
ADDRESS=<your_wallet_address>
ENDPOINT_PATH=/download/
PRIVATE_KEY=<your_private_key>

Running the Application (local)

1. Start Backend Server

pnpm backend dev

The backend API will be available at http://localhost:4021

2. Build and Configure MCP Server

pnpm mcp build

Configure MCP in .vscode/mcp.json:

{
 "inputs": [],
 "servers": {
 "x402-0g-storage": {
 "command": "node",
 "args": [
 "${workspaceFolder}/pkgs/mcp/dist/index.js"
 ],
 "envFile": "${workspaceFolder}/pkgs/mcp/.env"
 },
 }
}

3. Start Frontend Application

pnpm frontend dev

The frontend will be available at http://localhost:3001

Running the Application (AWS)

1. deploy

pnpm cdk run deploy '*' --require-approval never

2. destroy

pnpm cdk run destroy '*' --force

3. Configure MCP Server

Configure MCP in VS Code's settings.json:

"aws-x402-0g-storage-mcp": {
 "type": "sse",
 "url": "<yoururl>/mcp",
 "headers": {
 "VERSION": "1.2",
 "Accept": "application/json, text/event-stream",
 "Content-Type": "application/json"
 }
},

Using the MCP Server

1. File Storage & Management

Upload files to 0G Storage:

Upload your file to 0G Storage.
File path: <absolute_path_to_repo>/pkgs/mcp/samples/sample.txt
Storage duration: 30
use x402-0g-storage-mcp

Download files from 0G Storage:

Download the file from 0G Storage.
FileID: [file_id_from_upload]
use x402-0g-storage-mcp

Get file information:

Get information about the file.
FileID: [file_id_from_upload]
use x402-0g-storage-mcp

List stored files:

List my files from 0G Storage.
use x402-0g-storage-mcp

2. AI Recommendations & Learning

Generate AI recommendations from your data:

Generate AI recommendations from my shopping data.
UserID: user123
DataType: shopping_history
use x402-0g-storage-mcp

Train AI models on your data:

Train an AI model on my fitness tracking data.
UserID: user123
TrainingData: [fitness_data_array]
ModelType: collaborative_filtering
use x402-0g-storage-mcp

Index your data for efficient search:

Index my research papers for semantic search.
UserID: user123
DataType: research_papers
Data: [paper_data_array]
use x402-0g-storage-mcp

Search your data using AI:

Find similar documents to my current research.
UserID: user123
Query: machine learning applications
SearchType: semantic
use x402-0g-storage-mcp

3. Data Processing & Pipelines

Create data processing pipelines:

Create a data pipeline to analyze my sales data.
UserID: user123
PipelineConfig: {name: "Sales Analysis", stages: [...]}
use x402-0g-storage-mcp

4. Data Monetization & Payments

Check your profit history:

Show me my profit history from data monetization.
UserID: user123
use x402-0g-storage-mcp

Monitor data access statistics:

Get my data access statistics for this month.
UserID: user123
TimeRange: month
use x402-0g-storage-mcp

Environment Variables

Required for 0G Platform

ZERO_G_API_KEY - Your 0G platform API key for accessing AI, search, and payment services
PRIVATE_KEY - Your private key for x402 payment processing (hex format)

Example .env file

# 0G Platform Configuration
ZERO_G_API_KEY=your_0g_platform_api_key_here

# x402 Payment Configuration
PRIVATE_KEY=your_private_key_for_x402_payments_here

# Resource Server (for Lambda)
RESOURCE_SERVER_URL=http://localhost:4021

Package Details

Frontend (`pkgs/frontend`)

Next.js 15 application featuring:

React 19 with TypeScript and modern hooks
Progressive Web App (PWA) capabilities with next-pwa
Styling: Tailwind CSS with shadcn/ui components
AI Integration: Mastra AI framework with multiple providers (OpenAI, Google, Anthropic)
State Management: TanStack Query for server state
Theme Support: Dark/light mode with next-themes

Key Dependencies:

@mastra/core, @mastra/mcp for AI and MCP functionality
@radix-ui components for accessible UI primitives
Tailwind CSS and lucide-react for styling and icons

Backend (`pkgs/backend`)

Hono-based API server with:

Framework: Hono with Node.js server adapter
Payment Processing: x402 protocol integration for USDC payments
Environment: Docker support for containerized deployment
TypeScript: Full TypeScript support with modern ES modules

Key Dependencies:

@hono/node-server for HTTP server
x402, x402-hono for payment protocol
dotenv for environment configuration

MCP (`pkgs/mcp`)

Model Context Protocol server for 0G Storage operations:

Protocol: MCP SDK for VS Code/GitHub Copilot integration
Blockchain: Viem for Ethereum/Base interactions
Storage: 0G Storage modern cloud storage integration
Payment: x402-axios for automated payment handling
Deployment: AWS Lambda support with serverless-express

Key Dependencies:

@modelcontextprotocol/sdk for MCP implementation
viem for blockchain interactions
x402-axios for payment-enabled HTTP requests
@vendia/serverless-express for Lambda deployment

CDK (`pkgs/cdk`)

AWS Cloud Development Kit infrastructure:

Infrastructure as Code: AWS CDK v2 for cloud resources
Deployment: Lambda function deployment for MCP server
Testing: Jest for infrastructure testing
Build: esbuild for optimized Lambda bundles

Key Dependencies:

aws-cdk-lib, constructs for CDK infrastructure
@modelcontextprotocol/sdk for MCP Lambda integration
esbuild for bundling and optimization

Architecture

The project demonstrates a modern application architecture:

Frontend: React application for user interaction
Backend: Payment-enabled API server for file operations
MCP Server: Bridge between AI tools and blockchain/storage services
Infrastructure: Cloud-ready deployment with AWS CDK

Contributing

Follow the monorepo structure and use pnpm workspaces
Use Biome for code formatting: pnpm format
Ensure all packages build successfully: pnpm install && pnpm mcp build && pnpm frontend build
Test MCP integration with GitHub Copilot/VS Code

Name		Name	Last commit message	Last commit date
Latest commit History 61 Commits
.github/workflows		.github/workflows
.vscode		.vscode
docs		docs
pkgs		pkgs
.gitignore		.gitignore
README.md		README.md
biome.json		biome.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

AO-protocol/ao

Folders and files

Latest commit

History

Repository files navigation

Project Overview

Architecture (AWS)

Architecture (local)

Project Structure

Technologies

Getting Started

Prerequisites

Installation

Development Commands

Environment Setup

1. Backend Configuration

2. MCP Configuration

3. Frontend Configuration

4. CDK Configuration (Optional for AWS deployment)

Running the Application (local)

1. Start Backend Server

2. Build and Configure MCP Server

3. Start Frontend Application

Running the Application (AWS)

1. deploy

2. destroy

3. Configure MCP Server

Using the MCP Server

1. File Storage & Management

2. AI Recommendations & Learning

3. Data Processing & Pipelines

4. Data Monetization & Payments

Environment Variables

Required for 0G Platform

Example .env file

Package Details

Frontend (pkgs/frontend)

Backend (pkgs/backend)

MCP (pkgs/mcp)

CDK (pkgs/cdk)

Architecture

Contributing

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Frontend (`pkgs/frontend`)

Backend (`pkgs/backend`)

MCP (`pkgs/mcp`)

CDK (`pkgs/cdk`)

Packages