Skip to content

docs(ai-integration): align Docs MCP page with @seed-design/docs-mcp 0.7 #1930

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cha2hyun wants to merge 1 commit into
base: dev
Choose a base branch
from
Open

docs(ai-integration): align Docs MCP page with @seed-design/docs-mcp 0.7 #1930

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 41 additions & 172 deletions docs/content/ai-integration/(mcp)/docs-mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ description: AI Agent가 SEED 문서에 직접 접근할 수 있는 MCP 서버

Figma 연결 없이 독립적으로 실행되며, SEED를 사용하는 프로젝트에서 AI 도구의 문서 이해도를 높일 수 있습니다.

문서는 `section` + `path`로 주소가 정해집니다. 처음에는 `discover_seed_docs`로 섹션·카테고리 맵을
확인한 뒤, `list_docs` / `get_doc`로 필요한 문서만 가져오세요.

## 설치

<Tabs items={['Claude Code', 'Codex CLI', 'Gemini CLI', 'Cursor', 'Claude Desktop']}>
Expand Down Expand Up @@ -56,18 +59,29 @@ codex mcp add seed-docs -- npx -y @seed-design/docs-mcp

<Tab value="Cursor">

프로젝트 루트의 `.cursor/mcp.json`에 다음을 추가합니다:

```json
{
"mcpServers": {
"seed-docs": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@seed-design/docs-mcp"],
"type": "stdio"
"args": ["-y", "@seed-design/docs-mcp"]
}
}
}
```

Cursor GUI는 셸 프로필의 `PATH`를 물려받지 않습니다. macOS에서는 종종
`/usr/bin:/bin:/usr/sbin:/sbin`만 보이므로, nvm·fnm·Volta·Homebrew로 설치한 Node라면
위 설정에서 `npx`를 찾지 못해 서버가 MCP 목록에 **아예 나타나지 않을 수** 있습니다.
그 경우 `command`를 Node/`npx`의 절대 경로로 바꾸거나, Node를 찾은 뒤 `npx`를 실행하는
작은 셸 스크립트를 `command`로 지정하세요.

프로젝트 MCP는 Cursor **Settings → MCP**(또는 Customize → MCP)에서 활성화·승인이 필요합니다.
토글이 꺼져 있으면 `createClient` 시도 자체가 로그에 남지 않습니다.

Comment on lines +62 to +84

@coderabbitai coderabbitai Bot Aug 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

Cursor .cursor/mcp.json type stdio configuration schema

💡 Result:

In Cursor, MCP server configurations are managed via a JSON file named mcp.json [1][2]. You can place this file in two locations: - Project-specific:.cursor/mcp.json (recommended for team-shared tools) [1][3] - Global: ~/.cursor/mcp.json (for personal tools available across all projects) [1][3] When both exist, the project-level configuration takes priority [3][4]. For stdio (Standard I/O) transport, which is used for locally executed servers, the schema requires the following fields within the mcpServers object [1][5][6]: Field | Required | Description | |:--- |:--- |:--- | | type | Yes | Must be set to "stdio" [1][6] | | command | Yes | The command to start the server (e.g., npx, node, python, docker) [1][6] | | args | No | An array of arguments passed to the command [1][6] | | env | No | An object of environment variables for the server process [1][6] | | envFile | No | A path to an environment file (e.g.,.env) to load variables [1][6] | Example Configuration: { "mcpServers": { "my-local-server": { "type": "stdio", "command": "python", "args": ["${workspaceFolder}/tools/server.py"], "env": { "API_KEY": "${env:API_KEY}" } } } } Cursor supports config interpolation for values in command, args, and env fields, allowing you to use variables such as ${env:NAME}, ${userHome}, and ${workspaceFolder} [1][2]. Because stdio communication relies on stdin and stdout, ensure your server does not print debug statements or logs to stdout, as this will pollute the protocol stream and cause connection errors [5][7].

Citations:

🌐 Web query:

Cursor MCP .cursor/mcp.json createClient settings customize MCP toggle log

💡 Result:

