frontend-dev-mcp

frontend-dev-mcp 是一个面向前端研发场景的 MCP Server，目标是把项目结构理解、OpenAPI 类型生成、i18n 工程治理等能力封装成标准化 AI Tools，帮助 AI 助手更快理解前端仓库，并辅助开发者处理重复性工程任务。

当前能力

Tool	状态	说明
check_i18n_issues	已实现	基于 TypeScript AST 扫描 locale JSON 和源码，检查缺失 key、未使用 key、JSX 硬编码中文文案。
generate_api_types	已实现	读取 OpenAPI JSON/YAML，按 tag 过滤 operations，生成 TypeScript types 和 fetch/axios client。
get_project_structure	已实现	识别前端框架、包管理器、路由、模块目录和关键配置文件。

所有工具统一返回：

{
  content: [{ type: "text", text: result.summary }],
  structuredContent: result
}

技术栈

• TypeScript
• MCP TypeScript SDK
• zod/v3
• stdio transport
• Vitest

快速开始

安装依赖：

npm install

开发模式启动 MCP Server：

npm run dev

构建生产版本：

npm run build

启动构建后的 server：

npm run start

运行类型检查：

npm run typecheck

运行测试：

npm run test

只运行 tool 函数级测试：

npm run test:unit

构建后运行 MCP stdio 集成测试：

npm run test:integration

MCP Client 配置示例

构建后可以将 server 作为 stdio MCP server 接入支持 MCP 的客户端。

示例配置：

{
  "mcpServers": {
    "frontend-dev-mcp": {
      "command": "node",
      "args": [
        "C:/Users/wangqi/Downloads/frontend-dev-mcp/dist/index.js"
      ]
    }
  }
}

开发阶段也可以使用 tsx 直接运行源码：

{
  "mcpServers": {
    "frontend-dev-mcp": {
      "command": "npx",
      "args": [
        "tsx",
        "C:/Users/wangqi/Downloads/frontend-dev-mcp/src/index.ts"
      ]
    }
  }
}

Tool: check_i18n_issues

输入参数

type CheckI18nIssuesInput = {
  rootDir?: string;
  localeDir?: string;
  defaultLocale?: string;
  checkHardcodedText?: boolean;
  checkMissingKeys?: boolean;
  checkUnusedKeys?: boolean;
  include?: string[];
  exclude?: string[];
};

默认值：

• rootDir：当前工作目录
• localeDir：src/locales
• defaultLocale：en
• checkHardcodedText：true
• checkMissingKeys：true
• checkUnusedKeys：true
• include：["src/**/*.{ts,tsx,js,jsx}"]
• exclude：["**/*.test.*", "**/*.spec.*", "**/node_modules/**", "**/dist/**"]

输出结构

type CheckI18nIssuesOutput = {
  localeDir: string;
  locales: string[];
  missingKeys: Array<{
    locale: string;
    key: string;
    basedOn: string;
  }>;
  hardcodedTexts: Array<{
    file: string;
    text: string;
    line?: number;
  }>;
  unusedKeys: Array<{
    locale: string;
    key: string;
  }>;
  summary: string;
};

支持的扫描能力

• 读取 localeDir 下的 .json locale 文件。
• 将嵌套 locale 对象展开为点号路径，例如 profile.title。
• 识别源码中的 t("key")。
• 识别源码中的 const key = "profile.title"; t(key)。
• 识别源码中的 intl.formatMessage({ id: "key" })。
• 识别 JSX 中的 <Trans i18nKey="key" />。
• 以 defaultLocale 为基准检查其他语言缺失的 key。
• 检查 locale 中存在但源码未引用的 key。
• 检查 JSX 文本节点、字符串表达式和可见属性中的中文硬编码文案，例如 title、placeholder、alt、label。
• 支持 ignore 注释：
  • 文件级：/* i18n-ignore-file */ 或 // i18n-ignore-file
  • 行级：// i18n-ignore 或 {/* i18n-ignore */}，忽略当前行和下一行的 key 使用与硬编码文案扫描。

