# 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` | 已实现 | 识别前端框架、包管理器、路由、模块目录和关键配置文件。 |

所有工具统一返回：

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

## 技术栈

- TypeScript
- MCP TypeScript SDK
- `zod/v3`
- stdio transport
- Vitest

## 快速开始

安装依赖：

```powershell
npm install
```

开发模式启动 MCP Server：

```powershell
npm run dev
```

构建生产版本：

```powershell
npm run build
```

启动构建后的 server：

```powershell
npm run start
```

运行类型检查：

```powershell
npm run typecheck
```

运行测试：

```powershell
npm run test
```

只运行 tool 函数级测试：

```powershell
npm run test:unit
```

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

```powershell
npm run test:integration
```

## MCP Client 配置示例

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

示例配置：

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

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

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

## Tool: check_i18n_issues

### 输入参数

```ts
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/**"]`

### 输出结构

```ts
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 示例

忽略整个文件：

```tsx
/* i18n-ignore-file */

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

忽略单行或下一行：

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

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

## Tool: generate_api_types

### 输入参数

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

默认值：

- `outputDir`：`src/generated/api`
- `clientStyle`：`fetch`
- `generateHooks`：`false`

### 输出结构

```ts
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

### 输入参数

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

默认值：

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

### 输出结构

```ts
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`

输入：

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

预期结果摘要：

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

结构化结果示例：

```json
{
  "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`

输入：

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

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

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

Tool：`check_i18n_issues`

输入：

```json
{
  "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`

输入：

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

预期结果摘要：

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

生成文件：

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

### 示例 5：扫描项目结构

Tool：`get_project_structure`

输入：

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

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

## 项目结构

```txt
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](docs/technical-design.md)。