To configure Model Context Protocol (MCP) servers in Cursor, you can use either a project-specific file or a global configuration file [1][2][3]. Configuration Locations Project-specific: Create a file at.cursor/mcp.json in the root of your project [1][4]. This is recommended for team-shared tools and will take priority if a server name conflicts with the global config [1][4]. Global: Create a file at ~/.cursor/mcp.json [1][3]. This makes the configured servers available across all projects [1][4]. Configuration Format The file must use mcpServers as the top-level key; if this key is missing or misspelled, Cursor will ignore the file [4][5]. You can configure local servers (via command/args) or remote servers (via URL) [1][2][4]. Example.cursor/mcp.json: { "mcpServers": { "my-server": { "command": "npx", "args": ["-y", "mcp-server-package"], "env": { "API_KEY": "your-key-here" } } } } Managing and Troubleshooting Settings Panel: Access MCP management via Settings > Tools & MCP (in some older versions labeled Features > MCP) [6][7][5]. You can add servers here via the UI, which automatically updates your mcp.json [6][5]. Logs: If a server fails to connect, check the MCP logs. Open the Output panel (Ctrl/Cmd + Shift + U) and select the MCP Logs channel [6]. This is where specific errors such as JSON syntax issues, missing API keys, or initialization failures are reported [6]. Toggle/Refresh Issues: If a server appears connected in the settings but the AI agent cannot access its tools, toggle the server off and then on again in the Tools & MCP settings [6][8][9]. This forces a re-initialization of the server [9]. Additionally, verify that individual tools are not toggled off in the tool list within your chat panel [6]. Always ensure the master Enable MCP servers switch is active in the settings [6].

Citations:

🌐 Web query:

Cursor MCP log "createClient" Settings MCP Customize MCP

💡 Result:

To customize and manage Model Context Protocol (MCP) servers in Cursor, you primarily use the Cursor settings interface or direct configuration files [1][2]. Settings and Configuration You can manage your MCP servers via the Cursor interface or by manually editing configuration files [1][2]. 1. Interface: Go to Cursor Settings > Tools & MCP (or "Tools & Integrations" in some versions) [1][3][4]. From here, you can add new servers, and enable or disable existing ones using the toggle switches [2][4][5]. 2. Configuration Files: Cursor uses mcp.json files to define servers [6][2]. - Global Config: Located at ~/.cursor/mcp.json (or %USERPROFILE%.cursor\mcp.json on Windows) [1][3][6]. This configuration applies to all projects [1][6]. - Project-Level Config: Located at.cursor/mcp.json in your project root [1][6]. This configuration applies only to the current project and takes precedence over the global config if a server is defined in both [1][6]. Logging and Debugging To debug MCP connections, you can view logs through the built-in output panel or access raw files on your system [7][8]. 1. In-Editor Logs: Open the Command Palette (Cmd/Ctrl + Shift + P), search for "Developer: Show Logs...", and select "MCP Logs" (or "Cursor MCP" from the Output panel dropdown menu) [3][8][9]. 2. System Log Files: For deeper analysis, raw log files are stored in your Cursor application support directory [7][10][11]. The path generally follows: ~/Library/Application Support/Cursor/logs/[SESSION_ID]/window[N]/exthost/anysphere.cursor-always-local/Cursor MCP.log (Replace [SESSION_ID] with the relevant timestamped folder and [N] with your window number) [7]. If you are experiencing connection issues, check the "Tools & MCP" settings page to confirm the status indicator (green for connected, yellow for loading, red for error) [1][4][9]. If an MCP server is failing to initialize, logs often provide details on transport errors, authentication issues, or schema mismatches [7][9].

Citations:

MCP 안내에서 내부 로그 경로는 제거하세요.

