OpenFGA MCP Server

OpenFGA를 위한 Model Context Protocol (MCP) 서버입니다. Claude Code에서 OpenFGA 권한 관리 작업을 수행할 수 있습니다.

기능

• 스토어 관리: 스토어 목록 조회
• 모델 관리: Authorization Model 조회/배포
• 튜플 관리: 권한 관계(튜플) CRUD
• 권한 체크: Check, ListObjects, Expand

설치

npm install
npm run build

환경 설정

방법 1: JSON 환경변수 (권장)

export OPENFGA_ENVIRONMENTS='{
  "prod": {
    "url": "https://openfga.example.com",
    "defaultStoreId": "01ABC..."
  },
  "staging": {
    "url": "https://openfga-staging.example.com"
  }
}'

방법 2: 개별 환경변수

# 각 환경별로 설정
export OPENFGA_PROD_URL="https://openfga.example.com"
export OPENFGA_PROD_STORE_ID="01ABC..."

export OPENFGA_STAGING_URL="https://openfga-staging.example.com"

방법 3: 로컬 전용

# 기본값: http://localhost:8080
export OPENFGA_LOCAL_URL="http://localhost:8080"
export OPENFGA_LOCAL_STORE_ID="01XYZ..."

Claude Code 설정

프로젝트별 설정 (.claude/settings.json)

{
  "mcpServers": {
    "openfga": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/openfga-mcp/dist/index.js"]
    }
  },
  "env": {
    "OPENFGA_ENVIRONMENTS": "{\"prod\":{\"url\":\"https://openfga.example.com\",\"defaultStoreId\":\"01ABC...\"}}"
  }
}

글로벌 설정 (~/.claude.json)

{
  "mcpServers": {
    "openfga": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/openfga-mcp/dist/index.js"],
      "env": {
        "OPENFGA_ENVIRONMENTS": "{\"prod\":{\"url\":\"https://openfga.example.com\"}}"
      }
    }
  }
}

사용 가능한 도구

도구	설명
openfga_store_list	스토어 목록 조회
openfga_model_read	Authorization Model 조회
openfga_model_write	Authorization Model 배포 (DSL 파일/문자열)
openfga_tuple_read	튜플 조회 (필터 지원)
openfga_tuple_write	단일 튜플 생성
openfga_tuple_batch_write	여러 튜플 일괄 생성
openfga_tuple_delete	튜플 삭제
openfga_check	권한 체크
openfga_list_objects	접근 가능한 오브젝트 목록
openfga_expand	권한 트리 확장

openfga_model_write

DSL 파일을 OpenFGA에 배포합니다.

요구사항: fga CLI 설치 필요 (설치 가이드)

# macOS
brew install openfga/tap/fga

# 기타
go install github.com/openfga/cli/cmd/fga@latest

사용 예시

# 모델 조회
openfga_model_read(env: "prod")

# 모델 배포
openfga_model_write(env: "prod", filePath: "/path/to/model.fga")

# 권한 체크
openfga_check(env: "prod", user: "user:alice", relation: "can_view", object: "document:1")

# 튜플 생성
openfga_tuple_write(env: "prod", user: "user:alice", relation: "viewer", object: "document:1")

# 튜플 배치 생성
openfga_tuple_batch_write(env: "prod", tuples: [
  {user: "user:alice", relation: "viewer", object: "document:1"},
  {user: "user:bob", relation: "editor", object: "document:1"}
])

자연어로도 요청 가능:

prod 환경에서 user:alice가 document:1을 can_view 할 수 있는지 확인해줘

Hooks 연동 (선택)

모델 배포 후 설정 파일 자동 업데이트 등의 프로젝트별 작업이 필요하면 Claude Code Hook을 사용하세요:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "mcp__openfga__openfga_model_write",
      "hooks": [{
        "type": "command",
        "command": "./scripts/post-model-deploy.sh"
      }]
    }]
  }
}

Hook 스크립트는 stdin으로 JSON을 받습니다:

{
  "tool_name": "mcp__openfga__openfga_model_write",
  "tool_output": "모델 배포 완료!\nAuthorization Model ID: 01ABC...\nEnvironment: prod"
}

개발

# 소스 수정 후 빌드
npm run build

# 개발 모드 (watch)
npm run dev

라이선스

MIT