Ignore 示例

忽略整个文件：

/* i18n-ignore-file */

export function DebugPanel() {
  return <button type="button">调试按钮</button>;
}

忽略单行或下一行：

// i18n-ignore
const title = t("debug.title");

{/* i18n-ignore */}
<button type="button" title="临时按钮">临时保存</button>

Tool: generate_api_types

输入参数

type GenerateApiTypesInput = {
  source: string;
  outputDir?: string;
  clientStyle?: "fetch" | "axios";
  generateHooks?: boolean;
  includeTags?: string[];
  excludeTags?: string[];
};

默认值：

• outputDir：src/generated/api
• clientStyle：fetch
• generateHooks：false

输出结构

type GenerateApiTypesOutput = {
  source: string;
  outputDir: string;
  files: Array<{
    path: string;
    kind: "types" | "client" | "hooks";
  }>;
  operationsCount: number;
  schemaCount: number;
  summary: string;
};

支持的生成能力

• 读取本地或 HTTP/HTTPS OpenAPI JSON/YAML。
• 读取 components.schemas 并生成 types.ts。
• 读取 paths operations 并生成 client.ts。
• 生成 path/query/request body 参数类型。
• 在 client 中接入 path 参数替换、query 参数和 JSON request body。
• 支持 fetch 和 axios 两种 client 风格。
• 支持 includeTags / excludeTags 过滤 operation。
• 支持 generateHooks = true 时生成基础 React Query hooks 文件。

当前限制：

• 复杂 OpenAPI schema 组合能力有限，例如 oneOf、anyOf、allOf 暂未展开。
• 生成的 hooks 需要业务项目自行安装 @tanstack/react-query。

Tool: get_project_structure

输入参数

type GetProjectStructureInput = {
  rootDir?: string;
  includeRoutes?: boolean;
  includeModules?: boolean;
  includeConfigs?: boolean;
  maxDepth?: number;
};

默认值：

• rootDir：当前工作目录
• includeRoutes：true
• includeModules：true
• includeConfigs：true
• maxDepth：4

输出结构

type GetProjectStructureOutput = {
  rootDir: string;
  framework: "react" | "nextjs" | "vite-react" | "unknown";
  packageManager: "npm" | "pnpm" | "yarn" | "unknown";
  routes?: Array<{
    path: string;
    file: string;
    kind: "page" | "layout" | "api" | "unknown";
  }>;
  modules?: Array<{
    name: string;
    path: string;
    role: "pages" | "components" | "services" | "hooks" | "store" | "i18n" | "unknown";
  }>;
  configFiles?: Array<{
    name: string;
    path: string;
  }>;
  summary: string;
};

支持的扫描能力

• 识别 nextjs、vite-react、react、unknown。
• 识别 pnpm、npm、yarn。
• 扫描 Next.js App Router：app/**/page.tsx、src/app/**/page.tsx。
• 扫描 Next.js Pages Router：pages/**/*.tsx、src/pages/**/*.tsx。
• 扫描 React/Vite pages 目录：src/pages/**/*.tsx。
• 识别常见模块目录：components、services、hooks、store、locales、i18n。
• 识别关键配置文件：package.json、vite.config.*、next.config.*、tsconfig.json、ESLint、Prettier、Tailwind 配置。

使用示例

示例 1：检查测试 fixture 的 i18n 问题

Tool：check_i18n_issues

输入：

{
  "rootDir": "tests/fixtures/i18n-missing-keys",
  "localeDir": "src/locales",
  "defaultLocale": "en"
}

预期结果摘要：

检测到 2 个语言资源：en, zh-CN；发现 2 个缺失 key；1 处硬编码文案；3 个未使用 key。

结构化结果示例：