.cursor/mcp.json의 type: "stdio"는 Cursor MCP 스키마에서 유효합니다. 하지만 createClient, Settings → MCP, Customize → MCP는 Cursor 문서 경로/로그 메시지와 달리 보입니다. 사용자에게 검증 가능한 Tools & MCP 설정 경로와 MCP Logs 채널만 언급하세요.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/content/ai-integration/`(mcp)/docs-mcp.mdx around lines 62 - 84,
docs-mcp 안내에서 createClient 및 Settings → MCP/Customize → MCP 관련 문구를 제거하고, 사용자가
검증할 수 있는 Cursor의 “Tools & MCP” 설정 경로와 “MCP Logs” 채널만 언급하도록 수정하세요.
.cursor/mcp.json의 stdio 설정과 Node/npx 경로 안내는 유지하세요.

[Cursor MCP에 대해 자세히 알아보기](https://docs.cursor.com/context/model-context-protocol)

</Tab>
Expand All @@ -93,198 +107,87 @@ codex mcp add seed-docs -- npx -y @seed-design/docs-mcp

## 사용 가능한 도구

`@seed-design/docs-mcp@0.7.0` 기준으로 노출되는 도구입니다. 도구 표면은 마이너 버전에서
바뀔 수 있으니, 연결 직후 `discover_seed_docs`로 실제 맵을 확인하세요.

### Discovery

#### `discover_tools`
#### `discover_seed_docs`

사용 가능한 모든 도구를 탐색하고 각 도구의 용도를 확인합니다. MCP 서버에 처음 연결했을 때 호출하면 유용합니다.
사용 가능한 섹션과 카테고리 맵을 반환합니다. `list_docs` / `get_doc`를 쓰기 전에 먼저 호출하세요.

**파라미터:**
| 이름 | 타입 | 설명 |
|------|------|------|
| `query` | string (선택) | 도구를 필터링할 검색어 (예: 'installation', 'component') |
| `category` | string (선택) | 카테고리 필터 (`discovery`, `react`, `breeze`, `design-guidelines`, `rootage`, `icons`) |
**파라미터:** 없음

**예시:**
```
discover_tools({ query: "component" })
discover_seed_docs()
```

---

### React Components
### Documents

#### `list_react_components`
#### `list_docs`

사용 가능한 모든 SEED React 컴포넌트 목록을 반환합니다.

**파라미터:** 없음

**예시 응답:**
```
Found 45 React components:

- ActionButton (action-button)
- AlertDialog (alert-dialog)
- Avatar (avatar)
- Badge (badge)
...
```

#### `get_react_component`

특정 React 컴포넌트의 상세 문서를 반환합니다. 설치 방법, props, 사용 예시가 포함됩니다.
특정 섹션의 문서 목록을 반환합니다. 응답의 `path`를 `get_doc`에 넘깁니다.

**파라미터:**
| 이름 | 타입 | 설명 |
|------|------|------|
| `componentName` | string | 컴포넌트 이름 (kebab-case, 예: `action-button`, `text-field`) |
| `section` | string | `react`, `docs`, `breeze`, `ai-integration`, `lynx` |
| `category` | string (선택) | 예: `components`, `foundation`, `getting-started` |

**예시:**
```
get_react_component({ componentName: "action-button" })
```

#### `get_react_changelog`

SEED React 패키지의 변경 이력을 반환합니다. 버전 업그레이드 시 변경 사항을 확인할 때 유용합니다.

**파라미터:** 없음

---

### React 섹션별 도구

React 문서의 각 섹션에 접근하는 도구들입니다. 각 섹션마다 `list_*`와 `get_*` 도구가 제공됩니다.

| 섹션 | list 도구 | get 도구 | 설명 |
|------|-----------|----------|------|
| Getting Started | `list_react_getting_started` | `get_react_getting_started` | 설치, CLI, 스타일링 설정 |
| Stackflow | `list_react_stackflow` | `get_react_stackflow` | Stackflow 통합 가이드 |
| Developer Tools | `list_react_developer_tools` | `get_react_developer_tools` | Codemod, Figma 통합 |
| Migration | `list_react_migration` | `get_react_migration` | 마이그레이션 가이드 |
| AI Integration | `list_react_ai_integration` | `get_react_ai_integration` | AI 도구 통합 |
| Updates | `list_react_updates` | `get_react_updates` | 버전 업데이트 정보 |

#### 사용 예시

먼저 `list_*` 도구로 사용 가능한 문서를 확인합니다:

```
list_react_getting_started()
```

응답:
```
# SEED React - Getting Started Topics

- Installation - Vite (path: installation/vite)
- Installation - Manual (path: installation/manual)
- CLI - Commands (path: cli/commands)
- CLI - Configuration (path: cli/configuration)
- Styling - Theming (path: styling/theming)
- Styling - Tailwind CSS (path: styling/tailwind-css)
list_docs({ section: "react", category: "components" })
```

원하는 문서의 `path`를 사용해 상세 내용을 가져옵니다:

```
get_react_getting_started({ path: "installation/vite" })
```

---
#### `get_doc`

### Breeze

Breeze는 프로젝트에 바로 사용할 수 있는 유틸리티 UI 컴포넌트 모음입니다.

#### `list_breeze_components`

사용 가능한 Breeze 컴포넌트 목록을 반환합니다.

**파라미터:** 없음

**예시 응답:**
```
Found 1 Breeze components:

