opencode-agentation-mcp

OpenCode Agentation MCP Integration

Connect OpenCode agents to Agentation UI annotation system via MCP (Model Context Protocol).

Overview

This MCP server enables seamless UI feedback → AI agent → code fix workflow by integrating Agentation's annotation system with OpenCode's AI agents.

Features

• 🔗 MCP Protocol Support - Native Model Context Protocol integration
• 📝 Real-time Annotations - Process UI feedback as it's created
• 🤖 AI Agent Ready - Connect to Claude Code, Cursor, and other AI tools
• 🔧 Multiple Modes - Manual, hands-free, critique, and self-driving modes
• 📊 Rich Context - CSS selectors, React components, accessibility info
• 💬 Two-way Communication - Agents can ask clarifying questions

Installation

Prerequisites

• Node.js 18+
• npm or pnpm

Quick Install

# Install globally
npm install -g agentation-mcp

# Or install this repository
git clone https://github.com/YOUR_USERNAME/opencode-agentation-mcp.git
cd opencode-agentation-mcp
npm install

Start the Server

npm start

Or run in background:

npm start > /tmp/agentation-mcp.log 2>&1 &

Quick Start

1. Verify Server is Running

curl http://localhost:4747/health

Expected response:

{
  "status": "ok",
  "mode": "local"
}

2. Connect to OpenCode

Add to your OpenCode MCP configuration:

{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["agentation-mcp", "server", "--port", "4747"]
    }
  }
}

Available Tools

Query Tools

Tool	Description
agentation_list_sessions	List all active annotation sessions
agentation_get_session	Get session with all annotations
agentation_get_pending	Get pending annotations for a session
agentation_get_all_pending	Get all pending annotations across sessions

Action Tools

Tool	Description
agentation_acknowledge	Mark annotation as acknowledged
agentation_resolve	Mark annotation as resolved
agentation_dismiss	Dismiss annotation with reason
agentation_reply	Add reply to annotation thread

Watch Mode

Tool	Description
agentation_watch_annotations	Block until new annotations appear

Usage Examples

Basic Workflow

import { agentationTools } from './tools.js';

// Check for pending annotations
const pending = await agentationTools.agentation_get_all_pending();

if (pending.count > 0) {
  console.log(`Found ${pending.count} pending annotations`);

  // Process each annotation
  for (const annotation of pending.annotations) {
    // Acknowledge
    await agentationTools.agentation_acknowledge(annotation.id);

    // Fix the issue
    await coderAgent.fixIssue(annotation);

    // Resolve
    await agentationTools.agentation_resolve(
      annotation.id,
      "Fixed padding issue"
    );
  }
}

Hands-Free Mode

// Automatically process annotations as they're created
while (true) {
  const batch = await agentationTools.agentation_watch_annotations({
    batchWindowSeconds: 10,
    timeoutSeconds: 120,
  });

  for (const annotation of batch.annotations) {
    await agentationTools.agentation_acknowledge(annotation.id);
    await coderAgent.fixIssue(annotation);
    await agentationTools.agentation_resolve(annotation.id, "Issue fixed");
  }
}

Priority-Based Processing

const pending = await agentationTools.agentation_get_all_pending();

// Sort by priority (blocking > important > suggestion)
const sorted = agentationTools.agentation_sort_by_priority(pending.annotations);

// Process blocking issues first
for (const annotation of sorted) {
  await agentationTools.agentation_acknowledge(annotation.id);
  await coderAgent.fixIssue(annotation);
  await agentationTools.agentation_resolve(annotation.id, "Issue fixed");
}

API Endpoints

Health & Status

• GET /health - Server health check
• GET /status - Server status with uptime

Sessions

• GET /sessions - List all sessions
• POST /sessions - Create new session
• GET /sessions/:id - Get session with annotations

Annotations

• GET /pending - Get all pending annotations
• GET /sessions/:id/pending - Get pending for session
• POST /sessions/:id/annotations - Create annotation
• POST /annotations/:id/acknowledge - Acknowledge
• POST /annotations/:id/resolve - Resolve
• POST /annotations/:id/dismiss - Dismiss
• POST /annotations/:id/thread - Reply

Events

• GET /events - Global event stream (SSE)
• GET /sessions/:id/events - Session event stream (SSE)

Annotation Object

{
  id: string;              // Unique identifier
  comment: string;         // User's feedback
  elementPath: string;     // CSS selector path
  timestamp: number;       // Unix timestamp (ms)
  x: number;               // % of viewport width (0-100)
  y: number;               // px from document top
  element: string;         // Tag name ("button", "div")
  url?: string;            // Page URL
  boundingBox?: {          // Element dimensions
    x: number;
    y: number;
    width: number;
    height: number;
  };
  reactComponents?: string;   // Component tree
  cssClasses?: string;        // Class list
  computedStyles?: string;    // Key CSS properties
  accessibility?: string;     // ARIA attributes
  nearbyText?: string;        // Visible text
  selectedText?: string;      // Highlighted text
  intent?: "fix" | "change" | "question" | "approve";
  severity?: "blocking" | "important" | "suggestion";
  status?: "pending" | "acknowledged" | "resolved" | "dismissed";
  thread?: ThreadMessage[];   // Conversation thread
}

Architecture

User (Browser) → Agentation Toolbar → Agentation MCP Server (localhost:4747)
                                                    ↓
                                            OpenCode Agents
                                                    ↓
                                            Code Changes
                                                    ↓
                                            Annotation Resolved

Project Structure

opencode-agentation-mcp/
├── types.ts              # TypeScript type definitions
├── client.ts             # HTTP client for Agentation API
├── tools.ts              # MCP tool implementations
├── test.ts               # Test suite
├── demo.ts               # Demo script
├── package.json          # Package configuration
├── LICENSE               # MIT License
├── .gitignore            # Git ignore file
└── README.md             # Documentation

Scripts

npm install           # Install dependencies
npm run test          # Run test suite
npm run demo          # Run demo script
npm run type-check    # Type check TypeScript
npm start             # Start MCP server

Testing

Manual Testing

# Health check
curl http://localhost:4747/health

# List sessions
curl http://localhost:4747/sessions

# Get pending annotations
curl http://localhost:4747/pending

Automated Testing

npm test

Troubleshooting

Server Not Running

# Check if server is running
curl http://localhost:4747/health

# Start server
npm start

# Check logs
tail -f /tmp/agentation-mcp.log

No Annotations Found

# Check sessions
curl http://localhost:4747/sessions

# Check pending annotations
curl http://localhost:4747/pending

Connection Issues

# Verify server is accessible
npx agentation-mcp doctor

# Check server logs
tail -f /tmp/agentation-mcp.log

Resources

• Agentation Documentation
• MCP Protocol
• Agentation GitHub

License

MIT License - see LICENSE file for details.

Support

For issues or questions:

1. Check server is running: curl http://localhost:4747/health
2. Run diagnostics: npx agentation-mcp doctor
3. Review this documentation
4. Open an issue on GitHub

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

---

Version: 1.0.0 Last Updated: 2026-03-16 Status: ✅ Production Ready