# Run:AI MCP Server

NVIDIA Run:AI 인프라를 LLM 에이전트가 제어하는 MCP(Model Context Protocol) 서버.

426개 Run:AI API를 4개 메타 도구 + BM25 검색 엔진으로 동적 검색·실행합니다.

## 도구

| 도구 | 설명 |
|------|------|
| `search_runai_api_spec` | OpenAPI 스펙 BM25 검색 — 엔드포인트, 메서드, 스키마 반환 |
| `call_runai_api` | REST API 호출 (인증 자동, DELETE 시 confirm 필요) |
| `resolve_runai_names` | 엔티티 이름 → ID 변환 (cluster, project, workload 등) |
| `execute_runai_cli` | CLI 전용 작업 (port-forward, exec, logs, attach, diagnostics) |

## 워크플로우

```
search_runai_api_spec("create training workload")
  → resolve_runai_names([{ type: "project", name: "my-project" }])
  → call_runai_api({ method: "POST", path: "/api/v1/workloads/trainings", ... })
```

## 설치

```bash
npm install
npm run build
```

## 인증

Run:AI UI에서 **Application (서비스 계정)** 생성 → `clientID` + `clientSecret` 발급.
서버가 자동으로 `POST /api/v1/token` (client_credentials grant)으로 JWT를 발급·갱신합니다.

```bash
cp .env.example .env
# RUNAI_CLIENT_ID, RUNAI_CLIENT_SECRET 설정
```

정적 토큰(`RUNAI_API_TOKEN`)도 지원하나, JWT는 만료되므로 서비스 계정 방식을 권장합니다.

## Claude Code MCP 설정

`~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "runai": {
      "command": "node",
      "args": ["/path/to/runai-mcp-server/dist/index.js"],
      "env": {
        "RUNAI_API_BASE_URL": "https://your-instance.run.ai",
        "RUNAI_CLIENT_ID": "your-client-id",
        "RUNAI_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

## 개발

```bash
npm run dev      # ts-node 개발 실행
npm test         # 전체 테스트
npm run build    # 프로덕션 빌드
```

## 아키텍처

- **Registry Builder**: OpenAPI 3.0.3 스펙을 파싱하여 413개 OperationDescriptor 생성, $ref 자동 해결
- **BM25 Search**: IDF 기반 키워드 검색 + 동의어 확장 (job→workload, remove→delete 등)
- **Adaptive Schema**: 검색 결과 1-2개면 requestBody 스키마 포함, 3개+면 summary만 (토큰 절약)
- **Safety**: DELETE는 confirm_destructive 필수, CLI는 화이트리스트 + 쉘 인젝션 방어

## 라이선스

MIT