# OpenFGA MCP Server
[OpenFGA](https://openfga.dev/)를 위한 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 서버입니다.
Claude Code에서 OpenFGA 권한 관리 작업을 수행할 수 있습니다.
## 기능
- **스토어 관리**: 스토어 목록 조회
- **모델 관리**: Authorization Model 조회/배포
- **튜플 관리**: 권한 관계(튜플) CRUD
- **권한 체크**: Check, ListObjects, Expand
## 설치
```bash
npm install
npm run build
```
## 환경 설정
### 방법 1: JSON 환경변수 (권장)
```bash
export OPENFGA_ENVIRONMENTS='{
"prod": {
"url": "https://openfga.example.com",
"defaultStoreId": "01ABC..."
},
"staging": {
"url": "https://openfga-staging.example.com"
}
}'
```
### 방법 2: 개별 환경변수
```bash
# 각 환경별로 설정
export OPENFGA_PROD_URL="https://openfga.example.com"
export OPENFGA_PROD_STORE_ID="01ABC..."
export OPENFGA_STAGING_URL="https://openfga-staging.example.com"
```
### 방법 3: 로컬 전용
```bash
# 기본값: http://localhost:8080
export OPENFGA_LOCAL_URL="http://localhost:8080"
export OPENFGA_LOCAL_STORE_ID="01XYZ..."
```
## Claude Code 설정
### 프로젝트별 설정 (`.claude/settings.json`)
```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`)
```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 설치 필요 ([설치 가이드](https://openfga.dev/docs/getting-started/cli))
```bash
# 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을 사용하세요:
```json
{
"hooks": {
"PostToolUse": [{
"matcher": "mcp__openfga__openfga_model_write",
"hooks": [{
"type": "command",
"command": "./scripts/post-model-deploy.sh"
}]
}]
}
}
```
Hook 스크립트는 stdin으로 JSON을 받습니다:
```json
{
"tool_name": "mcp__openfga__openfga_model_write",
"tool_output": "모델 배포 완료!\nAuthorization Model ID: 01ABC...\nEnvironment: prod"
}
```
## 개발
```bash
# 소스 수정 후 빌드
npm run build
# 개발 모드 (watch)
npm run dev
```
## 라이선스
MIT
