arc-mcp

Exact code-to-design

plan_exact_design_extraction 과 extract_exact_design_document 는 @arc/design exact-first pipeline 을 arc-mcp에서 바로 쓰기 위한 도구입니다.

기본 동작:

1. workspacePath 기준으로 git root 를 workspace root 로 확정
2. runtimeBindingSources가 없으면 로컬 ARC web emitter manifest 를 자동 탐지
3. manifest 에 knownRoutes가 있으면 아직 contract 가 없는 route 만 자동 warm-up
4. fingerprint + runtime endpoint manifest + materialized endpoint 로 exact plan 생성
5. plan된 contract profile 에 맞는 extractor 만 실행

로컬 ARC web exact emitter 기본 경로:

• http://127.0.0.1:4173/.well-known/arc/web-render-contract-manifest.json
• http://localhost:4173/.well-known/arc/web-render-contract-manifest.json
• http://127.0.0.1:4174/.well-known/arc/web-render-contract-manifest.json
• http://localhost:4174/.well-known/arc/web-render-contract-manifest.json

자동 탐지가 싫으면 runtimeBindingSources를 직접 넘기면 됩니다.

중요:

• route warm-up 은 crawl 이 아닙니다.
• ARC web emitter 가 선언한 knownRoutes inventory 만 방문합니다.
• :slug 같은 동적 파라미터는 현재 pipeline slug 로만 해석합니다.
• 로컬 shell에 ARC_ACCESS_TOKEN/ARC_API_KEY가 없어도, Windsurf ~/.codeium/windsurf/mcp_config.json의 mcpServers.arc.env를 fallback으로 읽습니다.

Tool example

계획만 확인:

plan_exact_design_extraction(
  workspacePath="/Users/me/project/ARC/apps/web"
)

정확 추출 실행:

extract_exact_design_document(
  workspacePath="/Users/me/project/ARC/apps/web",
  outputFilePath="output/design/exact-document.json"
)

전체 document JSON도 응답에 같이 포함:

extract_exact_design_document(
  workspacePath="/Users/me/project/ARC/apps/web",
  includeDocumentJson=true
)

Figma bridge

capture_page_to_figma 는 Windsurf/Cascade에 generate_figma_design 가 직접 노출되지 않을 때 쓰는 우회 도구입니다.

동작 방식:

1. arc-mcp 가 Figma Remote MCP(https://mcp.figma.com/mcp)에 클라이언트로 연결
2. 내부적으로 generate_figma_design 를 호출해 captureId 생성
3. Playwright + 시스템 Chrome으로 대상 페이지를 열고 capture.js 를 주입
4. window.figma.captureForDesign(...) 를 실행
5. Figma Remote MCP를 polling 해서 최종 Figma URL 반환

Auth source priority

Figma 토큰은 아래 순서로 찾습니다.

1. arc-mcp 프로세스 env 의 FIGMA_OAUTH_TOKEN
2. arc web 에 저장된 현재 사용자용 Figma token (/api/me/integrations/figma/token)

즉, tenant에서 개발자 연결이 허용된 사용자라면 FIGMA_OAUTH_TOKEN 을 매번 로컬 env에 넣지 않아도 됩니다.

Recommended env

{
  "mcpServers": {
    "arc": {
      "command": "npx",
      "args": ["-y", "arc-mcp@latest"],
      "env": {
        "ARC_ACCESS_TOKEN": "<arcs-... session token>",
        "FIGMA_REGION": "us-east-1"
      }
    }
  }
}

선택 env:

• FIGMA_OAUTH_TOKEN: 서버 저장 토큰 대신 로컬 env 토큰을 우선 사용할 때
• ARC_CHROME_PATH: Chrome 실행 파일 경로를 강제로 지정할 때 사용
• FIGMA_MCP_URL: 기본값은 https://mcp.figma.com/mcp
• ARC_WEB_URL: ARC web dev server base URL 자동 탐지 override
• ARC_WEB_MANIFEST_URL: exact design extraction 용 runtime binding manifest URL override

하위 호환:

• ARC_API_KEY: 기존 env 이름도 계속 읽지만, 신규 설정은 ARC_ACCESS_TOKEN 권장

Tool example

기존 Figma 페이지에 넣기:

capture_page_to_figma(
  targetUrl="http://127.0.0.1:4173/admin",
  outputMode="existingFile",
  figmaUrl="https://www.figma.com/design/<fileKey>/Arc-Design?node-id=15-2"
)

새 파일 만들기:

capture_page_to_figma(
  targetUrl="http://127.0.0.1:4173/",
  outputMode="newFile",
  planKey="team::<planKey>"
)