MCP GoGrab AI - Complete Reference

Session: 77 | Last Updated: 2026-01-31

Overview

mcp-gograb-ai is a comprehensive MCP (Model Context Protocol) server with 78 tools for intelligent development assistance. It provides:

• Decision memory and learning
• Multi-agent collaboration (handoffs)
• Real-time WebSocket connectivity
• Code review, testing, and documentation
• Cross-platform support (Cursor, Claude Code, Claude Desktop, VSCode)
• Browser automation and testing (Session 76)
• Desktop connectivity and file operations (Session 76)
• Task scheduling and workflow automation (Session 76)
• Advanced outcome tracking (Session 77)

Location: MCP/mcp-gograb-ai/

Quick Start

For Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gograb-ai": {
      "command": "node",
      "args": ["/path/to/editor2/MCP/mcp-gograb-ai/dist/server.js"],
      "env": {
        "GOGRAB_BACKEND_URL": "http://localhost:3001",
        "GOGRAB_WORKSPACE": "editor2"
      }
    }
  }
}

For Claude Code / Cursor

Already configured via .mcp.json in the workspace root.

Tool Categories

1. Core Intelligence (Always Use First)

2. Session Management

3. Multi-Agent Collaboration (Session 74+)

4. Conventions & Learning

5. Code Intelligence

6. Space Builder Tools

7. Knowledge & Graph

8. Web & Documentation

9. Workflow & Recovery

10. Git Integration

11. Tool Contexts (Session 75.7)

12. Browser Automation (Session 76)

Tools for browser automation and testing via the browser agent.

Example - E2E Test Flow:

// Navigate to login page
browser_navigate({ url: "https://app.example.com/login" })

// Fill in credentials
browser_fill({ selector: "#email", value: "[email protected]" })
browser_fill({ selector: "#password", value: "password123" })

// Click submit button
browser_click({ selector: "button[type='submit']" })

// Wait for navigation
browser_wait({ condition: "network_idle", timeout: 5000 })

// Take screenshot of result
browser_screenshot({ name: "login-success", fullPage: false })

// Extract page title to verify
browser_extract({ selector: "h1.welcome", attribute: "textContent" })

13. Desktop Connectivity (Session 76)

Tools for desktop file operations and system integration. Sandboxed to Documents, Downloads, and tmp/gograb-agent for security.

Security Notes:

• All file operations restricted to:
  • ~/Documents/
  • ~/Downloads/
  • tmp/gograb-agent/
• Shell commands executed in sandbox
• Clipboard access requires user consent

Example - File Operations:

// List files in allowed directory
desktop_list_files({ path: "~/Documents/projects" })

// Read a file
desktop_read_file({ path: "~/Documents/config.json" })

// Write output file
desktop_write_file({
  path: "~/Documents/output.json",
  content: JSON.stringify(results, null, 2)
})

// Copy text to clipboard
desktop_clipboard_set({ content: "Copied from agent!" })

// Get clipboard content
desktop_clipboard_get()

14. Task Runner (Session 76)

Tools for scheduling tasks and creating multi-step workflows.

Example - Workflow with Sequential Tasks:

// Create individual tasks
task_create({
  id: "backup-db",
  name: "Backup Database",
  type: "manual",
  command: "pg_dump -U admin mydb > backup.sql"
})

task_create({
  id: "compress-backup",
  name: "Compress Backup",
  type: "manual",
  command: "gzip backup.sql"
})

task_create({
  id: "upload-backup",
  name: "Upload to S3",
  type: "manual",
  command: "aws s3 cp backup.sql.gz s3://backups/"
})

// Create workflow with all tasks
workflow_create({
  id: "full-backup",
  name: "Full Database Backup",
  tasks: ["backup-db", "compress-backup", "upload-backup"],
  sequential: true
})

// Execute the workflow
workflow_run({ workflowId: "full-backup" })

// Check status
task_status()

15. RPC & Agent Discovery (Session 76)

Tools for direct agent-to-agent communication and discovery.

Example - Agent Discovery and RPC:

// Find agents capable of browser testing
find_agents_for_task({ 
  taskType: "browser_testing",
  capabilities: ["screenshot", "navigation"]
})

