Simple Commenter

Simple Commenter MCP サーバー

Simple Commenter からウェブサイトやアセットに関するフィードバックを読み取り、検索、エクスポート、管理できる MCP サーバーです。同じツールカタログが、ローカルの npm/stdio 接続とホスト型 HTTPS アダプターの両方を支えています。

ホスト型接続

ホスト型のエンドポイントは https://www.simplecommenter.com/api/mcp です。ブラウザー OAuth を使用し、選択したプロジェクトへの許可と、読み取り、書き込み、設定の各スコープを分けて管理します。接続状況とセットアップを確認するには、プロジェクトのサイドバーで MCP を直接開いてください。アプリケーションをデプロイすると、ホスト型 MCP はデフォルトで有効になります。必要に応じて MCP_ENABLED=false で無効にできます。ホスト型アプリケーションの変更を反映するには、デプロイとリリースの検証が別途必要です。このパッケージをビルドしても、ホスト型アプリケーションはデプロイされません。

リモート MCP に対応しているクライアントは、このパッケージをインストールせずにホスト型エンドポイントを使用できます。ローカルクライアントは、以下の npm セットアップを引き続き利用できます。インタラクティブビューやファイルのアップロードへの対応状況はクライアントによって異なります。すべてのツールはテキストと構造化データも返します。

前提条件

MCP サーバーを使用するには、少なくとも1つのプロジェクトを設定した Simple Commenter アカウントが必要です。

1. simplecommenter.com で登録します
2. ダッシュボードでプロジェクトを作成し、ウェブサイトのドメインを追加します
3. サイトにウィジェットをインストールします（スクリプトタグまたはブラウザー拡張機能）

接続から読み取れるのは、許可されたプロジェクトのみです。アカウント全体の設定許可を持つ管理クライアントは、プロジェクトを作成することもできます。ローカルセットアップでは、最初のプロジェクトが作成された後にデフォルトのプロジェクトを選択できます。

クイックスタート

npx @simple-commenter/mcp-server init

セットアップウィザードでは、以下を行います。

1. メールアドレスと6桁のコードで認証します
2. デフォルトのプロジェクトを選択します
3. AI ワークフロー用のステータス設定を行います
4. プロジェクトのルートに .mcp.json を自動作成します

AI ツールを再起動すると、MCP サーバーに接続されます。

注記： npm install はパッケージをダウンロードするだけで、.mcp.json には一切変更を加えません。.mcp.json のエントリーは init によって書き込まれます（それ以外では、どのプロジェクトフォルダーに登録すればよいか判断できません）。代わりにグローバル設定（例：~/.claude.json）にサーバーを登録した場合、プロジェクトの .mcp.json が空または存在しないのは想定どおりです。その場合、doctor は警告としてのみ表示します。

セットアップを確認する

npx @simple-commenter/mcp-server doctor

Node.js のバージョン、設定、API 接続をチェックします（必須チェック）。サーバーがプロジェクトのファイルに登録されていない場合は、.mcp.json の状態を警告として表示します。

利用可能なツール

ツール	説明
get_connection_info	アカウント、プラン、付与された権限、接続コンテキストを更新します
list_projects	この接続で許可されているプロジェクトを一覧表示します
get_project_context	現在のステータス、タグ、ワークフロー設定、プロジェクトリンクを読み取ります
list_comments	1つのプロジェクト内のウェブサイトまたはアセットに関するフィードバックを、フィルターとページネーションを使って一覧表示します
get_comment	詳細情報 — DOM 要素の XPath、スクリーンショット、クリック位置、返信、および brief（AI が作成した開発者向け概要：タイトル、要約、修正案）
update_comment_status	ステータスを in_progress、done などに設定します
update_comment	ステータス、優先度、置換タグ、公開範囲、アーカイブ／復元状態を設定します
reply_to_comment	テキストと許可されたアップロード参照を使って返信します
prepare_attachment_upload	返信の添付ファイル用に、非公開で有効期限付きの署名付きアップロードを準備します
create_comment	自分で確認したページに新しいフィードバックを投稿します
search_comments	テキスト、日付、作成者、ステータス、タグ、ウェブサイト／アセットのソースで、許可されたプロジェクト全体を検索します
search, fetch	ナレッジワークフロー向けに、引用可能なフィードバックソースを取得します
export_comments	添付ファイルへのリンクと有効期限付き URL を含む、フィルター済みの完全な CSV をダウンロードします
feedback_report	フィードバック件数と内訳、およびレポート成果物を取得します
bulk_update_comments	最大 100 件の明示的な項目に対して、項目ごとの結果を返しながら、範囲を限定したトリアージ変更を適用します
create_project	アカウント全体の管理者権限を付与してプロジェクトを作成します
get_project_settings, update_project_settings	サポートされている非機密のプロジェクト設定を確認、編集します
list_team_members, add_team_member	チームメンバーを一覧表示するか、メールを送信せずにチームロールのメンバーを追加します
assign_team_member, remove_team_member	プロジェクトへの割り当てを管理するか、ワークスペースのメンバーシップを取り消します
start_task, get_task, list_tasks, cancel_task	永続的なエクスポート／レポートジョブを開始、管理します

