# 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 clients read, search, export, and manage website and asset feedback from [Simple Commenter](https://www.simplecommenter.com). The same tool catalog powers local npm/stdio connections and the hosted HTTPS adapter.

## Hosted connections

The hosted route is `https://www.simplecommenter.com/api/mcp`. It uses browser OAuth with selected-project grants and separate read, write, and settings scopes. Open **MCP** directly in a project's sidebar for connection status and setup. Hosted MCP is enabled by default when the application is deployed; `MCP_ENABLED=false` optionally disables it. The hosted application changes still need deployment and release validation; building this package alone does not deploy them.

Clients that support remote MCP can use the hosted route without installing this package. Local clients can continue using the npm setup below. Client support for interactive views and file uploads varies; every tool also returns text and structured data.

## 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 connection can read only projects permitted by its grant. Administrative clients with an account-wide settings grant can also create projects; local setup can select a default after the first project exists.

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

> **Note:** `npm install` only downloads the package — it does **not** touch
> `.mcp.json`. The `.mcp.json` entry is written by `init` (it doesn't know which
> project folder to register otherwise). If you registered the server in a global
> config (e.g. `~/.claude.json`) instead, an empty or missing project `.mcp.json`
> is expected and `doctor` will only show it as a warning.

### Verify your setup

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

Checks Node.js version, config, and API connectivity (hard checks), and notes the
`.mcp.json` state as a warning if the server isn't registered in the project file.

## Available Tools

| Tool | Description |
|------|-------------|
| `get_connection_info` | Refresh account, plan, granted permissions, and connection context |
| `list_projects` | List projects authorized for this connection |
| `get_project_context` | Read current statuses, tags, workflow settings, and project links |
| `list_comments` | List website or asset feedback in one project, with filters and pagination |
| `get_comment` | Full detail — DOM element XPath, screenshot, click position, replies, and the `brief` (AI-written developer brief: title, summary, suggested fix) |
| `update_comment_status` | Mark as in_progress, done, etc. |
| `update_comment` | Set status, priority, replacement tags, visibility, or archive/restore state |
| `reply_to_comment` | Reply with text and authorized upload references |
| `prepare_attachment_upload` | Prepare a private, expiring signed upload for a reply attachment |
| `create_comment` | File new feedback on a page after reviewing it yourself |
| `search_comments` | Search across authorized projects by text, dates, author, status, tags, or website/asset source |
| `search`, `fetch` | Retrieve citable feedback sources for knowledge workflows |
| `export_comments` | Download a complete filtered CSV with attachment links and an expiring URL |
| `feedback_report` | Obtain complete feedback counts and breakdowns, plus a report artifact |
| `bulk_update_comments` | Apply bounded triage changes to up to 100 explicit items, with per-item results |
| `create_project` | Create a project with an account-wide administrative grant |
| `get_project_settings`, `update_project_settings` | Inspect and edit supported non-secret project settings |
| `list_team_members`, `add_team_member` | List team members or add a team-role member without sending email |
| `assign_team_member`, `remove_team_member` | Manage project assignments or revoke workspace membership |
| `start_task`, `get_task`, `list_tasks`, `cancel_task` | Start and manage durable export/report jobs |

Comment and reply text uses Markdown Lite: `**bold**`, `` `code` `` and lines
starting with `- ` (bullets) are rendered; nothing else is. `reply_to_comment`
and `create_comment` may use those markers.

