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 detailed documentation.

• Radix (Scrypto)

🧪 Testing

Test the MCP server directly:

# Run in dev mode (with logs)
npm run dev

# In another terminal, test with echo
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npm run dev

🔧 Development

Watch Mode

npm run watch

Build for Production

npm run build
npm start

📝 Example Usage in Cursor

Once configured, you can ask Cursor:

Read Operations

• "Get avatar information for username 'testuser'"
• "Show me all NFTs for avatar ID abc123"
• "What's the karma score for avatar xyz789?"
• "Check OASIS API health"

Create/Write Operations ✨

• "Create a new avatar with username 'alice', email 'alice@example.com', password 'secure123'"
• "Mint an NFT with metadata URL 'https://example.com/nft.json' and symbol 'MYNFT'"
• "Create a holon with name 'MyData' and description 'Test data'"
• "Create an Ethereum wallet for avatar abc123"
• "Send 100 tokens from avatar abc123 to avatar xyz789"

A2A/SERV Operations 🤖

• "Discover SERV agents that provide data analysis services"
• "Get the agent card for agent abc-123"
• "Register my agent with capabilities for data analysis and Python skills"
• "Send a payment request for 0.01 SOL to agent xyz-789"
• "Show me all pending A2A messages"
• "Execute an AI workflow to analyze this data"

Smart Contract Operations 🔨

• "Generate a Solana smart contract from this JSON spec: {programName: 'token_vesting', ...}"
• "Compile this Solidity contract: [contract code]"
• "Deploy this compiled contract to Ethereum"
• "Generate and compile a token vesting contract for Solana"

🐛 Troubleshooting

MCP Server Not Found

• Check that the path in ~/.cursor/mcp.json is absolute
• Verify the file exists: ls -la /Users/maxgershfield/OASIS_CLEAN/MCP/dist/index.js
• Check file permissions: chmod +x /Users/maxgershfield/OASIS_CLEAN/MCP/dist/index.js

Connection Errors

• Verify OASIS API is running: curl http://localhost:5000/api/health
• Check environment variables in .env
• Check Cursor logs: View → Output → MCP

Build Errors

• Ensure Node.js 20+ is installed: node --version
• Clear node_modules and reinstall: rm -rf node_modules && npm install

📚 Documentation

• A2A_SERV_INTEGRATION.md - Complete guide to A2A Protocol & SERV Infrastructure tools
• ENDPOINT_INVENTORY.md - Full list of available endpoints and MCP tools
• HOW_TO_USE_MCP.md - Detailed usage guide

📚 Next Steps

• ✅ Add A2A Protocol & SERV Infrastructure tools
• Add STAR dApp creation tools
• Add more OpenSERV workflow tools