// Direct RPC call to specific agent
call_agent({
  agentId: "browser-agent-001",
  method: "runTest",
  params: {
    testSuite: "login-flow",
    timeout: 30000
  }
})

16. Outcome Tracking (Session 77)

Advanced outcome tracking with backend integration and module-specific reporting.

Example - Tracking Outcomes:

// Track a decision outcome with full context
track_outcome({
  decisionId: "dec-12345",
  outcome: "success",
  metrics: {
    executionTime: 1250,
    resourceUsage: "low",
    errorCount: 0
  },
  evidence: {
    testsPassed: 15,
    testsFailed: 0,
    coverage: 92.5
  },
  notes: "Migration completed without issues"
})

// Report outcome for a specific module
report_module_outcome({
  module: "user-management",
  feature: "password-reset",
  outcome: "success",
  version: "2.1.0",
  details: {
    usersAffected: 1500,
    completionRate: 99.8
  }
})

MCP Resources (Session 75.8)

Poll-able resources for Claude Desktop:

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      MCP SERVER (78 tools)                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌───────────────────┐    ┌───────────────────┐                │
│  │  RealtimeClient   │    │  Backend REST     │                │
│  │  (WebSocket)      │    │  API              │                │
│  └─────────┬─────────┘    └─────────┬─────────┘                │
│            │                        │                            │
│            ▼                        ▼                            │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              Backend AI-API (NestJS)                     │    │
│  │  • Socket.io Gateway (/mcp-stream)                       │    │
│  │  • Native WebSocket (/ws)                                │    │
│  │  • REST Endpoints (/ai-api/*)                            │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              VITTO Orchestrator                          │    │
│  │  • Autonomous handoff processing                         │    │
│  │  • AI-powered task planning                              │    │
│  │  • Stale handoff takeover                                │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              Extended Capabilities (Session 76-77)       │    │
│  │  • Browser Automation (9 tools)                          │    │
│  │  • Desktop Connectivity (7 tools)                        │    │
│  │  • Task Runner & Workflows (6 tools)                     │    │
│  │  • RPC & Agent Discovery (2 tools)                       │    │
│  │  • Advanced Outcome Tracking (2 tools)                   │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Dual WebSocket Architecture

Why two gateways?

Chrome Manifest V3 extensions cannot use Socket.io due to Service Worker limitations. The dual setup is architecturally necessary.

Handoff System

Creating a Handoff

create_handoff({
  toAgentType: 'browser',  // or 'code', 'any'
  type: 'test_request',    // or 'verification', 'fix_request', etc.
  summary: 'Test the login page',
  tasks: [
    { description: 'Navigate to /login' },
    { description: 'Submit form with test credentials' }
  ],
  priority: 'high'
})

Responding to a Handoff

respond_to_handoff({
  handoffId: 'handoff-xxx',
  action: 'complete',  // or 'acknowledge', 'start', 'reject'
  taskResults: [
    { taskId: 'task-1', status: 'completed', result: 'Passed' }
  ]
})

Handoff Flow

Claude Code                    Cowork Browser Agent
    │                                │
    │ create_handoff(browser)        │
    │ ──────────────────────────────>│
    │                                │
    │        handoff.created event   │
    │<───────────────────────────────│
    │                                │
    │                    acknowledge │
    │<───────────────────────────────│
    │                                │
    │                       complete │
    │<───────────────────────────────│
    │                                │

What's NOT Needed

The following features were considered but already exist:

Environment Variables

File Locations

Version History

Groundbreaking Features

1. 78 MCP tools - Most MCP servers have 5-10, we have 78
2. Multi-agent collaboration - Agents delegate work to each other
3. VITTO autonomous brain - AI processes handoffs without human intervention
4. Cross-platform learning - Cursor decisions inform Claude Code
5. Real-time everywhere - WebSocket events propagate instantly
6. Tool contexts - Filter tools by agent type for cleaner UX
7. Browser automation - Full E2E testing capabilities (Session 76)
8. Desktop connectivity - Sandboxed file/system operations (Session 76)
9. Task runner - Workflow automation with scheduling (Session 76)
10. Advanced outcome tracking - Backend-integrated learning (Session 77)

Tool Count Summary