Simple Commenter MCP Server

MCP server that lets AI clients read, search, export, and manage website and asset feedback from Simple Commenter. 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

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

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

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

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

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

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:

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:

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)

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

Environment variable (CI/Docker)

{
  "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:

simple-commenter-mcp doctor

Common issues:

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.

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

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.

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.