@vectorchat/mcp-server/vectorchat_flutter/AI_TOOLS_SYSTEM.md

VectorChat MCP Server - Encrypted AI-to-AI communication with hardware security (YubiKey/TPM). 45+ MCP tools for Windsurf, Claude, and AI assistants. Model-based identity with EMDM encryption. Dynamic AI playbook system, communication zones, message relay

# AI Tools System - Function Calling for VectorChat

## Overview

The AI Tools System provides a comprehensive set of functions that AI models can call to interact with the VectorChat network, look up users, discover routes, and access system information.

---

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                  AI Model (Allicia)                      │
│  Generates tool calls based on user requests            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│              AIToolsService (Flutter)                    │
│  - Parses tool calls                                     │
│  - Executes functions                                    │
│  - Returns formatted results                             │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│         WebSocket / Identity / System Services           │
│  - Network communication                                 │
│  - Identity management                                   │
│  - System information                                    │
└─────────────────────────────────────────────────────────┘
```

---

## Available Tools

### 1. lookup_user
**Description:** Look up a user by username or identity

**Parameters:**
```json
{
  "username": "string (required)"
}
```

**Returns:**
```json
{
  "success": true,
  "user": {
    "username": "Alice",
    "type": "user",
    "online": true,
    "identity": "Alice@[QmXxXx@2001:db8::1]",
    "fingerprint": "49f00993bc8905fb...",
    "reputation": 9.5,
    "last_seen": "2025-10-17T04:00:00Z"
  }
}
```

**Example:**
```
User: "Is Alice online?"
AI: <tool:lookup_user>{"username": "Alice"}</tool>
Result: "Yes, Alice is online with reputation 9.5/10"
```

---

### 2. discover_route
**Description:** Discover transmission route to a user

**Parameters:**
```json
{
  "target": "string (required)"
}
```

**Returns:**
```json
{
  "success": true,
  "route": {
    "target": "Bob@[QmYyYy@2001:db8::2]",
    "hops": ["QmXxXx", "QmYyYy"],
    "latency": 45,
    "protocol": "websocket",
    "available": true
  }
}
```

**Example:**
```
User: "How do I reach Bob?"
AI: <tool:discover_route>{"target": "Bob"}</tool>
Result: "Route to Bob: 2 hops, 45ms latency via WebSocket"
```

---

### 3. get_active_users
**Description:** Get list of currently active users

**Parameters:** None

**Returns:**
```json
{
  "success": true,
  "users": [
    {
      "username": "Alice",
      "type": "user",
      "online": true
    },
    {
      "username": "Allicia",
      "type": "ai_assistant",
      "online": true
    }
  ],
  "count": 2
}
```

**Example:**
```
User: "Who's online?"
AI: <tool:get_active_users>{}</tool>
Result: "2 users online: Alice (user), Allicia (ai_assistant)"
```

---

### 4. get_network_status
**Description:** Get current network status

**Parameters:** None

**Returns:**
```json
{
  "success": true,
  "status": {
    "connected": true,
    "daemon_status": "running",
    "p2p_mode": true,
    "ipfs_connected": false,
    "active_connections": 3,
    "uptime": 3600
  }
}
```

**Example:**
```
User: "What's the network status?"
AI: <tool:get_network_status>{}</tool>
Result: "Network connected, 3 active connections, 1 hour uptime"
```

---

### 5. get_my_identity
**Description:** Get current user identity

**Parameters:** None

**Returns:**
```json
{
  "success": true,
  "identity": {
    "username": "Raymond",
    "callsign": "Raymond@[QmZzZz@2001:db8::5]",
    "fingerprint": "49f00993bc8905fb...",
    "type": "user",
    "model_path": "/path/to/model"
  }
}
```

**Example:**
```
User: "What's my identity?"
AI: <tool:get_my_identity>{}</tool>
Result: "Your identity is Raymond@[QmZzZz@2001:db8::5]"
```

---

### 6. search_contacts
**Description:** Search contacts by name or type

**Parameters:**
```json
{
  "query": "string (optional)",
  "type": "user | ai_assistant | robot | all (optional)"
}
```

**Returns:**
```json
{
  "success": true,
  "contacts": [
    {
      "username": "Allicia",
      "type": "ai_assistant"
    }
  ],
  "count": 1
}
```

**Example:**
```
User: "Show me all AI assistants"
AI: <tool:search_contacts>{"type": "ai_assistant"}</tool>
Result: "Found 1 AI assistant: Allicia"
```

---

### 7. get_encryption_info
**Description:** Get encryption information

**Parameters:** None

**Returns:**
```json
{
  "success": true,
  "encryption": {
    "type": "EMDM V2",
    "key_space": "496 trillion",
    "model_based": true,
    "fingerprint": "49f00993bc8905fb...",
    "secure": true
  }
}
```

**Example:**
```
User: "How secure is this?"
AI: <tool:get_encryption_info>{}</tool>
Result: "Using EMDM V2 with 496 trillion key space - highly secure"
```

---

### 8. ping_user
**Description:** Ping a user to check availability

**Parameters:**
```json
{
  "username": "string (required)"
}
```

**Returns:**
```json
{
  "success": true,
  "ping": {
    "username": "Alice",
    "online": true,
    "latency": 23,
    "timestamp": "2025-10-17T04:00:00Z"
  }
}
```

**Example:**
```
User: "Ping Alice"
AI: <tool:ping_user>{"username": "Alice"}</tool>
Result: "Alice is online, 23ms latency"
```

---

### 9. get_message_history
**Description:** Get message history with a user

**Parameters:**
```json
{
  "username": "string (required)",
  "limit": "integer (optional, default: 10)"
}
```

**Returns:**
```json
{
  "success": true,
  "messages": [],
  "count": 0,
  "note": "Message history not yet implemented"
}
```

---

### 10. get_system_info
**Description:** Get system information

**Parameters:** None

**Returns:**
```json
{
  "success": true,
  "system": {
    "platform": "linux",
    "app_version": "1.0.0",
    "protocol_version": "AINET-Prompt v1.0.0",
    "encryption": "EMDM V2",
    "network": "VectorChat Interplanetary Identity Infrastructure"
  }
}
```

---

## Usage in AI Prompts

### System Prompt Addition

Add this to AI system prompts:

```
You have access to the following tools to help users:

