frontend-dev-mcp

frontend-dev-mcp is an MCP Server designed for frontend development scenarios. Its goal is to encapsulate capabilities such as project structure understanding, OpenAPI type generation, and i18n engineering governance into standardized AI Tools, helping AI assistants understand frontend repositories faster and assisting developers with repetitive engineering tasks.

Current Capabilities

All tools return the following uniformly:

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

Related MCP server: Text-Toolkit

Tech Stack

• TypeScript

• MCP TypeScript SDK

• zod/v3

• stdio transport

• Vitest

Quick Start

Install dependencies:

npm install

Start the MCP Server in development mode:

npm run dev

Build the production version:

npm run build

Start the built server:

npm run start

Run type checking:

npm run typecheck

Run tests:

npm run test

Run only tool function-level tests:

npm run test:unit

Run MCP stdio integration tests after building:

npm run test:integration

MCP Client Configuration Example

After building, you can connect the server as a stdio MCP server to clients that support MCP.

Example configuration:

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

During the development phase, you can also use tsx to run the source code directly:

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

Tool: check_i18n_issues

Input Parameters

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

Default values:

• rootDir: Current working directory

• localeDir: src/locales

• defaultLocale: en

• checkHardcodedText: true

• checkMissingKeys: true

• checkUnusedKeys: true

• include: ["src/**/*.{ts,tsx,js,jsx}"]

• exclude: ["**/*.test.*", "**/*.spec.*", "**/node_modules/**", "**/dist/**"]

Output Structure

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;
};

Supported Scanning Capabilities

• Reads .json locale files under localeDir.

• Flattens nested locale objects into dot-notation paths, e.g., profile.title.

• Identifies t("key") in source code.

• Identifies const key = "profile.title"; t(key) in source code.

• Identifies intl.formatMessage({ id: "key" }) in source code.

• Identifies <Trans i18nKey="key" /> in JSX.

• Checks for missing keys in other languages based on defaultLocale.

• Checks for keys that exist in locale files but are not referenced in the source code.

• Checks for hardcoded Chinese text in JSX text nodes, string expressions, and visible attributes, such as title, placeholder, alt, and label.

• Supports ignore comments:

  • File-level: /* i18n-ignore-file */ or // i18n-ignore-file

  • Line-level: // i18n-ignore or {/* i18n-ignore */}, ignores key usage and hardcoded text scanning for the current and next line.

Ignore Examples

Ignore an entire file:

/* i18n-ignore-file */

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

Ignore a single line or the next line:

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

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

Tool: generate_api_types

Input Parameters

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

Default values:

• outputDir: src/generated/api

• clientStyle: fetch

• generateHooks: false

Output Structure

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

Supported Generation Capabilities

• Reads local or HTTP/HTTPS OpenAPI JSON/YAML.

• Reads components.schemas and generates types.ts.

• Reads paths operations and generates client.ts.

• Generates types for path/query/request body parameters.

• Integrates path parameter replacement, query parameters, and JSON request body in the client.

• Supports both fetch and axios client styles.

• Supports includeTags / excludeTags for operation filtering.

• Supports generating basic React Query hooks files when generateHooks = true.

Current limitations:

• Limited support for complex OpenAPI schema combinations, e.g., oneOf, anyOf, allOf are not yet expanded.

• Generated hooks require the business project to install @tanstack/react-query independently.

Tool: get_project_structure

Input Parameters

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

Default values:

• rootDir: Current working directory

• includeRoutes: true

• includeModules: true

• includeConfigs: true

• maxDepth: 4

Output Structure

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;
};

Supported Scanning Capabilities

• Identifies nextjs, vite-react, react, unknown.

• Identifies pnpm, npm, yarn.

• Scans Next.js App Router: app/**/page.tsx, src/app/**/page.tsx.

• Scans Next.js Pages Router: pages/**/*.tsx, src/pages/**/*.tsx.

• Scans React/Vite pages directory: src/pages/**/*.tsx.

• Identifies common module directories: components, services, hooks, store, locales, i18n.

• Identifies key configuration files: package.json, vite.config.*, next.config.*, tsconfig.json, ESLint, Prettier, Tailwind configurations.

Usage Examples

Example 1: Checking i18n issues in test fixtures

Tool: check_i18n_issues

Input:

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

Expected result summary:

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

Structured result example:

{
  "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"
    }
  ]
}

Example 2: Checking only for missing keys

Tool: check_i18n_issues

Input:

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

Suitable for use in CI checks where only the integrity of multilingual resources is a concern.

Example 3: Limiting the source code scanning scope

Tool: check_i18n_issues

Input:

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

Suitable for excluding test files, build artifacts, and dependency directories in actual business repositories to reduce false positives.

Example 4: Generating API types and client

Tool: generate_api_types

Input:

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

Expected result summary:

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

Generated files:

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

Example 5: Scanning project structure

Tool: get_project_structure

Input:

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

Expected results will return the framework, package manager, routing, module directories, key configuration files, and a summary.

Project Structure

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

Test Fixtures

Current test fixtures cover:

• i18n-missing-keys: Used to verify missing keys, unused keys, and hardcoded Chinese.

• openapi-basic: Used for subsequent OpenAPI codegen testing.

• vite-react-basic: Used for subsequent Vite React project structure scanning.

• next-app-router: Used for subsequent Next.js App Router project structure scanning.

Tests are divided into two layers:

• Function-level integration tests: Directly call tool handlers in src/tools/* to verify business logic and structured output.

• MCP stdio integration tests: Start the built dist/index.js, call real tools via the MCP SDK client to verify server registration, transport, and return format.

Development Roadmap

1. check_i18n_issues: MVP completed.

2. generate_api_types: JSON/YAML, tag filtering, basic parameter and request body generation completed; complex schemas and more complete hooks to be added later.

3. get_project_structure: MVP completed; React Router AST parsing, monorepo workspace identification, and more complete configuration scanning to be added later.

For a more complete design description, see docs/technical-design.md.