AI로 구축

Mastra 기술과 CLI를 사용한 일상적인 AI 지원 개발에 대해서는 다음을 참조하세요.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 파일을 제공합니다. 모든 문서를 하나의 파일에 담는 것은 유용하지 않으므로 llms-full.txt 파일은 제공하지 않습니다. 대신 각 문서 페이지에는 자체 llms.txt 파일이 있습니다. 이 파일은 간소화된 Markdown 파일입니다. 각 문서 페이지 끝에서 해당 llms.txt 파일의 링크를 찾을 수 있습니다. Mastra 문서 URL에 /llms.txt를 추가하여 접근하세요. URL 끝에 .md 확장자를 추가하여 요청할 수도 있습니다. 다음에 대한 예introduction page:

• /docs/llms.txt
• /docs.md

MCP 문서 서버

경고

MCP 문서 서버는 일상적인 개발에 권장되지 않습니다. 더 최신 상태이며 성능도 우수한 Mastra Skill을 대신 사용하세요.

@mastra/mcp-docs-server 패키지는 Model Context Protocol(MCP)을 통해 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 명령은 MCP 문서 서버를 구성하지 않습니다. 마이그레이션 Tool과 같은 MCP 전용 Tool이 필요할 때 서버를 수동으로 추가하세요. 아래 Tool에 대한 특정 지침이 없는 경우 이 공통 JSON 구성을 사용하여 MCP 서버를 추가할 수 있습니다.

mcp.json

{
  "mcpServers": {
    "mastra": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mastra/mcp-docs-server@latest"]
    }
  }
}

클로드 코드 CLI

터미널 명령을 사용하여 설치합니다.

claude mcp add --scope project mastra -- npx -y @mastra/mcp-docs-server@latest

이렇게 하면 프로젝트 범위의 .mcp.json 파일이 아직 없을 경우 생성됩니다. Claude Code를 Visual Studio Code 확장 프로그램으로 사용할 때도 같은 명령을 사용할 수 있습니다. Claude Code와 함께 MCP 서버 사용에 대한 추가 정보

OpenAI 코덱스 CLI

1. 터미널에서 등록하세요.

   codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@latest

2. codex mcp list를 실행하여 서버가 enabled로 표시되는지 확인합니다. OpenAI Codex와 함께 MCP 서버를 사용하는 방법에 대한 추가 정보

커서

아래 버튼을 선택하여 설치하세요.

자동 설치를 따른 경우 왼쪽 하단에 커서를 열면 Mastra Docs MCP 서버를 활성화하라는 팝업이 표시됩니다.

커서와 함께 MCP 서버를 사용하는 방법에 대한 추가 정보

반중력

Google Antigravity는 외부 문서, API 및 프로젝트 컨텍스트에 액세스하기 위해 MCP 서버를 지원하는 Agent 우선 개발 플랫폼입니다.

1. Antigravity MCP 구성 파일을 엽니다.

   • Agent session을 클릭하고 편집기 측면 패널 상단의 “…” dropdown을 선택한 다음 MCP Servers를 선택하여 MCP Store에 접근합니다.
   • Antigravity의 MCP Store 인터페이스를 통해 접근할 수 있습니다.

2. 사용자 정의 MCP 서버를 추가하려면 MCP Store 상단에서 Manage MCP Servers를 선택하고 기본 탭에서 View raw config를 선택합니다.

3. Mastra MCP 서버 구성을 추가합니다.

   {
     "mcpServers": {
       "mastra-docs": {
         "command": "npx",
         "args": ["-y", "@mastra/mcp-docs-server"]
       }
     }
   }

4. 구성을 저장하고 Antigravity를 다시 시작하세요.

   일단 구성되면 Mastra MCP 서버는 Antigravity Agent에 다음을 노출합니다.

• 코드 생성 중 관련 컨텍스트를 프로그래밍 방식으로 검색할 수 있는 Mastra용 색인화된 문서 및 API 스키마
• Mastra Docs에 저장된 예제 코드 조각 및 사용 패턴에 액세스
• 편집기에서 오류 처리 및 디버깅 참조를 위한 구조화된 데이터
• 코드 제안 및 완성을 위한 현재 Mastra 프로젝트 패턴에 대한 메타데이터

MCP 서버는 Antigravity의 MCP Store에 나타나며, 필요한 경우 연결 상태와 인증을 관리할 수 있습니다.

Antigravity와 함께 MCP 서버 사용에 대한 추가 정보

비주얼 스튜디오 코드

1. Workspace에 .vscode/mcp.json 파일을 만듭니다
2. 다음 구성을 삽입합니다.
   .vscode/mcp.json

   {
     "servers": {
       "mastra": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@mastra/mcp-docs-server@latest"]
       }
     }
   }

MCP 서버를 설치하면 다음과 같이 사용할 수 있습니다.

1. VSCode 설정을 엽니다.

2. MCP 설정으로 이동합니다.

3. 채팅 > MCP 옵션에서 "활성화"를 클릭하세요.

   MCP는 VSCode의 Agent 모드에서만 작동합니다. Agent 모드에서 mcp.json 파일을 열고 "start" 버튼을 선택하세요. "start" 버튼은 mcp.json을 포함하는 .vscode 폴더가 Workspace 루트 또는 편집기 내 파일 탐색기의 최상위 수준에 있을 때만 표시됩니다. MCP 서버를 시작한 후 Copilot 창에서 Tool 버튼을 선택하여 사용 가능한 Tool을 확인합니다. Visual Studio Code와 함께 MCP 서버를 사용하는 방법에 대한 추가 정보

윈드서핑

1. 편집기에서 ~/.codeium/windsurf/mcp_config.json을 엽니다

2. 다음 구성을 삽입합니다.

   ~/.codeium/windsurf/mcp_config.json

   {
     "mcpServers": {
       "mastra": {
         "command": "npx",
         "args": ["-y", "@mastra/mcp-docs-server@latest"]
       }
     }
   }

3. 구성을 저장하고 Windsurf를 다시 시작하세요.

Windsurf와 함께 MCP 서버를 사용하는 방법에 대한 추가 정보

오픈코드

OpenCode 구성의 mcp 아래에서 MCP 서버를 정의할 수 있습니다. 프로젝트 루트에 다음 내용으로 opencode.jsonc 파일을 만드세요.

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mastra": {
      "type": "local",
      "command": ["npx", "-y", "@mastra/mcp-docs-server@latest"],
      "enabled": true
    }
  }
}

OpenCode와 함께 MCP 서버 사용에 대한 추가 정보

제드 자의 명칭

1. 편집기에서 ~/.config/zed/settings.json을 엽니다
2. 다음 구성을 삽입합니다.

~/.config/zed/settings.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가 설치되어 있고 정상적으로 작동하는지 확인합니다.
   • MCP 서버 충돌을 확인합니다.
   • 구성 파일 구문을 확인합니다.
2. Tool 호출 실패
   • MCP 서버 및/또는 IDE를 다시 시작합니다.
   • 최신 버전의 IDE로 업데이트하세요.