@granter-biz/cli

v0.6.1

Published

8 days ago

CLI & MCP server for Granter — tax invoice, accounting & HR automation

0High
0Medium
0Low

granter-biz

granter tax-invoice cash-receipt accounting cli mcp korea

granter-cli

Granter API를 위한 CLI & MCP 서버. 세금계산서, 현금영수증, 거래 내역, 급여, 재고, 전자결재까지 — 터미널 하나로 자동화합니다.

중요한 보안 기본값

이 버전부터 사용자가 의도하지 않은 실행을 줄이기 위해 기본 동작이 명확히 제한됩니다.

granter-mcp는 기본적으로 조회 도구만 노출합니다.
세금계산서 발행, 현금영수증 발행, 거래처/급여/결재 생성 같은 MCP 쓰기 도구는 GRANTER_MCP_ENABLE_WRITES=1을 설정한 경우에만 노출됩니다.
MCP 클라이언트에서 현재 상태가 헷갈리면 get_mcp_security_status 도구로 write tool 활성화 여부를 확인할 수 있습니다.
granter config --show는 API 키를 마스킹합니다. 전체 키 확인은 granter config --show --show-secret을 명시해야 합니다.
--base-url은 기본적으로 HTTPS만 허용합니다. 개발용 http://localhost, http://127.0.0.1, http://[::1]만 예외입니다.

설치

npm install -g @granter-biz/cli@latest --ignore-scripts

sudo npm install -g는 사용하지 마세요. 권한 오류가 나면 npm의 global prefix를 사용자 소유 경로로 바꾸거나 nvm/fnm/volta 같은 Node 버전 매니저를 사용한 뒤 다시 설치하세요.

안전한 설치/검증

설치 전 npm registry의 패키지 메타데이터를 확인하세요:

npm view @granter-biz/cli@latest name version repository.url maintainers dist.integrity dist.tarball

확인할 기준:

패키지명은 정확히 @granter-biz/cli입니다.
maintainer는 granter-biz <[email protected]>입니다.
repository.url은 github.com/granter-biz/granter-cli입니다.
dist.integrity 값은 npm registry가 제공하는 tarball 무결성 값입니다. 버전별 값은 GitHub Release 노트에도 함께 기록합니다.

설치 후에는 실행 파일과 버전을 확인하세요:

granter --version
granter --help

로컬에서 테스트

git clone https://github.com/granter-biz/granter-cli.git
cd granter-cli
npm install
npm run build
npm link          # granter, granter-mcp 명령어를 로컬에 등록
granter --help

운영 릴리즈 자동화

app-client public docs manifest와 CLI 카탈로그 동기화는 기본적으로 sibling repo 경로를 사용합니다:

npm run verify:api-sync

app-client 위치가 다르면 manifest 경로를 지정합니다:

GRANTER_APP_CLIENT_MANIFEST=/path/to/app-client/public/docs/public-api-manifest.json npm run verify:api-sync

문서 표시 순서까지 엄격히 비교해야 할 때는 --check-order를 넘깁니다:

npm run verify:api-sync -- --check-order

릴리즈는 다음 순서로 진행합니다. release:publish는 현재 버전의 npm 중복과 로컬/원격 태그 중복을 확인한 뒤 v{version} 태그를 push하고, GitHub Release workflow가 npm publish를 수행합니다.

npm run release:bump -- 0.2.2
npm run verify:release
git add CHANGELOG.md package.json package-lock.json src/cli.ts src/commands/init.ts src/mcp.ts
git commit -m "release 0.2.2"
npm run release:publish

이미 배포된 현재 릴리즈를 감사할 때는 npm/태그 중복을 허용합니다:

npm run verify:release:audit

MCP 서버도 바로 연결할 수 있습니다:

# Claude Code
claude mcp add granter -- granter-mcp

# 또는 절대 경로로
claude mcp add granter -- node /path/to/granter-cli/dist/mcp.js

설정

granter init은 그랜터에 로그인한 뒤 API 키를 자동으로 저장합니다. 대화형 터미널에서는 터미널에서 바로 로그인(이메일·비밀번호)할 수 있고, 결제·홈택스 인증서처럼 보안이 필요한 단계와 회원가입만 브라우저로 안내합니다:

granter init

테스트 키를 저장하려면:

granter init --key-type test

로그인은 기본적으로 터미널에서 진행됩니다(이메일을 비우고 Enter를 누르면 브라우저로 전환). 이메일을 미리 채우거나 항상 브라우저로 로그인하려면:

