mastergo-design/mastergo-magic-mcp

MasterGo Magic MCP는 MasterGo 디자인 도구를 AI 모델과 연결하기 위해 설계된 독립형 MCP (Model Context Protocol) 서비스입니다. 이를 통해 AI 모델이 MasterGo 디자인 파일에서 DSL (Domain Specific Language) 데이터를 직접 검색할 수 있습니다.

• MasterGo 디자인 파일에서 DSL 데이터 검색
• npx를 통해 직접 실행 가능
• 외부 의존성 불필요, Node.js 환경만 필요

MCP 서버가 연결되면, AI 채팅에서 다음과 같은 프롬프트를 사용할 수 있습니다:

SVG 추출 및 HTML에서 미리보기:

Extract SVG and preview in HTML: https://{domain}/file/{fileId}?layer_id={layerId}

디자인을 코드로 복원:

Restore design: https://{domain}/file/{fileId}?layer_id={layerId}

{domain}, {fileId}, {layerId}를 실제 값으로 교체하세요. 단축 링크(short links)도 사용할 수 있습니다:

Restore design: https://{domain}/goto/{shortLink}

디자인을 복원하고 HTML 파일로 저장:

Restore design, save as HTML file: https://{domain}/file/{fileId}?layer_id={layerId}

단축 링크도 사용할 수 있습니다:

Restore design, save as HTML file: https://{domain}/goto/{shortLink}

• https://mastergo.com 방문
• 개인 설정(personal settings) 진입
• 보안 설정(Security Settings) 탭 클릭
• 개인 액세스 토큰(personal access token) 찾기
• 클릭하여 토큰 생성

중요: 도구가 연결되었으나 "권한 없음(no permission)" 에러가 반환되는 경우, 다음 조건들을 확인하십시오:

• 계정 버전 요구사항: MasterGo Team Edition 이상의 계정이 필요합니다. 개인 무료 에디션은 MCP 도구 액세스를 지원하지 않습니다.

• 파일 위치 요구사항: 디자인 파일은 반드시 Team Projects에 위치해야 합니다. 초안함(draft box)에 있는 파일은 MCP 도구를 통해 접근할 수 없습니다.

디자인 파일은 반드시 다음 명령어를 통해 실행되어야 합니다:

npx @mastergo/magic-mcp --token=YOUR_TOKEN [--url=API_URL] [--rule=RULE_NAME] [--proxy=PROXY_URL] [--debug] [--no-rule]

--token=YOUR_TOKEN (필수): 인증을 위한 MasterGo API 토큰
--url=API_URL (선택 사항): API 기본 URL, 기본값은 http://localhost:3000
--rule=RULE_NAME

(선택 사항): 적용할 디자인 규칙을 추가합니다. 여러 번 사용할 수 있습니다
--proxy=PROXY_URL

