Metadata-Version: 2.4
Name: alphakey-mcp-server
Version: 2.1.0
Summary: AlphaKey IDaaS MCP Server — AI IDE에서 알파키 관리 API를 대화형으로 호출
Project-URL: Homepage, https://alphakey.kr
Project-URL: Repository, https://github.com/lgu-idaas/alphakey-mcp-server
Project-URL: Documentation, https://github.com/lgu-idaas/alphakey-mcp-server#readme
License-Expression: LicenseRef-Proprietary
Keywords: alphakey,iam,idaas,identity,mcp,saas,sso
Requires-Python: >=3.10
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: mcp[cli]<2.0.0,>=1.0.0
Description-Content-Type: text/markdown

# AlphaKey MCP Server

알파키(AlphaKey) IDaaS 관리 API를 AI 코딩 도구에서 대화형으로 호출할 수 있는 MCP(Model Context Protocol) 서버입니다.

> **130개 도구 제공**: 읽기 63개 + 쓰기 67개 (확인 게이트 포함)
>
> 지원 도구: Kiro, VS Code + GitHub Copilot, Cursor, Windsurf, Claude Desktop, Cline

---

## 설치 가이드 (처음부터 끝까지)

### STEP 1. uv 설치 (1회만)

터미널을 열고 아래 한 줄을 복사해서 실행하세요.

**Mac/Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

설치 확인:
```bash
uv --version
```
→ 버전 번호가 나오면 성공

---

### STEP 2. GitHub SSH 연결 확인 (1회만)

이 서버는 현재 private 레포이므로 GitHub SSH 인증이 필요합니다.

```bash
ssh -T git@github.com
```

✅ `Hi 사용자명! You've successfully authenticated` 나오면 OK

❌ `Permission denied` 나오면:
1. SSH 키 생성: `ssh-keygen -t ed25519 -C "내이메일@lguplus.co.kr"`
2. 공개키 복사: `cat ~/.ssh/id_ed25519.pub`
3. GitHub > Settings > SSH and GPG keys > New SSH key에 붙여넣기
4. 다시 `ssh -T git@github.com` 확인

---

### STEP 3. 알파키 API 토큰 준비

알파키 관리자 콘솔에서 토큰을 발급받으세요.

1. 알파키 관리자 콘솔 접속 (https://회사명.alphakey.kr)
2. 설정 및 관리 > OpenAPI 토큰 관리
3. 토큰 발급 클릭
4. 발급된 토큰 복사해두기

---

### STEP 4. MCP 설정 파일 편집

사용하는 도구에 따라 아래 파일을 열어주세요.

| 도구 | 파일 위치 | 여는 방법 |
|------|----------|----------|
| **Kiro** | 프로젝트 폴더/.kiro/settings/mcp.json | Kiro에서 프로젝트 열고 파일 생성 |
| **Claude Desktop (Mac)** | ~/Library/Application Support/Claude/claude_desktop_config.json | Finder에서 Cmd+Shift+G → 경로 붙여넣기 |
| **VS Code + Copilot** | 프로젝트 폴더/.vscode/mcp.json | VS Code에서 파일 생성 |
| **Cursor** | 프로젝트 폴더/.cursor/mcp.json | Cursor에서 파일 생성 |

파일이 없으면 새로 만드세요. 폴더도 없으면 폴더부터 만드세요.

---

### STEP 5. 아래 내용을 복사해서 붙여넣기

```json
{
  "mcpServers": {
    "alphakey": {
      "command": "uvx",
      "args": ["--from", "git+ssh://git@github.com/lgu-idaas/alphakey-mcp-server", "alphakey-mcp-server"],
      "env": {
        "ALPHAKEY_BASE_URL": "https://여기에_회사_테넌트_URL",
        "ALPHAKEY_TOKEN": "여기에_발급받은_토큰"
      }
    }
  }
}
```

**두 군데만 수정하세요:**
- `여기에_회사_테넌트_URL` → 예: `https://lguplus.alphakey.kr`
- `여기에_발급받은_토큰` → STEP 3에서 복사한 토큰

저장하세요.

---

### STEP 6. 도구 리로드

| 도구 | 리로드 방법 |
|------|------------|
| Kiro | `Cmd+Shift+P` → `Reload Window` |
| Claude Desktop | 완전 종료 후 재시작 |
| VS Code | `Cmd+Shift+P` → `Reload Window` |
| Cursor | `Cmd+Shift+P` → `Reload Window` |

---

### STEP 7. 테스트

AI 채팅에서 아래를 입력해보세요:

```
알파키 사용자 목록 보여줘
```

사용자 목록이 나오면 설치 성공! 🎉

---

## 문제 해결

| 증상 | 원인 | 해결 |
|------|------|------|
| `uv: command not found` | uv 미설치 | STEP 1 다시 실행 |
| `Permission denied (publickey)` | SSH 키 미등록 | STEP 2 진행 |
| `인증 오류` / 응답 없음 | 토큰 만료 또는 IP 제한 | 관리자 콘솔에서 토큰 재발급 |
| 도구에서 MCP 서버 안 보임 | 설정 파일 경로 오류 | STEP 4의 파일 위치 재확인 |
| JSON 파싱 에러 | JSON 문법 오류 | 쉼표, 중괄호 누락 확인 |

---

## 환경변수

| 변수 | 필수 | 설명 |
|------|------|------|
| `ALPHAKEY_BASE_URL` | ✅ | 알파키 테넌트 URL |
| `ALPHAKEY_TOKEN` | ✅ | 관리자 콘솔에서 발급받은 API 토큰 |
| `SSL_CA_BUNDLE` | ❌ | 자체 서명 인증서 사용 시 CA 번들 경로 |
| `ALPHAKEY_AUDIT_LOG` | ❌ | 감사 로그 경로 (기본: `~/.alphakey/audit.log`) |
| `ALPHAKEY_AUDIT_LOG_ENABLED` | ❌ | 감사 로그 활성화 (기본: `true`) |

---

## 보안

- TLS 통신 암호화 (HTTPS 강제)
- 토큰별 IP 제한 + 만료 기간
- 쓰기 작업 2단계 확인 게이트
- 입력값 검증 (ID/IP/날짜/enum)
- 감사 로그 (30일 로테이션)
- 에러 정보 은닉

---

## 제공 도구 (130개)

사용자/앱/그룹/보안/SSO/MFA/대시보드/프로비저닝/관리자 설정 전 영역을 커버합니다.

자연어로 질문하면 AI가 적절한 도구를 자동으로 호출합니다.

---

## 사용 예시

```
사용자 목록 보여줘
Figma 앱 사용자 몇 명이야?
이상 접속 내역 보여줘
감지 정책 목록 조회해줘
새 사용자 등록해줘
SSO 앱 연동 상세 조회해줘
```

---

## 라이선스

Copyright © LG유플러스. All rights reserved.

본 소프트웨어는 알파키(AlphaKey) IDaaS 서비스 이용 고객에게 제공됩니다.
