khdp 0.1.0__tar.gz

khdp-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,13 @@
+# Default owners for everything in the repo.
+*           @KoreaHealthDataPlatform/maintainers
+
+# Keep auth code under tighter review — anything that touches token
+# handling or HTTP request building requires a security-aware reviewer.
+/src/khdp/oauth.py        @KoreaHealthDataPlatform/security
+/src/khdp/token_store.py  @KoreaHealthDataPlatform/security
+/src/khdp/session.py      @KoreaHealthDataPlatform/security
+/src/khdp/mcp_server.py   @KoreaHealthDataPlatform/security
+
+# Wrapper configs are usually safe but should still be reviewed by a
+# wrapper-specific owner before merging.
+/wrappers/                 @KoreaHealthDataPlatform/maintainers

khdp-0.1.0/.github/branch-protection.md

@@ -0,0 +1,52 @@
+# Recommended branch-protection settings
+
+These settings are GitHub repository configuration, not files. Apply
+them via **Settings → Branches → Add rule** on
+<https://github.com/KoreaHealthDataPlatform/KHDPConnector>.
+
+## `main` branch rule
+
+- ✅ **Require a pull request before merging**
+  - Require approvals: **1**
+  - Dismiss stale pull request approvals when new commits are pushed
+  - Require review from Code Owners (uses [`.github/CODEOWNERS`](./CODEOWNERS))
+- ✅ **Require status checks to pass before merging**
+  - Require branches to be up to date before merging
+  - Required checks: `test (ubuntu-latest, 3.10)`, `test (ubuntu-latest, 3.11)`,
+    `test (ubuntu-latest, 3.12)`, `test (macos-latest, 3.12)`,
+    `test (windows-latest, 3.12)` (from [`ci.yml`](./workflows/ci.yml))
+- ✅ **Require conversation resolution before merging**
+- ✅ **Require signed commits** *(recommended)*
+- ✅ **Require linear history**
+- ✅ **Restrict who can push to matching branches**
+  - Limit to the `KoreaHealthDataPlatform/maintainers` team.
+- ✅ **Do not allow bypassing the above settings**
+- ❌ **Allow force pushes** (off)
+- ❌ **Allow deletions** (off)
+
+## Apply via the GitHub CLI
+
+If you have admin scope and `gh` 2.40+:
+
+```bash
+gh api -X PUT repos/KoreaHealthDataPlatform/KHDPConnector/branches/main/protection \
+  -F required_status_checks.strict=true \
+  -F required_status_checks.contexts[]='test (ubuntu-latest, 3.10)' \
+  -F required_status_checks.contexts[]='test (ubuntu-latest, 3.11)' \
+  -F required_status_checks.contexts[]='test (ubuntu-latest, 3.12)' \
+  -F required_status_checks.contexts[]='test (macos-latest, 3.12)' \
+  -F required_status_checks.contexts[]='test (windows-latest, 3.12)' \
+  -F enforce_admins=false \
+  -F required_pull_request_reviews.required_approving_review_count=1 \
+  -F required_pull_request_reviews.require_code_owner_reviews=true \
+  -F required_pull_request_reviews.dismiss_stale_reviews=true \
+  -F required_linear_history=true \
+  -F allow_force_pushes=false \
+  -F allow_deletions=false \
+  -F restrictions=null
+```
+
+> Replace `null` for `restrictions` with the team JSON if you want to
+> enforce a push allowlist. Read the rest of the
+> [Branches API docs](https://docs.github.com/en/rest/branches/branch-protection)
+> for full options.

khdp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Test
+        run: pytest -q

khdp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/khdp
+    permissions:
+      id-token: write   # required for PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

khdp-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+.venv/
+venv/
+env/
+
+# Tests / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# KHDP runtime artifacts (never commit tokens)
+*.token
+*.tokens.json
+.khdp/
+khdp.local.toml
+
+# Environment
+.env
+.env.local

khdp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to khdp
+
+Thanks for your interest. `khdp` is the official OAuth/MCP connector
+for the Korea Health Data Platform. Most contributions land as small,
+focused PRs.
+
+## Local setup
+
+```bash
+git clone https://github.com/KoreaHealthDataPlatform/KHDPConnector.git
+cd KHDPConnector
+python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\activate
+pip install -e '.[dev,keyring]'
+```
+
+## Before sending a PR
+
+```bash
+ruff check src tests
+pytest
+```
+
+CI runs the same checks across Linux / macOS / Windows on Python
+3.10–3.12. If your change adds a new tool or endpoint, please add a
+test under `tests/` that exercises it with `pytest-httpx`.
+
+## What we accept
+
+- Bug fixes with a clear repro and a regression test.
+- New MCP tools that map to a stable KHDP backend route (open an
+  issue first to align on the tool name and schema).
+- Documentation that improves the onboarding path for an external
+  AI coding agent.
+- Wrapper updates for new agent platforms (Cursor, Windsurf, …) under
+  `wrappers/`.
+
+## What we don't accept (yet)
+
+- Code that bypasses KHDP's auth or audit policies.
+- Tools that surface PHI or patient identifiers in agent context.
+- Vendor-specific tool reimplementations — the wrappers carry config
+  and prompts only; the tool surface lives in the MCP server.
+
+## Code style
+
+- Type-annotated Python 3.10+. We rely on `from __future__ import
+  annotations` for forward references.
+- `ruff` enforces formatting and import order. Keep the existing rule
+  set in `pyproject.toml`.
+- Public API additions deserve a short docstring explaining the
+  *why*, not the *what*. Don't restate the signature.
+
+## Reporting security issues
+
+See [SECURITY.md](./SECURITY.md). Don't open public issues for
+suspected vulnerabilities.
+
+## License
+
+By submitting a contribution you agree it will be released under the
+project's [Apache-2.0 License](./LICENSE).

khdp-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Korea Health Data Platform (KHDP)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

khdp-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: khdp
+Version: 0.1.0
+Summary: KHDP connector. CLI + MCP server for Korea Health Data Platform, with wrappers for Claude Code, OpenAI Codex, and Gemini.
+Project-URL: Homepage, https://github.com/KoreaHealthDataPlatform/KHDPConnector
+Project-URL: Repository, https://github.com/KoreaHealthDataPlatform/KHDPConnector
+Project-URL: Issues, https://github.com/KoreaHealthDataPlatform/KHDPConnector/issues
+Project-URL: Documentation, https://github.com/KoreaHealthDataPlatform/KHDPConnector#readme
+Author-email: Korea Health Data Platform <vital@snu.ac.kr>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: healthcare,khdp,mcp,oauth,omop,vitaldb
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: keyring
+Requires-Dist: keyring>=24.0; extra == 'keyring'
+Description-Content-Type: text/markdown
+
+# KHDPConnector
+
+Auth + MCP connector for the **Korea Health Data Platform (KHDP)**.
+
+`khdp-connector` is a CLI-first Python package that handles login
+against the KHDP central auth API and exposes the resulting Bearer
+session through a Model Context Protocol (MCP) server. The same MCP
+server backs thin wrappers for **Claude Code**, **OpenAI Codex CLI**,
+and **Gemini CLI** so KHDP authentication looks the same across every
+coding-agent surface.
+
+> **Status:** alpha. APIs and tool names will move during Phase 0–1 of
+> the [PLAN.md](./PLAN.md) roadmap.
+
+## How it talks to KHDP
+
+The connector uses KHDP's password-based auth API. It implements two
+endpoints that are safe for headless / CLI use:
+
+* `POST /_api/oauth/login {appId, redirectUrl, mail, password}` →
+  `{accessToken, refreshToken, expireTime}`
+* `POST /_api/member/refresh-token {refreshToken}` →
+  same shape, rotated.
+
+All subsequent KHDP API calls go out with `Authorization: Bearer
+<accessToken>`.
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  Claude Code   ·   Codex CLI   ·   Gemini CLI   ·  …       │
+│        │              │              │                      │
+│        └──────── MCP (stdio JSON-RPC) ───────┐             │
+│                                              ▼             │
+│                                    khdp-connector (this)   │
+│                                              │             │
+│                                              ▼             │
+│   POST /_api/oauth/login          POST /_api/member/...    │
+│       (login + refresh)               (any KHDP endpoint)  │
+│                          khdp.net                          │
+└────────────────────────────────────────────────────────────┘
+```
+
+## Install
+
+```bash
+pipx install khdp-connector            # recommended; isolates from system Python
+# or
+pip install khdp-connector
+# or with OS-keychain support:
+pipx install 'khdp-connector[keyring]'
+```
+
+## One-time configuration
+
+You need a KHDP-registered `app_id` (UUID) and a registered
+`redirect_url`. Drop them into a config file or env vars:
+
+```toml
+# ./khdp.local.toml
+app_id       = "00000000-0000-0000-0000-000000000000"
+redirect_url = "https://example.org/khdp-cli"
+api_base     = "https://khdp.net/_api"  # default; override for staging
+```
+
+…or:
+
+```bash
+export KHDP_APP_ID=00000000-0000-0000-0000-000000000000
+export KHDP_REDIRECT_URL=https://example.org/khdp-cli
+```
+
+> **Don't have an `app_id` yet?** Coordinate with the KHDP team to
+> register a CLI-class app. snuh.ai's public `app_id` won't work for
+> the CLI — its `redirect_url` allowlist excludes anything outside
+> `snuh.ai`.
+
+## CLI usage
+
+```bash
+khdp login          # prompts for email + password (or use --email / --password-stdin)
+khdp status         # is a token cached? when does it expire?
+khdp refresh        # force a refresh-token rotation
+khdp api GET /member/me              # authenticated KHDP API call
+khdp logout         # delete cached tokens
+khdp config         # print resolved configuration
+khdp mcp            # run the MCP server on stdio (for agents)
+```
+
+Configuration resolution order (highest first):
+
+1. `KHDP_*` environment variables
+2. `khdp.local.toml` in the current working directory
+3. `~/.config/khdp/config.toml` (or platform equivalent)
+4. Built-in defaults
+
+For non-interactive use:
+
+```bash
+KHDP_EMAIL=me@example.com khdp login --password-stdin <<< "$KHDP_PASSWORD"
+```
+
+## MCP server
+
+```bash
+khdp mcp
+# or
+khdp-mcp
+```
+
+Tools exposed on `stdio`:
+
+| Tool | Purpose |
+| --- | --- |
+| `khdp_auth_status`  | Is the user logged in? When does the token expire? |
+| `khdp_auth_refresh` | Rotate the refresh token to extend the session. |
+| `khdp_auth_logout`  | Delete locally cached tokens. |
+| `khdp_api_request`  | Authenticated HTTP passthrough to the KHDP API. |
+
+The MCP server **never** accepts a password through tool arguments —
+passwords would otherwise flow through the LLM context window. Login
+is initiated out-of-band via `khdp login` in the user's terminal; the
+MCP server just reads the resulting token cache.
+
+Future tools (per [PLAN.md](./PLAN.md)) will add dataset I/O, OMOP
+queries, audit log retrieval, and IRB result-pinning.
+
+## Wrappers
+
+The same MCP server backs a thin wrapper per agent platform.
+
+### Claude Code
+
+```bash
+claude mcp add khdp -- khdp mcp
+cp -r wrappers/claude-code/skills/khdp-auth ~/.claude/skills/
+```
+
+### OpenAI Codex CLI
+
+Append `wrappers/codex/config.example.toml` to `~/.codex/config.toml`,
+copy `wrappers/codex/AGENTS.md` to your project root.
+
+### Gemini CLI
+
+Merge `wrappers/gemini/settings.example.json` into
+`~/.gemini/settings.json`, or install as a Gemini Extension under
+`.gemini/extensions/khdp/`.
+
+## Development
+
+```bash
+git clone https://github.com/KoreaHealthDataPlatform/KHDPConnector.git
+cd KHDPConnector
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e '.[dev,keyring]'
+pytest
+```
+
+## Security model
+
+- **No secret in the binary.** The CLI ships only the user-provided
+  `app_id`. There is no embedded client secret.
+- **Password never leaves the local machine** unencrypted; it goes
+  only to KHDP's TLS endpoint, never to the LLM, never to the MCP
+  context. The MCP tool surface deliberately omits a password
+  argument.
+- **Per-app token isolation.** Multiple KHDP apps on one machine are
+  kept separate by `app_id`.
+- **Token storage.** OS keychain (Keychain / Credential Manager /
+  Secret Service) when the `keyring` extra is installed; otherwise a
+  JSON file with `0600` permissions in the platform user-config dir.
+- **No revocation endpoint exposed by KHDP today.** `khdp logout` only
+  clears local state. Access tokens expire naturally; refresh tokens
+  go invalid the next time the access token is rotated.
+
+## Roadmap
+
+See [PLAN.md](./PLAN.md) for the full roadmap. The current
+implementation covers Phase 1 (auth) and a generic API passthrough.
+Dataset I/O, OMOP analysis, and IRB-grade result pinning land in later
+phases.
+
+## License
+
+Apache 2.0. See [LICENSE](./LICENSE).

khdp-0.1.0/PLAN.md

@@ -0,0 +1,191 @@
+# KHDP 커넥터 아키텍처 계획
+
+## 목적
+
+KHDP 데이터 및 도구를 외부 AI 코딩 에이전트(Claude Code, Codex CLI, OpenCode, Cursor 등)에서 안전하고 일관되게 사용할 수 있도록 하는 커넥터 레이어를 설계한다. 특정 LLM 벤더에 종속되지 않으면서, KHDP의 인증·감사·접근통제 정책을 클라이언트 환경과 무관하게 서버 측에서 강제하는 것이 목표.
+
+## 설계 원칙
+
+1. **Vendor neutrality**: 의료 데이터 인프라는 다년(5–10년) 단위로 운영되는 반면 LLM 벤더 지형은 1–2년 단위로 변한다. 도구 인터페이스는 벤더 중립 표준(MCP)을 1차로 채택한다.
+2. **Server-enforced security**: 인증·권한·감사 로그는 클라이언트가 무엇이든(LLM 추론이든 사람이든) 서버 측에서 강제된다. 클라이언트가 보안 프로토콜을 재구현하지 않는다.
+3. **Reusable across surfaces**: 같은 백엔드를 MCP, CLI, 웹 UI, CI 환경에서 모두 동일하게 사용할 수 있어야 한다.
+4. **Defense in depth**: manifest 기반 access control, AES-GCM URL 토큰, k-anonymity egress control 등 기존 KHDP 보안 레이어와 정합적으로 통합된다.
+5. **Auditability over flexibility**: IRB·내부자 위협 모델에 부합하도록, 호출 경로의 자유도보다 감사 가능성을 우선한다.
+
+## 3-tier 구조
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Tier 3: Vendor-specific 자산 (선택적)                          │
+│   - Anthropic Skills (SKILL.md + 보조 스크립트)                │
+│   - GPTs Custom Actions, Gemini Extensions 등                 │
+└─────────────────────────────────────────────────────────────┘
+                            ↓ 참조
+┌─────────────────────────────────────────────────────────────┐
+│ Tier 2: 벤더 중립 가이드 (KHDP_AGENT_GUIDE.md)                  │
+│   - 도메인 워크플로우, 도구 사용 순서, 컨벤션                       │
+│   - AGENTS.md / CLAUDE.md 형식으로 호환                         │
+└─────────────────────────────────────────────────────────────┘
+                            ↓ 호출
+┌─────────────────────────────────────────────────────────────┐
+│ Tier 1: KHDP MCP 서버 (1차 산출물)                              │
+│   - 결정론적 도구 노출 (auth, dataset I/O, OMOP query)           │
+│   - 인증/감사/권한 캡슐화                                         │
+└─────────────────────────────────────────────────────────────┘
+                            ↓ 호출
+┌─────────────────────────────────────────────────────────────┐
+│ KHDP Backend (snuh.ai)                                       │
+│   - manifest registry, OMOP CDM, audit log, RID issuer       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Tier 1: KHDP MCP 서버
+
+### 노출 도구 (초안)
+
+**인증**
+- `khdp_auth_status` — 현재 인증 상태와 사용자 컨텍스트 조회
+- `khdp_auth_login` — OAuth 부트스트랩 (loopback redirect 처리)
+- `khdp_auth_logout` — 토큰 폐기
+
+**데이터셋 I/O**
+- `khdp_dataset_list` — 권한 있는 데이터셋 목록 조회 (manifest 기반)
+- `khdp_dataset_describe` — 데이터셋 메타데이터·스키마·라이선스 조회
+- `khdp_dataset_download` — 데이터셋 다운로드 (RID 기반 AES-GCM URL 발급)
+- `khdp_dataset_upload` — 데이터셋 업로드 (PHI 스캔·manifest 등록 포함)
+
+**OMOP CDM 분석**
+- `khdp_omop_describe_table` — OMOP 테이블 스키마와 row 수
+- `khdp_omop_find_concept` — concept_id ↔ 명칭 검색 (vocabulary 통합)
+- `khdp_omop_sample_rows` — 테이블 샘플 (egress 정책 적용)
+- `khdp_omop_query` — DuckDB 기반 read-only SQL 실행 (k-anonymity·row limit)
+
+**감사·재현성**
+- `khdp_audit_log_query` — 본인의 호출 이력 조회
+- `khdp_result_pin` — IRB 재현성 요건 충족용 결과·쿼리·환경 스냅샷 저장
+
+### 인증 모델
+
+- **OAuth 2.0 + PKCE (loopback)** 채택. RFC 8252 권장 패턴.
+- 서버 사이드 배포 시 `https://khdp.net/oauth/callback`, 로컬 MCP는 `http://127.0.0.1:<port>/callback`.
+- Refresh token은 클라이언트 머신에 0600 퍼미션으로 저장, OS keychain 통합 옵션 검토.
+- 모든 토큰은 사용자 단위. 다중 사용자 머신에서는 사용자별 격리.
+
+### 감사 로그 통합
+
+- 모든 MCP 도구 호출은 (user_id, tool, params_hash, timestamp, client_ua, result_status) 튜플로 immutable log에 기록.
+- `params_hash`는 PHI를 평문 저장하지 않기 위해 정규화 후 해시.
+- IRB 감사 시 `khdp_result_pin`으로 고정된 결과만 재현성 보장 대상.
+
+### 기술 스택 (잠정)
+
+- **언어**: Python 3.12 (KHDP 기존 인프라 호환)
+- **MCP SDK**: 공식 Python SDK (`mcp` 패키지)
+- **데이터 액세스**: DuckDB (read-only concurrent connection), 기존 KHDP storage layer 재사용
+- **배포**: 로컬 모드(stdio)와 원격 모드(HTTP+SSE) 둘 다 지원
+- **컨테이너**: 기존 Firecracker/gVisor 샌드박스 정책과 동일한 격리 수준
+
+## Tier 2: 벤더 중립 가이드 (KHDP_AGENT_GUIDE.md)
+
+OpenAI 진영의 `AGENTS.md`, Anthropic 진영의 `CLAUDE.md` 양쪽 모두에서 자연스럽게 참조되도록 작성.
+
+### 포함 내용
+
+- KHDP MCP 도구 카탈로그 요약
+- 도메인 워크플로우 (예시)
+  - "OMOP 코호트 분석 시: `find_concept` → `describe_table` → `sample_rows` → `query` 순서. 단일 SQL로 끝내려 하지 말고 코딩 에이전트 루프 활용."
+  - "데이터셋 업로드 전: 반드시 PHI 스캔 도구로 검증. manifest는 자동 생성됨."
+  - "결과를 논문/IRB 보고서에 인용할 경우 `khdp_result_pin` 필수."
+- 안 되는 것 명시 (negative examples)
+  - 의료 판단·진단·생성 표현 회피 (UI 카피 정책과 동일)
+  - 환자 식별자 평문 출력 금지
+  - egress 한도를 우회하려는 다단 쿼리 분해 금지
+
+### 배포 위치
+
+- KHDP 공식 문서 사이트 (`docs.khdp.net/agent-guide`)
+- 프로젝트 워크스페이스 루트에 자동 배치되는 옵션 제공 (`khdp init` 시)
+
+## Tier 3: 벤더별 자산 (선택적)
+
+### Anthropic Skill
+
+- `khdp-omop-analysis/SKILL.md` — OMOP 분석 워크플로우 자동 트리거
+- `khdp-dataset-management/SKILL.md` — 데이터셋 입출력 워크플로우
+- 보조 스크립트(검증·정규화)를 함께 패키징
+- Claude Code 사용자에게 자동 발견·로드되는 편의 기능
+
+### 기타 (필요 시)
+
+- Cursor `.cursorrules`, Windsurf rules 등 IDE별 설정 어댑터
+- OpenAI Custom GPT용 OpenAPI 스펙 (MCP 서버를 HTTP로 노출 시 자동 생성 가능)
+
+## 단계별 로드맵
+
+### Phase 0: 설계 확정 (현재)
+- [ ] 노출 도구 시그니처 확정 (위 초안 검토)
+- [ ] 인증 모델 결정: OAuth scope 정의, refresh token 저장 정책
+- [ ] 감사 로그 스키마 확정 (기존 audit log와 통합)
+- [ ] MCP transport 결정: 로컬 stdio 우선 / 원격 HTTP는 후속
+
+### Phase 1: MVP MCP 서버
+- [ ] 인증 도구 (`auth_status`, `auth_login`, `auth_logout`)
+- [ ] 읽기 전용 도구 (`dataset_list`, `dataset_describe`, `omop_describe_table`)
+- [ ] 단일 사용자, stdio transport, 로컬 실행
+- [ ] 단위 테스트 + audit log smoke test
+
+### Phase 2: 데이터 입출력
+- [ ] `dataset_download` (AES-GCM URL 발급 통합)
+- [ ] `dataset_upload` (PHI 스캔, manifest 자동 생성)
+- [ ] 토큰 갱신 자동화
+
+### Phase 3: OMOP 분석 도구
+- [ ] `omop_find_concept`, `omop_sample_rows`, `omop_query`
+- [ ] k-anonymity egress 정책 통합
+- [ ] DuckDB read-only concurrent 연결 풀
+
+### Phase 4: 재현성 + 다중 사용자
+- [ ] `khdp_result_pin` (결과 스냅샷)
+- [ ] 원격 HTTP transport (다중 사용자 시나리오)
+- [ ] per-user credential 격리 검증
+
+### Phase 5: Tier 2/3 자산
+- [ ] `KHDP_AGENT_GUIDE.md` 작성·배포
+- [ ] Anthropic Skill 패키징
+- [ ] 외부 에이전트 호환성 검증 (Claude Code, Codex CLI, OpenCode, Cursor 각각)
+
+## 결정 필요 항목
+
+### 1. 인증 backend
+- (a) infmedix 자체 OAuth provider 구축 (KCMVP 모듈 OEM 라인 활용)
+- (b) 기존 SNUH SSO 연동
+- (c) 단기적으로 API key + 장기적으로 OAuth 마이그레이션
+- → 1차 의견: (c). MVP 부담을 줄이고, OAuth는 다중 사용자 단계(Phase 4)에서 도입.
+
+### 2. MCP 서버 배포 위치
+- (a) 사용자 로컬 머신 (stdio)
+- (b) snuh.ai 서버 사이드 (HTTP+SSE)
+- (c) 둘 다 지원
+- → 1차 의견: (c). MVP는 (a)로 시작, Phase 4에서 (b) 추가. 로컬은 단일 연구자 자동화에, 원격은 IRB 감사·다중 사용자 환경에.
+
+### 3. 의료 데이터 egress 정책
+- MCP 도구가 반환하는 데이터의 row limit, 컬럼 마스킹, k-anonymity 임계값을 어디서 결정할 것인가
+- → MCP 서버가 아닌 KHDP backend의 기존 egress control layer에서 강제. MCP는 단순 패스스루.
+
+### 4. 외부 호환성 검증 범위
+- 어느 에이전트까지 1차 지원 대상으로 명시할 것인가
+- → 1차 의견: Claude Code, Codex CLI, OpenCode를 우선. Cursor·Windsurf는 best-effort.
+
+## 위험 요소
+
+- **MCP 표준 변동성**: 2024–2026년 동안 빠르게 진화 중. transport, auth, 권한 모델이 바뀔 여지. → 추상화 레이어로 격리, SDK 버전 핀.
+- **다중 LLM의 도구 호출 비결정성**: 같은 MCP 도구를 모델마다 다르게 호출. → Tier 2 가이드 + 도구 시그니처 엄격화로 완충.
+- **OAuth 부트스트랩 UX**: 의료 연구자(비개발자)에게 loopback OAuth는 낯섦. → CLI 한 줄 명령(`khdp login`)으로 캡슐화.
+- **Skill vs MCP 중복 유지보수**: Tier 1과 Tier 3가 중복 진화하지 않도록 Tier 3는 워크플로우(가이드)에만 집중하고 도구 자체는 절대 재구현하지 않음.
+
+## 참고
+
+- MCP 사양: https://modelcontextprotocol.io
+- RFC 8252 (OAuth for Native Apps), RFC 7636 (PKCE)
+- Anthropic Agent Skills 문서
+- KHDP 기존 설계 문서: AES-GCM URL 스킴, manifest access control, k-anonymity egress