{"id":15948,"library":"agentation-mcp","title":"Agentation MCP Server","description":"Agentation MCP (Model Context Protocol) is a Node.js server designed to provide visual feedback to AI coding agents, such as Claude Code. It facilitates a two-way communication channel where a browser toolbar can send web page annotations to the server, and AI agents can consume these annotations as actionable feedback. The server exposes both an HTTP API for browser interaction (e.g., creating sessions, adding annotations) and an MCP interface (via stdio) to AI agents, offering tools to list, retrieve, acknowledge, resolve, and dismiss annotations. It also supports 'hands-free mode' for continuous agent processing via a `watch_annotations` tool. Currently at version 1.2.0, the package primarily focuses on CLI-driven server operation but ships with TypeScript types, implying programmatic integration is possible. Its key differentiator is providing a structured, visual feedback loop specifically for AI agents interacting with web content.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install agentation-mcp","lang":"bash","label":"npm"},{"cmd":"yarn add agentation-mcp","lang":"bash","label":"yarn"},{"cmd":"pnpm add agentation-mcp","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While the primary usage is via the CLI `agentation-mcp server`, the library likely exports a `startServer` function (or similar) for programmatic control, especially since it ships TypeScript types. Avoid CommonJS `require()` as the package targets Node.js 18+ and is likely ESM-first.","wrong":"const { startServer } = require('agentation-mcp');","symbol":"startServer","correct":"import { startServer } from 'agentation-mcp';"},{"note":"Type-only import for configuration options when programmatically starting the server. Use `type` keyword for clarity and to ensure it's removed during transpilation.","wrong":"import { ServerOptions } from 'agentation-mcp';","symbol":"ServerOptions","correct":"import { type ServerOptions } from 'agentation-mcp';"},{"note":"Although the `agentation-mcp` package is mainly consumed via its `npx agentation-mcp` CLI, if one were to programmatically invoke parts of the CLI functionality or integrate it into a larger application, the CLI entry point might be exposed from a subpath like `agentation-mcp/cli`. This is an assumption based on common Node.js CLI package structures.","wrong":"import { AgentationMcpCli } from 'agentation-mcp';","symbol":"AgentationMcpCli","correct":"import { runCli } from 'agentation-mcp/cli';"}],"quickstart":{"code":"import { startServer, type ServerOptions } from 'agentation-mcp';\n\nconst serverOptions: ServerOptions = {\n  port: parseInt(process.env.AGENTATION_PORT ?? '4747', 10),\n  mcpOnly: process.env.AGENTATION_MCP_ONLY === 'true',\n  httpUrl: process.env.AGENTATION_HTTP_URL,\n  // Add other environment variables for webhooks if needed\n  // For example, webhookUrl: process.env.AGENTATION_WEBHOOK_URL,\n  // webhooks: process.env.AGENTATION_WEBHOOKS?.split(','),\n};\n\nasync function main() {\n  try {\n    console.log(`Starting Agentation MCP server with options:`, serverOptions);\n    const server = await startServer(serverOptions);\n    console.log(`Agentation MCP HTTP server listening on http://localhost:${serverOptions.port}`);\n    console.log(`MCP server started (stdio interface for AI agents).`);\n\n    // Keep the process alive, or handle graceful shutdown\n    process.on('SIGINT', async () => {\n      console.log('Shutting down server...');\n      await server.stop(); // Assuming a `stop` method exists\n      process.exit(0);\n    });\n    process.on('SIGTERM', async () => {\n      console.log('Shutting down server...');\n      await server.stop();\n      process.exit(0);\n    });\n\n  } catch (error) {\n    console.error('Failed to start Agentation MCP server:', error);\n    process.exit(1);\n  }\n}\n\nmain();","lang":"typescript","description":"Demonstrates how to programmatically start the Agentation MCP server, configuring its port and other options via environment variables, and includes basic signal handling for graceful shutdown."},"warnings":[{"fix":"Consult the TypeScript declaration files (`.d.ts`) or source code to understand the exact programmatic API if you intend to embed the server rather than use the CLI.","message":"The package primarily emphasizes CLI usage via `npx agentation-mcp server`. While it ships TypeScript types, direct programmatic imports and instantiation of the server are not explicitly documented in the README, requiring users to infer the API based on common Node.js server patterns.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your Node.js environment is version 18.0.0 or higher. Use `nvm use 18` or similar version management tools.","message":"The package requires Node.js version 18 or greater. Running with older Node.js versions will result in execution errors.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"When integrating with AI agent runners, ensure that the stdio pipes are correctly established and managed for the `agentation-mcp server` process. Refer to the specific AI agent's documentation (e.g., Claude Code) for integration guidelines.","message":"The MCP server uses stdio for communication with AI agents. Customizing or proxying this communication requires careful handling of child processes and their standard input/output streams, which is beyond the scope of simple HTTP proxying.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change the port using the `--port` option for the CLI (e.g., `agentation-mcp server --port 8080`) or by setting the `AGENTATION_PORT` environment variable if running programmatically.","cause":"The default HTTP server port (4747) is already in use by another process on your system.","error":"Error: listen EADDRINUSE: address already in use :::4747"},{"fix":"Run `npx agentation-mcp doctor` to diagnose setup issues. If the problem persists, try `npx agentation-mcp init` again to re-run the interactive setup wizard, ensuring Claude Code is running and accessible.","cause":"The integration with the `claude` CLI might not have completed successfully, or the `agentation` tool was not registered with Claude Code.","error":"Command 'claude mcp add agentation' failed or did not register correctly."},{"fix":"Verify the exact export names and module structure by inspecting the package's `index.d.ts` or source code. If the package is ESM-only (likely for Node.js 18+), ensure your consuming project is also configured for ESM (e.g., `\"type\": \"module\"` in `package.json`). If `startServer` is a default export, use `import startServer from 'agentation-mcp';`.","cause":"This error typically indicates that `startServer` is not a named export from the `agentation-mcp` package, or the module format (ESM/CJS) is being mishandled.","error":"TypeError: (0, import_agentation_mcp.startServer) is not a function"}],"ecosystem":"npm"}