
══════════════════════════════════════════════════════
  K-System MCP - 설치 안내 (v0.5 기준)
══════════════════════════════════════════════════════

  K-System ACE ERP를 Claude AI로 자동화하는 도구입니다.
  사전에 관리자가 회사를 등록해두어야 하며, 본인의 회사
  이메일로 인증해 사용합니다.


──────────────────────────────────────────────────────
[★ Windows 쉬운 설치 — install.bat 더블클릭 권장]
──────────────────────────────────────────────────────

  install.bat 한 개로 설치 전 과정이 자동 처리됩니다.
  사용자 입력은 (1) 이메일 OTP (2) config.json DB 정보 두 개만.

  ● 사용법
    1. 브라우저에서 install.bat 다운로드 → 임의 폴더에 저장
       https://aitwin.flextudio.com/client/install.bat
    2. 더블클릭 → UAC "예"
    3. 자동 진행 (Node/Git/Claude/MCP 자동) — 약 2~5분
    4. 이메일 OTP 입력 → 메모장에서 config.json 편집·저장 → 연결 테스트 자동

  ● 적용 환경
    Windows 10 1809+ 또는 11 (winget 사용 가능 환경)
    winget이 차단된 환경에선 아래 수동 절차([1단계] 이후) 사용


──────────────────────────────────────────────────────
[1단계] 사전 설치 (처음 1회만) — 수동 절차
──────────────────────────────────────────────────────

  아래 3개를 순서대로 설치합니다.
  이미 설치되어 있으면 건너뛰세요.

  ★★★ 매우 중요 ★★★
  각 설치 후 반드시 cmd를 닫고 새로 열어야 합니다!
  (안 열면 방금 설치한 프로그램이 인식되지 않습니다)

  (1) Node.js — 반드시 LTS 버전
      https://nodejs.org 접속 → 왼쪽 "LTS" 버튼 클릭 → 설치 (모두 Next)
      ★ cmd를 새로 열고 확인: node -v

  (2) Git
      ★ cmd를 새로 열고: winget install Git.Git
      (또는 https://git-scm.com → 다운로드 → 설치, 모두 Next)
      ★ cmd를 새로 열고 확인: git --version

  (3) Claude Code
      ★ cmd를 새로 열고: npm install -g @anthropic-ai/claude-code
      ★ cmd를 새로 열고 확인: claude --version

      "claude"이 인식되지 않으면:
      → cmd에서: npm config get prefix
      → 나오는 경로를 복사 (예: C:\Users\사용자명\AppData\Roaming\npm)
      → cmd에서: setx PATH "%PATH%;복사한경로"
      → cmd를 새로 열고 다시: claude --version

  (3-1) Git Bash 경로 설정
      ★ cmd에서 아래 한 줄을 그대로 복사+붙여넣기:
      setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"
      ★ cmd를 새로 열어야 적용

  (3-2) Claude 로그인
      ★ cmd에서: claude
      → 로그인 방식 선택이 나오면 ★ 반드시 1번 선택 ★
        ("Anthropic" 선택하면 API Platform으로 연결되므로 주의!)
      → 브라우저가 열리면 claude.ai 계정으로 로그인
      → 로그인 완료 후 cmd로 돌아옴
      → Ctrl+C 로 종료


──────────────────────────────────────────────────────
[2단계] K-System MCP 설치
──────────────────────────────────────────────────────

  1. zip 파일을 C:\ksystem-mcp 에 압축 해제
     (zip 다운로드: https://aitwin.flextudio.com/client/ksystem-mcp-latest.zip)

     ★ 주의: 폴더가 이중으로 되지 않도록!
       올바름: C:\ksystem-mcp\ksystem-mcp.cjs
       잘못됨: C:\ksystem-mcp\ksystem-mcp\ksystem-mcp.cjs

  2. ★ cmd에서:
     cd C:\ksystem-mcp
     npm install

     "added XX packages" 가 나오면 성공

  3. ★ cmd에서 이메일 인증:
     node setup.cjs

       API 서버: Enter (기본값 자동)
       회사 이메일: 본인의 회사 이메일 입력 (관리자가 등록한 도메인)
       → 이메일로 6자리 인증 코드가 도착합니다
       인증 코드: 받은 6자리 코드 입력
       ✅ 등록 완료

     setup.cjs를 처음 실행하면 인증을 먼저 진행합니다.
     인증이 끝나면 DB 접속정보 입력용 브라우저 화면이 자동으로 열립니다.

  4. ★ 브라우저 관리 화면에서 DB 정보 입력

     인증 직후 자동으로 열립니다. 안 열리면 cmd에 표시된 URL을 복사해 여세요.
     (나중에 다시 열려면: Claude에게 "DB 설정 열어줘" → manage_database)

     서버·사용자명·비밀번호·DB명을 입력 → [연결 테스트] → [저장].

     ⚠ 사용자명·비밀번호는 이 PC에 묶인 키로 암호화되어 저장됩니다.
        config.json에 평문으로 남지 않습니다.
     ⚠ config.json을 직접 편집하지 마세요. Claude에게 "config.json에 DB 정보
        넣어줘"라고 시키는 것도 안 됩니다 — 차단되어 있습니다.
        (암호화를 우회해 평문이 남고, 연결 테스트가 깨집니다)
     ⚠ 비밀번호를 Claude 프롬프트(대화창)에 입력하지 마세요. 반드시 위 관리 화면의
        비밀번호 입력란을 쓰세요.
        이슈 리포트(report_issue)가 최근 프롬프트 5건을 자동 첨부해 개발팀 서버로
        보내기 때문에, 대화창에 친 비밀번호는 외부로 나갈 수 있습니다.
     ⚠ 인증 토큰은 auth.json에 별도 저장됩니다 (시스템이 자동 관리 — 건드리지 마세요)

     저장 후 [연결 테스트]가 성공하면 다음 단계로 진행.


──────────────────────────────────────────────────────
[config.json 구조 — 참고용 (직접 편집하지 마세요)]
──────────────────────────────────────────────────────

  ⚠ 아래는 관리 화면이 저장하는 결과 형식입니다. 무엇이 저장되는지 이해하기
     위한 참고 자료이지, 손으로 적어 넣는 양식이 아닙니다.
     config.json 직접 편집은 차단되어 있습니다.

  ✅ databases 안에 여러 DB를 등록하고 active_database로 선택해 사용합니다.
  ✅ 인증 토큰(auth.json)은 시스템이 자동 관리 — config.json엔 DB 정보만.
  ✅ username·password는 ENC: 로 시작하는 암호문으로 저장됩니다 (이 PC 전용 키).

  {
    "active_database": "DOOSANERP",   ← 지금 사용중인 DB 이름 (= 업무DB명)

    "databases": {

      "DOOSANERP": {                  ← DB 키 = 실제 업무DB명
        "server":   "192.168.10.50",
        "username": "ENC:...",        ← 관리 화면이 암호화해 기록
        "password": "ENC:..."
      },

      "SAMSUNGERP": {
        "server":   "192.168.20.30",
        "username": "ENC:...",
        "password": "ENC:..."
      }
    }
  }

  ✅ 관리 화면에서 입력할 최소 항목은 서버 + 사용자명 + 비밀번호 3개입니다.
     - DB 키("DOOSANERP") = 실제 업무DB명 → biz_database 자동
     - ops_database 미지정 시 업무DB + "Common" 자동 (예: DOOSANERPCommon)
     - port=1433, auth="sql", company_seq=1 미지정 시 기본값

  ※ Windows 인증을 쓰는 DB라면 관리 화면에서 인증 방식을 "Windows"로 선택하세요.
     Windows 계정과 도메인은 인증한 회사 이메일에서 자동으로 파생하므로
     따로 입력하지 않습니다 (계정은 config.json에 저장되지 않습니다).

  ※ 운영DB명이 업무DB+"Common" 규칙과 다르면 관리 화면의 운영DB 칸에 직접 지정.

  ● 필드 설명 (관리 화면 입력 항목 ↔ 저장 형식)
    server         DB 서버 주소 (SSMS의 "서버 이름" 부분)
                     예) 192.168.10.50, demosql.ksystemace.com
    username       DB 사용자명 (SQL 인증) — 암호화 저장
                     * Windows 인증은 저장하지 않음 (인증 이메일에서 파생)
    password       비밀번호 — 암호화 저장 (평문으로 남지 않음)
    port           DB 포트 (생략 시 1433)
    auth           "sql" (기본) 또는 "windows"
    biz_database   업무 DB 이름 (생략 시 databases 키 사용)
    ops_database   운영 DB 이름 (생략 시 업무DB + "Common")
    company_seq    법인 ID (생략 시 1)

  ● 가장 간단한 케이스 (1개 DB만)
    databases에 1개만 두고 active_database를 그 이름으로 설정.

  ● 여러 DB 사용
    databases에 여러 키 추가 → active_database만 바꿔서 전환.

  ● 연결 테스트
    cmd에서 node setup.cjs → 활성 DB 자동 테스트


──────────────────────────────────────────────────────
[3단계] Claude Code에 연결
──────────────────────────────────────────────────────

  ★ cmd에서 아래 한 줄을 그대로 복사+붙여넣기:

  claude mcp add-json ksystem -s user "{\"type\":\"stdio\",\"command\":\"node\",\"args\":[\"C:/ksystem-mcp/launcher.cjs\"]}"

  "Added stdio MCP server ksystem" 이 나오면 성공
  한 번만 실행하면 이후 자동 연결됩니다.

  ★ 중요: launcher.cjs가 매번 자동 업데이트를 확인합니다.
  새 버전이 나오면 다음 실행 시 자동으로 받아 적용합니다.

  Mac에서는:
  claude mcp add-json ksystem -s user '{"type":"stdio","command":"node","args":["/Users/사용자명/ksystem-mcp/launcher.cjs"]}'


──────────────────────────────────────────────────────
[4단계] 사용 시작
──────────────────────────────────────────────────────

  ★ 반드시 C:\ksystem-mcp 폴더에서 실행!

  cd C:\ksystem-mcp
  claude

  ※ 도구 권한 확인 창은 자동 설정됩니다 (v0.5.6+).
     처음 1~2회 세션 이후에는 묻지 않습니다.

  Claude가 시작되면 자연어로 말하세요:

    "이 고객사의 영업 환경설정을 알려줘"
    "수주입력 화면의 체크 로직을 분석해줘"
    "구매발주에 승인일 필드를 추가하는 SP를 만들어줘"
    "영업 프로세스 체인을 자동 테스트해줘"
    "이번 달 수주 현황을 보여줘"

  종료: Ctrl+C 또는 "exit" 입력

  바탕화면 바로가기:
    1. 메모장에 아래 입력:
       cd /d C:\ksystem-mcp
       claude
    2. "claude시작.bat" 으로 저장 → 바탕화면에서 더블클릭


══════════════════════════════════════════════════════
  여기까지가 설치입니다.
  아래는 사용 중 필요할 때 참고하세요.
══════════════════════════════════════════════════════


──────────────────────────────────────────────────────
[등록이 안 될 때]
──────────────────────────────────────────────────────

  Q. "등록된 회사가 없습니다" 에러
  A. 관리자에게 본인 회사가 등록되어 있는지 + 도메인이 허용된 이메일인지
     확인 요청하세요.

  Q. 인증 메일이 안 옴
  A. 스팸함 확인. 그래도 없으면 관리자에게 SES 발신 도메인 확인 요청.

  Q. "코드가 일치하지 않습니다"
  A. 이메일의 가장 최근 코드 사용. 5회 틀리면 새로 발송 필요.

  Q. "force_update" 에러
  A. 사용 중인 버전이 너무 낮음. 최신 zip으로 업데이트.


──────────────────────────────────────────────────────
[설정 변경 — 관리 화면에서만]
──────────────────────────────────────────────────────

  Claude에게 이렇게 말하세요:
      "DB 설정 열어줘"          (= manage_database action=open)
  브라우저 관리 화면이 열립니다. 추가·수정·삭제·활성 전환·연결 테스트를
  전부 여기서 합니다.

  ⛔ config.json 직접 편집은 차단되어 있습니다.
     · 메모장으로 고치는 것도, Claude에게 고쳐 달라고 하는 것도 안 됩니다.
     · Claude가 config.json을 수정하려 하면 권한 규칙이 거부합니다.
     · 이유: 손으로 적으면 비밀번호가 평문으로 남고, Windows 인증은 계정이
       잘못 저장돼 연결 테스트가 18452 오류로 깨집니다.
  (launcher 자동 업데이트 시에도 config.json은 절대 덮어쓰지 않습니다)

  ※ 인증 토큰은 같은 폴더의 auth.json에 별도 저장됩니다 (시스템이 자동 관리 — 건드리지 X).

  ● 비밀번호 변경
    관리 화면 → 해당 DB 선택 → 비밀번호 입력 → [저장]
    (활성 DB면 즉시 재연결 — MCP 재시작 불필요)

  ● DB 전환 (등록된 DB 끼리)
    Claude에게 "OO DB로 전환해줘"  또는 관리 화면에서 [활성으로]

  ● 새 DB 추가
    관리 화면 → [추가] → 입력 → [연결 테스트] → [저장]


──────────────────────────────────────────────────────
[setup.cjs 역할]
──────────────────────────────────────────────────────

  node setup.cjs 는 두 가지 일만 합니다:

    1) 처음 실행: 이메일 OTP로 인증 → 브라우저 관리 화면 자동 열기 →
                  DB 입력·저장 후 Enter → 자동 연결 테스트
    2) 이후 실행: 활성 DB(active_database)에 자동 연결 테스트

  DB 정보 변경(서버·DB명·비밀번호·DB 전환 등)은 모두
  브라우저 관리 화면에서 합니다. (위 [설정 변경 — 관리 화면에서만] 참고)

  ● DB 변경 후 Claude에 반영하기 (★ 중요)

    config.json을 수정해도 Claude에는 바로 반영되지 않습니다.
    MCP 서버를 재시작해야 새 설정이 로드됩니다.

    [방법 1] Claude 대화 중에 재시작 (추천)
       1. Claude 대화창에서 /mcp 입력
       2. ksystem 선택 → "restart" 선택
       3. "connected" 가 나오면 새 설정으로 연결된 것

    [방법 2] Claude 자체 재시작
       1. Ctrl+C 로 Claude 종료
       2. cd C:\ksystem-mcp
       3. claude