`create_comment` takes a `page` path (e.g. `/pricing`) and `text`. To pin the
comment to a specific element on the page, pass `anchor_selector` (a CSS
selector — preferred) or `anchor_text` (the element's exact, full visible text)
with `anchor_tag`. Without an anchor it becomes a page-level comment: it shows
in the dashboard and in the widget's feedback list, just without an on-page pin.
The `init` wizard asks whether the AI may create comments and replies. Disabled
actions are rejected by the local adapter, including direct tool calls. Hosted
access is controlled by OAuth scopes and granted projects. Status suggestions
guide the workflow; they do not grant additional permission.

All tools validate arguments and return machine-readable `structuredContent` with
a JSON text fallback. Write annotations identify actions that change feedback or
account access. Custom status choices come from the selected project's current
context, so switching projects does not reuse an outdated default enum.

### Search, export, and reports

`search_comments`, `export_comments`, and `feedback_report` accept `project_id` or
`project_ids`, text (`query` or `search`), `status`, `priority`, `tags`, `slug`,
`created_after`, `created_before`, `author`, `include_archived`, and `source`
(`all`, `website`, or `asset`). Creation timestamps use ISO 8601 with a timezone.
Search results paginate with `limit` (1–100) and `offset`; reports and exports
cover the complete filtered result set instead of only the current page.

`search` accepts a `query` and returns source IDs, titles, and URLs. Pass one of
those IDs to `fetch`; it does not retrieve arbitrary remote URLs.

Use `start_task` with `operation: "export_comments"` or `"feedback_report"`,
filter `arguments`, and an `idempotency_key` for long jobs. Poll `get_task` at the
returned interval. Jobs are durable service records accessed through ordinary
tools; this server does not advertise the experimental MCP protocol tasks
capability.

### Safe writes and attachments

New project/member creation, bulk updates, and job creation require an
`idempotency_key`. Use the same key and identical arguments for a retry. The
original create/reply/update tools accept keys without requiring them for older
clients. If a write without a key times out, inspect the data before retrying.

For reply attachments, call `prepare_attachment_upload` with a project,
filename, MIME type, and exact byte size. Upload the file bytes with an HTTP PUT
to the returned signed URL using its required headers, then pass
`attachments: [{ "upload_id": "returned-id" }]` to `reply_to_comment`. The
service verifies ownership and completion. Your client must be able to upload
file bytes; this tool does not import remote URLs or access local files itself.

### Resources, workflow prompts, and interactive views

Resources expose the current connection, authorized projects, project context,
comment detail, and job progress through `simplecommenter://` URIs. Discover the
exact resource templates through `resources/templates/list`.

The prompts `triage_feedback`, `release_report`, and `investigate_comment` load
authorized project context and provide source-based workflows. They do not
perform writes merely because the prompt was selected.

An optional MCP Apps resource, `ui://simplecommenter/feedback.html`, provides
search and pagination inside compatible hosts. It uses the host's MCP bridge,
loads no external scripts or fonts, and performs only read operations. Clients
without interactive views receive the same feedback as text and structured data.

## Embedding the server

```js
import { createMcpServer } from "@simple-commenter/mcp-server/src/server.js";

const server = createMcpServer({
  client: {
    mcpOperation: (operation, args) => authorizedOperations(operation, args),
  },
  defaultProjectId: null,
  connectionContext: { transport: "streamable-http" },
});
await server.connect(transport);
```

Create a server with a request-scoped authenticated client for each hosted
request. The factory never reads the user's home directory or local token
configuration. Authorization must remain enforced by `authorizedOperations`;
tool annotations and default project selection do not enforce access control.
The implementation is pinned to official MCP SDK 1.30.0.

## 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

## Install as a Codex plugin

This repository is also packaged as a Codex plugin, so it can be installed as
one unit instead of wiring up the server by hand. The plugin bundles the hosted
MCP connection with the `fix-feedback` skill, which runs the whole loop from
open feedback to a landed fix.

| Path | Purpose |
|------|---------|
| `.codex-plugin/plugin.json` | Plugin manifest and marketplace listing metadata |
| `.mcp.json` | Hosted server connection over Streamable HTTP, browser OAuth on first use |
| `skills/fix-feedback/` | Bundled skill for triaging and fixing open feedback |
| `assets/` | Icon and logo used in the plugin listing |

Install by pointing a plugin marketplace or a local install at
`simple-commenter/mcp-server`. The hosted route needs no npm install. Clients
that support only local stdio can still use the `init` flow described above.

## Development

```bash
npm install
npm test
```

## Release and directory listing

`server.json` is a draft for the official MCP Registry, with both npm/stdio and
the hosted Streamable HTTP route. It has not been submitted and does not imply
that Simple Commenter is listed. Before releasing:

1. Deploy the hosted route and OAuth discovery on the public domain. MCP is on
   by default; remove any existing `MCP_ENABLED=false` override to use it.
2. Verify fresh sign-in, read-only and selected-project grants, writes,
   revocation, token refresh, exports, and uploads in the intended clients.
3. Run `npm test` and `npm pack --dry-run`; keep the package version, manifest
   version, npm package entry, and `mcpName` consistent.
4. Verify ownership of the `simple-commenter` GitHub namespace and npm package.
   Publish the npm package before submitting registry metadata, as required by
   the [official registry guide](https://modelcontextprotocol.io/registry/quickstart).
5. Remove the draft release marker only when those checks pass, review the
   complete manifest, and explicitly authorize npm and registry publication.

The registry submission is a separate release action. This package's tests and
build never publish, register, or deploy it automatically.