{"id":"46bed713-a6b6-4842-b6ed-9087c969ba8d","slug":"opencode-agentation-mcp","kind":"skill","name":"opencode-agentation-mcp","summary":"Connect OpenCode agents to Agentation UI annotation system via MCP","owner":"siddheshbmane","repoUrl":"https://github.com/siddheshbmane/opencode-agentation-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-03-19T12:11:58.000Z","addedAt":"2026-10-21T20:47:02.384Z","logoUrl":"https://avatars.githubusercontent.com/u/46445083?u=147e932756cfd48361edab7653c8a5e39d503cf1&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T07:36:07.658Z","sample":false,"url":"https://conduits.dev/tools/opencode-agentation-mcp","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# OpenCode Agentation MCP Integration\n\nConnect OpenCode agents to Agentation UI annotation system via MCP (Model Context Protocol).\n\n## Overview\n\nThis MCP server enables seamless **UI feedback → AI agent → code fix** workflow by integrating Agentation's annotation system with OpenCode's AI agents.\n\n### Features\n\n- 🔗 **MCP Protocol Support** - Native Model Context Protocol integration\n- 📝 **Real-time Annotations** - Process UI feedback as it's created\n- 🤖 **AI Agent Ready** - Connect to Claude Code, Cursor, and other AI tools\n- 🔧 **Multiple Modes** - Manual, hands-free, critique, and self-driving modes\n- 📊 **Rich Context** - CSS selectors, React components, accessibility info\n- 💬 **Two-way Communication** - Agents can ask clarifying questions\n\n## Installation\n\n### Prerequisites\n\n- Node.js 18+\n- npm or pnpm\n\n### Quick Install\n\n```bash\n# Install globally\nnpm install -g agentation-mcp\n\n# Or install this repository\ngit clone https://github.com/YOUR_USERNAME/opencode-agentation-mcp.git\ncd opencode-agentation-mcp\nnpm install\n```\n\n### Start the Server\n\n```bash\nnpm start\n```\n\nOr run in background:\n\n```bash\nnpm start > /tmp/agentation-mcp.log 2>&1 &\n```\n\n## Quick Start\n\n### 1. Verify Server is Running\n\n```bash\ncurl http://localhost:4747/health\n```\n\nExpected response:\n```json\n{\n  \"status\": \"ok\",\n  \"mode\": \"local\"\n}\n```\n\n### 2. Connect to OpenCode\n\nAdd to your OpenCode MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentation\": {\n      \"command\": \"npx\",\n      \"args\": [\"agentation-mcp\", \"server\", \"--port\", \"4747\"]\n    }\n  }\n}\n```\n\n## Available Tools\n\n### Query Tools\n\n| Tool | Description |\n|------|-------------|\n| `agentation_list_sessions` | List all active annotation sessions |\n| `agentation_get_session` | Get session with all annotations |\n| `agentation_get_pending` | Get pending annotations for a session |\n| `agentation_get_all_pending` | Get all pending annotations across sessions |\n\n### Action Tools\n\n| Tool | Description |\n|------|-------------|\n| `agentation_acknowledge` | Mark annotation as acknowledged |\n| `agentation_resolve` | Mark annotation as resolved |\n| `agentation_dismiss` | Dismiss annotation with reason |\n| `agentation_reply` | Add reply to annotation thread |\n\n### Watch Mode\n\n| Tool | Description |\n|------|-------------|\n| `agentation_watch_annotations` | Block until new annotations appear |\n\n## Usage Examples\n\n### Basic Workflow\n\n```typescript\nimport { agentationTools } from './tools.js';\n\n// Check for pending annotations\nconst pending = await agentationTools.agentation_get_all_pending();\n\nif (pending.count > 0) {\n  console.log(`Found ${pending.count} pending annotations`);\n\n  // Process each annotation\n  for (const annotation of pending.annotations) {\n    // Acknowledge\n    await agentationTools.agentation_acknowledge(annotation.id);\n\n    // Fix the issue\n    await coderAgent.fixIssue(annotation);\n\n    // Resolve\n    await agentationTools.agentation_resolve(\n      annotation.id,\n      \"Fixed padding issue\"\n    );\n  }\n}\n```\n\n### Hands-Free Mode\n\n```typescript\n// Automatically process annotations as they're created\nwhile (true) {\n  const batch = await agentationTools.agentation_watch_annotations({\n    batchWindowSeconds: 10,\n    timeoutSeconds: 120,\n  });\n\n  for (const annotation of batch.annotations) {\n    await agentationTools.agentation_acknowledge(annotation.id);\n    await coderAgent.fixIssue(annotation);\n    await agentationTools.agentation_resolve(annotation.id, \"Issue fixed\");\n  }\n}\n```\n\n### Priority-Based Processing\n\n```typescript\nconst pending = await agentationTools.agentation_get_all_pending();\n\n// Sort by priority (blocking > important > suggestion)\nconst sorted = agentationTools.agentation_sort_by_priority(pending.annotations);\n\n// Process blocking issues first\nfor (const annotation of sorted) {\n  await agentationTools.agentation_acknowledge(annotation.id);\n  await coderAgent.fixIssue(annotation);\n  await agentationTools.agentation_resolve(annotation.id, \"Issue fixed\");\n}\n```\n\n## API Endpoints\n\n### Health & Status\n\n- `GET /health` - Server health check\n- `GET /status` - Server status with uptime\n\n### Sessions\n\n- `GET /sessions` - List all sessions\n- `POST /sessions` - Create new session\n- `GET /sessions/:id` - Get session with annotations\n\n### Annotations\n\n- `GET /pending` - Get all pending annotations\n- `GET /sessions/:id/pending` - Get pending for session\n- `POST /sessions/:id/annotations` - Create annotation\n- `POST /annotations/:id/acknowledge` - Acknowledge\n- `POST /annotations/:id/resolve` - Resolve\n- `POST /annotations/:id/dismiss` - Dismiss\n- `POST /annotations/:id/thread` - Reply\n\n### Events\n\n- `GET /events` - Global event stream (SSE)\n- `GET /sessions/:id/events` - Session event stream (SSE)\n\n## Annotation Object\n\n```typescript\n{\n  id: string;              // Unique identifier\n  comment: string;         // User's feedback\n  elementPath: string;     // CSS selector path\n  timestamp: number;       // Unix timestamp (ms)\n  x: number;               // % of viewport width (0-100)\n  y: number;               // px from document top\n  element: string;         // Tag name (\"button\", \"div\")\n  url?: string;            // Page URL\n  boundingBox?: {          // Element dimensions\n    x: number;\n    y: number;\n    width: number;\n    height: number;\n  };\n  reactComponents?: string;   // Component tree\n  cssClasses?: string;        // Class list\n  computedStyles?: string;    // Key CSS properties\n  accessibility?: string;     // ARIA attributes\n  nearbyText?: string;        // Visible text\n  selectedText?: string;      // Highlighted text\n  intent?: \"fix\" | \"change\" | \"question\" | \"approve\";\n  severity?: \"blocking\" | \"important\" | \"suggestion\";\n  status?: \"pending\" | \"acknowledged\" | \"resolved\" | \"dismissed\";\n  thread?: ThreadMessage[];   // Conversation thread\n}\n```\n\n## Architecture\n\n```\nUser (Browser) → Agentation Toolbar → Agentation MCP Server (localhost:4747)\n                                                    ↓\n                                            OpenCode Agents\n                                                    ↓\n                                            Code Changes\n                                                    ↓\n                                            Annotation Resolved\n```\n\n## Project Structure\n\n```\nopencode-agentation-mcp/\n├── types.ts              # TypeScript type definitions\n├── client.ts             # HTTP client for Agentation API\n├── tools.ts              # MCP tool implementations\n├── test.ts               # Test suite\n├── demo.ts               # Demo script\n├── package.json          # Package configuration\n├── LICENSE               # MIT License\n├── .gitignore            # Git ignore file\n└── README.md             # Documentation\n```\n\n## Scripts\n\n```bash\nnpm install           # Install dependencies\nnpm run test          # Run test suite\nnpm run demo          # Run demo script\nnpm run type-check    # Type check TypeScript\nnpm start             # Start MCP server\n```\n\n## Testing\n\n### Manual Testing\n\n```bash\n# Health check\ncurl http://localhost:4747/health\n\n# List sessions\ncurl http://localhost:4747/sessions\n\n# Get pending annotations\ncurl http://localhost:4747/pending\n```\n\n### Automated Testing\n\n```bash\nnpm test\n```\n\n## Troubleshooting\n\n### Server Not Running\n\n```bash\n# Check if server is running\ncurl http://localhost:4747/health\n\n# Start server\nnpm start\n\n# Check logs\ntail -f /tmp/agentation-mcp.log\n```\n\n### No Annotations Found\n\n```bash\n# Check sessions\ncurl http://localhost:4747/sessions\n\n# Check pending annotations\ncurl http://localhost:4747/pending\n```\n\n### Connection Issues\n\n```bash\n# Verify server is accessible\nnpx agentation-mcp doctor\n\n# Check server logs\ntail -f /tmp/agentation-mcp.log\n```\n\n## Resources\n\n- [Agentation Documentation](https://www.agentation.com/)\n- [MCP Protocol](https://modelcontextprotocol.io/)\n- [Agentation GitHub](https://github.com/benjitaylor/agentation)\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\nFor issues or questions:\n1. Check server is running: `curl http://localhost:4747/health`\n2. Run diagnostics: `npx agentation-mcp doctor`\n3. Review this documentation\n4. Open an issue on GitHub\n\n## Contributing\n\nContributions are welcome! Please open an issue or pull request on GitHub.\n\n---\n\n**Version:** 1.0.0\n**Last Updated:** 2026-03-16\n**Status:** ✅ Production Ready\n"}