──────────────────────────────────────────────────────
[이상 보고]
──────────────────────────────────────────────────────

  사용 중 오류가 나면 Claude에게 말하세요:

    "이슈 리포트 해줘"


──────────────────────────────────────────────────────
[업데이트]
──────────────────────────────────────────────────────

  Claude Code MCP를 launcher.cjs로 등록해 두면 (3단계 참고),
  Claude를 시작할 때마다 자동으로 최신 버전을 확인합니다. 별도 작업 불필요.

  새 버전은 Claude가 켜진 뒤 뒤에서 조용히 받아 두고, 다음에 Claude를 시작할 때
  적용합니다. 업데이트 확인이 기동을 붙잡지 않게 하려는 것입니다
  (예전엔 여기서 최대 10초를 기다려 콜드 부팅 첫 세션이 도구 0개로 시작하곤 했습니다).
  적용이 끝나면 첫 도구 응답에 "자동 업데이트 완료" 알림이 1회 표시됩니다.

  응급 복구(파일 깨짐 등) 필요 시 install.bat 재실행으로 새로 받을 수 있습니다:
    https://aitwin.flextudio.com/client/install.bat


──────────────────────────────────────────────────────
[문제 해결]
──────────────────────────────────────────────────────

  Q. 설치 후 명령어가 인식되지 않음
  A. ★ cmd를 닫고 새로 여세요. 이것만으로 대부분 해결됩니다.

  Q. "requires git-bash" 에러
  A. setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"
     → cmd를 새로 열고 다시 시도

  Q. DB 연결 실패
  A. SSMS에서 동일 정보로 접속되는지 먼저 확인
     node setup.cjs 로 접속정보 수정 후 재시도

  Q. MCP 도구가 안 보임
  A. claude mcp remove ksystem
     claude mcp add-json ksystem "{\"type\":\"stdio\",\"command\":\"node\",\"args\":[\"C:/ksystem-mcp/launcher.cjs\"]}"
     ★ 경로에 \ 대신 / 사용!
     ★ C:\ksystem-mcp 폴더에서 claude를 실행했는지 확인

  Q. 서버는 "Connected"인데 ksystem 도구가 0개 (특히 PC를 켠 직후 첫 세션)
  A. Claude Code는 MCP 서버가 뜨기를 기본 30초까지만 기다리고,
     넘으면 그 세션을 도구 없이 시작합니다. 세션을 새로 열면 정상인 이유입니다.
     ★ 우선 Claude Code를 완전히 닫고 새로 열어 보세요 (대부분 이걸로 해결).
     ★ 그래도 반복되면 대기 시간을 늘리세요 — MCP_TIMEOUT (단위: 밀리초)

       setx MCP_TIMEOUT 60000

       → 반드시 cmd와 Claude Code를 모두 닫고 새로 열어야 적용됩니다.

     ⚠ MCP_TIMEOUT은 "기다리는 쪽"인 Claude Code 클라이언트의 환경변수입니다.
       .claude.json 의 서버 "env" 블록에 적어도 효과가 없습니다 —
       그 값은 MCP 서버(자식 프로세스)에만 전달되고, 정작 기다리는 클라이언트는
       계속 기본 30초를 씁니다. 위처럼 사용자 환경변수로 설정하세요.

     ※ 참고: 0.6.6부터 업데이트 확인이 기동을 붙잡지 않습니다([업데이트] 참고).
        그 전 버전에서는 업데이트 확인만으로 최대 10초가 소모됐습니다.


