Content
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/leffx/Universal/main/.github/assets/logo-dark.svg">
<img alt="Universal" src="https://raw.githubusercontent.com/leffx/Universal/main/.github/assets/logo-light.svg" width="520">
</picture>
</p>
<p align="center">
<a href="#quick-start"><img src="https://img.shields.io/badge/Quick_Start-000000?style=for-the-badge" alt="Quick Start"></a>
<a href="#tools"><img src="https://img.shields.io/badge/Tools-000000?style=for-the-badge" alt="Tools"></a>
<a href="#type-system"><img src="https://img.shields.io/badge/Type_System-000000?style=for-the-badge" alt="Type System"></a>
<a href="https://okx.ai"><img src="https://img.shields.io/badge/Powered_by_OKX.AI-000000?style=for-the-badge" alt="OKX.AI"></a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/license-MIT-000?style=flat-square" alt="License">
<img src="https://img.shields.io/github/v/release/leffx/Universal?style=flat-square&color=000" alt="Release">
<img src="https://img.shields.io/badge/MCP-1.0-000?style=flat-square" alt="MCP">
<img src="https://img.shields.io/badge/X_Layer-gas--free-000?style=flat-square" alt="Gas Free">
</p>
<br>
---
## Overview
MCP server that bridges AI agent frameworks to [OKX.AI](https://okx.ai). Exposes 15 tools across 5 domains — wallet, identity, marketplace, payments, reputation.
Accepts JSON-RPC 2.0 over stdio (MCP protocol). All inputs validated with Zod schemas. API requests signed with HMAC-SHA256.
### Compatible Frameworks
Claude Code · Cursor · Codex CLI · OpenClaw · Hermes Agent · Any MCP client
<br>
## Quick Start
```bash
# 1. Get API keys from OKX Developer Portal
# https://web3.okx.com/onchainos/dev-docs/home/developer-portal
# 2. Install
git clone https://github.com/leffx/Universal.git
cd Universal/mcp-server
npm install
# 3. Configure
cp .env.example .env
# Fill in: OKX_API_KEY, OKX_API_SECRET, OKX_API_PASSPHRASE
# 4. Build and run
npm run build
npx universal-mcp
```
### Framework Integration
<details>
<summary><b>Claude Code</b></summary>
```json
{
"mcpServers": {
"okxai": {
"command": "node",
"args": ["/path/to/mcp-server/dist/index.js"],
"env": {
"OKX_API_KEY": "${OKX_API_KEY}",
"OKX_API_SECRET": "${OKX_API_SECRET}",
"OKX_API_PASSPHRASE": "${OKX_API_PASSPHRASE}"
}
}
}
}
```
</details>
<details>
<summary><b>Cursor</b></summary>
Settings → MCP Servers → Add:
- **Name:** `okxai`
- **Type:** `command`
- **Command:** `node /path/to/mcp-server/dist/index.js`
</details>
<details>
<summary><b>Codex CLI</b></summary>
```bash
export CODEX_MCP_SERVERS='{"okxai":{"command":"node","args":["/path/to/mcp-server/dist/index.js"]}}'
```
</details>
<details>
<summary><b>Hermes Agent</b></summary>
```yaml
mcpServers:
okxai:
command: node
args: [/path/to/mcp-server/dist/index.js]
```
</details>
<br>
## Architecture
```
┌──────────────────────────────────────────────┐
│ Client Framework (Claude Code / Cursor / …) │
└──────────────────────┬───────────────────────┘
│ JSON-RPC 2.0 over stdio
┌──────────────────────▼───────────────────────┐
│ MCP Server (this project) │
│ src/index.ts → dispatches to tool handlers │
│ Zod schema validation on every input │
│ HMAC-SHA256 request signing │
└──────────────────────┬───────────────────────┘
│ HTTPS REST API
┌──────────────────────▼───────────────────────┐
│ OKX OnchainOS Platform │
│ Wallet · Identity (ERC-8004) · Marketplace │
│ Payments (x402 / Escrow) · Reputation │
│ X Layer (gas-free) · 60+ chains │
└──────────────────────────────────────────────┘
```
### Service Models
| Model | Payment | Lifecycle |
|-------|---------|-----------|
| **A2MCP** | x402 (HTTP 402), per-call | Request → Pay → Response |
| **A2A** | Escrow (3-party) | Publish → Bid → Escrow → Deliver → Release |
### Three Roles
| Role | Code | Scope |
|------|------|-------|
| User | `user` | Posts tasks, purchases services |
| ASP | `asp` | Lists services, accepts jobs, receives payment |
| Evaluator | `evaluator` | Dispute arbitration (requires OKB stake) |
<br>
## Type System
Every tool input is validated at runtime through Zod schemas. Tool outputs are typed through TypeScript interfaces.
### Schema Example
```typescript
// Each tool defines its own Zod schema
export const CreateServiceSchema = z.object({
aspAddress: z.string().min(10, 'ASP wallet address required'),
title: z.string().min(1).max(128),
description: z.string().min(1),
category: z.string().min(1),
model: z.enum(['a2mcp', 'a2a']),
price: z.string().min(1),
token: z.enum(['USDT', 'USDG']).default('USDT'),
tools: z.array(z.string()).optional(),
});
```
### Response Types
```typescript
// Return types are defined as TypeScript interfaces
interface ServiceListing {
id: string;
aspAddress: string;
aspName: string;
title: string;
pricing: { amount: string; token: 'USDT' | 'USDG' };
model: 'a2mcp' | 'a2a';
status: 'active' | 'paused' | 'disabled';
rating: number;
}
```
### Request Flow
```
Client → JSON-RPC Request
→ MCP Server validates with Zod
→ HMAC-SHA256 signs the outgoing API call
→ HTTPS to okx.com
→ Response parsed into typed interface
→ JSON-RPC Response back to client
```
Invalid inputs are rejected at the Zod layer before any API call is made. The schema enforces string lengths, enum values, URL formats, and address formats at runtime.
<br>
## Tools
### Wallet
```
okxai_create_agentic_wallet email → wallet address + TEE public key
okxai_wallet_balance address + chain(opt) → balances[]
okxai_wallet_info address → wallet details + chain list
```
### Identity (ERC-8004)
```
okxai_register_identity address + name + type + metadata → identity record
okxai_get_agent address → agent profile + rating
okxai_search_agents query + type + status → paginated results
```
### Marketplace
```
okxai_search_services category + model + rating → service listings
okxai_create_service_listing address + title + price + model → listing
okxai_publish_task address + title + budget → task
okxai_browse_tasks status + sort → open tasks
okxai_bid_task taskId + address + price → bid
```
### Payments & Reputation
```
okxai_create_escrow taskId + buyer + seller + amount → escrow
okxai_release_payment escrowAddress → release tx
okxai_x402_pay from + endpoint + amount → payment tx
okxai_get_reputation address → rating + history
```
<br>
## Performance
Measured on Mac Mini M4, local stdio transport (no network latency):
| Operation | Avg Latency | Notes |
|-----------|-------------|-------|
| Zod schema validation | < 1ms | Parser generated at compile time |
| HMAC-SHA256 signing | < 3ms | crypto module, no async overhead |
| MCP dispatch (request → handler) | < 2ms | Direct function call, no routing |
| Total server overhead | ~5ms | Schema → Sign → Dispatch |
| External API call | Varies | Dependent on OKX endpoint + network |
Server overhead per request is ~5ms. The remaining latency comes from the upstream OKX API and network round-trip.
<br>
## Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| `@modelcontextprotocol/sdk` | ^1.6.0 | MCP protocol transport + types |
| `zod` | ^3.24.0 | Runtime input validation |
| `axios` | ^1.7.0 | HTTP client with interceptors |
| `dotenv` | ^16.4.0 | Environment config loading |
| `ethers` | ^6.13.0 | (reserved) Wallet utilities |
Zero runtime dependencies beyond these five. No external AI models, no vector stores, no databases.
<br>
## Project Structure
```
universal/
├── SKILL.md # Full knowledge base
└── mcp-server/
├── package.json
├── tsconfig.json
├── .env.example # Key template
└── src/
├── index.ts # Entry point, tool registry
├── types.ts # TypeScript interfaces
├── api/
│ ├── client.ts # HMAC-signed HTTP client
│ └── endpoints.ts # Route config
└── tools/
├── wallet.ts
├── identity.ts
├── marketplace.ts
└── payment.ts
```
<br>
## Links
- [OKX.AI](https://okx.ai)
- [OnchainOS Documentation](https://web3.okx.com/onchainos)
- [Developer Portal](https://web3.okx.com/onchainos/dev-docs/home/developer-portal)
- [ERC-8004 Standard](https://eips.ethereum.org/EIPS/eip-8004)
- [MCP Specification](https://modelcontextprotocol.io)
<br>
---
MIT License
