GenClass

@genclass/mcp

让你的编码 Agent 看见竞态、重放它，并验证修复。

适用于 Claude Code 和其他编码 Agent 的 MCP 服务。它会连接到你在本机运行的应用页面 （通过 @genclass/runtime 的 Agent 链接），并向 Agent 提供：

• 按顺序记录发生的事情。 每次点击、请求和响应，响应送达的顺序，每个响应写入应用状态的内容，以及导致这些错误的点击和请求所引发的未捕获错误。
• 不会抛出异常的 Bug。 覆盖较新数据的响应（典型的过期搜索结果或编辑内容丢失）、两次点击提交了同一订单，以及设备端模型自身的检测结果。
• 在用户发现前找到竞态。 genclass_explore 会重新执行你的步骤，让网络以不同顺序（也可以按你指定的速度）响应，并报告与响应按序返回时相比，哪些结果发生了变化。
• 验证依据。 genclass_replay 会再次按导致 Bug 的确切顺序传送响应：修复前（复现）和修复后（未复现）；genclass_explain 会编写一个在 Bug 存在时会失败的 Playwright 测试。

所有内容都保留在你的机器上。无需依赖项。该服务免费。对于希望由服务代为运行整个流程的开发者，GenClass 在 Enterprise 方案中会将其作为服务运行：MCP 服务、采集器和仪表板由 GenClass 托管或部署在你的网络内（genclass.dev/enterprise）。

安装

选择你的客户端。每个代码块都固定了此版本，因此客户端启动的正是此版本； npx -y @genclass/[email protected] config <client> 会输出相同的内容，而 genclass_setup 会输出其运行所在客户端对应的代码块。

Claude Code

作为插件安装（包含服务、一个会在每次提示词中加入新发现的提示词钩子，以及一个告诉 Claude 何时使用它的技能）：

/plugin marketplace add genclass-dev/GenClass-lib
/plugin install genclass@genclass

或者仅安装服务（--scope project 会为项目中的所有人写入 .mcp.json；--scope user 则适用于你的所有项目）：

claude mcp add --scope project genclass -- npx -y @genclass/[email protected]
# or: npx -y @genclass/[email protected] init --hook   (.mcp.json, plus the prompt hook in .claude/settings.json)

Claude Desktop

设置、开发者、编辑配置（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "genclass": {
      "command": "npx",
      "args": [
        "-y",
        "@genclass/[email protected]"
      ]
    }
  }
}

Cursor

或 cursor://anysphere.cursor-deeplink/mcp/install?name=genclass&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBnZW5jbGFzcy9tY3BAMC4yLjAiXX0%3D

或者使用项目中的 .cursor/mcp.json（适用于所有项目的配置文件为 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "genclass": {
      "command": "npx",
      "args": [
        "-y",
        "@genclass/[email protected]"
      ]
    }
  }
}

VS Code

或在终端中运行：

code --add-mcp '{"name":"genclass","command":"npx","args":["-y","@genclass/[email protected]"]}'

或者在工作区根目录下使用 .mcp.json（可移植格式；.vscode/mcp.json 在 servers 下使用相同的条目）：

{
  "mcpServers": {
    "genclass": {
      "command": "npx",
      "args": [
        "-y",
        "@genclass/[email protected]"
      ]
    }
  }
}

Codex CLI

codex mcp add genclass -- npx -y @genclass/[email protected]

或者使用 ~/.codex/config.toml（在受信任项目中使用 .codex/config.toml）。首次启动时会下载软件包，因此请设置超过默认 10 秒的等待时间：

[mcp_servers.genclass]
command = "npx"
args = ["-y", "@genclass/[email protected]"]
startup_timeout_sec = 30

Gemini CLI

gemini mcp add genclass npx -- -y @genclass/[email protected]   # -s user: for all projects

或者使用项目中的 .gemini/settings.json（适用于所有项目的配置文件为 ~/.gemini/settings.json）：

{
  "mcpServers": {
    "genclass": {
      "command": "npx",
      "args": [
        "-y",
        "@genclass/[email protected]"
      ]
    }
  }
}

Windsurf（Devin Desktop）

~/.codeium/windsurf/mcp_config.json（Windsurf）、~/.config/devin/mcp_config.json（Devin Desktop 的 Cascade Agent；Windows 上为 %APPDATA%\devin\mcp_config.json）：

{
  "mcpServers": {
    "genclass": {
      "command": "npx",
      "args": [
        "-y",
        "@genclass/[email protected]"
      ]
    }
  }
}

Devin CLI 和 Devin Desktop 的 Devin Local Agent：

devin mcp add -s user genclass -- npx -y @genclass/[email protected]

Cline

cline mcp add genclass --yes -- npx -y @genclass/[email protected]