{
  "localeDir": "src/locales",
  "locales": ["en", "zh-CN"],
  "missingKeys": [
    {
      "locale": "zh-CN",
      "key": "common.cancel",
      "basedOn": "en"
    },
    {
      "locale": "zh-CN",
      "key": "profile.title",
      "basedOn": "en"
    }
  ],
  "hardcodedTexts": [
    {
      "file": "src/App.tsx",
      "text": "保存",
      "line": 7
    }
  ],
  "unusedKeys": [
    {
      "locale": "en",
      "key": "common.cancel"
    },
    {
      "locale": "en",
      "key": "common.submit"
    },
    {
      "locale": "zh-CN",
      "key": "common.submit"
    }
  ]
}

示例 2：只检查缺失 key

Tool：check_i18n_issues

输入：

{
  "rootDir": "tests/fixtures/i18n-missing-keys",
  "localeDir": "src/locales",
  "defaultLocale": "en",
  "checkMissingKeys": true,
  "checkUnusedKeys": false,
  "checkHardcodedText": false
}

适合在只关心多语言资源完整性的 CI 检查中使用。

示例 3：限制源码扫描范围

Tool：check_i18n_issues

输入：

{
  "rootDir": "tests/fixtures/i18n-missing-keys",
  "localeDir": "src/locales",
  "include": ["src/**/*.{ts,tsx}"],
  "exclude": [
    "**/*.test.*",
    "**/*.spec.*",
    "**/node_modules/**",
    "**/dist/**"
  ]
}

适合在实际业务仓库中排除测试文件、构建产物和依赖目录，降低误报。

示例 4：生成 API types 和 client

Tool：generate_api_types

输入：

{
  "source": "tests/fixtures/openapi-basic/openapi.json",
  "outputDir": "src/generated/api",
  "clientStyle": "fetch",
  "generateHooks": false,
  "includeTags": ["user"]
}

预期结果摘要：

从 tests/fixtures/openapi-basic/openapi.json 生成 1 个 schema、1 个 operation，输出 2 个文件到 src/generated/api。

生成文件：

src/generated/api/
  types.ts
  client.ts

示例 5：扫描项目结构

Tool：get_project_structure

输入：

{
  "rootDir": "tests/fixtures/vite-react-basic",
  "includeRoutes": true,
  "includeModules": true,
  "includeConfigs": true,
  "maxDepth": 4
}

预期结果会返回框架、包管理器、路由、模块目录、关键配置文件和 summary。

项目结构

frontend-dev-mcp/
  docs/
    technical-design.md
  src/
    index.ts
    tools/
      checkI18nIssues.ts
      generateApiTypes.ts
      getProjectStructure.ts
  tests/
    fixtures/
      i18n-missing-keys/
      next-app-router/
      openapi-basic/
      vite-react-basic/
    checkI18nIssues.test.ts
    generateApiTypes.test.ts
    getProjectStructure.test.ts
  package.json
  tsconfig.json
  vitest.config.ts

测试 Fixtures

当前测试 fixture 覆盖：

• i18n-missing-keys：用于验证缺失 key、未使用 key 和硬编码中文。
• openapi-basic：用于后续 OpenAPI codegen 测试。
• vite-react-basic：用于后续 Vite React 项目结构扫描。
• next-app-router：用于后续 Next.js App Router 项目结构扫描。

测试分为两层：

• 函数级集成测试：直接调用 src/tools/* 中的 tool handler，验证业务逻辑和结构化输出。
• MCP stdio 集成测试：启动构建后的 dist/index.js，通过 MCP SDK client 调用真实 tool，验证 server 注册、transport 和返回格式。

开发路线

1. check_i18n_issues：已完成 MVP。
2. generate_api_types：已完成 JSON/YAML、tag 过滤、基础参数和请求体生成；后续补复杂 schema 和更完整 hooks。
3. get_project_structure：已完成 MVP；后续补 React Router AST 解析、monorepo workspace 识别和更完整配置扫描。

更完整的设计说明见 docs/technical-design.md。