# Tibero MCP Server

Tibero 데이터베이스의 스키마를 탐색하고 읽기 전용 SQL을 실행하는 Model Context Protocol(MCP) 서버입니다. MCP 프로토콜은 Node.js로 동작하며, `npx`로 바로 실행할 수 있습니다.

Tibero용 공식 Node.js 드라이버가 없어 실제 DB 접속은 Maven Central의 `tbjdbc6` JDBC 드라이버와 Java 17 이상을 사용합니다. MCP 초기화와 도구 목록 조회는 DB 연결 없이 동작합니다.

## 요구사항

- Node.js 18 이상
- Java 17 이상 (`java`가 PATH에 있거나 `JAVA_HOME` 설정)
- 접근 가능한 Tibero 포트(기본값 `8629`)

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

```bash
npx -y tibero-mcp --check
```

## MCP 클라이언트 설정

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

```json
{
  "mcpServers": {
    "tibero": {
      "command": "npx",
      "args": ["-y", "tibero-mcp"],
      "env": {
        "TIBERO_HOST": "localhost",
        "TIBERO_PORT": "8629",
        "TIBERO_SID": "tibero",
        "TIBERO_USER": "readonly_user",
        "TIBERO_PASSWORD": "your_password",
        "POLICY_ALLOWED_SCHEMA": "readonly_schema"
      }
    }
  }
}
```

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

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

```json
{
  "env": {
    "TIBERO_JDBC_URL": "jdbc:tibero:thin:@db.example.com:8629:tibero",
    "TIBERO_USER": "readonly_user",
    "TIBERO_PASSWORD": "your_password"
  }
}
```

### 환경 변수

| 이름 | 필수 | 설명 |
| --- | --- | --- |
| `TIBERO_HOST` | 조건부 | Tibero 호스트. `TIBERO_JDBC_URL` 사용 시 생략 가능 |
| `TIBERO_PORT` | 아니요 | 리스너 포트, 기본값 `8629` |
| `TIBERO_SID` | 조건부 | 데이터베이스 SID. `TIBERO_JDBC_URL` 사용 시 생략 가능 |
| `TIBERO_DATABASE` | 아니요 | `TIBERO_SID` 별칭 |
| `TIBERO_USER` | 예 | Tibero 사용자명 |
| `TIBERO_PASSWORD` | 아니요 | Tibero 비밀번호, 기본값은 빈 문자열 |
| `TIBERO_JDBC_URL` | 조건부 | 기존 설정 호환용 JDBC 형식 URL |
| `TIBERO_JDBC_JAR` | 아니요 | 로컬 `tbjdbc6` JAR 경로. 없으면 Maven Central에서 캐시 |
| `POLICY_ALLOWED_SCHEMA` | 아니요 | 접근을 허용할 스키마, 기본값은 사용자명 |
| `POLICY_HARD_MAX_ROWS` | 아니요 | 쿼리 최대 행 수, 기본값 `10000` |
| `POLICY_HARD_MAX_BYTES` | 아니요 | 결과 최대 바이트 수, 기본값 `20971520` |
| `POLICY_HARD_TIMEOUT_MS` | 아니요 | 쿼리 제한 시간, 기본값 `30000` |
| `TIBERO_CONNECTION_TIMEOUT_MS` | 아니요 | 연결 제한 시간, 기본값 `30000` |

### `.env` 파일

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

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

## 제공 기능

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

서버는 공식 MCP TypeScript SDK를 사용합니다. stdout은 MCP 메시지에만 사용합니다. Tibero/Oracle 호환을 위해 SQL에 `LIMIT`를 붙이지 않고 JDBC `maxRows`로 결과 행 수를 제한합니다.

## 보안

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

## 개발 및 테스트

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

Maven 빌드 단계는 없습니다. npm 패키지에 `bin/`, `src/`, `package.json`, README, 라이선스만 포함됩니다. 첫 DB 연결 시 `tbjdbc6` JAR을 `~/.tibero-mcp`에 캐시합니다.

## npm 배포

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

```bash
npm view tibero-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 또는 인증 절차가 추가로 필요합니다. `tibero-mcp` 이름은 실제 게시 시점까지 예약되지 않습니다.

## 라이선스

[MIT](LICENSE)