1. lookup_user - Find information about a user
2. discover_route - Find how to reach a user
3. get_active_users - See who's online
4. get_network_status - Check network health
5. get_my_identity - Get user's identity info
6. search_contacts - Search for contacts
7. get_encryption_info - Get security details
8. ping_user - Check if user is reachable
9. get_message_history - View past messages
10. get_system_info - Get system details

To use a tool, respond with:
<tool:tool_name>{"param": "value"}</tool>

Example:
User: "Is Alice online?"
You: <tool:lookup_user>{"username": "Alice"}</tool>
```

---

## Integration Example

### In Chat Screen

```dart
import 'services/ai_tools_service.dart';

class ChatScreen extends StatefulWidget {
  // ...
}

class _ChatScreenState extends State<ChatScreen> {
  late AIToolsService _toolsService;
  
  @override
  void initState() {
    super.initState();
    
    _toolsService = AIToolsService(
      websocket: widget.websocketService,
      identity: widget.identityManager,
    );
  }
  
  Future<void> _processAIResponse(String aiResponse) async {
    // Check if AI is calling a tool
    final toolCall = _toolsService.parseToolCall(aiResponse);
    
    if (toolCall != null) {
      // Execute the tool
      final result = await _toolsService.executeTool(
        toolName: toolCall['tool'],
        parameters: toolCall['parameters'],
      );
      
      // Format result for AI
      final formattedResult = _toolsService.formatToolResponse(result);
      
      // Send result back to AI
      await _sendToAI(formattedResult);
    } else {
      // Regular AI response, display to user
      _displayMessage(aiResponse);
    }
  }
}
```

---

## Tool Call Format

### Request Format
```xml
<tool:tool_name>{"param1": "value1", "param2": "value2"}</tool>
```

### Response Format
```json
{
  "status": "success",
  "data": {
    "success": true,
    ...
  }
}
```

---

## Error Handling

### Tool Execution Errors
```json
{
  "success": false,
  "error": "User lookup failed: User not found"
}
```

### Network Errors
```json
{
  "success": false,
  "error": "Not connected to daemon"
}
```

### Parse Errors
```json
{
  "success": false,
  "error": "Invalid tool call format"
}
```

---

## Future Enhancements

### v1.1
- [ ] Async tool execution with callbacks
- [ ] Tool execution history
- [ ] Tool usage analytics
- [ ] Custom tool registration

### v1.2
- [ ] Multi-step tool chains
- [ ] Tool result caching
- [ ] Tool permissions system
- [ ] Tool rate limiting

### v2.0
- [ ] Robot control tools
- [ ] IPFS direct access tools
- [ ] Smart contract interaction tools
- [ ] Quantum communication tools (future)

---

## Security Considerations

### Tool Access Control
- Tools respect user permissions
- Network operations require authentication
- Sensitive operations require confirmation

### Data Privacy
- User lookups respect privacy settings
- Message history encrypted
- Identity information protected

### Rate Limiting
- Prevent tool abuse
- Throttle expensive operations
- Monitor usage patterns

---

## Testing

### Unit Tests
```dart
test('lookup_user returns user info', () async {
  final result = await toolsService.executeTool(
    toolName: 'lookup_user',
    parameters: {'username': 'Alice'},
  );
  
  expect(result['success'], true);
  expect(result['user']['username'], 'Alice');
});
```

### Integration Tests
```dart
testWidgets('AI can call tools', (tester) async {
  // Setup
  final toolsService = AIToolsService(...);
  
  // Execute
  final result = await toolsService.executeTool(
    toolName: 'get_active_users',
    parameters: {},
  );
  
  // Verify
  expect(result['success'], true);
  expect(result['users'], isNotEmpty);
});
```

---

## Documentation

### For AI Models
Include tool documentation in system prompt so AI knows:
- What tools are available
- How to call them
- What they return
- When to use them

### For Developers
- API documentation
- Integration examples
- Best practices
- Troubleshooting guide

---

## Conclusion

The AI Tools System enables AI models to:
- ✅ Access network information
- ✅ Look up users
- ✅ Discover routes
- ✅ Check system status
- ✅ Search contacts
- ✅ Get encryption details

This makes AI assistants truly useful and integrated with the VectorChat network!

---

**Building the Interplanetary Identity Infrastructure** 🌍→🔴→🌌