granter init --key-type test --email [email protected]   # 이메일만 미리 채움 (비밀번호는 가려진 채 입력)
granter init --key-type test --browser                 # 브라우저로 로그인

비밀번호는 화면에 표시되지 않고 저장·로깅되지 않으며 HTTPS로 한 번만 전송됩니다. 2단계 인증·소셜 로그인을 쓰면 자동으로 브라우저로 전환됩니다.

온보딩 중 현재 워크스페이스에 유료 구독이 없으면, CLI가 모든 워크스페이스와 각 구독 상태(유료 여부)를 보여주고 발급할 워크스페이스를 고르도록 안내합니다. 워크스페이스를 미리 지정하거나 항상 목록을 보려면:

# 워크스페이스를 id 또는 정확한 이름으로 지정 (비대화형/스크립트용)
granter init --key-type test --workspace 2892
granter init --key-type test --workspace "A지점"

# 온보딩 중 항상 워크스페이스 선택 목록 표시
granter init --key-type test --choose-workspace

이미 API 키를 발급받았다면 직접 설정할 수도 있습니다:

granter config --api-key YOUR_API_KEY

설정 확인:

granter config --show

--show는 API 키를 마스킹합니다. 전체 키 확인이 꼭 필요한 경우에만 granter config --show --show-secret을 사용하세요.

업데이트

granter update

granter update(별칭 granter upgrade)는 npm install -g @granter-biz/cli@latest --ignore-scripts를 실행해 최신 버전으로 갱신합니다. 특정 버전/태그를 지정하려면 granter update --tag 0.3.0처럼 사용하세요.

업데이트가 끝나면 이전 버전과 새 버전 사이의 변경 요약이 표시되며, 하위호환성이 깨지는 변경은 ⚠ BREAKING으로 강조됩니다. npm으로 직접 업데이트한 경우에도 다음 대화형 실행 시 버전 변경과 breaking 변경이 1회 안내됩니다.

대화형 터미널에서는 새 버전이 있을 때 명령 실행 시 안내가 표시됩니다(하루 1회 확인, stderr로만 출력, CI·파이프 환경에서는 비활성). 끄려면 다음 중 하나를 사용하세요:

export GRANTER_NO_UPDATE_CHECK=1   # 또는 NO_UPDATE_NOTIFIER=1, 또는 --no-update-check 플래그

릴리즈 노트 (사람 + AI 에이전트)

설치된 버전에 동봉된 릴리즈 노트를 언제든 확인할 수 있습니다:

granter changelog                    # 최신 릴리즈 1건
granter changelog --since 0.5.0      # 0.5.0 이후의 모든 변경 (breaking 강조)
granter changelog --all              # 전체 이력
granter changelog --since 0.5.0 --json   # 구조화 출력 (에이전트/스크립트용)

MCP를 쓰는 AI 에이전트는 get_changelog 도구(sinceVersion 파라미터)로 같은 정보를 조회할 수 있으며, 응답의 breaking[] 배열로 하위호환성 변경 여부를 판단할 수 있습니다.

유지보수 규칙: 하위호환성이 깨지는 릴리즈는 CHANGELOG 해당 버전에 ### Breaking changes 섹션(또는 호환 이 들어간 섹션 제목)으로 기록합니다. CLI·MCP의 breaking 감지는 이 섹션 제목을 기준으로 동작합니다.

API 탐색

CLI가 지원하는 Public API 전체 목록과 연결된 CLI 명령을 확인할 수 있습니다:

granter apis
granter apis --group assets
granter apis --group manual
granter apis --group organizations
granter apis --group workspace
granter apis --kind write
granter apis --search salary
granter apis show daily-financial-report
granter apis show daily-financial-report --format json
granter apis --json

사용법

조회

# 카드 사용 내역
granter tickets --type EXPENSE_TICKET --from 2026-04-01 --to 2026-04-30

# 계좌 입출금
granter tickets --type BANK_TRANSACTION_TICKET --from 2026-04-01 --to 2026-04-16

# 포스기/CREFIA 정산 상세 수수료 항목
granter tickets --type MERCHANT_CARD_SETTLEMENT_DETAIL_TICKET --from 2026-01-01 --to 2026-12-31

# 티켓 계정과목/태그/설명 수정
granter tickets-update --file ticket-update.json

# 티켓 데이터 갱신 요청
granter tickets-refresh

# 티켓 간 연결 생성/갱신
granter ticket-references --referenceable-id 90101 --referenceable-type TAX_INVOICE_TICKET
granter ticket-references create --file ticket-reference.json --idempotency-key ticket-ref-001
granter ticket-references delete --file ticket-reference-delete.json --idempotency-key ticket-ref-delete-001

