mcp-react-toolkit

mcp-toolkit

面向 React + TypeScript 开发自动化的 MCP 服务。兼容 Claude Desktop、Cline、Cursor，也可作为普通 CLI 脚本使用——一套协议，零重复。

涵盖 9 个类别的 59 个工具——组件脚手架、代码质量检查、完整的 CRUD 功能工厂、CRA→Vite 迁移等。每个工具都作为独立的 MCP 服务提供，单独构建和测试。

---

为什么要做这个工具包——Token 的账怎么算

有件事没人会在你开始构建 Agent 工作流时告诉你：真正耗费资源的不是模型，而是循环本身。不使用组合工具的 Agent 会把所有事情都慢慢来——读取文件、思考、写入文件、读回文件检查自己的工作，然后重复——而每一轮都会将截至目前的完整对话重新作为输入 Token 发送。等你为一个真实的多文件任务进行到第 20 步时，仅重新发送的上下文每次调用就可能达到 50K+ Token。成本很快就会累积起来，这和你使用哪种模型其实关系不大。

我不是盲目相信这一点——有几个来源用真实数据支持了它。LeanOps 的测量结果显示，Agent 循环在 5 步时消耗的 Token 约为单次直接调用的 3.2 倍，在 50 步时约为 30 倍，而在典型的构建与调试过程中深入运行后会超过 100 倍——因为重新发送的上下文约占总费用的 62%。Vantage 的发现也类似：真实的 Agent 会话输入与输出之比约为 25:1（直接调用更接近 1:1），一个 50 轮的会话通常会达到 100 万输入 Token；同一团队在类似工作中使用非 Agent 方式，每次交互的成本大约低 200 倍。还有一篇近期关于 Agent Token 经济学的 arXiv 论文指出，Agent 任务消耗的 Token 大约是单轮任务的 1000 倍，而且相同任务每次运行的消耗差异最高可达 30 倍——所以这不仅成本高，还难以预测。

这个工具包的组合工具就是为了解决这个问题。workflow-runner 的 schema_to_feature 和 cra-to-vite 并不会在 Agent 现有循环中再增加一次工具调用——它们会将原本需要 7 或 8 轮独立读写与验证的操作，替换为一次进程内调用，运行完整的生成器或迁移流程，并返回最终结果。这就是“将 50 轮循环压缩成 1 次调用”的模式；上文研究显示这种模式能节省 10–100 倍成本。它与仅仅在不变的循环中再添加一个工具完全不同，后者只能节省 20–40%。

为了让结论有据可依，我还运行了一个真实的实测基准，而不是只相信理论——ax-benchmark，包含 6 个任务，由 claude -p 在无头模式下运行，分为三组（仅 Agent、Agent 在循环中增加一次 MCP 工具调用，以及不使用 Agent、直接调用工具）。这是一个有意设置得较保守的基准，因为它只测试在其他部分不变的循环中增加一次工具调用，而不是上文所述更深层的流程压缩：

	仅 Agent	Agent + 一次 MCP 工具调用	直接调用工具
分析任务（审查、无障碍、遗留代码）	基准	成本降低约 41%	完全免费，速度快约 15 倍（适用时）
全部 6 个任务，综合结果	基准	成本降低约 19%	—
新代码（组件、测试）	基准	成本大致持平	不适用于新颖工作

有两点值得提前说明：这里合理的衡量指标是成本，而不是耗时——仅 Agent 组在无头模式下运行，没有 Shell 访问权限，并且在开放式任务中过度探索，导致耗时增加，但实际成本并未因此增加。而对于小型、新颖的单文件工作，工具结构化输出的开销可能抵消它节省的成本——真正的收益体现在重复、机械性的多文件工作中，而这也恰好是上文所述多轮循环开销影响最大的场景。

---

安装

已作为 mcp-react-toolkit 发布到 npm。无需克隆或构建：

npx mcp-react-toolkit --list            # list all 59 tools
npx mcp-react-toolkit legacy-analyzer   # run one as an MCP server (stdio)