- AnimateNumber (animate-number)
```

#### `get_breeze_component`

특정 Breeze 컴포넌트의 상세 문서를 반환합니다.
한 문서의 전체 내용을 반환합니다.

**파라미터:**
| 이름 | 타입 | 설명 |
|------|------|------|
| `componentName` | string | 컴포넌트 이름 (kebab-case, 예: `animate-number`) |
| `section` | string | `react`, `docs`, `breeze`, `ai-integration`, `lynx` |
| `path` | string | 예: `components/action-button`, `getting-started/styling/tailwind-css` |

**예시:**
```
get_breeze_component({ componentName: "animate-number" })
get_doc({ section: "react", path: "components/action-button" })
get_doc({ section: "docs", path: "foundation/color" })
```

---

### Design Guidelines

컴포넌트의 디자인 가이드라인 문서에 접근합니다. 해부도(anatomy), 속성, 사용 권장사항 등이 포함됩니다.

#### `list_docs_components`
#### `get_full_docs`

디자인 가이드라인이 있는 컴포넌트 목록을 반환합니다.

**파라미터:** 없음

**예시 응답:**
```
Found 25 component design guidelines:

- ActionButton (action-button)
- Avatar (avatar)
- BottomSheet (bottom-sheet)
...
```

#### `get_docs_component`

특정 컴포넌트의 디자인 가이드라인을 반환합니다.
한 섹션의 문서를 한꺼번에 반환합니다. 컨텍스트가 커지므로 가능하면 `get_doc`을 우선하세요.

**파라미터:**
| 이름 | 타입 | 설명 |
|------|------|------|
| `componentName` | string | 컴포넌트 이름 (kebab-case, 예: `action-button`) |
| `section` | string | `react`, `docs`, `breeze`, `ai-integration`, `lynx` |

**예시:**
```
get_docs_component({ componentName: "action-button" })
get_full_docs({ section: "ai-integration" })
```

---

### Rootage

SEED의 Rootage 스펙(디자인 토큰 및 컴포넌트 스펙의 원본 JSON 데이터)에 접근합니다.

#### `get_rootage`

Rootage 리소스를 반환합니다. 경로 없이 호출하면 사용 가능한 모든 리소스 목록을 반환합니다.
SEED Rootage 스펙(토큰·컴포넌트 JSON)을 반환합니다. `path` 없이 호출하면 인덱스입니다.

**파라미터:**
| 이름 | 타입 | 설명 |
|------|------|------|
| `path` | string (선택) | 리소스 경로 (예: `/color.json`, `/components/action-button.json`) |
| `path` | string (선택) | 예: `/color.json`, `/components/action-button.json` |

**예시:**

리소스 목록 조회:
```
get_rootage()
```

특정 리소스 조회:
```
get_rootage({ path: "/components/action-button.json" })
```

Expand Down Expand Up @@ -327,18 +230,6 @@ list_icons({ type: "monochrome", variant: "line", limit: 20 })
search_icons({ query: "화살표" })
```

**예시 응답:**
```
Found 15 icons matching "화살표":
View in browser: https://seed-design.io/foundations/iconography/library?search=화살표

- icon_arrow_left_line [monochrome] (line)
Matched: arrow, 화살표, left
- icon_arrow_right_line [monochrome] (line)
Matched: arrow, 화살표, right
...
```

#### `get_icon_details`

특정 아이콘의 상세 정보와 React 컴포넌트 import 문을 반환합니다.
Expand All @@ -353,28 +244,6 @@ View in browser: https://seed-design.io/foundations/iconography/library?search=
get_icon_details({ iconName: "icon_arrow_left_line" })
```

**예시 응답:**
```markdown
# icon_arrow_left_line

**Type:** monochrome
**Variant:** line
**Keywords:** arrow, left, back, 화살표, 왼쪽

## Usage

### React
\`\`\`tsx
import { IconArrowLeftLine } from "@karrotmarket/react-monochrome-icon"

<IconArrowLeftLine />
\`\`\`

## Documentation

View this icon: https://seed-design.io/foundations/iconography/library?icon=icon_arrow_left_line
```

---

## 프로그래매틱 사용
Expand Down