🐚 Agentis MCP Connector

A comprehensive development kit that enables fast integration with Agentis Model Context Protocols (MCPs), allowing Web3 applications to connect and utilize Agentis MCPs globally.

🌟 Features

• 🔌 Easy Integration: Simple SDK for connecting to Agentis MCP ecosystem
• ⚡ Real-time Communication: WebSocket support for live updates
• 🛠️ Tool Execution: Execute MCP tools programmatically
• 🤖 Agent Management: Create, update, and manage AI agents
• 📦 MCP Discovery: Browse and search available MCPs
• 🔐 Authentication: Support for API keys and JWT tokens
• 📊 Analytics: Track usage and performance metrics
• 🌐 Web3 Ready: Built for blockchain and DeFi applications

📦 Installation

npm install @agentis/mcp-connector

🚀 Quick Start

Server Setup

const { createServer } = require('@agentis/mcp-connector');

async function startServer() {
  const server = await createServer({
    supabaseUrl: 'your_supabase_url',
    supabaseAnonKey: 'your_supabase_key',
    port: 8080,
    corsOrigins: ['http://localhost:3000'],
    authRequired: false
  });

  // Enable WebSocket for real-time features
  server.enableWebSocket();
  
  // Start the server
  await server.start();
  
  console.log('🚀 Agentis MCP Connector is running!');
}

startServer();

Client Usage

const { MCPConnectorClient } = require('@agentis/mcp-connector');

const client = new MCPConnectorClient({
  serverUrl: 'http://localhost:8080',
  enableWebSocket: true
});

// Get available MCPs
const mcps = await client.getMCPs({ category: 'Trading' });

// Create an agent
const agent = await client.createAgent({
  user_id: 'user-123',
  name: 'Trading Bot',
  category: 'Trading',
  temperature: 0.7
});

// Attach MCP to agent
await client.attachMCPToAgent({
  agent_id: agent.data.id,
  mcp_id: mcps.data[0].id
});

// Execute a tool
const result = await client.executeTool({
  agent_id: agent.data.id,
  mcp_id: mcps.data[0].id,
  tool_name: 'get_token_price',
  parameters: { symbol: 'SOL' }
});

🏗️ Architecture

The Agentis MCP Connector consists of several key components:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web3 Apps     │    │   Client SDK    │    │   MCP Server    │
│                 │◄──►│                 │◄──►│                 │
│ • DeFi          │    │ • HTTP Client   │    │ • REST API      │
│ • NFT           │    │ • WebSocket     │    │ • WebSocket     │
│ • Trading       │    │ • Event Mgmt    │    │ • Tool Exec     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                 │
                                 ▼
                       ┌─────────────────┐
                       │   Supabase DB   │
                       │                 │
                       │ • Users         │
                       │ • Agents        │
                       │ • MCPs          │
                       │ • Tools         │
                       └─────────────────┘

🔧 Configuration

Environment Variables

Create a .env file:

# Required
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key

# Optional
PORT=8080
AUTH_REQUIRED=false
API_KEY=your_api_key
ENABLE_WEBSOCKET=true
CORS_ORIGINS=http://localhost:3000,http://localhost:3001

Server Configuration

const config = {
  supabaseUrl: 'your_supabase_url',
  supabaseAnonKey: 'your_supabase_key',
  port: 8080,
  corsOrigins: ['http://localhost:3000'],
  authRequired: false,
  rateLimitOptions: {
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100 // limit each IP to 100 requests per windowMs
  }
};

📚 API Reference

MCPs

Get MCPs

const mcps = await client.getMCPs({
  category: 'Trading',
  is_premium: false,
  page: 1,
  limit: 20
});

Search MCPs

const results = await client.searchMCPs('solana trading', {
  category: 'DeFi',
  page: 1
});

Get MCP Details

const details = await client.getMCPDetails('mcp-uuid');
// Returns MCP info + available tools

Agents

Create Agent

const agent = await client.createAgent({
  user_id: 'user-123',
  name: 'My Trading Bot',
  description: 'Automated trading agent',
  category: 'Trading',
  temperature: 0.7
});

Update Agent

const updated = await client.updateAgent('agent-uuid', {
  name: 'Updated Bot Name',
  temperature: 0.8
});

