cai-mcp-server 0.1.1__tar.gz

cai_mcp_server-0.1.1/.env.example

@@ -0,0 +1,8 @@
+CAI_BASE_URL=https://your-workbench.example.com
+CAI_TOKEN=replace-with-a-workbench-api-key
+CAI_ENABLE_JOB_RUNS=false
+CAI_ALLOWED_JOBS=[]
+CAI_MAX_RECORDS=100
+CAI_TIMEOUT_SECONDS=30
+CAI_VERIFY_TLS=true
+CAI_LOG_LEVEL=INFO

cai_mcp_server-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+.env
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+*.py[cod]
+dist/

cai_mcp_server-0.1.1/.ipynb_checkpoints/AGENT_GUIDE-checkpoint.md

@@ -0,0 +1,92 @@
+# Cloudera AI Workbench MCP 에이전트 가이드
+
+이 MCP는 Cloudera AI Workbench API v2를 업무 단위 tool로 제공한다. 사용자는 API 경로,
+project ID, job ID, page token을 입력하지 않는다. 에이전트는 자연어 이름과 선택적 필터만
+받아 tool을 호출한다.
+
+## 도구 선택
+
+| 사용자 요청 | 호출할 tool |
+|---|---|
+| Workbench 전체 상태, 최근 실패, 현재 실행 workload, 리소스 요약 | `get_workbench_overview` |
+| workload를 이름/프로젝트/상태/유형/생성자/기간으로 찾기 | `find_workloads` |
+| 현재 CPU·메모리·GPU 사용량 및 집계 | `get_current_resource_usage` |
+| 이름으로 job 상태와 최근 run 확인 | `get_job_status` |
+| 허용된 job 실행 | `run_job` |
+
+프로젝트 자체 목록을 직접 반환하는 공개 tool은 없다. 프로젝트 이름이 필요한 경우
+workload 결과의 `project_name`을 사용하고, job 조회/실행 시에는 사람이 아는 job 이름으로
+질의한다.
+
+## 기본 호출 규칙
+
+- 상태 요약은 입력 없이 `get_workbench_overview(window_hours=24)`를 호출한다.
+- workload 검색은 먼저 `find_workloads`를 입력 없이 호출한다. `lookback_hours`는 사용자가
+  기간을 말했을 때만 지정한다.
+- 리소스 질문은 `get_current_resource_usage(status="running")`를 기본으로 사용한다.
+- 사용자가 말한 상태나 workload 유형을 임의로 번역하지 않는다. 서버가 Workbench의 현재
+  허용 목록을 검증하므로 오류가 나오면 반환된 허용 값으로 다시 질문한다.
+- `job_id`, `project_id`, API filter JSON, page token을 사용자에게 요구하지 않는다.
+
+## 이름 해석
+
+`get_job_status`와 `run_job`은 `job_name`만 필수다.
+
+- `project_name`을 생략하고 job 이름이 한 개면 프로젝트를 자동 선택한다.
+- 같은 이름이 여러 프로젝트에 있으면 후보 프로젝트명을 사용자에게 보여주고 선택을
+  요청한다.
+- 부분 일치나 임의의 유사 이름을 선택하지 않는다.
+- 조회는 대소문자 무시의 유일한 일치만 허용하지만, 실행은 allowlist의 정확한 이름과
+  프로젝트 조합만 허용한다.
+
+## 실행 tool 안전 규칙
+
+`run_job`은 새 run을 만들 수 있는 non-idempotent 작업이다.
+
+- `CAI_ENABLE_JOB_RUNS=true`이고 `CAI_ALLOWED_JOBS`에 정확히 허용된 조합이어야 한다.
+- 사용자가 명시적으로 실행을 요청하지 않으면 호출하지 않는다.
+- 사용자에게 실행할 job과 프로젝트를 다시 확인받은 뒤 호출한다.
+- `confirm=true` 같은 임의 확인 파라미터를 만들어 보안 경계로 사용하지 않는다.
+- 실패 후 자동 재시도하지 않는다. 재시도하면 중복 run이 생성될 수 있다.
+- 비허용, 모호한 이름, 프로젝트 불일치가 반환되면 실행하지 않고 설명한다.
+
+## 결과 해석
+
+`get_workbench_overview`의 `execution_summary`와 `recent_failures`는 이 환경에서 접근 가능한
+`/api/v2/usage`의 상태와 생성 시각으로 계산된다. `/api/v2/workloads/executions`의 상세
+실행 이력이 아니다. 결과에 `history_source: "usage"`가 있으면 이 의미를 사용자에게
+명시한다.
+
+`running_resource_totals`는 현재 workload가 보고한 CPU 코어, 메모리 GB, NVIDIA GPU 수의
+합계다. 사용률 퍼센트나 과거 누적 비용으로 해석하지 않는다.
+
+## 오류 처리
+
+- 인증서/연결 오류: 사용자에게 일시적 연결 문제로 알리고 토큰을 다시 출력하거나
+  노출하지 않는다.
+- HTTP 401: API Key가 없거나 잘못된 상태다.
+- HTTP 403: 현재 사용자가 해당 Workbench API operation 권한이 없는 상태다. 다른 tool로
+  대체 가능한지 먼저 확인한다.
+- 빈 결과: "없음"으로 단정하기 전에 적용된 필터와 기간을 함께 표시한다.
+- API 오류 원문에 토큰, Cookie, private key가 포함되지 않도록 한다.
+
+## 대표 대화 예시
+
+사용자: `현재 Workbench 상태 보여줘`
+
+→ `get_workbench_overview`를 입력 없이 호출하고, 실행 중 workload 수·리소스 합계·최근
+실패를 요약한다.
+
+사용자: `ksy-agent 프로젝트에서 실행 중인 애플리케이션 찾아줘`
+
+→ `find_workloads(project_name="ksy-agent", workload_type="application", status="running")`
+
+사용자: `Nightly Train job 상태 알려줘`
+
+→ `get_job_status(job_name="Nightly Train")`. 중복 후보가 반환되면 프로젝트를 질문한다.
+
+사용자: `Nightly Train 실행해줘`
+
+→ 먼저 정확한 프로젝트를 확인하고, allowlist/전역 실행 스위치 오류가 없는 경우에만
+`run_job`을 호출한다.
+