或者依次选择 MCP Servers、Configure、Configure MCP Servers（配置文件为 ~/.cline/data/settings/cline_mcp_settings.json）：

{
  "mcpServers": {
    "genclass": {
      "command": "npx",
      "args": [
        "-y",
        "@genclass/[email protected]"
      ]
    }
  }
}

Goose

goose://extension?cmd=npx&arg=-y&arg=%40genclass%2Fmcp%400.2.0&id=genclass&name=genclass&description=Find%20race%20conditions%20by%20reordering%20responses%2C%20replay%20one%2C%20prove%20the%20fix（打开即可安装），或使用 goose configure（Add Extension、Command-line Extension，命令为 npx -y @genclass/[email protected]），或编辑 ~/.config/goose/config.yaml：

extensions:
  genclass:
    type: stdio
    name: genclass
    enabled: true
    cmd: npx
    args: ["-y", "@genclass/[email protected]"]
    env_keys: []
    envs: {}
    timeout: 300

Zed

编辑 ~/.config/zed/settings.json（项目中的 .zed/settings.json），或依次选择 Settings、AI、MCP Servers、Add Server：

{
  "context_servers": {
    "genclass": {
      "command": "npx",
      "args": [
        "-y",
        "@genclass/[email protected]"
      ]
    }
  }
}

JetBrains IDEs

AI Assistant：依次选择 Settings、Tools、AI Assistant、Model Context Protocol (MCP)、Add，然后粘贴此 JSON。Junie：项目中的 .junie/mcp/mcp.json（所有项目使用 ~/.junie/mcp/mcp.json），粘贴相同的 JSON：

{
  "mcpServers": {
    "genclass": {
      "command": "npx",
      "args": [
        "-y",
        "@genclass/[email protected]"
      ]
    }
  }
}

OpenCode

编辑项目中的 opencode.json（所有项目使用 ~/.config/opencode/opencode.json），或运行 opencode mcp add：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "genclass": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@genclass/[email protected]"
      ],
      "enabled": true
    }
  }
}

其他 MCP 客户端：stdio 服务，命令为 npx，参数为 -y @genclass/[email protected]，无需环境变量。

然后连接应用的开发构建版本（一次即可）。Agent 链接需要最新的运行时版本 @genclass/runtime 0.3.0-beta.1 或更高版本：运行 npm install @genclass/runtime@beta（直接运行 npm install @genclass/runtime 会安装 npm 的 latest，即较旧的 0.2.x 版本，该版本没有 Agent 入口）：

import { GenClass } from "@genclass/runtime";
import { connectAgent } from "@genclass/runtime/agent";

const rt = GenClass.init();
if (import.meta.env.DEV) connectAgent(rt); // Next.js: process.env.NODE_ENV === "development"

加载开发服务器上的页面，并让 Agent 查询 genclass_status。Agent 也可以查询 genclass_setup，它会读取你的 package.json 并显示适用于你所用框架的配置行。

Agent 会如何使用它

you:    the search results are sometimes for an older query
agent:  genclass_findings → f1 [stale-write] /search: the response to GET /api/search "?q=reac"
        overwrote "search.results" after a newer GET /api/search had already written it
        genclass_explain f1 → steps, delivery order, a replay, a regression test
        genclass_replay arm f1 → (loads the page, types) → result: REPRODUCED
        (fixes the handler to keep only the latest answer, adds the test)
        genclass_replay arm f1 → result: not reproduced
        genclass_explore start {slow_ms: 600} → 8 runs → report: no race

在真实页面上使用无头 Chromium（该软件包的端到端检查）时，explore 在 6 次重新排序的运行中有 5 次发现了该竞态；开发者的快速后端上从未出现过这一问题。生成的测试在存在 bug 的页面上失败，在修复后的页面上通过；而在修复后的页面上运行 explore 则未报告任何问题。详情见：docs/runtime/AGENT.md。

工具

工具
genclass_status	已连接的页面、发现项数量、explore 和 replay 状态
genclass_findings	按优先级排序并去重的发现项：竞态、过时写入、错误、重复请求、模型检测、视觉检查
genclass_explain	按因果顺序展示某项发现、记录的步骤、重放结果以及 Playwright 回归测试
genclass_explore	start / report / stop：查找依赖响应顺序的内容
genclass_replay	arm / result：精确复现某项发现
genclass_analytics	按端点统计延迟、错误率和请求数、学习到的关系与流程；生产环境数据来自你的 GenClass 控制面板
genclass_setup	适用于你所用框架的配置行，以及运行该框架的客户端配置行
genclass_scan	{url, phone?, hosted?}：使用无头 Chromium 的 23 项视觉检查审计任意页面（开发服务器或你并不拥有的网站）：给出评分，以及每个问题对应的元素、选择器和建议的 CSS 修复方案，并提供 JSON 报告。运行 npx @genclass/runtime@beta scan --json --local（或项目自己的运行时）；需要 Playwright 的 Chromium（npx playwright install chromium），也可以对 genclass.dev 页面检查设置 hosted: true（仅限公开页面）
genclass_clear	清除已记录的运行记录和发现项