コメントと返信のテキストでは Markdown Lite が使われます。レンダリングされるのは **太字**、`コード`、および - で始まる行（箇条書き）だけです。それ以外はレンダリングされません。reply_to_comment と create_comment では、これらのマーカーを使用できます。

create_comment は page パス（例：/pricing）と text を受け取ります。ページ上の特定の要素にコメントを固定するには、anchor_tag とともに anchor_selector（CSS セレクター — 推奨）または anchor_text（要素に表示されている正確な全文テキスト）を渡します。アンカーがない場合はページ単位のコメントになり、ページ上には固定されませんが、ダッシュボードとウィジェットのフィードバック一覧に表示されます。init ウィザードでは、AI にコメントや返信の作成を許可するかどうかを選択できます。無効にした操作は、ツールを直接呼び出した場合も含め、ローカルアダプターによって拒否されます。ホスト型アクセスは OAuth スコープと許可されたプロジェクトによって制御されます。ステータスの提案はワークフローを案内するものであり、追加の権限を付与するものではありません。

すべてのツールは引数を検証し、機械可読な structuredContent と、JSON テキストのフォールバックを返します。書き込みアノテーションは、フィードバックまたはアカウントアクセスを変更する操作を示します。カスタムステータスの選択肢は選択中のプロジェクトの現在のコンテキストから取得されるため、プロジェクトを切り替えても古いデフォルトの列挙値は再利用されません。

検索、エクスポート、レポート

search_comments、export_comments、feedback_report は、project_id または project_ids、テキスト（query または search）、status、priority、tags、slug、 created_after、created_before、author、include_archived、source （all、website、または asset）を受け付けます。作成日時には、タイムゾーンを含む ISO 8601 形式を使用します。 検索結果は limit（1～100）と offset でページ分割されます。レポートとエクスポートには 現在のページだけでなく、フィルターに一致する結果セット全体が含まれます。

search は query を受け付け、ソース ID、タイトル、URL を返します。その ID のいずれかを fetch に渡してください。任意のリモート URL を取得することはできません。

長時間かかる処理には、operation: "export_comments" または "feedback_report"、フィルター arguments、idempotency_key を指定して start_task を使用します。返された間隔で get_task をポーリングしてください。ジョブは通常のツールからアクセスする永続的なサービスレコードです。このサーバーは、実験的な MCP プロトコルのタスク機能を 公開していません。

安全な書き込みと添付ファイル

新規プロジェクト／メンバーの作成、一括更新、ジョブの作成には idempotency_key が必要です。再試行時は、同じキーと同一の引数を使用してください。元の作成／返信／更新ツールは、古い クライアント向けに、必須ではありませんがキーを受け付けます。キーなしの書き込みがタイムアウトした場合は、再試行する前にデータを確認してください。

返信にファイルを添付するには、プロジェクト、ファイル名、MIME タイプ、正確なバイト数を指定して prepare_attachment_upload を呼び出します。返された署名付き URL に、必須ヘッダーを付けて HTTP PUT でファイルのバイト列をアップロードし、その後 attachments: [{ "upload_id": "returned-id" }] を reply_to_comment に渡します。サービスは所有権とアップロードの完了を検証します。クライアントはファイルのバイト列をアップロードできる必要があります。このツール自体は、リモート URL のインポートやローカルファイルへのアクセスは行いません。

リソース、ワークフロープロンプト、インタラクティブビュー

リソースは、simplecommenter:// URI を通じて、現在の接続、認可されたプロジェクト、プロジェクトのコンテキスト、 コメントの詳細、ジョブの進行状況を公開します。正確なリソーステンプレートは resources/templates/list で確認してください。

プロンプト triage_feedback、release_report、investigate_comment は、認可されたプロジェクトのコンテキストを読み込み、情報源に基づくワークフローを提供します。 プロンプトを選択しただけで書き込みが行われることはありません。

オプションの MCP Apps リソース ui://simplecommenter/feedback.html は、互換性のあるホスト内で検索とページ分割を提供します。ホストの MCP ブリッジを使用し、外部スクリプトやフォントは読み込まず、読み取り操作のみを行います。インタラクティブビューに対応していないクライアントにも、同じフィードバックがテキストおよび構造化データで提供されます。

サーバーの埋め込み

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);

ホストされるリクエストごとに、リクエストスコープの認証済みクライアントを使ってサーバーを作成してください。ファクトリーがユーザーのホームディレクトリやローカルトークンの設定を読み取ることはありません。認可は authorizedOperations によって引き続き適用される必要があります。 ツールのアノテーションやデフォルトのプロジェクト選択では、アクセス制御は適用されません。 実装は公式 MCP SDK 1.30.0 に固定されています。

一般的なワークフロー

AI エージェントに次のように依頼してください。

"Simple Commenter で未対応のフィードバックを確認し、問題を修正してください"

エージェントは次の操作を行います。