将它添加到 Claude Desktop / Cursor / Cline：

// claude_desktop_config.json
{
  "mcpServers": {
    "legacy-analyzer": { "command": "npx", "args": ["-y", "mcp-react-toolkit", "legacy-analyzer"] }
  }
}

将工具名称替换为 npx mcp-react-toolkit --list 中的任意名称。重启客户端后，即可看到该工具。

---

交互式仪表板

大多数 MCP 工具会返回原始 JSON。这些工具除了返回 JSON，还会提供交互式 HTML 仪表板，包含健康评分、可排序的问题分类、浅色／深色模式切换，以及可调用工具包中其他工具的一键修复操作。整个产物自包含，无需服务端，也不会发送外部请求：

运行环境	你会获得
Claude Desktop（MCP Apps）	直接在对话中内嵌渲染（沙盒 iframe）
Claude Code · Cursor · CLI	JSON，以及一个可点击的 file:// 链接，指向同一仪表板
任意浏览器	相同的独立 HTML

分析工具（legacy-analyzer、component-reviewer、dep-auditor 等）会提供审计视图，包含等级、分类卡片和可筛选的问题表格。生成工具（component-factory、code-modernizer 等）会提供结果视图，列出创建／更改的文件、差异和后续操作。由内部 @mcp-showcase/ui-kit 软件包提供支持：无依赖，每份报告约 30 KB。

---

工具

组件开发

工具	功能
component-factory	根据 41 个 shadcn/ui 模板搭建 React 组件，并附带测试和 Storybook
component-reviewer	审计 TypeScript 错误、无障碍问题和测试覆盖率，评级从 A+ 到 F
component-fixer	自动修复损坏的导入、缺失的依赖和内联样式重构
component-improver	为组件扩展变体、完善 Story 和边界情况测试
storybook-generator	自动生成 Storybook Story，包括默认状态、变体、尺寸、回调和 play 函数

代码质量与现代化

工具	功能
typescript-enforcer	扫描 any 类型、不安全的类型断言和缺失的修饰符，共 7 条规则，评分 0–10
accessibility-checker	WCAG 2.1 审计，包括替代文本、标签关联、ARIA 角色和键盘导航
a11y-autofixer	应用安全的无障碍修复（img 替代文本、空白 rel、htmlFor、tabIndex）
quality-pipeline	5 阶段审计（测试 · 类型 · 性能 · 无障碍 · 设计令牌），评级 A–F
review-gate	对生成或更改的代码进行静态 A–F 质量把关
enforce-design-tokens	标记硬编码的颜色／间距／圆角／阴影，建议设计令牌并评级 A–F
render-analyzer	检测不必要的重复渲染、缺失的 memo，以及内联对象／函数
performance-audit	检查内存泄漏、体积较大的导入、未优化的图像和过深的嵌套
bundle-budget-guard	根据每种模式的预算限制压缩后的资源大小，出现回归时让 CI 失败
code-modernizer	基于 AST 将 JS/JSX 转换为 TypeScript，并将 PropTypes 转换为接口
react-compiler-migrator	标记 React 19 Compiler 中多余的 useMemo/useCallback/memo
codemod-runner	通用正则 codemod 引擎，带有具名内置项；默认采用试运行模式
refactor-executor	安全执行重构计划，包括移动／重命名／拆分、更新导入和回滚
redux-state-analyzer	审计 Redux 反模式（选择器、变更操作、RTK Query 迁移提示）
api-contract-differ	比较两个 API 快照，区分破坏性变更与增量变更，并可在 CI 中阻止破坏性变更
i18n-extractor	扫描 JSX 中的硬编码字符串，提取为 i18n 键和消息目录
generate-tests	分析 TS/React 源文件并生成 Vitest 测试套件
test-gap-analyzer	查找未实现的函数、未覆盖的分支和缺失的边界情况
test-data-factory	将 FieldSchema 转换为供测试／Story 使用的类型化 fixture 工厂
fix-failing-tests	运行测试套件，按根因分类失败，并生成针对性修复
legacy-analyzer	面向任意 React/Next.js/Remix 应用的 22 项健康审计，评分 0–100，并提供迁移提示

