agent-eyes

v1.0.6

Published

25 days ago

MCP server that bridges browser console errors to AI coding agents

0High
0Medium
0Low

oseifelix

mcp model-context-protocol browser console errors debugging ai ai-agent developer-tools nextjs react

👁️ AgentEyes

Let your AI coding agent see your browser's console errors in real-time.

AgentEyes bridges the gap between your development browser and AI coding assistants. Instead of copy-pasting error messages, your AI can now directly query what's happening in your browser.

🎯 The Problem

When debugging web apps, you often need to:

See an error in your browser console
Copy it manually
Paste it to your AI assistant
Wait for a response

AgentEyes eliminates steps 1-3. Your AI assistant can now directly ask: "What errors are in the browser?"

🔧 How It Works

┌─────────────────┐    WebSocket     ┌─────────────────┐    Stdio/MCP    ┌─────────────────┐
│   Your Browser  │ ───────────────► │  AgentEyes      │ ◄────────────── │   AI Agent      │
│   (Next.js app) │   Port 3001      │  Server         │                 │   (IDE)         │
└─────────────────┘                  └─────────────────┘                 └─────────────────┘

Your browser sends errors to AgentEyes via WebSocket (port 3001)
AgentEyes server stores the last 20 errors in memory
Your AI agent queries errors using the get_browser_logs MCP tool

📋 Prerequisites

Before you start, make sure you have:

✅ Node.js 18+ installed (download here)
✅ An AI-powered IDE that supports MCP (VS Code, Cursor, Windsurf, or AntiGravity)
✅ A Next.js 13+ app (or any React app)

🚀 Quick Start (3 Steps)

Step 1: Install the Package

Open your terminal and run:

npm install agent-eyes

Step 2: Add AgentEyes to Your IDE

Choose your IDE below and follow the instructions:

Create or edit .vscode/mcp.json in your project:

{
  "servers": {
    "agent-eyes": {
      "command": "npx",
      "args": ["agent-eyes"]
    }
  }
}

Edit your Cursor MCP settings at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "agent-eyes": {
      "command": "npx",
      "args": ["agent-eyes"]
    }
  }
}

Then restart Cursor.

Click on Manage MCPs in AntiGravity, then click View raw config and add:

{
  "mcpServers": {
    "agent-eyes": {
      "command": "npx",
      "args": ["agent-eyes"]
    }
  }
}

Click Refresh to apply.

Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
Type "Open Windsurf Settings" → Navigate to Advanced → Cascade
Click "View raw config" to open ~/.codeium/windsurf/mcp_config.json
Add the following:

{
  "mcpServers": {
    "agent-eyes": {
      "command": "npx",
      "args": ["agent-eyes"]
    }
  }
}

Click the MCP servers button (hammer icon) and hit Refresh

Step 3: Add the React Component to Your App

In your Next.js app, edit app/layout.tsx (or create it):

import { AgentEyesProvider } from 'agent-eyes/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AgentEyesProvider>
          {children}
        </AgentEyesProvider>
      </body>
    </html>
  );
}

💡 Don't worry about production! The component automatically disables itself when NODE_ENV is not "development". It adds zero overhead to your production builds.

✅ Test It's Working

Start your Next.js app in development mode:
```
npm run dev
```
Open your browser and navigate to your app (usually http://localhost:3000)
Trigger a test error in the browser console (F12 → Console):
```
console.error("Test error from AgentEyes!")
```
Ask your AI agent:
"Check my browser for any errors"

If everything is set up correctly, your AI will respond with the test error!

💬 Usage Examples

Once set up, you can ask your AI assistant things like:

"What errors are showing in my browser?"
"Check the browser console for any issues"
"Are there any unhandled exceptions in my app?"
"Debug my frontend - what's going wrong?"

The AI will use the get_browser_logs tool to fetch errors including:

❌ console.error() calls
💥 Uncaught exceptions (window.onerror)
⚠️ Unhandled promise rejections

🔍 API Reference

Tool: `get_browser_logs`

Returns the last 20 browser errors with:

| Field | Description | |-------|-------------| | Timestamp | When the error occurred | | Type | error, crash, or unhandledrejection | | Message | The error message | | Stack | First 3 lines of the stack trace | | URL | The page where the error occurred |

🛠️ Troubleshooting

"Port 3001 is already in use"

AgentEyes automatically handles this! On startup, it will:

Detect if another Node.js process is using port 3001
Terminate the old instance (e.g., a zombie AgentEyes process)
Start fresh

If the port is used by a non-Node.js service (like Python or Java), AgentEyes will not kill it and will log a warning instead. In this case, you'll need to free the port manually.

"Cannot find module 'agent-eyes/react'"

Make sure you installed the package:

npm install agent-eyes

"No browser errors captured yet"

Check that:

Your Next.js app is running in development mode (npm run dev)
You added <AgentEyesProvider /> to your layout
An error has actually occurred in the browser

AI says "Unknown tool: get_browser_logs"

Your IDE hasn't loaded the MCP server. Try:

Restart your IDE
Check your MCP config file for typos
Look for MCP errors in your IDE's output panel

🏗️ Development

Want to contribute or run locally?

# Clone the repository
git clone https://github.com/oseifelix/agent-eyes.git
cd agent-eyes

# Install dependencies
npm install

# Build the TypeScript
npm run build

# Run the server
npm start

📄 License

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Made with ❤️ for the AI-assisted development community