1. list_projects を呼び出してプロジェクトを見つけます
2. status=todo を指定して list_comments を呼び出し、未対応の問題を取得します
3. 各項目に対して get_comment を呼び出し、要素、スクリーンショット、ページ URL を確認します
4. 作業中のコメントを in_progress にします
5. コードを修正します
6. 修正内容を返信します
7. done にします

CLI コマンド

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 と logout は、引き続き init と reset のエイリアスとして使用できます。

グローバルにインストールされていない場合は、代わりに npx @simple-commenter/mcp-server を先頭に付けてください。

デフォルトのプロジェクトを変更する

別のプロジェクトに切り替えるには、もう一度 init を実行してください。

simple-commenter-mcp init

セットアップウィザードが最初から実行され、新しいデフォルトプロジェクトと設定を選択できます。

まっさらな状態から始めるには、まずリセットしてください。

simple-commenter-mcp reset
simple-commenter-mcp init

reset は保存済みの設定と .mcp.json を削除するため、最初からやり直せます。

設定

.mcp.json（init によって自動作成）

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

環境変数（CI／Docker）

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

認証の優先順位

サーバーは次の順序で認証情報を確認します。

1. --token <token> CLI フラグ
2. SIMPLE_COMMENTER_API_TOKEN 環境変数
3. init コマンドで作成された ~/.simple-commenter/config.json

トラブルシューティング

doctor を実行して、よくある問題を診断します。

simple-commenter-mcp doctor

よくある問題：

確認項目	解決方法
設定ファイルが見つからない	simple-commenter-mcp init を実行します
認証トークンがない	init を実行するか、SIMPLE_COMMENTER_API_TOKEN を設定します
API 接続に失敗した	インターネット接続を確認し、--api-url で API URL を確認します
デフォルトプロジェクトが設定されていない	init を実行してプロジェクトを選択します
.mcp.json が見つからない	プロジェクトのルート（package.json または .git がある場所）から init を実行します
.mcp.json が simple-commenter を参照していない	reset を実行してから init を実行し、再作成します

セキュリティ

• 認証情報は chmod 600（所有者のみアクセス可能）で ~/.simple-commenter/config.json に保存されます
• ファイルのアクセス権限が広すぎる場合、サーバーが警告します
• 共有マシンでは、設定ファイルの代わりに環境変数を使用してください
• .simple-commenter/ を .gitignore に追加してください
• API トークンをバージョン管理に絶対にコミットしないでください。CI/CD パイプラインでは環境変数を使用してください。

対応する AI ツール

MCP サーバーは、Model Context Protocol に対応するあらゆるツールで動作します。

• Claude Code — Anthropic の CLI コーディングエージェント
• Cursor — AI 搭載コードエディター
• MCP 対応の任意のエージェント — このプロトコルはオープンで、利用が広がっています

Codex プラグインとしてインストールする

このリポジトリは Codex プラグインとしてもパッケージ化されているため、サーバーを手動で設定する代わりに、一式をまとめてインストールできます。このプラグインには、ホスト型 MCP 接続と fix-feedback スキルが含まれており、未対応のフィードバックから修正の適用まで、一連の作業を実行します。

パス	目的
.codex-plugin/plugin.json	プラグインのマニフェストとマーケットプレイス掲載用メタデータ
.mcp.json	Streamable HTTP によるホスト型サーバー接続。初回使用時はブラウザーで OAuth を実行
skills/fix-feedback/	未対応のフィードバックをトリアージして修正する、同梱のスキル
assets/	プラグイン掲載で使用するアイコンとロゴ

プラグインマーケットプレイスまたはローカルインストールの対象として simple-commenter/mcp-server を指定してインストールします。ホスト型の接続方法では npm のインストールは不要です。 ローカル stdio のみをサポートするクライアントでも、上記の init フローを使用できます。

開発

npm install
npm test

リリースとディレクトリへの掲載

server.json は公式 MCP Registry 向けのドラフトで、npm/stdio と ホスト型 Streamable HTTP の接続方法の両方を記載しています。まだ提出されておらず、 Simple Commenter が掲載済みであることを意味するものではありません。リリース前に、次の作業を行ってください。

1. 公開ドメインにホスト型接続方法と OAuth ディスカバリーをデプロイします。MCP は デフォルトで有効です。使用するには、既存の MCP_ENABLED=false の上書きを削除します。
2. 想定するクライアントで、新規サインイン、読み取り専用および選択したプロジェクトへの権限付与、書き込み、 権限の取り消し、トークンの更新、エクスポート、アップロードを検証します。
3. npm test と npm pack --dry-run を実行し、パッケージのバージョン、マニフェストの バージョン、npm パッケージのエントリー、mcpName の整合性を保ちます。
4. simple-commenter の GitHub 名前空間と npm パッケージの所有権を確認します。 公式レジストリーガイドで定められているとおり、 レジストリーのメタデータを提出する前に npm パッケージを公開します。
5. これらの確認に合格した場合にのみ、ドラフトリリースのマーカーを削除し、マニフェスト全体を確認して、 npm とレジストリーへの公開を明示的に承認します。

レジストリーへの提出は、独立したリリース作業です。このパッケージのテストと ビルドによって、自動的に公開、登録、デプロイされることはありません。