cai_mcp_server-0.1.1/.ipynb_checkpoints/README-checkpoint.md

@@ -0,0 +1,183 @@
+# Cloudera AI Workbench MCP Server
+
+Cloudera Agent Studio가 `uvx`로 실행하는 로컬 Python MCP 서버입니다. MCP 통신은
+`stdio`만 사용하고, 서버 프로세스가 인증된 Cloudera AI Workbench API v2를 직접
+호출합니다. 별도의 원격 MCP HTTP 서버는 운영하지 않습니다.
+
+이 서버는 API 목록을 그대로 노출하지 않습니다. Agent가 실제 운영 질문과 작업을
+처리할 수 있도록 여러 API 호출·이름 해석·집계를 묶은 5개 업무형 tool만 제공합니다.
+
+## 기술 기준
+
+- Python 3.11 이상
+- 공식 [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) v2
+- `mcp>=2.0.0,<3`
+- MCP transport: `stdio`
+- REST client: `httpx.AsyncClient`
+- API prefix: 코드에 고정된 `/api/v2`
+
+stdout은 MCP wire message 전용이며 애플리케이션 로그는 stderr로 출력됩니다. API path나
+HTTP method를 모델 입력으로 받는 범용 호출 도구는 없습니다.
+
+## 제공 tool과 API 매핑
+
+| MCP tool | 역할 | 내부 Workbench API v2 |
+|---|---|---|
+| `get_workbench_overview` | 최근 workload 상태·실패·현재 실행 중 workload·자원 합계 요약 | `GET /usage` |
+| `find_workloads` | 이름, 시간, 상태, 프로젝트, 유형, 생성자로 workload 검색 | `GET /usage` |
+| `get_current_resource_usage` | 현재 workload의 CPU·메모리·GPU 값을 전체/프로젝트/유형별 집계 | `GET /usage` |
+| `get_job_status` | job 이름을 전체 접근 가능 job에서 찾아 최근 run 상태 조회 | 내부 `GET /jobs`, `GET .../runs` |
+| `run_job` | 허용 목록의 job 이름을 안전하게 해석하여 새 run 시작 | 내부 `GET /jobs`, `POST .../runs` |
+
+`get_current_resource_usage` 결과는 `/api/v2/usage`가 현재 각 workload에 보고한 CPU,
+memory, GPU 수치의 합계입니다. 사용률 퍼센트나 과거 시간 구간의 누적 소비량으로
+해석하면 안 되며, 응답의 `metric_semantics`에도 이 제한을 표시합니다.
+
+`get_workbench_overview`도 `/api/v2/usage`만 사용합니다. `/api/v2/workloads/executions`는
+Cloudera Observability machine user로 구성된 환경에서만 접근 가능한 경우가 있어 기본
+Workload 사용자 인증으로는 호출하지 않습니다. 따라서 overview의 `execution_summary`와
+`recent_failures`는 usage 응답의 상태/생성 시각을 기준으로 계산됩니다.
+
+job 목록은 공개 tool이 아닙니다. `get_job_status`와 `run_job`이 사람이 입력한 이름을 API
+ID로 변환할 때만 내부에서 사용합니다. `project_id`, `job_id`, page token과 API filter
+JSON은 어떤 MCP tool도 입력받지 않습니다.
+
+## Tool 파라미터
+
+| Tool | 필수 입력 | Optional 입력과 기본값 |
+|---|---|---|
+| `get_workbench_overview` | 없음 | `window_hours=24` (1~168) |
+| `find_workloads` | 없음 | `query=null`, `project_name=null`, `status=null`, `workload_type=null`, `creator=null`, `lookback_hours=null`, `max_results=20` |
+| `get_current_resource_usage` | 없음 | `project_name=null`, `workload_type=null`, `status="running"` |
+| `get_job_status` | `job_name` | `project_name=null`, `recent_runs=5` |
+| `run_job` | `job_name` | `project_name=null` |
+
+`find_workloads`의 `lookback_hours`는 workload 생성 시각 필터입니다. 생략하면 시간 필터를
+적용하지 않으므로 오래 실행 중인 workload도 상태 검색에서 누락되지 않습니다. `status`와
+`workload_type`은 서버가 Workbench의 `/workloadstatus`, `/workloadtypes` 목록과
+대소문자 무시 방식으로 검증하며, 잘못된 값이면 현재 사용할 수 있는 값을 반환합니다.
+
+`get_job_status`는 전체 접근 가능 job을 이름으로 검색합니다. `project_name`을 생략해도
+job 이름이 유일하면 자동으로 프로젝트를 찾습니다. 동일 이름이 여러 프로젝트에 있으면
+ID가 아닌 프로젝트명 후보를 반환하므로 Agent가 사용자에게 선택을 요청할 수 있습니다.
+조회는 유일한 대소문자 무시 일치도 허용하지만 임의의 부분 일치를 선택하지 않습니다.
+
+## 인증 및 환경변수
+
+`CAI_BASE_URL`에는 Workbench 도메인만 입력합니다. `CAI_TOKEN`은 Workbench에서
+`audience=API`로 생성한 API Key여야 합니다. AI Inference workload의 `/tmp/jwt`는 이
+API의 자격증명이 아니므로 사용하지 않습니다.
+
+| 이름 | 필수 | 기본값 | 설명 |
+|---|---:|---|---|
+| `CAI_BASE_URL` | 예 | 없음 | Workbench origin. 예: `https://ml-xxxx.example.com` |
+| `CAI_TOKEN` | 예 | 없음 | Workbench API v2 Bearer API Key (`audience=API`) |
+| `CAI_ENABLE_JOB_RUNS` | 아니요 | `false` | `run_job` 기능의 운영자 전역 스위치 |
+| `CAI_ALLOWED_JOBS` | 실행 시 | `[]` | 정확한 `project/job` 쌍의 JSON 배열 또는 comma 목록 |
+| `CAI_MAX_RECORDS` | 아니요 | `100` | 내부 API 한 번에 읽는 최대 record 수(1~500) |
+| `CAI_TIMEOUT_SECONDS` | 아니요 | `30` | REST timeout(초) |
+| `CAI_VERIFY_TLS` | 아니요 | `true` | TLS 인증서 검증 |
+| `CAI_LOG_LEVEL` | 아니요 | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
+
+운영 환경에서는 `CAI_VERIFY_TLS=true`를 유지하십시오. `CAI_TOKEN`은 로그와 tool 결과에
+출력하지 않습니다.
+
+## `run_job` 안전 정책
+
+`run_job`은 MCP annotation에서 destructive/non-idempotent tool로 선언되어 있고, 다음 두
+조건을 모두 만족해야 실행됩니다.
+
+```dotenv
+CAI_ENABLE_JOB_RUNS=true
+CAI_ALLOWED_JOBS=["Fraud Detection/Nightly Train","Forecast/Daily Refresh"]
+```
+
+`job_name`은 항상 필수입니다. `project_name`을 생략했을 때 allowlist에 같은 job 이름이
+정확히 하나면 프로젝트를 자동 선택합니다. 둘 이상의 프로젝트에 같은 job 이름이
+등록되어 있을 때만 `project_name`을 요구합니다. 실행 시에는 대소문자를 포함한 정확한
+allowlist 일치만 허용하고 부분 일치나 추정은 하지 않습니다.
+
+`confirm=true` 같은 모델 입력을 보안 경계로 사용하지 않습니다. 재시도하면 새 run이
+중복 생성될 수 있으므로 POST 요청은 자동 재시도하지 않습니다. 초기 버전은 임의
+환경변수나 실행 인자도 모델에게 받지 않습니다.
+
+## 로컬 개발과 테스트
+
+[uv](https://docs.astral.sh/uv/)를 설치한 뒤 다음을 실행합니다.
+
+```bash
+cp .env.example .env
+# .env의 Workbench URL과 API Key를 수정
+
+uv sync --all-extras
+uv run ruff check .
+uv run pytest
+```
+
+MCP Inspector로 tool schema를 확인할 수 있습니다.
+
+```bash
+uv run --env-file .env mcp dev src/cai_mcp_server/server.py:mcp --with-editable .
+```
+
+서버 자체는 stdio peer가 연결해야 하므로 실행 중 터미널에 문자를 직접 입력하지
+마십시오.
+
+```bash
+uv run --env-file .env cai-mcp-server
+```
+
+## wheel 및 uvx 검증
+
+```bash
+uv build
+uvx --from ./dist/cai_mcp_server-0.1.0-py3-none-any.whl cai-mcp-server
+```
+
+개발 중에는 현재 소스를 바로 설치할 수도 있습니다.
+
+```bash
+uvx --from . cai-mcp-server
+```
+
+패키지 저장소에 배포한 뒤 Agent Studio에는 다음 형태로 등록합니다.
+
+```json
+{
+  "command": "uvx",
+  "args": [
+    "--from",
+    "cai-mcp-server==0.1.0",
+    "cai-mcp-server"
+  ]
+}
+```
+
+환경변수를 포함한 전체 예시는 `agent-studio.json`에 있습니다. Agent Studio에는 MCP
+server 정의를 등록한 뒤 workflow 설정에서 실제 secret 값을 넣어야 합니다. private
+package index를 사용한다면 Agent Studio runtime에서 접근 가능한 uv/Python index도
+구성해야 합니다.
+
+## 테스트 범위와 live 검증
+
+자동 테스트는 다음을 검증합니다.
+
+- 필수 API Key, 실행 스위치, 정확한 job allowlist parsing
+- 공식 API v2 path, JSON query filter, Bearer header, POST body
+- API 응답 정규화, 실행/현재 자원 집계, 동적 status/type 검증
+- project 이름 생략, 중복 후보 반환, 읽기용 대소문자 무시 해석
+- 실행용 exact allowlist와 유일한 allowlisted project 추론
+- upstream 오류의 민감 정보 제거
+- 공개 tool이 승인된 5개뿐인지와 tool 호출 성공/차단
+- 모든 공개 tool input에서 `project_id`, `job_id`가 제외되는지
+- 실제 subprocess의 stdio MCP initialize 및 tool 목록 조회
+
+Workbench 배포 버전에 따라 인스턴스의 정확한 계약은
+`https://<workbench-domain>/api/v2/swagger.json`에서 확인할 수 있습니다. 실제 endpoint를
+사용한 live 검증은 유효한 `CAI_BASE_URL`과 `CAI_TOKEN`이 있을 때 별도로 수행하십시오.
+
+관련 공식 문서:
+
+- [Cloudera AI Workbench API v2 시작 안내](https://docs.cloudera.com/machine-learning/cloud/api/index.html)
+- [Cloudera AI API v2 REST reference](https://docs.cloudera.com/machine-learning/cloud/rest-api-reference/index.html)
+- [Agent Studio MCP server 등록](https://docs.cloudera.com/machine-learning/cloud/use-ai-studios/topics/ml-register-mcp-server.html)

cai_mcp_server-0.1.1/AGENT_GUIDE.md

@@ -0,0 +1,92 @@
+# Cloudera AI Workbench MCP 에이전트 가이드
+
+이 MCP는 Cloudera AI Workbench API v2를 업무 단위 tool로 제공한다. 사용자는 API 경로,
+project ID, job ID, page token을 입력하지 않는다. 에이전트는 자연어 이름과 선택적 필터만
+받아 tool을 호출한다.
+
+## 도구 선택
+
+| 사용자 요청 | 호출할 tool |
+|---|---|
+| Workbench 전체 상태, 최근 실패, 현재 실행 workload, 리소스 요약 | `get_workbench_overview` |
+| workload를 이름/프로젝트/상태/유형/생성자/기간으로 찾기 | `find_workloads` |
+| 현재 CPU·메모리·GPU 사용량 및 집계 | `get_current_resource_usage` |
+| 이름으로 job 상태와 최근 run 확인 | `get_job_status` |
+| 허용된 job 실행 | `run_job` |
+
+프로젝트 자체 목록을 직접 반환하는 공개 tool은 없다. 프로젝트 이름이 필요한 경우
+workload 결과의 `project_name`을 사용하고, job 조회/실행 시에는 사람이 아는 job 이름으로
+질의한다.
+
+## 기본 호출 규칙
+
+- 상태 요약은 입력 없이 `get_workbench_overview(window_hours=24)`를 호출한다.
+- workload 검색은 먼저 `find_workloads`를 입력 없이 호출한다. `lookback_hours`는 사용자가
+  기간을 말했을 때만 지정한다.
+- 리소스 질문은 `get_current_resource_usage(status="running")`를 기본으로 사용한다.
+- 사용자가 말한 상태나 workload 유형을 임의로 번역하지 않는다. 서버가 Workbench의 현재
+  허용 목록을 검증하므로 오류가 나오면 반환된 허용 값으로 다시 질문한다.
+- `job_id`, `project_id`, API filter JSON, page token을 사용자에게 요구하지 않는다.
+
+## 이름 해석
+
+`get_job_status`와 `run_job`은 `job_name`만 필수다.
+
+- `project_name`을 생략하고 job 이름이 한 개면 프로젝트를 자동 선택한다.
+- 같은 이름이 여러 프로젝트에 있으면 후보 프로젝트명을 사용자에게 보여주고 선택을
+  요청한다.
+- 부분 일치나 임의의 유사 이름을 선택하지 않는다.
+- 조회는 대소문자 무시의 유일한 일치만 허용하지만, 실행은 allowlist의 정확한 이름과
+  프로젝트 조합만 허용한다.
+
+## 실행 tool 안전 규칙
+
+`run_job`은 새 run을 만들 수 있는 non-idempotent 작업이다.
+
+- `CAI_ENABLE_JOB_RUNS=true`이고 `CAI_ALLOWED_JOBS`에 정확히 허용된 조합이어야 한다.
+- 사용자가 명시적으로 실행을 요청하지 않으면 호출하지 않는다.
+- 사용자에게 실행할 job과 프로젝트를 다시 확인받은 뒤 호출한다.
+- `confirm=true` 같은 임의 확인 파라미터를 만들어 보안 경계로 사용하지 않는다.
+- 실패 후 자동 재시도하지 않는다. 재시도하면 중복 run이 생성될 수 있다.
+- 비허용, 모호한 이름, 프로젝트 불일치가 반환되면 실행하지 않고 설명한다.
+
+## 결과 해석
+
+`get_workbench_overview`의 `execution_summary`와 `recent_failures`는 이 환경에서 접근 가능한
+`/api/v2/usage`의 상태와 생성 시각으로 계산된다. `/api/v2/workloads/executions`의 상세
+실행 이력이 아니다. 결과에 `history_source: "usage"`가 있으면 이 의미를 사용자에게
+명시한다.
+
+`running_resource_totals`는 현재 workload가 보고한 CPU 코어, 메모리 GB, NVIDIA GPU 수의
+합계다. 사용률 퍼센트나 과거 누적 비용으로 해석하지 않는다.
+
+## 오류 처리
+
+- 인증서/연결 오류: 사용자에게 일시적 연결 문제로 알리고 토큰을 다시 출력하거나
+  노출하지 않는다.
+- HTTP 401: API Key가 없거나 잘못된 상태다.
+- HTTP 403: 현재 사용자가 해당 Workbench API operation 권한이 없는 상태다. 다른 tool로
+  대체 가능한지 먼저 확인한다.
+- 빈 결과: "없음"으로 단정하기 전에 적용된 필터와 기간을 함께 표시한다.
+- API 오류 원문에 토큰, Cookie, private key가 포함되지 않도록 한다.
+
+## 대표 대화 예시
+
+사용자: `현재 Workbench 상태 보여줘`
+
+→ `get_workbench_overview`를 입력 없이 호출하고, 실행 중 workload 수·리소스 합계·최근
+실패를 요약한다.
+
+사용자: `ksy-agent 프로젝트에서 실행 중인 애플리케이션 찾아줘`
+
+→ `find_workloads(project_name="ksy-agent", workload_type="application", status="running")`
+
+사용자: `Nightly Train job 상태 알려줘`
+
+→ `get_job_status(job_name="Nightly Train")`. 중복 후보가 반환되면 프로젝트를 질문한다.
+
+사용자: `Nightly Train 실행해줘`
+
+→ 먼저 정확한 프로젝트를 확인하고, allowlist/전역 실행 스위치 오류가 없는 경우에만
+`run_job`을 호출한다.
+

cai_mcp_server-0.1.1/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: cai-mcp-server
+Version: 0.1.1
+Summary: Task-level MCP tools for Cloudera AI Workbench API v2
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28.0
+Requires-Dist: mcp<3,>=2.0.0
+Requires-Dist: pydantic-settings<3,>=2.7.0
+Provides-Extra: dev
+Requires-Dist: mcp[cli]<3,>=2.0.0; extra == 'dev'
+Requires-Dist: pytest<10,>=8.4; extra == 'dev'
+Requires-Dist: ruff<1,>=0.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cloudera AI Workbench MCP Server
+
+Cloudera Agent Studio가 `uvx`로 실행하는 로컬 Python MCP 서버입니다. MCP 통신은
+`stdio`만 사용하고, 서버 프로세스가 인증된 Cloudera AI Workbench API v2를 직접
+호출합니다. 별도의 원격 MCP HTTP 서버는 운영하지 않습니다.
+
+이 서버는 API 목록을 그대로 노출하지 않습니다. Agent가 실제 운영 질문과 작업을
+처리할 수 있도록 여러 API 호출·이름 해석·집계를 묶은 5개 업무형 tool만 제공합니다.
+
+## 기술 기준
+
+- Python 3.11 이상
+- 공식 [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) v2
+- `mcp>=2.0.0,<3`
+- MCP transport: `stdio`
+- REST client: `httpx.AsyncClient`
+- API prefix: 코드에 고정된 `/api/v2`
+
+stdout은 MCP wire message 전용이며 애플리케이션 로그는 stderr로 출력됩니다. API path나
+HTTP method를 모델 입력으로 받는 범용 호출 도구는 없습니다.
+
+## 제공 tool과 API 매핑
+
+| MCP tool | 역할 | 내부 Workbench API v2 |
+|---|---|---|
+| `get_workbench_overview` | 최근 workload 상태·실패·현재 실행 중 workload·자원 합계 요약 | `GET /usage` |
+| `find_workloads` | 이름, 시간, 상태, 프로젝트, 유형, 생성자로 workload 검색 | `GET /usage` |
+| `get_current_resource_usage` | 현재 workload의 CPU·메모리·GPU 값을 전체/프로젝트/유형별 집계 | `GET /usage` |
+| `get_job_status` | job 이름을 전체 접근 가능 job에서 찾아 최근 run 상태 조회 | 내부 `GET /jobs`, `GET .../runs` |
+| `run_job` | 허용 목록의 job 이름을 안전하게 해석하여 새 run 시작 | 내부 `GET /jobs`, `POST .../runs` |
+
+`get_current_resource_usage` 결과는 `/api/v2/usage`가 현재 각 workload에 보고한 CPU,
+memory, GPU 수치의 합계입니다. 사용률 퍼센트나 과거 시간 구간의 누적 소비량으로
+해석하면 안 되며, 응답의 `metric_semantics`에도 이 제한을 표시합니다.
+
+`get_workbench_overview`도 `/api/v2/usage`만 사용합니다. `/api/v2/workloads/executions`는
+Cloudera Observability machine user로 구성된 환경에서만 접근 가능한 경우가 있어 기본
+Workload 사용자 인증으로는 호출하지 않습니다. 따라서 overview의 `execution_summary`와
+`recent_failures`는 usage 응답의 상태/생성 시각을 기준으로 계산됩니다.
+
+job 목록은 공개 tool이 아닙니다. `get_job_status`와 `run_job`이 사람이 입력한 이름을 API
+ID로 변환할 때만 내부에서 사용합니다. `project_id`, `job_id`, page token과 API filter
+JSON은 어떤 MCP tool도 입력받지 않습니다.
+
+## Tool 파라미터
+
+| Tool | 필수 입력 | Optional 입력과 기본값 |
+|---|---|---|
+| `get_workbench_overview` | 없음 | `window_hours=24` (1~168) |
+| `find_workloads` | 없음 | `query=null`, `project_name=null`, `status=null`, `workload_type=null`, `creator=null`, `lookback_hours=null`, `max_results=20` |
+| `get_current_resource_usage` | 없음 | `project_name=null`, `workload_type=null`, `status="running"` |
+| `get_job_status` | `job_name` | `project_name=null`, `recent_runs=5` |
+| `run_job` | `job_name` | `project_name=null` |
+
+`find_workloads`의 `lookback_hours`는 workload 생성 시각 필터입니다. 생략하면 시간 필터를
+적용하지 않으므로 오래 실행 중인 workload도 상태 검색에서 누락되지 않습니다. `status`와
+`workload_type`은 서버가 Workbench의 `/workloadstatus`, `/workloadtypes` 목록과
+대소문자 무시 방식으로 검증하며, 잘못된 값이면 현재 사용할 수 있는 값을 반환합니다.
+
+`get_job_status`는 전체 접근 가능 job을 이름으로 검색합니다. `project_name`을 생략해도
+job 이름이 유일하면 자동으로 프로젝트를 찾습니다. 동일 이름이 여러 프로젝트에 있으면
+ID가 아닌 프로젝트명 후보를 반환하므로 Agent가 사용자에게 선택을 요청할 수 있습니다.
+조회는 유일한 대소문자 무시 일치도 허용하지만 임의의 부분 일치를 선택하지 않습니다.
+
+## 인증 및 환경변수
+
+`CAI_BASE_URL`에는 Workbench 도메인만 입력합니다. `CAI_TOKEN`은 Workbench에서
+`audience=API`로 생성한 API Key여야 합니다. AI Inference workload의 `/tmp/jwt`는 이
+API의 자격증명이 아니므로 사용하지 않습니다.
+
+| 이름 | 필수 | 기본값 | 설명 |
+|---|---:|---|---|
+| `CAI_BASE_URL` | 예 | 없음 | Workbench origin. 예: `https://ml-xxxx.example.com` |
+| `CAI_TOKEN` | 예 | 없음 | Workbench API v2 Bearer API Key (`audience=API`) |
+| `CAI_ENABLE_JOB_RUNS` | 아니요 | `false` | `run_job` 기능의 운영자 전역 스위치 |
+| `CAI_ALLOWED_JOBS` | 실행 시 | `[]` | 정확한 `project/job` 쌍의 JSON 배열 또는 comma 목록 |
+| `CAI_MAX_RECORDS` | 아니요 | `100` | 내부 API 한 번에 읽는 최대 record 수(1~500) |
+| `CAI_TIMEOUT_SECONDS` | 아니요 | `30` | REST timeout(초) |
+| `CAI_VERIFY_TLS` | 아니요 | `true` | TLS 인증서 검증 |
+| `CAI_LOG_LEVEL` | 아니요 | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
+
+운영 환경에서는 `CAI_VERIFY_TLS=true`를 유지하십시오. `CAI_TOKEN`은 로그와 tool 결과에
+출력하지 않습니다.
+
+## `run_job` 안전 정책
+
+`run_job`은 MCP annotation에서 destructive/non-idempotent tool로 선언되어 있고, 다음 두
+조건을 모두 만족해야 실행됩니다.
+
+```dotenv
+CAI_ENABLE_JOB_RUNS=true
+CAI_ALLOWED_JOBS=["Fraud Detection/Nightly Train","Forecast/Daily Refresh"]
+```
+
+`job_name`은 항상 필수입니다. `project_name`을 생략했을 때 allowlist에 같은 job 이름이
+정확히 하나면 프로젝트를 자동 선택합니다. 둘 이상의 프로젝트에 같은 job 이름이
+등록되어 있을 때만 `project_name`을 요구합니다. 실행 시에는 대소문자를 포함한 정확한
+allowlist 일치만 허용하고 부분 일치나 추정은 하지 않습니다.
+
+`confirm=true` 같은 모델 입력을 보안 경계로 사용하지 않습니다. 재시도하면 새 run이
+중복 생성될 수 있으므로 POST 요청은 자동 재시도하지 않습니다. 초기 버전은 임의
+환경변수나 실행 인자도 모델에게 받지 않습니다.
+
+## 로컬 개발과 테스트
+
+[uv](https://docs.astral.sh/uv/)를 설치한 뒤 다음을 실행합니다.
+
+```bash
+cp .env.example .env
+# .env의 Workbench URL과 API Key를 수정
+
+uv sync --all-extras
+uv run ruff check .
+uv run pytest
+```
+
+MCP Inspector로 tool schema를 확인할 수 있습니다.
+
+```bash
+uv run --env-file .env mcp dev src/cai_mcp_server/server.py:mcp --with-editable .
+```
+
+서버 자체는 stdio peer가 연결해야 하므로 실행 중 터미널에 문자를 직접 입력하지
+마십시오.
+
+```bash
+uv run --env-file .env cai-mcp-server
+```
+
+## wheel 및 uvx 검증
+
+```bash
+uv build
+uvx --from ./dist/cai_mcp_server-0.1.0-py3-none-any.whl cai-mcp-server
+```
+
+개발 중에는 현재 소스를 바로 설치할 수도 있습니다.
+
+```bash
+uvx --from . cai-mcp-server
+```
+
+패키지 저장소에 배포한 뒤 Agent Studio에는 다음 형태로 등록합니다.
+
+```json
+{
+  "command": "uvx",
+  "args": [
+    "--from",
+    "cai-mcp-server==0.1.0",
+    "cai-mcp-server"
+  ]
+}
+```
+
+환경변수를 포함한 전체 예시는 `agent-studio.json`에 있습니다. Agent Studio에는 MCP
+server 정의를 등록한 뒤 workflow 설정에서 실제 secret 값을 넣어야 합니다. private
+package index를 사용한다면 Agent Studio runtime에서 접근 가능한 uv/Python index도
+구성해야 합니다.
+
+## 테스트 범위와 live 검증
+
+자동 테스트는 다음을 검증합니다.
+
+- 필수 API Key, 실행 스위치, 정확한 job allowlist parsing
+- 공식 API v2 path, JSON query filter, Bearer header, POST body
+- API 응답 정규화, 실행/현재 자원 집계, 동적 status/type 검증
+- project 이름 생략, 중복 후보 반환, 읽기용 대소문자 무시 해석
+- 실행용 exact allowlist와 유일한 allowlisted project 추론
+- upstream 오류의 민감 정보 제거
+- 공개 tool이 승인된 5개뿐인지와 tool 호출 성공/차단
+- 모든 공개 tool input에서 `project_id`, `job_id`가 제외되는지
+- 실제 subprocess의 stdio MCP initialize 및 tool 목록 조회
+
+Workbench 배포 버전에 따라 인스턴스의 정확한 계약은
+`https://<workbench-domain>/api/v2/swagger.json`에서 확인할 수 있습니다. 실제 endpoint를
+사용한 live 검증은 유효한 `CAI_BASE_URL`과 `CAI_TOKEN`이 있을 때 별도로 수행하십시오.
+
+관련 공식 문서:
+
+- [Cloudera AI Workbench API v2 시작 안내](https://docs.cloudera.com/machine-learning/cloud/api/index.html)
+- [Cloudera AI API v2 REST reference](https://docs.cloudera.com/machine-learning/cloud/rest-api-reference/index.html)
+- [Agent Studio MCP server 등록](https://docs.cloudera.com/machine-learning/cloud/use-ai-studios/topics/ml-register-mcp-server.html)