agentation-mcp

library1.2.0jsnpmunverified

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.

llm-agents

npm install agentation-mcp

package ↗

INSTALL

IMPORT

SIG · AGENTATION-MCP

agentation-mcp

llm-agentsjavascriptv1.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

startServer

✓ import { startServer } from 'agentation-mcp';

✗ const { startServer } = require('agentation-mcp');

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.

ServerOptions

✓ import { type ServerOptions } from 'agentation-mcp';

✗ import { ServerOptions } from 'agentation-mcp';

Type-only import for configuration options when programmatically starting the server. Use `type` keyword for clarity and to ensure it's removed during transpilation.

AgentationMcpCli

✓ import { runCli } from 'agentation-mcp/cli';

✗ import { AgentationMcpCli } from 'agentation-mcp';

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.

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.

import { startServer, type ServerOptions } from 'agentation-mcp'; const serverOptions: ServerOptions = { port: parseInt(process.env.AGENTATION_PORT ?? '4747', 10), mcpOnly: process.env.AGENTATION_MCP_ONLY === 'true', httpUrl: process.env.AGENTATION_HTTP_URL, // Add other environment variables for webhooks if needed // For example, webhookUrl: process.env.AGENTATION_WEBHOOK_URL, // webhooks: process.env.AGENTATION_WEBHOOKS?.split(','), }; async function main() { try { console.log(`Starting Agentation MCP server with options:`, serverOptions); const server = await startServer(serverOptions); console.log(`Agentation MCP HTTP server listening on http://localhost:${serverOptions.port}`); console.log(`MCP server started (stdio interface for AI agents).`); // Keep the process alive, or handle graceful shutdown process.on('SIGINT', async () => { console.log('Shutting down server...'); await server.stop(); // Assuming a `stop` method exists process.exit(0); }); process.on('SIGTERM', async () => { console.log('Shutting down server...'); await server.stop(); process.exit(0); }); } catch (error) { console.error('Failed to start Agentation MCP server:', error); process.exit(1); } } main();

Debug

Known issues

gotchaThe 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.

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.

affects: >=1.0.0

breakingThe package requires Node.js version 18 or greater. Running with older Node.js versions will result in execution errors.

fix

Ensure your Node.js environment is version 18.0.0 or higher. Use `nvm use 18` or similar version management tools.

affects: <1.0.0

gotchaThe 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.

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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: listen EADDRINUSE: address already in use :::4747

The default HTTP server port (4747) is already in use by another process on your system.

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.

Command 'claude mcp add agentation' failed or did not register correctly.

The integration with the `claude` CLI might not have completed successfully, or the `agentation` tool was not registered with Claude Code.

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.

TypeError: (0, import_agentation_mcp.startServer) is not a function

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.

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';`.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

65 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/agentation-mcp ↗