Pointa

Visual feedback for AI-powered development

Point. Annotate. Let AI implement.

Website • Quick Start • Chrome Extension • npm

What is Pointa?

Pointa is a browser extension and local server that lets you add visual annotations to your localhost development projects. Click on any element, leave a comment, and your AI coding agent (Cursor, Claude Code, Windsurf, etc.) can automatically implement the changes.

Think of it as "visual issue tracking" that your AI can read and act on - no more copying CSS selectors or describing which button you're talking about.

You can also use the extension to...

• Report bugs in seconds

• Get your AI coding tool to bulk fix your annotations (through MCP integration)

• Capture UI from other websites with clean screenshots and CSS metadata

Key Features

• 🎯 Point and click annotations - Click any element to leave feedback
• 🤖 AI-ready - Integrates with AI coding agents via MCP protocol
• 🏠 Local-first - Works on localhost, no cloud dependencies
• 📦 Multi-page tracking - Annotate across different routes and pages
• 🔒 Privacy-focused - All data stays on your machine

How It Works

Architecture

Pointa consists of two main components:

┌─────────────────────────────────────────┐
│         Browser Extension               │
│  - UI for creating annotations          │
│  - Element selection & highlighting     │
│  - Annotation management interface      │
└───────────────┬─────────────────────────┘
                │
                │ HTTP API
                ▼
┌─────────────────────────────────────────┐
│         Local Server (Node.js)          │
│  - MCP server for AI agents             │
│  - HTTP API for extension               │
│  - File-based storage (~/.pointa)       │
└─────────────────────────────────────────┘

1. Browser Extension (/extension)

• Chromium-based extension (Chrome, Edge, Brave, etc.)
• Injects UI for creating and viewing annotations
• Communicates with local server via HTTP
• Provides visual feedback on annotated elements

2. Local Server (/annotations-server)

• Node.js server running on port 4242
• Exposes MCP protocol for AI coding agents
• Stores annotations in ~/.pointa directory
• RESTful API for extension communication

3. Data Flow

User clicks element → Extension captures context → Server stores annotation
                                                            ↓
AI Agent ← MCP Protocol ← Server provides annotation data

Annotate visually localhost like you would annotate a Figma screen

Then jump to your AI coding tool of choice and simply ask to work on thos annotations (voila!)

Quick Start

Prerequisites

• Node.js 18+
• Chromium-based browser (Chrome, Edge, Brave, etc.)
• An AI coding agent that supports MCP (Cursor, Claude Code, Windsurf, etc.)

Installation

1. Install the server (optional)

The server will be automatically installed when you configure your AI tool with npx. However, if you want to manually install and manage it:

npm install -g pointa-server
pointa-server start

Note: With the npx approach (recommended), you can skip this step entirely.

2. Install the browser extension

Option A: From Chrome Web Store (recommended)

• Install from Chrome Web Store

Option B: Load unpacked (for development)

• Clone this repository
• Open chrome://extensions/
• Enable "Developer mode"
• Click "Load unpacked" and select the /extension directory

3. Connect your AI coding agent

Add the MCP server to your AI agent's configuration using npx (recommended):

{
  "mcpServers": {
    "pointa": {
      "command": "npx",
      "args": ["-y", "pointa-server"]
    }
  }
}

This approach automatically:

• Installs the server if not present
• Starts the HTTP daemon for the Chrome extension (if needed)
• Keeps the server up-to-date

See the AI Agent Setup section for tool-specific instructions.

Usage

1. Open your localhost development server in your browser
2. Click the Pointa extension icon to activate
3. Click on any element you want to annotate
4. Add your feedback/instructions
5. Ask your AI coding agent to "implement the Pointa annotations"

AI Agent Setup

Cursor

1. Open Settings → Cursor Settings
2. Go to Tools & Integrations tab
3. Click + Add new global MCP server
4. Add this configuration:

{
  "mcpServers": {
    "pointa": {
      "command": "npx",
      "args": ["-y", "pointa-server"]
    }
  }
}

5. Save and restart Cursor

Note: The npx command automatically handles server installation and startup. No need to manually run pointa-server start.

Claude Code

Add to your Claude configuration file (~/.config/claude/config.json or similar):

{
  "mcpServers": {
    "pointa": {
      "command": "npx",
      "args": ["-y", "pointa-server"]
    }
  }
}

