OASIS Unified MCP Server

OASIS Unified MCP Server

Unified Model Context Protocol (MCP) server for interacting with OASIS, OpenSERV, and STAR platforms.

🚀 Quick Start

1. Install Dependencies

cd MCP
npm install

2. Configure Environment

Create a .env file:

# Copy the example
cp env.example .env

# Edit .env with your settings
# OASIS_API_URL=http://localhost:5000
# OASIS_API_KEY=your_api_key_here (optional)

3. Build

npm run build

4. Run in Development

npm run dev

5. Configure Cursor

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "oasis-unified": {
      "command": "node",
      "args": ["/Users/maxgershfield/OASIS_CLEAN/MCP/dist/index.js"],
      "env": {
        "OASIS_API_URL": "http://localhost:5000",
        "OASIS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Important: Use absolute paths in the config file.

6. Restart Cursor

Restart Cursor IDE to load the MCP server.

📋 Available Tools

OASIS Tools

Read Operations

• oasis_get_avatar - Get avatar by ID, username, or email
• oasis_get_karma - Get karma score for avatar
• oasis_get_nfts - Get all NFTs for avatar
• oasis_get_nft - Get NFT details by ID
• oasis_get_wallet - Get wallet for avatar
• oasis_get_holon - Get holon (data object) by ID
• oasis_health_check - Check OASIS API health

Create/Write Operations ✨

• oasis_register_avatar - Create a new avatar
• oasis_authenticate_avatar - Authenticate (login) and get JWT token
• oasis_mint_nft - Mint a new NFT on Solana
• oasis_create_nft - Single command: authenticate → Glif image → mint (use this for consistent NFT creation)

See AGENT_NFT_MINT_WORKFLOW.md for the full workflow (single MCP command + curl).

• oasis_save_holon - Create or update a holon (data object)
• oasis_update_avatar - Update avatar information
• oasis_create_wallet - Create a wallet for an avatar (basic)
• oasis_create_wallet_full - Create wallet with full options (recommended)
• oasis_set_default_wallet - Set default wallet for an avatar
• oasis_send_transaction - Send tokens between avatars/addresses

See WALLET_CREATION_GUIDE.md for detailed wallet creation instructions.

A2A Protocol & SERV Infrastructure Tools 🤖

Complete Agent Workflow

1. oasis_authenticate_avatar - Authenticate as a User or Wizard avatar (the owner)
2. oasis_register_avatar - Create an Agent avatar (set avatarType: "Agent") - Requires authentication from User/Wizard
3. oasis_authenticate_avatar - Authenticate as the Agent avatar to get JWT token
4. oasis_register_agent_capabilities - Register agent services and skills (agent manages itself)
5. oasis_register_agent_as_serv_service - Register agent in SERV infrastructure
6. oasis_discover_agents_via_serv - Discover registered agents (no auth required)
7. oasis_get_my_agents - Get all agents owned by authenticated user (requires User/Wizard auth)

Agent Discovery

• oasis_get_agent_card - Get agent card by ID
• oasis_get_all_agents - List all A2A agents
• oasis_get_agents_by_service - Find agents by service name
• oasis_get_my_agents - Get agents owned by authenticated user (requires auth)
• oasis_discover_agents_via_serv - Discover agents via SERV infrastructure

Agent Registration

• oasis_register_agent_capabilities - Register agent capabilities (requires auth)
• oasis_register_agent_as_serv_service - Register agent as SERV service (requires auth + capabilities)

A2A Communication

• oasis_send_a2a_jsonrpc_request - Send JSON-RPC 2.0 requests (ping, payment_request, etc.)
• oasis_get_pending_a2a_messages - Get pending messages for agent
• oasis_mark_a2a_message_processed - Mark message as processed

OpenSERV Integration

• oasis_register_openserv_agent - Register OpenSERV AI agent as A2A agent
• oasis_execute_ai_workflow - Execute AI workflows via A2A Protocol

See A2A_SERV_INTEGRATION.md for detailed documentation.

Smart Contract Generator Tools 🔨

• scgen_generate_contract - Generate smart contract from JSON specification
• scgen_compile_contract - Compile smart contract source code
• scgen_deploy_contract - Deploy compiled contract to blockchain
• scgen_generate_and_compile - Generate and compile in one step
• scgen_get_cache_stats - Get compilation cache statistics

Supported Blockchains:

• Ethereum (Solidity)
• Solana (Rust/Anchor)

Solana RPC Tools ⚡

Direct Solana blockchain operations via RPC (bypasses OASIS API):

• solana_send_sol - Send SOL tokens directly via Solana RPC
• solana_get_balance - Get SOL balance for a wallet address
• solana_get_transaction - Get transaction details by signature

**See SOLANA_RPC_ENDPOINTS.md for detail