(선택 사항): HTTP/HTTPS 프록시 (Proxy) URL (예: http://127.0.0.1:7890), 또한 HTTPS_PROXY / HTTP_PROXY 환경 변수 (Environment variables)를 지원합니다
--debug

(선택 사항): 상세한 에러 정보를 위해 디버그 (Debug) 모드를 활성화합니다
--no-rule

(선택 사항): 기본 규칙을 비활성화합니다

매개변수(Parameters)는 공백으로 구분된 형식을 사용할 수도 있습니다:

npx @mastergo/magic-mcp --token YOUR_TOKEN --url API_URL --rule RULE_NAME --proxy PROXY_URL --debug

또는 명령줄 인자 (Command line arguments) 대신 환경 변수 (Environment variables)를 사용할 수도 있습니다:

MG_MCP_TOKEN 또는 MASTERGO_API_TOKEN: MasterGo API 토큰 (Token)
API_BASE_URL: API 기본 URL (Base URL)
RULES: 규칙의 JSON 배열 (예: '["rule1", "rule2"]')
HTTPS_PROXY / https_proxy / HTTP_PROXY / http_proxy: HTTP(S) 프록시 URL (--proxy 인자가 우선순위를 가집니다)

Smithery는 MCP 서비스를 쉽게 설치하고 관리할 수 있게 해주는 MCP 서버 마켓플레이스 (Marketplace)입니다.

• Smithery 마켓플레이스 방문
• "Connect" 또는 "Install" 버튼 클릭
• 사용할 MCP 클라이언트 (Client) 선택 (예: Claude Desktop, Cursor 등)
• 안내에 따라 설치 및 설정을 완료

VSCode 확장 프로그램 (Extension) 마켓플레이스에서 LINGMA를 검색하여 설치하세요.

로그인 후, 채팅창에서 [MCP tools]를 클릭합니다.

상단의 [MCP Square]를 클릭하여 MCP 마켓플레이스로 이동한 뒤, MasterGo 디자인 협업 도구를 찾아 설치합니다.

설치 후 [MCP Servers]로 돌아가서, 우리의 MCP 서비스를 편집하여 본인의 MasterGo 토큰으로 교체합니다.

마지막으로, 채팅 인터페이스에서 채팅 모드를 에이전트 (Agent) 모드로 전환합니다.

Cursor MCP 사용 가이드 참조: https://docs.cursor.com/context/model-context-protocol#using-mcp-tools-in-agent

MCP 서버를 명령줄 인자 또는 환경 변수를 사용하여 구성할 수 있습니다:

옵션 1: 명령줄 인자 사용

{
"mcpServers": {
"mastergo-magic-mcp": {
...

옵션 2: 환경 변수 사용

{
"mcpServers": {
"mastergo-magic-mcp": {
...

옵션 3: SSE (Streamable HTTP) 사용

로컬 설치가 필요하지 않습니다. MCP 서버가 원격에서 실행되며 SSE를 통해 접속합니다:

{
"mcpServers": {
"mastergo-magic-mcp": {
...

옵션 1: 명령줄 인자 (command line arguments) 사용

{
"mcpServers": {
"@master/mastergo-magic-mcp": {
...

옵션 2: 환경 변수 (environment variables) 사용

{
"mcpServers": {
"@master/mastergo-magic-mcp": {
...

Open Code는 type: "local" 및 command 배열을 포함하는 mcp 설정 블록을 사용합니다:

{
"mcp": {
"mastergo-magic-mcp": {
...

src 디렉토리는 MasterGo Magic MCP 서비스의 핵심 구현을 포함하고 있습니다:

index.ts: MCP 서버를 초기화하고 모든 도구(tools)를 등록하는 애플리케이션의 엔트리 포인트 (Entry point)
http-util.ts: MasterGo API로의 HTTP 요청을 처리하기 위한 유틸리티 (Utility)
types.d.ts: 프로젝트를 위한 TypeScript 타입 정의 (type definitions)

MCP 도구들의 구현을 포함합니다:

base-tool.ts: 모든 MCP 도구의 기본 클래스 (Base class)
get-dsl.ts: MasterGo 디자인 파일에서 DSL (Domain Specific Language) 데이터를 가져오는 도구
get-component-link.ts: 링크에서 컴포넌트 문서를 가져오는 도구
get-meta.ts: 메타데이터 (metadata) 정보를 가져오는 도구
get-component-workflow.ts: Vue 및 React 컴포넌트를 위한 구조화된 컴포넌트 개발 워크플로우를 제공하고, 워크플로우 파일 및 컴포넌트 사양을 생성하는 도구

추가 문서가 포함된 마크다운 (markdown) 파일들입니다:

meta.md: 메타데이터 구조 및 사용법에 관한 문서
component-workflow.md: 구조화된 컴포넌트 개발 프로세스를 안내하는 컴포넌트 개발 워크플로우 문서

• yarn 및 yarn build를 실행하여 의존성을 설치하고 코드를 빌드하세요.
• dist/index.js의 절대 경로를 찾으세요.
• 본인의 토큰을 사용하여 로컬 MCP 설정을 추가하세요.

"mastergo-mcp-local": {
"command": "node",
"args": [
...

• 로컬 MCP가 활성화되었는지 확인하기 위해 에디터를 재시작하세요.

실행에 성공하면, 로컬 실행 결과를 바탕으로 디버깅(debug)을 할 수 있습니다. 수정 사항을 바탕으로 자신만의 MCP 서비스를 구축할 수도 있습니다.

여러분의 코드 기여(code contributions)를 환영하며, MasterGo의 MCP 서비스를 함께 만들어 나가기를 기대합니다.

ISC