无需询问即可获取新发现

• Channels（Claude Code 研究预览版）：使用 claude --dangerously-load-development-channels server:genclass 启动 Claude Code，新发现会在发生时直接推送到会话中（notifications/claude/channel）。
• 提示词钩子（Claude Code 插件的一部分）：运行 npx -y @genclass/[email protected] init --hook，将 UserPromptSubmit 钩子添加到 .claude/settings.json；之后每条提示词都会附带自上次以来发生变化的发现项。

环境

变量	默认值
GENCLASS_AGENT_PORT	47357	桥接服务的端口（页面随后需要调用 connectAgent(rt, { url })）
GENCLASS_STATE_DIR	.genclass/agent	发现的问题在不同会话间的持久化位置；设为 none 则仅保存在内存中
GENCLASS_DASHBOARD		你的仪表板私有链接，供 genclass_analytics 使用 production 时读取（sample 会读取公开示例）
GENCLASS_REPORT		设为 on（并设置 GENCLASS_DASHBOARD），或设为仪表板链接或密钥：将此服务的循环日志镜像到该仪表板的“闭环开发”视图（每个发现的问题、每次读取其证据、每次启动的重放及其判定结果、每个编写的回归测试、每份探索报告、每次清除），以图示展示每个问题的进展（发现、复现、验证修复、关闭或重新处理）、统计数量并列出日志。仅包括 ID、类型、页面路径、判定结果、数量和时间，绝不包括页面文本；默认关闭，只有设置后才启用（AGENT.md 第 4.5 节）
GENCLASS_AGENT_ORIGINS		除本机外允许访问的确切页面来源，例如 http://192.168.1.20:5173（页面随后需要调用 connectAgent(rt, { anyHost: true })）
GENCLASS_TOKEN_DIR	~/.genclass	桥接服务存放 API 令牌的位置（权限模式为 0600），供钩子和其他会话使用

安全

桥接服务仅监听 127.0.0.1，并检查 Host 标头。页面只能从你的机器（localhost、127.0.0.1、*.localhost）或你在 GENCLASS_AGENT_ORIGINS 中列出的来源（*.test 或局域网开发主机）与其通信：你访问的公共网站、路由器页面或强制门户都无法植入发现的问题，且页面只能向自己的运行记录添加内容。 Agent API 会拒绝浏览器访问，并且需要只有你的用户才能读取的令牌。页面发送的所有内容都会经过验证、限制大小、剥除不可见字符，并作为引用数据展示给 Agent，绝不会作为指令。除“隐私”部分所述的例外情况外，任何数据都不会离开你的机器。请参阅 AGENT.md 第 6 节。

隐私

此服务不会收集或向 GenClass 或其他任何人发送数据。发现的问题会保留在你的机器上，存放于服务工作目录中的 .genclass/agent/（对于在此处启动服务的客户端，即项目目录；对于不在此处启动服务的客户端，例如 Claude Desktop，请设置 GENCLASS_STATE_DIR），该目录会被服务加入 gitignore；此外也会保存在桥接服务的内存中。桥接服务的令牌存放在 ~/.genclass。唯一会离开机器的请求是 genclass_analytics {source: "production"}；当你将 GENCLASS_DASHBOARD 设为仪表板私有链接时，它会读取你自己的 GenClass 仪表板。genclass_scan 会在本地浏览器中加载 Agent 指定的页面（这是页面本身的流量）；只有设置 hosted: true 时，URL 才会发送到 genclass.dev 进行页面检查；如果项目没有提供带 scan 的 @genclass/runtime，npx 会从 npm 下载它。设置 GENCLASS_REPORT 后（默认关闭），服务还会分批将循环日志镜像到该仪表板：每个发现问题的 ID、类型和页面路径，读取其证据的时间，每次启动的重放及其判定结果，编写回归测试的时间，每份探索报告（比较的页面加载次数、发现的竞态）以及每次清除，以便仪表板的“闭环开发”视图图示展示每个问题的进展（发现、复现、验证修复、关闭或重新处理），并列出 Agent 执行的操作；绝不发送标题、证据行、快照或任何页面文本，发送的任何内容都不会用于决策。你的应用中的运行时有其单独披露的诊断数据（PRIVACY.md），可通过 GenClass.init({ telemetry: false }) 关闭；Agent 链接不属于这些诊断数据。

许可证

Apache-2.0