agentation-vue-mcp 0.0.2

package/LICENSE

@@ -0,0 +1,27 @@
+PolyForm Shield License 1.0.0
+
+Copyright (c) 2026 Benji Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, and distribute the Software, subject to the following conditions:
+
+1. You may not use the Software to provide a product or service that competes
+   with the Software or any product or service offered by the Licensor that
+   includes the Software.
+
+2. You may not remove or obscure any licensing, copyright, or other notices
+   included in the Software.
+
+3. If you distribute the Software or any derivative works, you must include a
+   copy of this license.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+For more information, see https://polyformproject.org/licenses/shield/1.0.0

package/README.md

@@ -0,0 +1,171 @@
+# Agentation MCP
+
+MCP (Model Context Protocol) server for Agentation - visual feedback for AI coding agents.
+
+This package provides an MCP server that allows AI coding agents (like Claude Code) to receive and respond to web page annotations created with the Agentation toolbar.
+
+## Installation
+
+```bash
+npm install agentation-vue-mcp
+# or
+pnpm add agentation-vue-mcp
+```
+
+## Quick Start
+
+### 1. Add to your agent
+
+The fastest way to configure Agentation across any supported agent:
+
+```bash
+npx add-mcp "npx -y agentation-vue-mcp server"
+```
+
+Uses [add-mcp](https://github.com/neondatabase/add-mcp) to auto-detect installed agents (Claude Code, Cursor, Codex, Windsurf, and more).
+
+Or for Claude Code specifically:
+
+```bash
+claude mcp add agentation -- npx agentation-vue-mcp server
+```
+
+
+### 2. Start the server
+
+```bash
+agentation-vue-mcp server
+```
+
+This starts both:
+- **HTTP server** (port 4747) - receives annotations from the browser toolbar
+- **MCP server** (stdio) - exposes tools for Claude Code
+
+### 3. Verify your setup
+
+```bash
+agentation-vue-mcp doctor
+```
+
+## CLI Commands
+
+```bash
+agentation-vue-mcp init                    # Setup wizard (registers via claude mcp add)
+agentation-vue-mcp server [options]        # Start the annotation server
+agentation-vue-mcp doctor                  # Check your setup
+agentation-vue-mcp help                    # Show help
+```
+
+### Server Options
+
+```bash
+--port <port>      # HTTP server port (default: 4747)
+--mcp-only         # Skip HTTP server, only run MCP on stdio
+--http-url <url>   # HTTP server URL for MCP to fetch from
+```
+
+## MCP Tools
+
+The MCP server exposes these tools to AI agents:
+
+| Tool | Description |
+|------|-------------|
+| `agentation_list_sessions` | List all active annotation sessions |
+| `agentation_get_session` | Get a session with all its annotations |
+| `agentation_get_pending` | Get pending annotations for a session |
+| `agentation_get_all_pending` | Get pending annotations across all sessions |
+| `agentation_acknowledge` | Mark an annotation as acknowledged |
+| `agentation_resolve` | Mark an annotation as resolved |
+| `agentation_dismiss` | Dismiss an annotation with a reason |
+| `agentation_reply` | Add a reply to an annotation thread |
+| `agentation_watch_annotations` | Block until new annotations appear, then return batch |
+
+## HTTP API
+
+The HTTP server provides a REST API for the browser toolbar:
+
+### Sessions
+- `POST /sessions` - Create a new session
+- `GET /sessions` - List all sessions
+- `GET /sessions/:id` - Get session with annotations
+
+### Annotations
+- `POST /sessions/:id/annotations` - Add annotation
+- `GET /annotations/:id` - Get annotation
+- `PATCH /annotations/:id` - Update annotation
+- `DELETE /annotations/:id` - Delete annotation
+- `GET /sessions/:id/pending` - Get pending annotations
+- `GET /pending` - Get all pending annotations
+
+### Events (SSE)
+- `GET /sessions/:id/events` - Session event stream
+- `GET /events` - Global event stream (optionally filter with `?domain=...`)
+
+### Health
+- `GET /health` - Health check
+- `GET /status` - Server status
+
+## Hands-Free Mode
+
+Use `agentation_watch_annotations` in a loop for automatic feedback processing -- the agent picks up new annotations as they're created:
+
+1. Agent calls `agentation_watch_annotations` (blocks until annotations appear)
+2. Annotations arrive -- agent receives batch after collection window
+3. Agent processes each annotation:
+   - `agentation_acknowledge` -- mark as seen
+   - Make code changes
+   - `agentation_resolve` -- mark as done with summary
+4. Agent calls `agentation_watch_annotations` again (loop)
+
+Example CLAUDE.md instructions:
+
+```markdown
+When I say "watch mode", call agentation_watch_annotations in a loop.
+For each annotation: acknowledge it, make the fix, then resolve it with a summary.
+Continue watching until I say stop or timeout is reached.
+```
+
+## Webhooks
+
+Configure webhooks to receive notifications when users request agent action:
+
+```bash
+# Single webhook
+export AGENTATION_WEBHOOK_URL=https://your-server.com/webhook
+
+# Multiple webhooks (comma-separated)
+export AGENTATION_WEBHOOKS=https://server1.com/hook,https://server2.com/hook
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AGENTATION_STORE` | Storage backend (`memory` or `sqlite`) | `sqlite` |
+| `AGENTATION_WEBHOOK_URL` | Single webhook URL | - |
+| `AGENTATION_WEBHOOKS` | Comma-separated webhook URLs | - |
+| `AGENTATION_EVENT_RETENTION_DAYS` | Days to keep events | `7` |
+
+## Programmatic Usage
+
+```typescript
+import { startHttpServer, startMcpServer } from 'agentation-vue-mcp';
+
+// Start HTTP server on port 4747
+startHttpServer(4747);
+
+// Start MCP server (connects via stdio)
+await startMcpServer('http://localhost:4747');
+```
+
+## Storage
+
+By default, data is persisted to SQLite at `~/.agentation/store.db`. To use in-memory storage:
+
+```bash
+AGENTATION_STORE=memory agentation-vue-mcp server
+```
+
+## License
+
+PolyForm Shield 1.0.0