Or use the CLI:

claude mcp add --transport stdio pointa -- npx -y pointa-server

Note: The npx command automatically handles server installation and startup.

Windsurf

1. Navigate to Settings → Advanced Settings
2. Scroll to the Cascade section
3. Add:

{
  "mcpServers": {
    "pointa": {
      "command": "npx",
      "args": ["-y", "pointa-server"]
    }
  }
}

4. Save and restart Windsurf

Note: The npx command automatically handles server installation and startup. No need to manually run pointa-server start.

Other Editors (VS Code, etc.)

Install an MCP-compatible AI extension and add:

{
  "mcpServers": {
    "pointa": {
      "command": "npx",
      "args": ["-y", "pointa-server"]
    }
  }
}

Note: The npx command automatically handles server installation and startup. If your tool doesn't support the command/args format, you can use the HTTP endpoint approach:

{
  "mcpServers": {
    "pointa": {
      "url": "http://127.0.0.1:4242/mcp"
    }
  }
}

(Requires manually running pointa-server start first)

Server Commands

# Start the server
pointa-server start

# Check server status
pointa-server status

# Stop the server
pointa-server stop

# Restart the server
pointa-server restart

Development

Repository Structure

pointa-app/
├── extension/              # Browser extension
│   ├── manifest.json       # Extension configuration
│   ├── background/         # Service worker
│   ├── content/            # Content scripts
│   │   └── modules/        # Feature modules
│   ├── popup/              # Extension popup UI
│   └── assets/             # Icons and fonts
│
├── annotations-server/     # MCP server (npm package)
│   ├── bin/cli.js          # CLI entry point
│   ├── lib/server.js       # Server implementation
│   └── package.json        # Server package config
│
└── docs/                   # Documentation

Running Locally

Extension Development:

1. Clone the repository
2. Open chrome://extensions/
3. Enable Developer mode
4. Click "Load unpacked" → select /extension directory
5. Make changes and reload extension to test

Server Development:

cd annotations-server
npm install
npm run dev  # Auto-restarts on changes

Testing the Integration:

1. Start the server (locally or globally)
2. Load the extension
3. Open a localhost page (e.g., http://localhost:3000)
4. Create an annotation
5. Check that it appears in your AI agent's MCP tools

Code Style

• 2 spaces for indentation
• Meaningful variable names
• Comments for complex logic
• Follow existing patterns in the codebase

Tech Stack

Extension:

• Vanilla JavaScript (no frameworks)
• Chrome Extension Manifest V3
• CSS with custom properties for theming

Server:

• Node.js with Express
• MCP SDK (@modelcontextprotocol/sdk)
• File-based storage (node-persist)

Contributing

We welcome contributions! Here's how you can help:

1. Report bugs - Open an issue with details about the problem
2. Suggest features - Share your ideas in the issues
3. Submit PRs - Fix bugs or implement features
4. Improve docs - Help make the documentation clearer

Please read CONTRIBUTING.md for detailed guidelines.

Good First Issues

Look for issues labeled:

• good first issue - Great for newcomers
• help wanted - Community contributions needed

Known Limitations

• Shadow DOM: Elements inside Shadow DOM (Web Components) cannot be annotated due to DOM isolation
• Local development only: Designed for localhost/local domains only
• Chromium browsers: Currently only supports Chrome-based browsers

Uninstalling

Remove the extension:

• Go to chrome://extensions/ and remove Pointa

Uninstall the server:

npm uninstall -g pointa-server
rm -rf ~/.pointa  # Remove data directory

Remove from AI agent:

• Remove the pointa entry from your MCP server configuration

Troubleshooting

Server not detected

• Run pointa-server status to check if it's running
• Make sure port 4242 is not blocked by firewall

Extension not working

• Verify you're on a local development URL (localhost, 127.0.0.1, *.local, etc.)
• Check browser console for errors
• Try reloading the extension

MCP connection failed

• Verify server is running
• Check your AI agent's configuration matches the examples
• Restart your AI agent after configuration changes

For more issues, check GitHub Issues.

Documentation

• Development Guide
• Update System
• Contributing Guidelines

License

MIT - see LICENSE for details.

Acknowledgments

Built with ❤️ by Julien Berthomier at Argil.io

---

Star this repo if you find it useful! ⭐