@thinkdata/cli

ThinkERD CLI — 데이터베이스 스키마를 ERD로 가져오고, AI 에이전트에 연결한다

하나의 도구에 네 가지 모드가 있습니다.

| 명령 | 하는 일 | |---|---| | mcp | MCP 서버로 동작 — Claude Code·Cursor 등이 ERD를 조회 | | extract | DB 스키마를 뽑아 ERD에 반영 | | compare | DB와 ERD 모델의 차이 비교 | | serve | 브라우저(ThinkERD 웹)용 로컬 에이전트 |

mcp 모드 하나로 읽기와 쓰기가 모두 됩니다 — 0.3.2부터 sync_schema_from_database 도구가 DB에 직접 접속해 다이어그램에 반영합니다. 셸 스크립트도, 별도 명령도 필요 없습니다. extract·compare는 CI처럼 에이전트가 없는 자리를 위해 남아 있습니다.

사전 준비

ThinkERD 앱 메뉴 → Settings → Developer & API 에서 Personal Access Token(PAT)을 발급합니다. Pro 이상 플랜에서 가능하며, 스키마를 반영하려면 write 스코프가 필요합니다.

스코프는 필요한 만큼만 주십시오. 워크스페이스를 지정해 발급하면 그 밖의 리소스는 조회되지 않습니다.

MCP 연결

.mcp.json(Claude Code) 또는 각 IDE의 설정 파일에 넣습니다.

{
  "mcpServers": {
    "thinkerd": {
      "command": "npx",
      "args": ["-y", "@thinkdata/cli", "mcp"],
      "env": {
        "THINKERD_API_URL": "https://api.thinkerd.io",
        "THINKERD_TOKEN": "<발급받은 PAT>",
        "THINKERD_DIAGRAM_ID": "<다이어그램 UUID>"
      }
    }
  }
}

THINKERD_DIAGRAM_ID는 sync_schema_from_database 도구가 씁니다 — 없으면 그 도구만 못 쓰고 조회는 그대로 됩니다.

DB 접속 문자열은 여기에 적지 마십시오. 작업 디렉토리의 .env에 있는 DATABASE_URL을 CLI가 직접 읽습니다. 이 파일에 또 적으면 자격증명이 두 곳에 생깁니다.

| IDE | 설정 파일 | |---|---| | Claude Code | 레포 루트 .mcp.json (또는 claude mcp add) | | Cursor | ~/.cursor/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json |

⚠️ .mcp.json에는 토큰이 평문으로 들어갑니다. .gitignore에 .mcp.json을 넣고, 팀에는 값 없는 .mcp.json.example만 커밋하십시오.

CLI는 작업 디렉토리의 .env에서 THINKERD_*와 DATABASE_URL도 읽습니다(이미 환경에 있는 값은 덮지 않습니다). 그 파일에 이미 값이 있다면 env 블록을 통째로 비워도 됩니다. 나머지 키는 읽지 않습니다 — 쓰지도 않을 자격증명을 끌어올 이유가 없습니다.

Claude Code는 Claude Desktop의 설정 파일을 읽지 않습니다. 이름이 비슷해 그쪽 경로를 따라가는 경우가 있는데, JSON 형식은 같아도 파일이 다릅니다.

종전의 @thinkdata/mcp-server 도 계속 동작합니다(별칭). 다만 그쪽은 MCP만 있고 extract가 없어, 새로 설정한다면 이 패키지를 쓰는 편이 낫습니다.

DB 스키마를 ERD에 반영 — sync_schema_from_database

에이전트에게 "ERD 동기화해줘"라고 하면 됩니다. 실제 DB에 붙어 테이블·컬럼·FK를 읽고 다이어그램에 병합합니다.

• 방향은 하나입니다. DB(마이그레이션 결과)가 정본이고 ERD가 따라갑니다.
• 병합이라 캔버스 배치·색·주제영역은 보존됩니다.
• DB에서 사라진 테이블도 지우지 않고 보고만 합니다 — 설계 중인 엔터티가 ERD에 먼저 있을 수 있기 때문입니다.
• PostgreSQL·MySQL·Oracle·SQL Server를 지원합니다. 드라이버는 optionalDependencies라 없으면 설치 안내가 나옵니다.

diagramId·connectionString을 인수로 줄 수도 있고, 생략하면 위 env의 THINKERD_DIAGRAM_ID·DATABASE_URL을 씁니다.

스키마를 ERD에 반영 — CLI 경로 (CI용)

에디터에서는 위의 sync_schema_from_database 도구를 쓰십시오. 아래는 에이전트가 없는 자리(CI·마이그레이션 훅)를 위한 같은 동작의 명령입니다.

npx @thinkdata/cli extract "postgresql://user:pass@host:5432/db" \
    --diagram <다이어그램ID> --pat thkd_...

병합입니다. 캔버스 좌표·색·주제영역은 보존하고 컬럼과 관계만 갱신합니다. DB에서 사라진 엔터티는 지우지 않고 세어서 알려 줍니다 — 설계 중인 테이블이 ERD에 먼저 그려져 있을 수 있기 때문입니다.

다이어그램 ID 찾는 곳: 탐색기에서 다이어그램 우클릭 → Properties → Identification Information → ID (복사 아이콘). 주소창에는 나오지 않습니다.

--diagram 없이 실행하면 브라우저가 폴링해 가는 종전 경로로 동작합니다.

마이그레이션 훅에 붙이기

스키마가 바뀔 때마다 ERD가 따라오게 하려면 마이그레이션 뒤에 겁니다.

{
  "scripts": {
    "db:migrate": "drizzle-kit migrate && npm run erd:sync",
    "erd:sync": "thinkdata extract $DATABASE_URL --diagram $THINKERD_DIAGRAM_ID --pat $THINKERD_PAT"
  }
}

이 훅을 두려고 셸 스크립트 파일을 만들 필요는 없습니다. 예전에는 .env를 소싱하려고 래퍼를 두는 형태가 흔했는데, 값은 CI 시크릿으로 넣고 위 한 줄이면 됩니다.

DB 드라이버는 선택 설치입니다

pg·mysql2·oracledb·mssql 은 optionalDependencies 이고 실제로 그 DB에 접속할 때만 로드됩니다. MCP만 쓰는 경우 드라이버가 없어도 됩니다.

설치되지 않은 드라이버를 쓰려 하면 무엇을 깔아야 하는지 알려 줍니다.

명령 목록

thinkdata mcp        [--api-url <url>] [--token <pat>] [--dev]
thinkdata extract    <connection-string> [--diagram <id>] [--pat <token>] [--schema <name>]
thinkdata compare    <connection-string> [--project <id>] [--pat <token>]
thinkdata serve      [--port 3100]
thinkdata login      [token]
thinkdata whoami

환경변수

| 변수 | 설명 | 기본값 | |---|---|---| | THINKERD_API_URL | ThinkERD API URL | https://api.thinkerd.io | | THINKERD_TOKEN | Personal Access Token | — |

보안

• 토큰은 SHA-256 해시로만 서버에 저장됩니다
• 워크스페이스/프로젝트 단위로 접근 범위를 제한할 수 있습니다
• 토큰 만료일을 설정할 수 있습니다 (기본 90일)

라이선스

MIT