Get User Agents

const agents = await client.getUserAgents('user-123', true); // include stats

Tool Execution

Execute Tool

const result = await client.executeTool({
  agent_id: 'agent-uuid',
  mcp_id: 'mcp-uuid',
  tool_name: 'get_token_price',
  parameters: {
    symbol: 'SOL',
    vs_currency: 'USD'
  }
});

if (result.data.success) {
  console.log('Result:', result.data.result);
  console.log('Execution time:', result.data.executionTime, 'ms');
}

🔌 WebSocket Real-time Features

Connection & Authentication

const client = new MCPConnectorClient({
  serverUrl: 'http://localhost:8080',
  enableWebSocket: true
});

// Connect with authentication
await client.connectWebSocket({
  userId: 'user-123',
  walletAddress: '0x123...abc'
});

Event Subscriptions

// Subscribe to events
client.subscribeToChannels([
  'mcp.updates',
  'agent.agent-uuid',
  'global.notifications'
]);

// Listen for events
client.on('mcp.event', (event) => {
  console.log('MCP Event:', event);
});

client.on('agent.event', (event) => {
  console.log('Agent Event:', event);
});

client.on('tool.execution.result', (result) => {
  console.log('Tool completed:', result);
});

Real-time Tool Execution

// Execute tool via WebSocket for real-time results
client.executeToolViaWebSocket({
  agent_id: 'agent-uuid',
  mcp_id: 'mcp-uuid',
  tool_name: 'monitor_price',
  parameters: { symbol: 'SOL' }
});

// Results come via WebSocket events
client.on('tool.execution.result', (result) => {
  if (result.success) {
    console.log('Live price update:', result.result);
  }
});

🔐 Authentication

API Key Authentication

const client = new MCPConnectorClient({
  serverUrl: 'http://localhost:8080',
  apiKey: 'your-api-key'
});

JWT Token Authentication

// Set Authorization header manually
client.http.defaults.headers.Authorization = 'Bearer your-jwt-token';

📊 Database Schema

The connector works with the following Supabase database schema:

Core Tables

• users: User accounts and wallet addresses
• mcps: Available Model Context Protocols
• tools: Tools available in each MCP
• agents: User-created AI agents
• agent_mcps: Relationship between agents and MCPs
• user_mcps: User's purchased/owned MCPs
• transactions: Payment and usage history
• agent_modes: Agent operation modes

Example Queries

-- Get user's agents with attached MCPs
SELECT a.*, m.name as mcp_name 
FROM agents a
LEFT JOIN agent_mcps am ON a.id = am.agent_id
LEFT JOIN mcps m ON am.mcp_id = m.id
WHERE a.user_id = 'user-uuid';

-- Get available tools for an MCP
SELECT * FROM tools 
WHERE mcp_id = 'mcp-uuid' 
ORDER BY display_order;

🛠️ Examples

Basic Server

node examples/basic-usage.js server

Client Usage

node examples/basic-usage.js client

Tool Execution

node examples/basic-usage.js tools

WebSocket Demo

node examples/basic-usage.js websocket

🚀 Deployment

Docker Deployment

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/
COPY env.example ./.env

EXPOSE 8080 8081

CMD ["node", "dist/server.js"]

Environment Setup

# Build the project
npm run build

# Start the server
npm start

# Development mode with auto-reload
npm run dev

🔍 Monitoring & Health Checks

Health Check Endpoint

curl http://localhost:8080/health

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0.0",
    "uptime": 3600,
    "websocket": {
      "connected": 5,
      "status": "running"
    }
  }
}

WebSocket Info

curl http://localhost:8080/api/websocket/info

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🆘 Support

• 📧 Email: [email protected]
• 💬 Discord: Agentis Community
• 📖 Documentation: docs.agentis.dev
• 🐛 Issues: GitHub Issues

🗺️ Roadmap

• [ ] v1.1: Enhanced authentication with Web3 wallet integration
• [ ] v1.2: Built-in rate limiting and caching
• [ ] v1.3: Plugin system for custom MCPs
• [ ] v1.4: GraphQL API support
• [ ] v2.0: Distributed deployment support

Built with ❤️ by the Agentis Team

Enabling the future of Web3 AI agents, one MCP at a time.