Frame

curl -H "Authorization: Bearer $FRAME_MCP_TOKEN" \
  https://axe.axelabs.ai/frame/schemas

{
  "version": "1.0",
  "service": "frame",
  "schemas": {
    "[email protected]": {
      "description": "단일 계정의 시점 잔액 (debit/credit 합계 + 순 balance).",
      "produced_by": ["query_balance"],
      "key_fields": ["entity_id", "account_code", "as_of_date", "debit", "credit", "balance", "policy_id"]
    },
    "[email protected]": { ... },
    "[email protected]": { ... }
  }
}

src/frame/
├── auth.py                  TokenClaims, encode/decode_token
├── auth_oidc.py             Microsoft id_token 검증
├── config.py                customers.yaml 로더 + accessor
├── cli.py                   37+ click commands
├── errors.py                FrameError 계층
├── observability.py         @instrument, Prometheus
│
├── db/
│   ├── engine.py            async pool, context manager
│   ├── shared.py            shared 테이블 정의
│   ├── entity.py            entity 메타 factory (35개 테이블)
│   └── migrations.py        upgrade_all(), register_entity()
│
├── ingest/                  파일 → raw_transaction
│   ├── reader.py            xls/xlsx/csv parser
│   ├── llm.py               Claude format 분석
│   ├── profile.py           format_profile 캐시
│   ├── hometax.py           홈택스 vendor
│   ├── kb_fund.py           KB 펀드
│   └── card.py              카드사
│
├── accounting/              M2+ 회계 계층
│   ├── chart.py             chart-of-accounts
│   ├── journal.py           분개 모델
│   ├── classify.py          raw → journal_line
│   ├── balance.py           trial_balance, B/S
│   └── reconcile.py         대사
│
├── ops/                     MCP tool 로직
│   ├── queries.py
│   ├── write.py             post_journal (5계층 검증)
│   ├── period.py            list_periods, transition_period
│   ├── workflow.py          reconcile_and_propose, closing_*
│   ├── open_item.py
│   ├── quarterly_close.py
│   └── snapshot.py
│
├── mcp/                     MCP 서버
│   ├── server.py            FastMCP instance, 44 tools 등록
│   ├── http_server.py       Starlette, OAuth middleware
│   ├── prompts.py           4 prompts (reconcile_walkthrough 등)
│   ├── oauth.py             OAuth proxy (D-ops-15, dormant)
│   └── tools/               각 tool 구현 (13 .py)
│
├── security/
│   └── pii.py               pgcrypto pgp_sym_encrypt
│
alembic/
├── versions/                shared (0001~0007)
└── entity_versions/         per-entity (0001~0016)

docs/ops/                    운영 정책 6 파일
├── naming-conventions.md
├── access-control.md
├── jwt-issuance.md
├── mcp-client-config.md
├── onboarding-operator.md
└── onboarding-employee.md

# DB
frame migrate                          # shared + 모든 entity
frame register-entity --id axec --legal-name "에이엑스이 코퍼레이션"
# fund (D-ops-22, 2026-05-22) — KIP / KVF 등록
frame register-entity --id axev_kvf_001 \
    --legal-name "AXE 시드 1호 벤처투자조합" \
    --kind kvf \
    --fund-meta '{"founded_at":"2024-03-15","commitment_total_krw":5000000000,"term_years":7}'
frame list-entities
 
# 기간
frame open-period --entity axec --year 2026
frame close-period --entity axec --period-id 7 --status soft_closed
frame list-periods --entity axec
 
# 추출
frame seed-profile <spec.json>
frame ingest --entity axec --file <path>
frame list-issues --entity axec
 
# 스크래핑 (외부 포털 → ingest, host-only / launchd)
frame scrape lottecard                 # 롯데 법인카드 승인내역(개인정보 미포함) → axec 적재
frame scrape lottecard --entity axtest --since 2026-04-01 --until 2026-04-30
#   헤드풀 Playwright (EIWAF 가 headless 차단). 법인전체 = 법인의 모든 카드.
#   자격증명: FRAME_LOTTE_PORTAL_USERNAME / _PASSWORD (vault → .env.local).
frame scrape-due [--dry-run]           # launchd tick: shared.scrape_schedule 중 due 인 것만 실행
#   주기는 DB(MCP set_scrape_schedule)로 조정. com.frame.scrape-tick 이 08–21시 매시 호출.
 
# 회계
frame post-journal --entity axec --spec-path <json>
frame classify --entity axec
frame trial-balance --entity axec --as-of 2026-05-31
frame integrity-check --entity axec
 
# 토큰 발급
frame mcp-token --sub [email protected] --customer axe \
    --entity axec:read,write,close \
    --entity axev:read,write,close \
    --ttl 2592000
 
# 서버
frame mcp-serve                        # stdio
frame mcp-health <token>

Claude Code/claude.ai → POST /frame/mcp (no auth)
frame                 → 401 + WWW-Authenticate: Bearer resource_metadata="..."
client                → GET /.well-known/oauth-protected-resource
frame                 → {resource: "https://axe.axelabs.ai/frame/mcp", authorization_servers: [Microsoft]}
client                → Microsoft OAuth flow (PKCE)
Microsoft             → access_token (aud = Application ID URI)
client                → POST /frame/mcp Authorization: Bearer <access_token>
frame middleware      → JWKS RS256 verify + aud + iss + email extract → entity 매핑
frame                 → MCP session 생성 → tool 호출 가능

# DB
FRAME_DB_HOST=postgres
FRAME_DB_PORT=5432
FRAME_DB_USER=frame
FRAME_DB_PASSWORD=
FRAME_DB_NAME=frame
 
# JWT
FRAME_JWT_SECRET=                       # ≥32 bytes
AZURE_FRAME_MCP_CLIENT_SECRET=          # OAuth confidential client
 
# PII
FRAME_PII_PASSPHRASE_AXEC=
FRAME_PII_PASSPHRASE_AXEV=
FRAME_PII_PASSPHRASE_REALCHOICE=
FRAME_PII_SALT_DIR=/root/.frame
 
# MCP HTTP
FRAME_MCP_HOST=0.0.0.0
FRAME_MCP_PORT=3710
FRAME_MCP_LOG_LEVEL=INFO
FRAME_MCP_ALLOWED_HOSTS=frame-mcp:*,localhost:*,...
FRAME_MCP_ALLOWED_ORIGINS=https://axe.axelabs.ai,...
 
# Multi-tenant
FRAME_CUSTOMERS_YAML=/etc/axe/customers.yaml
FRAME_CUSTOMER_ID=axe
FRAME_DEPLOY_COLOR=blue
 
# Blueprint platform identity (D-axe-idp-1) — 전부 빈 기본값 = 비활성(non-breaking).
# BLUEPRINT_ISSUER set 시 Blueprint 발급 platform 토큰을 신뢰. 상세: architecture/platform-identity.
BLUEPRINT_ISSUER=                       # 미설정=무시(현재 동작). set 시 활성
BLUEPRINT_JWKS_URL=                     # 미설정 시 issuer 에서 유도
BLUEPRINT_AUDIENCE=https://axe.axelabs.ai
 
# 롯데카드 스크래퍼 (host-only — MCP 컨테이너엔 없음, launchd 만 사용)
FRAME_LOTTE_PORTAL_USERNAME=            # 법인관리자 로그인 ID
FRAME_LOTTE_PORTAL_PASSWORD=            # vault frame/axe/lotte-portal-password
 
# Storage (host bind mount)
FRAME_STORAGE_HOST_DIR=${HOME}/frame/.local   # default — host 의 home 기준. /Users/axe/... hardcode 금지