Monorepo 与基础设施

工具	功能
dep-auditor	检查未使用的依赖、重复版本、循环导入，并分析对打包体积的影响
monorepo-manager	列出工作区、查看依赖关系图、检查健康状况、查找共享依赖
lighthouse-runner	静态 HTML 审计——元标签、无障碍、OG/Twitter 卡片、规范链接、JSON-LD
json-viewer	交互式 HTML JSON 查看器——可折叠、可搜索，支持深色/浅色模式

CRUD 工厂

输入一个 JSON API 示例（或 OpenAPI 架构），即可生成完整的类型化 CRUD 功能。每个生成器都基于共享的 FieldSchema 契约，因此各部分可以组合使用。

工具	功能
infer-fields	JSON 示例 / OpenAPI → 类型化 FieldSchema（类型、外键关系、表格/表单默认值）
zod-schema-generator	FieldSchema → Zod 架构 + 推断出的 TS 类型
api-client-generator	FieldSchema → RTK Query 切片 或 TanStack Query 钩子，并附带缓存标签
form-generator	FieldSchema → React Hook Form + Zod 表单（创建 / 编辑）
table-generator	FieldSchema → TanStack Table（排序 / 筛选 / 分页）
detail-generator	FieldSchema → 类型化详情视图 + 删除操作
crud-composer	将各部分接入路由——React Router 7 或 Next App Router
form-wizard-generator	FieldSchema → 多步骤 RHF+Zod 向导，每步均进行验证
msw-mock-generator	FieldSchema → MSW 处理程序 + 种子数据，让功能可通过模拟 API 运行
workflow-runner	端到端运行整条链路，并由 review-gate 控制——生成文件、日志和 A–F 等级
e2e-generator	FieldSchema → Playwright CRUD 流程规范（创建→编辑→删除 + 无障碍）
playwright-scaffolder	搭建 Playwright 测试框架——配置、夹具、基础 POM、身份验证设置
visual-regression-setup	为路由/故事生成 Playwright toHaveScreenshot 规范——检测 CSS 偏差

CRA → Vite

将 Create React App 项目迁移到 Vite：分析 → 规划 → 搭建 → 迁移 → 验证。

工具	功能
cra-to-vite	编排器——依次运行下面六个工具，一次调用即可生成评级报告
craconfig-analyzer	深入检查 CRA 配置（react-scripts、env、proxy、jest、browserslist、SVG）
dependency-remapper	CRA 依赖 → Vite 迁移计划（包含要移除/添加的依赖及版本，以及未映射项）
env-var-migrator	在源码和 .env 文件中将 REACT_APP_* → import.meta.env.VITE_*
jest-to-vitest-migrator	将 jest.* → vi.*，添加相应导入，并标记需手动检查的情况
vite-project-scaffolder	生成 vite.config.ts、main.tsx、严格模式 tsconfig 和 Vitest 配置块
webpack-config-translator	尽力将 webpack/CRACO 配置转换为 Vite 配置，并列出需手动检查的项目

样板代码

工具	功能
barrel-generator	生成 index.ts 汇总导出文件，重新导出整个文件夹——无需维护会逐渐过时的导出列表
type-from-json	JSON 示例 → 纯 TS 接口（嵌套对象会生成各自的接口）
zustand-store-generator	状态结构 → 类型化 Zustand 存储（设置器、重置、持久化/开发工具）
svg-to-component	原始 SVG → 类型化 React 组件（SVGProps、currentColor）——达到 SVGR 级别
env-config-generator	经过 Zod 验证的类型化环境变量模块（Vite/Next）——缺少或无效变量时快速失败
states-scaffolder	加载/空/错误状态组件 + 数据视图的切换包装器

元工具

