Component Doc MCP

组件文档mcp

分析React组件并自动生成文档、JSDoc注释和Storybook文件的MCP服务器

使用技术：TypeScript、Node.js、模型上下文协议（MCP）\ 核心能力：文件系统处理、利用TypeScript Compiler API解析AST、开发CLI工具

______________________________________________________________________

🎯 项目概述

允许AI助手执行以下操作：

• React组件 分析 和props、类型、文档提取
• 基于组件结构和上下文的JSDoc注释 生成
• 自动包含variant特定故事的Storybook文件 生成
• 大型代码库中的组件 搜索 和导航

实际使用示例：要求“向Button组件添加文档”→分析代码后生成JSDoc建议和Storybook文件

______________________________________________________________________

工具列表

列表_组件

扫描项目中的所有React组件文件并返回列表。

工作原理

1. glob使用在项目根目录中 **/*.{tsx,jsx} 按递归方式搜索阵列中的文件。 node_modules哇 dist不包括。
2. path.basename()将文件名提取到。示例： src/components/Button.tsx → Button
3. 文件名为 index如果是，则使用父目录名称。示例： src/components/Modal/index.tsx → Modal
4. namingConvention 根据设置过滤元件名称。 pascal（例如： Button）和 kebab（例如： user-profile），如果指定了多个规则，只要匹配一个规则，就会通过。
5. Button.tsx哇 Button/index.tsx如果存在，请删除重复数据。

输出示例

Components (3):

- Button
- Card
- user-profile

______________________________________________________________________

分析成分

通过分析特定的组件文件，自动生成包含props、说明和示例的文档。

工作原理

1. glob使用多个图案（Button.tsx, Button/index.tsx 等）搜索元件文件。如果未找到，则返回错误。
2. 用于异步操作 fs/promises使用读取元件文件。
3. 使用TypeScript Compiler API type Props 或 interface Props解析并提取prop定义。同一文件中的类型别名（例如： type CardMode = "default" | "scroll"）显示为实际值。外部类型（例如： React.ButtonHTMLAttributes）只显示类型名称。
4. 解析组件函数上方的JSDoc注释。
5. 仅使用必需的props创建示例使用示例。示例值根据prop类型生成。

输出示例

Component "Button" in "/project/path/Button.tsx"

Description:
사용자 액션을 트리거하는 클릭 가능한 버튼 컴포넌트

Props (3):

- variant?: "primary" | "secondary"
  버튼의 시각적 스타일
- size?: "sm" | "md" | "lg"
  버튼 크기
- onClick: () => void
  클릭 이벤트 핸들러

Usage Example:

import { Button } from './Button';

{}}>;

______________________________________________________________________

建议描述

收集上下文信息，为没有文档的组件生成适当的JSDoc说明。

工作原理

1. 查找元件文件: analyze_component使用与相同的阵列匹配查找元件文件。
2. Props提取：解析prop定义以查看元件接收的prop。
3. 提取代码片断：捕获元件的return语句（前10行）以了解呈现的内容。
4. 查找相关元件：搜索同一目录中的其他元件，为元件的目的和使用模式提供上下文。
5. 收集文件上下文：确定项目结构中元件的位置，包括文件路径。

输出示例

Component: Button
Location: /path/to/shared/ui/elements/Button.tsx

Props (3):
- variant?: "primary" | "secondary"
- size?: "sm" | "md" | "lg"
- onClick: () => void

Code snippet:
return (
  
    {children}
  
);

Related components in same directory:
IconButton, LinkButton

______________________________________________________________________

搜索组件

通过名称或关键字搜索元件，返回匹配结果。

工作原理

1. 收集所有元件: list_components使用与相同的元件导航查找项目中的所有元件。
2. 通过查询过滤：对元件名称执行不区分大小写的部分字符串匹配。
3. 返回匹配项：列出包含搜索查询的所有组件。

输出示例

Found 2 component(s) matching "button":

- Button
- IconButton

使用案例

• 查找与特定功能相关的所有组件（例如“auth”、“form”）
• 查找名称相似的组件（例如“card”>Card、ProductCard、UserCard）
• 在不熟悉的代码中导航可用组件
• 在创建新元件之前快速检查元件是否存在

______________________________________________________________________

create_storybook

根据组件的props定义创建Storybook文件。

工作原理

1. 查找元件文件：使用与其他工具相同的阵列匹配来查找元件。
2. Props提取：解析prop定义以识别元件输入。
3. 创建模板：创建包含meta设置和基本故事的Storybook文件。如果组件具有variant props（variant，size，type），则会自动为每个variant值创建其他故事。
4. 保存文件：在与元件相同的目录中 .stories.tsx 创建文件。

______________________________________________________________________

项目结构

src/
├── index.ts                    # 서버 설정, 핸들러 등록
├── config.ts
├── types.ts
├── utils/
│   ├── componentUtils.ts       # 공유 유틸 함수
│   └── tsParser.ts             # TypeScript 파서
└── tools/
    ├── index.ts
    ├── list_components.ts      # 모든 컴포넌트 나열
    ├── analyze_component.ts    # 컴포넌트 상세 분석
    ├── suggest_description.ts  # JSDoc용 컨텍스트 수집
    ├── search_component.ts     # 키워드로 컴포넌트 검색
    └── create_storybook.ts     # Storybook 파일 생성

______________________________________________________________________

要求

• Node.js>=18.0.0
• .tsx 或 .jsx 带有组件的React/TypeScript项目
• （选项） create_storybook 工具的Storybook

______________________________________________________________________

安装

npm install
npm run build

______________________________________________________________________

使用方法

{
  "mcpServers": {
    "component-doc": {
      "command": "node",
      "args": [
        "/path/to/component-doc-mcp/dist/index.js",
        "/path/to/your/project"
      ]
    }
  }
}

使用MCP Inspector进行测试

npx @modelcontextprotocol/inspector node dist/index.js /path/to/your/project

设置

设置为 CLI参数>config.json>默认值 顺序。

config.json

/path/to/your/project 在项目根目录中 config.json 文件

{
  "namingConvention": ["pascal", "kebab"]
}

命令行界面

node dist/index.js /path/to/project --naming-convention pascal,kebab

或

{ "mcpServers": { "component-doc": { "command": "node", "args": [ "/path/to/component-doc-mcp/dist/index.js", "/path/to/your/project", "--naming-convention", "pascal,kebab" ] } } }

______________________________________________________________________

## 使用示例

사용자: "프로젝트의 모든 컴포넌트 보여줘" → Claude가 list_components 호출

사용자: "Button 컴포넌트 어떻게 써?" → Claude가 analyze_component 호출

사용자: "Card 컴포넌트에 JSDoc 설명 추가해줘" → Claude가 suggest_description 호출 → Claude가 props와 코드 기반으로 설명 제안 → 사용자 승인 후 Claude가 파일에 JSDoc 추가

사용자: "Modal에 Storybook 파일 만들어줘" → Claude가 create_storybook 호출 → variant 스토리가 포함된 Modal.stories.tsx 생성