npm package: @simple-commenter/mcp-server
Description: MCP server for Simple Commenter — lets AI agents work with website feedback
Author: Simple Commenter
Latest version: 1.0.4

# Simple Commenter MCP Server

[![npm version](https://img.shields.io/npm/v/@simple-commenter/mcp-server)](https://www.npmjs.com/package/@simple-commenter/mcp-server)
[![license](https://img.shields.io/npm/l/@simple-commenter/mcp-server)](LICENSE)

MCP server that lets AI coding agents (Claude Code, Cursor, etc.) fetch website feedback from [Simple Commenter](https://simplecommenter.com), understand what needs fixing, and update comment status as they work.

## Prerequisites

Before using the MCP server, you need a Simple Commenter account with at least one project configured:

1. Sign up at [simplecommenter.com](https://simplecommenter.com)
2. Create a project in the dashboard and add your website domain
3. Install the widget on your site (script tag or browser extension)

The MCP server connects to projects you've already set up in the dashboard — it does not create projects for you.

## Quick Start

```bash
npx @simple-commenter/mcp-server init
```

The setup wizard will:
1. Authenticate with your email + a 6-digit code
2. Let you pick a default project
3. Configure status preferences for AI workflows
4. Auto-create a `.mcp.json` in your project root

Restart your AI tool and the MCP server is connected.

### Verify your setup

```bash
npx @simple-commenter/mcp-server doctor
```

Checks Node.js version, config, API connectivity, and `.mcp.json` — reports pass/fail for each.

## Available Tools

| Tool | Description |
|------|-------------|
| `list_projects` | List all websites/projects in your account |
| `list_comments` | List comments with filters (status, priority, page, search) |
| `get_comment` | Full detail — DOM element XPath, screenshot, click position, replies |
| `update_comment_status` | Mark as in_progress, done, etc. |
| `reply_to_comment` | Reply with what you found and fixed |

## Typical Workflow

Ask your AI agent:

> "Check Simple Commenter for open feedback and fix the issues"

The agent will:
1. Call `list_projects` to find your project
2. Call `list_comments` with `status=todo` to get open issues
3. Call `get_comment` on each to see the element, screenshot, and page URL
4. Mark comments as `in_progress` while working
5. Fix the code
6. Reply with what was fixed
7. Mark as `done`

## CLI Commands

```bash
simple-commenter-mcp init      # Setup wizard — login + pick project
simple-commenter-mcp serve     # Start MCP server (default, used by AI tools)
simple-commenter-mcp doctor    # Health check — verify setup + connectivity
simple-commenter-mcp status    # Show account info + projects
simple-commenter-mcp reset     # Remove config + .mcp.json (clean slate)
```

`login` and `logout` still work as aliases for `init` and `reset`.

If not installed globally, prefix with `npx @simple-commenter/mcp-server` instead.

## Changing Your Default Project

To switch to a different project, run `init` again:

```bash
simple-commenter-mcp init
```

This re-runs the full setup wizard and lets you pick a new default project and preferences.

For a clean start, reset first:

```bash
simple-commenter-mcp reset
simple-commenter-mcp init
```

`reset` removes your saved config and `.mcp.json`, so you start fresh.

## Configuration

### `.mcp.json` (auto-created by init)

```json
{
  "mcpServers": {
    "simple-commenter": {
      "command": "simple-commenter-mcp",
      "args": ["serve"]
    }
  }
}
```

### Environment variable (CI/Docker)

```json
{
  "mcpServers": {
    "simple-commenter": {
      "command": "npx",
      "args": ["@simple-commenter/mcp-server", "serve"],
      "env": {
        "SIMPLE_COMMENTER_API_TOKEN": "your-token"
      }
    }
  }
}
```

### Authentication priority

The server checks for credentials in this order:
1. `--token <token>` CLI flag
2. `SIMPLE_COMMENTER_API_TOKEN` environment variable
3. `~/.simple-commenter/config.json` (from `init` command)

## Troubleshooting

Run `doctor` to diagnose common issues:

```bash
simple-commenter-mcp doctor
```

**Common issues:**

| Check | Fix |
|-------|-----|
| Config file not found | Run `simple-commenter-mcp init` |
| No authentication token | Run `init` or set `SIMPLE_COMMENTER_API_TOKEN` |
| API connection failed | Check your internet connection; verify the API URL with `--api-url` |
| No default project set | Run `init` and select a project |
| `.mcp.json` not found | Run `init` from your project root (where `package.json` or `.git` is) |
| `.mcp.json` doesn't reference simple-commenter | Run `reset` then `init` to recreate it |

## Security

- Credentials are stored in `~/.simple-commenter/config.json` with `chmod 600` (owner-only)
- The server warns if file permissions are too open
- For shared machines, use environment variables instead of the config file
- Add `.simple-commenter/` to your `.gitignore`
- Never commit your API token to version control. Use environment variables in CI/CD pipelines.

## Supported AI Tools

The MCP server works with any tool that supports the Model Context Protocol:

- **Claude Code** — Anthropic's CLI coding agent
- **Cursor** — AI-powered code editor
- **Any MCP-compatible agent** — The protocol is open and growing

## Development

```bash
npm install
npm test
```