# 기관 연동 상태 / 로그인 연동
granter organizations
granter organizations --is-connected true

# 인증서 위치를 모를 때는 후보를 먼저 찾습니다.
# NPKI 후보는 유효한 인증서를 먼저 보여주고, 소유자, 만료일, CA, fingerprint를 함께 출력합니다.
granter organizations certificate-find --query corporation
granter organizations certificate-find --query "회사명"

# 운영 실연동 전에 live key 여부, 인증서 후보, 정확한 --cert-file 기반 권장 실행 커맨드를 점검합니다.
granter organizations certificate-doctor --query corporation

# 기업 국민카드(KB)는 organization enum으로 KB를 사용합니다.
granter organizations certificate-connect --target-organization KB --client-type CORPORATE --query corporation --certificate-index 1

# 인증서 비밀번호는 커맨드 히스토리에 남기지 않도록 stdin 또는 환경변수로 전달합니다.
# 보안상 비밀번호를 직접 받는 --password 인자는 제공하지 않습니다.
printf '%s' "$CERT_PASSWORD" | granter organizations certificate-connect --target-organization KB --client-type CORPORATE --query corporation --certificate-index 1 --password-stdin
GRANTER_CERT_PASSWORD="$CERT_PASSWORD" granter organizations certificate-connect --target-organization KB --client-type CORPORATE --query corporation --certificate-index 1

# 운영 실연동 검증 시에는 test key로 샘플 응답을 받지 않도록 live key를 강제합니다.
printf '%s' "$CERT_PASSWORD" | granter organizations certificate-connect --target-organization KB --client-type CORPORATE --query corporation --certificate-index 1 --password-stdin --require-live-key

granter organizations login-connect --file organization-login-connect.json
granter organizations login-reconnect --file organization-login-reconnect.json

# 자산 목록 (카드, 계좌, 홈택스 등)
granter assets --type CARD
granter assets --type BANK_ACCOUNT
granter assets --type HOME_TAX_ACCOUNT

# 수기 자산 / 거래 입력
granter cards create --file card-create.json --idempotency-key card-001
granter bank-accounts create --file bank-account-create.json --idempotency-key bank-account-001
granter card-usages create --file card-usages-create.json --idempotency-key card-usages-001
granter bank-transactions create --file bank-transactions-create.json --idempotency-key bank-transactions-001

# 계좌 잔액 추이
granter balances --from 2026-04-01 --to 2026-04-16

# 자금일보
granter daily-financial-report --from 2026-04-01 --to 2026-04-16

# 워크스페이스 / 사용자 / 요금제
granter workspace-profile
granter user-profiles
granter subscription

# 거래처 / 구성원 / 팀
granter contacts
granter people
granter teams

# 계정과목 / 태그
granter categories
granter tags
granter tag-details

# 기준 데이터 생성/수정
granter tags create --file tag-create.json --idempotency-key tag-create-001
granter tags update --file tag-update.json
granter tag-details create --file tag-detail-create.json
granter tag-details update --file tag-detail-update.json
granter categories create --file category-create.json
granter categories update --file category-update.json
granter contacts create --file contact-create.json
granter contacts update --file contact-update.json
granter people invite --file people-invite.json

# 전자결재
granter workflows --status PENDING
granter workflows create --file workflow-create.json

# 급여 내역
granter salary --from 2026-03-01 --to 2026-03-31
granter salary create --file salary-create.json

# 재고
granter inventory products
granter inventory stock

# 근태 / 연차
granter attendance list --from 2026-04-01 --to 2026-04-16
granter attendance leave-balances
granter attendance leave-histories --from 2026-01-01 --to 2026-04-16

# 환율 / 공휴일
granter exchange-rates --base-date 2026-04-16
granter holidays --from 2026-04-01 --to 2026-04-30

포스기/CREFIA는 승인·매출 전표와 정산 상세가 분리됩니다. MERCHANT_CARD_TRANSACTION_TICKET은 카드 승인/매출 원거래 조회용이고, 수수료 항목(POS-가맹점수수료, POS-포인트수수료, POS-기타수수료, POS-매입금액)은 MERCHANT_CARD_SETTLEMENT_DETAIL_TICKET의 merchantSettlementDetailTransaction에서 확인합니다.

세금계산서 발행

JSON 파일로 payload를 작성한 뒤 발행합니다:

# 수기 세금계산서 기록 생성
granter invoice create --file tax-invoice-create.json --idempotency-key tax-invoice-001

# 발행
granter invoice issue --file invoice.json

# 수정발행
granter invoice modify --file modify.json

