> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # AI로 구축 Mastra 기술과 CLI를 사용한 일상적인 AI 지원 개발에 대해서는 다음을 참조하세요.[Develop](https://mastra.zisheng.pro/ko/docs/getting-started/develop). 이 페이지에서는 코딩 Agent에게 Mastra 문서에 대한 액세스 권한을 부여하는 다른 방법을 다룹니다. ## 임베디드 패키지 문서 Mastra 패키지에는 `dist/docs`에 문서가 내장되어 있습니다. Mastra 패키지를 설치하면 AI Agent가 `node_modules`에서 이 파일을 직접 읽어 패키지의 API와 패턴을 이해할 수 있습니다. 각`dist/docs` includes: - `SKILL.md`: 스킬 기준에 따른 스킬 파일 - `references/`: 패키지와 관련된 문서 파일이 있는 폴더 - `assets/SOURCE_MAP.json`: 공개 내보내기를 해당 위치에 연결하는 소스 맵 파일`node_modules` ## 컨텍스트 파일 Mastra는 사용 가능한 모든 문서 페이지의 개요가 포함된 루트 [`llms.txt`](https://mastra.ai/llms.txt) 파일을 제공합니다. 모든 문서를 하나의 파일에 담는 것은 유용하지 않으므로 `llms-full.txt` 파일은 제공하지 않습니다. 대신 각 문서 페이지에는 자체 `llms.txt` 파일이 있습니다. 이 파일은 간소화된 Markdown 파일입니다. 각 문서 페이지 끝에서 해당 `llms.txt` 파일의 링크를 찾을 수 있습니다. Mastra 문서 URL에 `/llms.txt`를 추가하여 접근하세요. URL 끝에 `.md` 확장자를 추가하여 요청할 수도 있습니다. 다음에 대한 예[introduction page](https://mastra.zisheng.pro/ko/docs): - [`/docs/llms.txt`](https://mastra.ai/docs/llms.txt) - [`/docs.md`](https://mastra.ai/docs.md) ## MCP 문서 서버 > **경고:** MCP 문서 서버는 일상적인 개발에 권장되지 않습니다. 더 최신 상태이며 성능도 우수한 [Mastra Skill](https://mastra.zisheng.pro/ko/docs/getting-started/develop)을 대신 사용하세요. `@mastra/mcp-docs-server` 패키지는 [Model Context Protocol(MCP)](https://modelcontextprotocol.io/docs/getting-started/intro)을 통해 Mastra 전체 문서에 로컬로 직접 접근할 수 있게 합니다. Cursor, Windsurf, Cline, Claude Code, VS Code, Codex 또는 MCP를 지원하는 모든 Tool에서 작동합니다. 이러한 Tool은 Agent에 기능을 추가하거나 새 프로젝트를 스캐폴딩하거나 작업 방식을 탐색하는 등 Agent가 정확한 작업별 정보를 검색하는 데 도움이 되도록 설계되었습니다. 로컬 MCP 서버를 사용할 수 없어 원격 서버에 연결해야 한다면 `https://mastra.mcp.kapa.ai` URL을 사용하세요. 요청 속도 제한을 위해 Google Account로 인증해야 합니다(익명 ID만 전송됨). 가능하다면 더 나은 성능과 안정성을 위해 로컬 MCP 서버를 사용하는 것이 좋습니다. ### 설치 [`create-mastra`](https://mastra.zisheng.pro/ko/reference/cli/create-mastra) 명령은 MCP 문서 서버를 구성하지 않습니다. 마이그레이션 Tool과 같은 MCP 전용 Tool이 필요할 때 서버를 수동으로 추가하세요. 아래 Tool에 대한 특정 지침이 없는 경우 이 공통 JSON 구성을 사용하여 MCP 서버를 추가할 수 있습니다. ```json { "mcpServers": { "mastra": { "type": "stdio", "command": "npx", "args": ["-y", "@mastra/mcp-docs-server@latest"] } } } ``` #### 클로드 코드 CLI 터미널 명령을 사용하여 설치합니다. ```bash claude mcp add --scope project mastra -- npx -y @mastra/mcp-docs-server@latest ``` 이렇게 하면 프로젝트 범위의 `.mcp.json` 파일이 아직 없을 경우 생성됩니다. Claude Code를 [Visual Studio Code 확장 프로그램](https://code.claude.com/docs/en/vs-code#connect-to-external-tools-with-mcp)으로 사용할 때도 같은 명령을 사용할 수 있습니다. [Claude Code와 함께 MCP 서버 사용에 대한 추가 정보](https://docs.claude.com/en/docs/claude-code/mcp) #### OpenAI 코덱스 CLI 1. 터미널에서 등록하세요. ```bash codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@latest ``` 2. `codex mcp list`를 실행하여 서버가 `enabled`로 표시되는지 확인합니다. [OpenAI Codex와 함께 MCP 서버를 사용하는 방법에 대한 추가 정보](https://developers.openai.com/codex/mcp) #### 커서 아래 버튼을 선택하여 설치하세요. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=mastra\&config=eyJjb21tYW5kIjoibnB4IC15IEBtYXN0cmEvbWNwLWRvY3Mtc2VydmVyIn0%3D) 자동 설치를 따른 경우 왼쪽 하단에 커서를 열면 Mastra Docs MCP 서버를 활성화하라는 팝업이 표시됩니다. ![Cursor 내부에 \"New MCP server detected: mastra\"라고 표시된 팝업. 사용자는 작업으로 \"Skip\" 또는 \"Enable\"을 선택할 수 있습니다.](/ko/assets/images/enable-mastra-docs-cursor-cd5872abdc36c0e10951a59a47f25e12.png) [커서와 함께 MCP 서버를 사용하는 방법에 대한 추가 정보](https://cursor.com/de/docs/context/mcp) #### 반중력 Google Antigravity는 외부 문서, API 및 프로젝트 컨텍스트에 액세스하기 위해 MCP 서버를 지원하는 Agent 우선 개발 플랫폼입니다. 1. Antigravity MCP 구성 파일을 엽니다. - **Agent session**을 클릭하고 편집기 측면 패널 상단의 **“…” dropdown**을 선택한 다음 **MCP Servers**를 선택하여 **MCP Store**에 접근합니다. - Antigravity의 MCP Store 인터페이스를 통해 접근할 수 있습니다. ![Antigravity MCP Store. 상단에는 검색창이 있고 그 아래에는 사용 가능한 MCP 서버 목록이 있습니다. 맨 오른쪽 상단에는 드롭다운 메뉴가 있습니다.](/ko/assets/images/antigravity_mcp_server-689ea495d9c7139cc431f1f1b9827f9b.png) 2. 사용자 정의 MCP 서버를 추가하려면 MCP Store 상단에서 **Manage MCP Servers**를 선택하고 기본 탭에서 **View raw config**를 선택합니다. ![Manage MCP Servers 옵션과 View raw config 버튼을 표시하는 Antigravity MCP Store.](/ko/assets/images/antigravity_managed_mcp-b661e8c04b3219000f8d842e5eb26a1a.png) 3. Mastra MCP 서버 구성을 추가합니다. ```json { "mcpServers": { "mastra-docs": { "command": "npx", "args": ["-y", "@mastra/mcp-docs-server"] } } } ``` 4. 구성을 저장하고 Antigravity를 다시 시작하세요. ![MCP 서버가 활성화되었음을 보여주는 UI. 개별 Tool을 전환할 수도 있습니다.](/ko/assets/images/antigravity_final_interface_mcp-7fa132dbe76cdee9f61136a26d6e6615.png) 일단 구성되면 Mastra MCP 서버는 Antigravity Agent에 다음을 노출합니다. - 코드 생성 중 관련 컨텍스트를 프로그래밍 방식으로 검색할 수 있는 Mastra용 색인화된 문서 및 API 스키마 - Mastra Docs에 저장된 예제 코드 조각 및 사용 패턴에 액세스 - 편집기에서 오류 처리 및 디버깅 참조를 위한 구조화된 데이터 - 코드 제안 및 완성을 위한 현재 Mastra 프로젝트 패턴에 대한 메타데이터 MCP 서버는 Antigravity의 MCP Store에 나타나며, 필요한 경우 연결 상태와 인증을 관리할 수 있습니다. [Antigravity와 함께 MCP 서버 사용에 대한 추가 정보](https://antigravity.google) #### 비주얼 스튜디오 코드 1. Workspace에 `.vscode/mcp.json` 파일을 만듭니다 2. 다음 구성을 삽입합니다. ```json { "servers": { "mastra": { "type": "stdio", "command": "npx", "args": ["-y", "@mastra/mcp-docs-server@latest"] } } } ``` MCP 서버를 설치하면 다음과 같이 사용할 수 있습니다. 1. VSCode 설정을 엽니다. 2. MCP 설정으로 이동합니다. 3. 채팅 > MCP 옵션에서 "활성화"를 클릭하세요. ![VSCode 설정 페이지의 항목. 옵션 이름은 \"Chat \> MCP: Enabled (Preview)\"입니다. 설명에는 \"Enables integration with Model Context Protocol servers to provide additional tools and functionality.\"라고 표시됩니다.](/ko/assets/images/vscode-mcp-setting-8d1eb4f3df1e33606503f8c5e937e9e3.png) MCP는 VSCode의 Agent 모드에서만 작동합니다. Agent 모드에서 `mcp.json` 파일을 열고 "start" 버튼을 선택하세요. "start" 버튼은 `mcp.json`을 포함하는 `.vscode` 폴더가 Workspace 루트 또는 편집기 내 파일 탐색기의 최상위 수준에 있을 때만 표시됩니다. ![편집기에 start 버튼이 표시된 mcp.json 파일의 스크린샷](/ko/assets/images/vscode-start-mcp-26480d86080c4907cb497a325de106a4.png) MCP 서버를 시작한 후 Copilot 창에서 Tool 버튼을 선택하여 사용 가능한 Tool을 확인합니다. ![사용 가능한 Tool을 확인할 수 있는 VSCode의 Tools 페이지](/ko/assets/images/vscode-mcp-running-d92d6ed234d1148093dc804b0ead3515.png) [Visual Studio Code와 함께 MCP 서버를 사용하는 방법에 대한 추가 정보](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) #### 윈드서핑 1. 편집기에서 `~/.codeium/windsurf/mcp_config.json`을 엽니다 2. 다음 구성을 삽입합니다. ```json { "mcpServers": { "mastra": { "command": "npx", "args": ["-y", "@mastra/mcp-docs-server@latest"] } } } ``` 3. 구성을 저장하고 Windsurf를 다시 시작하세요. [Windsurf와 함께 MCP 서버를 사용하는 방법에 대한 추가 정보](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json) #### 오픈코드 [OpenCode 구성](https://opencode.ai/docs/config/)의 `mcp` 아래에서 MCP 서버를 정의할 수 있습니다. 프로젝트 루트에 다음 내용으로 `opencode.jsonc` 파일을 만드세요. ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "mastra": { "type": "local", "command": ["npx", "-y", "@mastra/mcp-docs-server@latest"], "enabled": true } } } ``` [OpenCode와 함께 MCP 서버 사용에 대한 추가 정보](https://opencode.ai/docs/mcp-servers) #### 제드 자의 명칭 1. 편집기에서 `~/.config/zed/settings.json`을 엽니다 2. 다음 구성을 삽입합니다. ```json { "context_servers": { "Mastra": { "command": "npx", "args": ["-y", "@mastra/mcp-docs-server@latest"] } } } ``` ### 용법 구성이 완료되면 AI Tool에 Mastra에 대해 질문하거나 조치를 취하도록 지시할 수 있습니다. 이 단계에서는 Mastra의 MCP 서버에서 최신 정보를 가져옵니다. **기능 추가:** - "Agent에 평가를 추가하고 테스트를 작성하세요" - "다음을 수행하는 Workflow를 작성해 주세요.`[task]`" - "내 Agent가 액세스할 수 있는 새 Tool을 만들어 보세요.`[3rd party API]`" **통합에 대해 문의하세요.** - "Mastra는 AI SDK와 함께 작동하나요? 내 `[React/Svelte/etc]` 프로젝트에서는 어떻게 사용할 수 있나요?" - "Mastra는 `[provider]` 음성 및 보이스 API를 지원하나요? 이를 사용하는 방법을 내 코드의 예제로 보여 주세요." **기존 코드를 디버그하거나 업데이트합니다.** - "Agent Memory에서 버그가 발생했습니다. 최근 관련 변경 사항이나 버그 수정이 있었나요?" - "Mastra에서 작업 Memory는 어떻게 작동하며 `[task]`에 어떻게 사용할 수 있나요? 예상한 대로 작동하지 않는 것 같습니다." - "새로운 Workflow 기능이 있는 것을 확인했습니다. 해당 기능을 설명하고 이를 사용하도록 `[workflow]`를 업데이트해 주세요." ### 문제 해결 1. **서버가 시작되지 않음** - [npx](https://docs.npmjs.com/cli/v11/commands/npx)가 설치되어 있고 정상적으로 작동하는지 확인합니다. - MCP 서버 충돌을 확인합니다. - 구성 파일 구문을 확인합니다. 2. **Tool 호출 실패** - MCP 서버 및/또는 IDE를 다시 시작합니다. - 최신 버전의 IDE로 업데이트하세요.