Simple Commenter

Simple Commenter MCP 服务

MCP 服务，可让 AI 客户端读取、搜索、导出和管理来自 Simple Commenter 的网站和资源反馈。相同的工具目录同时支持本地 npm/stdio 连接和托管 HTTPS 适配器。

托管连接

托管路由为 https://www.simplecommenter.com/api/mcp。它使用浏览器 OAuth，通过项目授权和独立的读取、写入及设置权限范围进行访问。可直接在项目侧边栏中打开 MCP，查看连接状态并进行设置。应用部署后，托管 MCP 默认启用；也可以通过 MCP_ENABLED=false 将其禁用。托管应用的更改仍需部署并通过发布验证；仅构建此软件包并不会部署这些更改。

支持远程 MCP 的客户端无需安装此软件包即可使用托管路由。本地客户端仍可使用下方的 npm 设置。各客户端对交互式视图和文件上传的支持各不相同；每个工具都会返回文本和结构化数据。

先决条件

使用 MCP 服务前，你需要拥有 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	列出一个项目中的网站或资源反馈，支持筛选和分页
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	下载完整的筛选后 CSV，其中包含附件链接和会过期的 URL
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：会渲染 **bold**、`code` 和以 - 开头的行（项目符号）；其他内容均不会渲染。reply_to_comment 和 create_comment 可以使用这些标记。

create_comment 接受 page 路径（例如 /pricing）和 text。若要将评论固定到 页面上的特定元素，请传入 anchor_selector（CSS 选择器——首选）或 anchor_text（元素完整且精确的可见文本）， 并同时传入 anchor_tag。如果不指定锚点，评论将作为页面级评论：它会显示在控制面板和小组件的反馈列表中，只是不固定在页面上。 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。

对于长时间运行的任务，请使用 start_task，并设置 operation: "export_comments" 或 "feedback_report"、 筛选条件 arguments 和 idempotency_key。按返回的间隔轮询 get_task。 任务是通过常规工具访问的持久服务记录；此服务不声明支持实验性的 MCP 协议任务功能。

安全写入和附件

创建新项目/成员、批量更新和创建任务时，都必须提供 idempotency_key。 重试时请使用相同的键和完全相同的参数。原有的创建/回复/更新工具接受密钥，但旧版 客户端无需提供密钥。如果不带密钥的写入超时，请在重试前检查数据。

对于回复附件，请使用项目、文件名、MIME 类型和准确的字节大小调用 prepare_attachment_upload。 使用其必需的请求头，通过 HTTP PUT 将文件字节上传到返回的签名 URL，然后向 reply_to_comment 传递 attachments: [{ "upload_id": "returned-id" }]。服务会验证所有权和上传完成状态。客户端必须能够上传文件字节；此工具不会导入远程 URL，也不会自行访问本地文件。

资源、工作流提示词和交互视图

资源通过 simplecommenter:// URI 提供当前连接、已授权项目、项目上下文、 评论详情和任务进度。通过 resources/templates/list 查找确切的资源模板。

提示词 triage_feedback、release_report 和 investigate_comment 会加载已授权的项目上下文，并提供基于来源的工作流。仅仅选择提示词不会执行写入操作。

可选的 MCP Apps 资源 ui://simplecommenter/feedback.html 可在兼容的宿主中提供搜索和分页功能。它使用宿主的 MCP bridge，不加载外部脚本或字体，并且只执行读取操作。没有交互视图的客户端会收到相同的反馈文本和结构化数据。

嵌入服务

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 Agent：

“检查 Simple Commenter 中未解决的反馈并修复问题”

Agent 将会：

1. 调用 list_projects 查找你的项目
2. 调用 list_comments 并设置 status=todo，获取未解决的问题
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. ~/.simple-commenter/config.json（由 init 命令创建）

故障排除

运行 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 重新创建

安全性

• 凭据存储在 ~/.simple-commenter/config.json 中，并设置 chmod 600（仅所有者可访问）
• 如果文件权限过于宽松，服务会发出警告
• 对于共享机器，请使用环境变量，而不是配置文件
• 将 .simple-commenter/ 添加到 .gitignore
• 切勿将 API 令牌提交到版本控制中。在 CI/CD 管道中使用环境变量。

支持的 AI 工具

此 MCP 服务适用于所有支持模型上下文协议的工具：

• Claude Code — Anthropic 的 CLI 编码 Agent
• Cursor — AI 驱动的代码编辑器
• 任何兼容 MCP 的 Agent — 该协议开放且不断发展

安装为 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 注册表的草案，包含 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 和注册表。

提交到注册表是单独的发布操作。此软件包的测试和构建绝不会自动发布、注册或部署它。