# 취소발행
granter invoice cancel --file cancel.json

{
  "issueType": "정발행",
  "taxType": "TAX",
  "chargeDirection": "정과금",
  "reportingDate": "2026-04-16",
  "issueScheduleType": "IMMEDIATE",
  "purposeType": "CHARGE",
  "supplyValue": 100000,
  "taxAmount": 10000,
  "totalAmount": 110000,
  "cash": 0,
  "check": 0,
  "bankBill": 0,
  "accountReceivable": 110000,
  "note": "4월 개발 용역",
  "supplier": {
    "registrationNumber": "1234567890",
    "companyName": "공급자 회사",
    "name": "담당자명",
    "email": "[email protected]",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "businessPlace": "서울특별시 강남구",
    "id": 101
  },
  "contractor": {
    "registrationNumber": "0987654321",
    "companyName": "거래처 회사",
    "name": "구매담당자",
    "email": "[email protected]",
    "businessTypes": "도매업",
    "businessItems": "소프트웨어 유통",
    "businessPlace": "서울특별시 서초구",
    "id": 202
  },
  "contractorType": "BUSINESS",
  "forceIssue": false,
  "writeSpecification": true,
  "tradeItems": [
    {
      "purchaseExpiryDate": "2026-04-16",
      "taxItemName": "개발 용역",
      "standards": "건",
      "quantity": 1,
      "unitPrice": 100000,
      "supplyValue": 100000,
      "taxAmount": 10000,
      "note": ""
    }
  ],
  "memo": ""
}

현금영수증

# 수기 현금영수증 기록 생성
granter cash-receipt create --file cash-receipt-create.json --idempotency-key cash-receipt-001

# 발행
granter cash-receipt issue --file receipt.json

# 취소
granter cash-receipt cancel --file cancel-receipt.json

MCP 서버 (AI 연동)

Claude Code, Claude Desktop 등 AI 도구와 연동하면 자연어로 Granter API를 사용할 수 있습니다.

Claude Code

claude mcp add granter -- granter-mcp

기본 MCP 서버는 조회 도구만 노출합니다. 세금계산서 발행, 현금영수증 발행, 거래처/급여/결재 생성 같은 쓰기 도구를 AI 클라이언트에 노출해야 하는 경우에만 MCP 서버 프로세스 환경변수에 GRANTER_MCP_ENABLE_WRITES=1을 지정하세요.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "granter": {
      "command": "granter-mcp"
    }
  }
}

쓰기 도구가 필요한 환경에서만 다음 env 블록을 추가하세요:

"env": {
  "GRANTER_MCP_ENABLE_WRITES": "1"
}

연동 후 이렇게 사용합니다

"이번 달 카드 사용 내역 보여줘"
"주식회사 베타에 4월분 세금계산서 100만원 발행해줘"
"3월 급여 내역 조회해줘"
"잔여 연차 확인해줘"
"오늘 환율 알려줘"

지원 API와 탐색 도구가 MCP에 등록되어 Granter API 기능을 자연어로 호출할 수 있습니다.

지원하는 API

| 도메인 | 명령어 | 설명 | |--------|--------|------| | 거래/증빙 | tickets tickets-update tickets-refresh ticket-references ticket-references create ticket-references delete | 카드, 계좌, 세금계산서, 현금영수증 조회, 갱신, 티켓 보정/연결 | | 자산 | assets | 카드, 계좌, 홈택스 연동 현황 | | 기관 연동 | organizations organizations certificate-find organizations certificate-doctor organizations certificate-connect organizations certificate-reconnect organizations login-connect organizations login-reconnect | 은행, 카드, 증권, 홈택스 기관 상태 조회 및 인증서/로그인 연동 | | 수기 입력 | cards create bank-accounts create card-usages create bank-transactions create invoice create cash-receipt create | 수기 자산, 거래, 증빙 기록 생성 | | 잔액 | balances | 계좌별 잔액 시계열 | | 기준 데이터 | tags tag-details categories people contacts teams | 분류/담당자/거래처 | | 전자결재 | workflows | 결재 문서 및 승인 상태 | | 급여 | salary | 급여 내역, 공제, 수당 | | 재고 | inventory products inventory stock | 품목 마스터, 재고 수량 | | 근태 | attendance list attendance leave-balances attendance leave-histories | 출결, 연차 | | 기타 | exchange-rates holidays | 환율, 공휴일 | | 세금계산서 | invoice issue invoice modify invoice cancel | 발행/수정/취소 | | 현금영수증 | cash-receipt issue cash-receipt cancel | 발행/취소 |

License

MIT