──────────────────────────────────────────────────────
[Mac 사용자]
──────────────────────────────────────────────────────

  Windows와 다른 점만:
  - 설치 경로: ~/ksystem-mcp
  - Git Bash 설정 불필요
  - 인증: SQL Server 인증만 사용 가능
  - 연결: claude mcp add-json ksystem '{"type":"stdio","command":"node","args":["/Users/사용자명/ksystem-mcp/launcher.cjs"]}'
  - 실행: cd ~/ksystem-mcp && claude


──────────────────────────────────────────────────────
[이 도구는 무엇인가요?]
──────────────────────────────────────────────────────

  K-System MCP는 Claude AI가 ERP 데이터베이스에 직접 접근하여
  분석/구축/테스트를 수행하도록 돕는 도구입니다.

  사용자 ──> Claude AI ──> K-System MCP ──> ERP DB

  ● Claude AI: 사용자 질문을 이해하고, 도구를 선택하고,
    SP를 분석하고, 코드를 생성합니다.

  ● K-System MCP: Claude가 모르는 ERP 전문 지식을 제공합니다.
    - 화면의 서비스WF, 이벤트, Lua, CodeHelp, 환경설정 분석
    - 프로세스 체인 연결 관계 (견적→수주→출하→거래명세서→매출)
    - 확정/중단/진행/점프 메커니즘
    - ERP 화면의 조회/저장/삭제를 AI가 직접 실행
    - SP/테이블/필드 역추적, Site 커스터마이징 비교

  ● 이런 일을 할 수 있습니다:
    - "수주입력 화면 분석해줘" → 비즈니스 규칙 분석
    - "구매발주에 승인일 추가하는 SP 만들어줘" → 코드 생성 + 검증
    - "영업 프로세스 테스트해줘" → 견적→수주→출하 자동 실행
    - "이번 달 수주 현황 보여줘" → 데이터 즉시 조회
    - "이 SP 어디서 쓰이지?" → 역추적
    - "사용자 매뉴얼 만들어줘" → HTML 산출물 생성


[선택] 화면 구동 기능 (execute_ui)
──────────────────────────────────────
실제 웹 화면을 자동 구동하는 기능입니다 — 화면 검증, 기초 데이터 입력, 실사용 흐름 재현, 시연. 필요할 때만 설치하세요.

  cd ksystem-mcp/playwright-poc
  npm install
  npx playwright install chromium     (브라우저 ~170MB 다운로드)

로그인 계정은 DB 설정 화면(관리 UI)의 "ERP 접속정보"에 입력하면
자동 로그인되며, 비워두면 최초 1회 브라우저 창에서 직접 로그인합니다.
사내 프록시로 다운로드가 막히면 PLAYWRIGHT_DOWNLOAD_HOST 로 미러를 지정하세요.


══════════════════════════════════════════════════════
  K-System MCP  engineered by Olim
  Powered by K-System ACE Framework + Claude AI
══════════════════════════════════════════════════════
