docs(ai-integration): align Docs MCP page with @seed-design/docs-mcp 0.7 - #1930
docs(ai-integration): align Docs MCP page with @seed-design/docs-mcp 0.7#1930cha2hyun wants to merge 1 commit into
Conversation
The published page still described the pre-0.7 per-topic tools (discover_tools, list_react_components, …). Agents following it call names that no longer exist. Document the section/path surface that 0.7.0 actually exposes, and note Cursor GUI PATH pitfalls with bare npx.
|
📝 WalkthroughWalkthroughMCP 문서 안내에 ChangesMCP 문서 사용 안내
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with 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.
Inline comments:
In `@docs/content/ai-integration/`(mcp)/docs-mcp.mdx:
- Around line 62-84: docs-mcp 안내에서 createClient 및 Settings → MCP/Customize → MCP
관련 문구를 제거하고, 사용자가 검증할 수 있는 Cursor의 “Tools & MCP” 설정 경로와 “MCP Logs” 채널만 언급하도록
수정하세요. .cursor/mcp.json의 stdio 설정과 Node/npx 경로 안내는 유지하세요.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: ab111f6a-3e75-4f10-8ab0-7936292ffdea
📒 Files selected for processing (1)
docs/content/ai-integration/(mcp)/docs-mcp.mdx
| 프로젝트 루트의 `.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` 시도 자체가 로그에 남지 않습니다. | ||
|
|
There was a problem hiding this comment.
📐 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:
- 1: https://cursor.com/docs/mcp.md
- 2: https://cursor.com/docs/mcp
- 3: https://cursor.com/help/customization/mcp
- 4: https://www.truefoundry.com/blog/mcp-servers-in-cursor-setup-configuration-and-security-guide
- 5: https://www.mcpforge.tech/blog/cursor-mcp-json
- 6: https://dev.to/serenitiesai/how-to-set-up-mcp-servers-in-cursor-ide-complete-guide-2026-5gdl
- 7: https://shahvatsal.com/blog/designing-custom-mcp-servers-developer-agents-2026
🌐 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:
- 1: https://cursor.com/help/customization/mcp
- 2: https://cursor.com/docs/mcp
- 3: https://www.mcpforge.tech/blog/cursor-mcp-json
- 4: https://stackmcp.dev/blog/setup-mcp-servers-cursor
- 5: https://evomap.ai/blog/how-to-add-mcp-servers-to-cursor
- 6: https://aitoolsguidebook.com/en/articles/cursor-mcp-server-not-connecting/
- 7: https://www.learncursor.dev/learn/cursor-agents/how-to-use-mcp
- 8: https://forum.cursor.com/t/mcp-tools-only-available-to-agent-after-manually-toggling-server-off-on-even-when-already-enabled/152859
- 9: https://forum.cursor.com/t/mcp-servers-configured-but-agent-cannot-use-their-tools/153150
🌐 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:
- 1: https://www.truefoundry.com/blog/mcp-servers-in-cursor-setup-configuration-and-security-guide
- 2: https://cursor.com/docs/mcp
- 3: https://natoma.ai/blog/how-to-enabling-mcp-in-cursor
- 4: https://medium.com/@kpetropavlov/building-a-custom-mcp-server-with-cursor-ide-weather-traffic-home-assistant-integration-6ec8f2729783
- 5: https://www.apideck.com/blog/unlocking-ai-potential-how-to-quickly-set-up-a-cursor-mcp-server
- 6: https://snyk.io/articles/how-to-add-a-new-mcp-server-to-cursor/
- 7: https://forum.cursor.com/t/mcp-logging-issue/57577
- 8: https://forum.cursor.com/t/where-can-we-find-mcp-error-log/74719
- 9: https://karuppiah.dev/debugging-features-and-extensions-in-vscode-with-cursor-editor-and-mcp-tools-debugging-as-example
- 10: https://forum.cursor.com/t/cursor-3-4-20-kills-stdio-mcp-servers-1-5s-after-successful-initialize-sigkill-v2-fsm-race/160892
- 11: https://forum.cursor.com/t/mcp-server-connected-green-dot-and-tools-discovered-in-logs-but-0-tools-in-ui-and-agent/160620
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 경로 안내는 유지하세요.
1 participant
The published page still described the pre-0.7 per-topic tools (discover_tools, list_react_components, …). Agents following it call names that no longer exist. Document the section/path surface that 0.7.0 actually exposes, and note Cursor GUI PATH pitfalls with bare npx.
Summary by CodeRabbit
section및path기반 문서 조회 절차를 추가했습니다.type: "stdio"를 반영하고, PATH 상속 문제와 MCP 활성화·승인 절차를 설명했습니다.