# CUBRID MCP Server

CUBRID 데이터베이스의 스키마를 탐색하고 읽기 전용 SQL을 실행하는 Model Context Protocol(MCP) 서버입니다. 순수 Node.js 프로젝트입니다.

## 요구사항

- Node.js 18 이상
- CUBRID 10.2 이상
- 접근 가능한 CUBRID Broker 포트(기본값 `33000`)

설치 없이 실행 환경을 확인할 수 있습니다.

```bash
npx -y cubrid-mcp --check
```

## MCP 클라이언트 설정

Claude Desktop, Cursor 등 stdio MCP 클라이언트의 설정에 다음 서버를 추가합니다.

```json
{
  "mcpServers": {
    "cubrid": {
      "command": "npx",
      "args": ["-y", "cubrid-mcp"],
      "env": {
        "CUBRID_HOST": "localhost",
        "CUBRID_PORT": "33000",
        "CUBRID_DATABASE": "your_database",
        "CUBRID_USER": "readonly_user",
        "CUBRID_PASSWORD": "your_password",
        "POLICY_ALLOWED_SCHEMA": "readonly_schema"
      }
    }
  }
}
```

Windows에서 클라이언트가 `npx`를 찾지 못하면 `command`를 `npx.cmd`로 변경합니다. `-y`는 최초 설치 확인 메시지가 MCP stdio 통신을 방해하지 않도록 합니다.

기존 Java 서버 설정과 호환되도록 JDBC URL 형식도 지원합니다.

```json
{
  "env": {
    "CUBRID_JDBC_URL": "jdbc:cubrid:db.example.com:33000:your_database:::?charSet=utf-8",
    "CUBRID_USER": "readonly_user",
    "CUBRID_PASSWORD": "your_password"
  }
}
```

### 환경 변수

| 이름 | 필수 | 설명 |
| --- | --- | --- |
| `CUBRID_HOST` | 조건부 | CUBRID 호스트. `CUBRID_JDBC_URL` 사용 시 생략 가능 |
| `CUBRID_PORT` | 아니요 | Broker 포트, 기본값 `33000` |
| `CUBRID_DATABASE` | 조건부 | 데이터베이스명. `CUBRID_JDBC_URL` 사용 시 생략 가능 |
| `CUBRID_USER` | 예 | CUBRID 사용자명 |
| `CUBRID_PASSWORD` | 아니요 | CUBRID 비밀번호, 기본값은 빈 문자열 |
| `CUBRID_JDBC_URL` | 조건부 | 기존 설정 호환용 JDBC 형식 URL |
| `POLICY_ALLOWED_SCHEMA` | 아니요 | 접근을 허용할 스키마, 기본값은 사용자명 |
| `POLICY_HARD_MAX_ROWS` | 아니요 | 쿼리 최대 행 수, 기본값 `10000` |
| `POLICY_HARD_MAX_BYTES` | 아니요 | 결과 최대 바이트 수, 기본값 `20971520` |
| `POLICY_HARD_TIMEOUT_MS` | 아니요 | 쿼리 제한 시간, 기본값 `30000` |
| `CUBRID_CONNECTION_TIMEOUT_MS` | 아니요 | 연결 제한 시간, 기본값 `10000` |

### `.env` 파일

`npx`를 실행하는 작업 폴더에 `.env` 파일을 두면 연결 설정을 자동으로 읽습니다. `.env.example`을 `.env`로 복사한 뒤 실제 접속 정보를 입력하세요. `.env`는 `.gitignore`에 포함되어 GitHub에 업로드되지 않습니다.

연결 정보는 npm 패키지에 저장되지 않으며 실행 환경에서만 전달됩니다.

## 제공 기능

- `db.ping`: 데이터베이스 연결 확인
- `db.listTables`: 테이블과 뷰 목록 조회
- `db.describeTable`: 컬럼, 기본 키, 인덱스 조회
- `db.query`: 정책 범위 안에서 SELECT 쿼리 실행
- 스키마 요약, 테이블 상세, SQL 정책 MCP 리소스

서버는 공식 MCP TypeScript SDK와 네이티브 CAS 프로토콜 기반 `cubrid-client`를 사용합니다. stdout은 MCP 메시지에만 사용합니다.

## 보안

`db.query`는 단일 `SELECT`/읽기 전용 CTE만 허용하고, 다른 스키마 참조와 SQL 주석 및 쓰기 키워드를 차단합니다. 애플리케이션 정책은 완전한 SQL 방화벽이 아니므로 실제 운영에서는 반드시 조회 권한만 가진 전용 CUBRID 계정을 사용하세요.

## 개발 및 테스트

```bash
npm install
npm test
npm run check
```

Java 빌드 단계는 없습니다. npm 패키지에 `bin/`, `src/`, `package.json`, README, 라이선스만 포함됩니다.

## npm 배포

게시 전 패키지 이름과 포함 파일을 확인합니다.

```bash
npm view cubrid-mcp
npm pack --dry-run
npm login
npm whoami
npm publish --access public
```

`npm publish` 전에 테스트가 자동 실행됩니다. 이후 릴리스는 변경 범위에 맞게 버전을 올린 뒤 게시합니다.

```bash
npm version patch
npm publish --access public
```

npm의 2단계 인증이 활성화되어 있으면 게시 과정에서 OTP 또는 인증 절차가 추가로 필요합니다. `cubrid-mcp` 이름은 실제 게시 시점까지 예약되지 않습니다.

## 라이선스

[MIT](LICENSE)