工具	功能
mcp-tool-factory	在此软件包中搭建、接入并验证新的 MCP 工具
mcp-tool-improviser	从 7 个维度分析并改进 MCP 工具——提出差异、应用更改、回滚
docs-generator	生成 README（基于 MCP 工具）或 API 参考文档（基于 TS 模块和 JSDoc）

自动化工作流

将工具串联起来，完成常见任务：

工作流	链
代码现代化	legacy-analyzer → code-modernizer → typescript-enforcer → generate-tests
组件质量流水线	component-factory → component-reviewer → accessibility-checker → storybook-generator
渲染性能审计	render-analyzer → performance-audit → quality-pipeline
应用健康检查	legacy-analyzer → component-reviewer → generate-tests
依赖健康检查	dep-auditor [unused → duplicates → bundle-impact] → monorepo-manager
完整 CRUD 功能	workflow-runner（一次调用即可组合整个 CRUD Factory 链）
CRA → Vite 迁移	cra-to-vite（一次调用即可组合整个 CRA→Vite 链）

---

MCP 的工作原理

Claude Desktop / Cline / Cursor
        │  JSON-RPC over stdio
        ▼
   MCP Server (e.g. typescript-enforcer)
        │
        ▼
   Tool handlers (your code)

每个服务都扩展了 tools/shared/ 中的 McpServerBase，负责处理传输、路由和错误格式化。添加一个新工具只需约 50 行代码：

import { McpServerBase } from '@mcp-showcase/shared';

class MyTool extends McpServerBase {
  constructor() {
    super({ name: 'my-tool', version: '1.0.0' });
  }

  protected registerTools(): void {
    this.addTool('do_thing', 'Does a thing', {
      type: 'object',
      properties: { path: { type: 'string', description: 'Target path' } },
      required: ['path'],
    }, async (args) => {
      const { path } = args as { path: string };
      return this.success({ result: `Processed ${path}` });
    });
  }
}

new MyTool().run();

---

从源代码运行（贡献者）

日常使用建议通过 npm（参见安装）。仅在需要修改工具或运行展示 UI 时才克隆仓库：

git clone https://github.com/Nishant-Chaudhary5338/mcp-toolkit.git
cd mcp-toolkit
npm install
npm run build
npm test          # run the full suite across all tools
npm run dev       # server on :3002, client on :5173

按照安装 中的相同方式，将 Claude Desktop 指向本地构建版本，只需将 npx -y mcp-react-toolkit <name> 替换为 node /path/to/mcp-toolkit/tools/<name>/build/index.js。

用作 CLI / 在 CI 中使用

每个工具的 build/index.js 都包含 #!/usr/bin/env node shebang — 将 JSON-RPC 消息通过管道传入其标准输入：

# Health score + migration hints for a full app
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"analyze-legacy-app","arguments":{"path":"/path/to/app"}}}' \
  | node tools/legacy-analyzer/build/index.js

# Review a component — grade A+ to F
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"review","arguments":{"path":"src/components/Button.tsx"}}}' \
  | node tools/component-reviewer/build/index.js

# List a tool's available commands
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node tools/legacy-analyzer/build/index.js

---

测试

每个工具旁边都有 Vitest 测试套件，直接覆盖其核心逻辑 — 无需 MCP 传输。

npm test                              # all tools
npm run test -w tools/legacy-analyzer # single tool

CI 会在每次推送和 PR 时针对 Node 20 和 22 运行。

---

配套软件包

code-graph-indexer — 将任意 TS/React/Next.js 仓库索引为可查询的代码图（文件、组件、函数及其关联关系），并回答结构性问题：谁调用了它、影响范围、死代码、语义搜索。同属一个系列，但为独立软件包。

npx code-graph-indexer ui --root .

---

贡献

请参阅 CONTRIBUTING.md — 了解如何搭建新工具、编写测试和提交 PR。

技术栈

TypeScript strict · Node.js · MCP SDK 1.12 · Vitest · React 19 · Vite · Tailwind CSS · Express

作者

Nishant Chaudhary — 高级前端工程师 · [email protected]

另请参阅：dashcraft · react-present · ai-builder

MIT 许可证