나일-mcp

Nile 데이터베이스 플랫폼을 위한 모델 컨텍스트 프로토콜(MCP) 서버 구현입니다. 이 서버를 통해 LLM 애플리케이션은 표준화된 인터페이스를 통해 Nile 플랫폼과 상호 작용할 수 있습니다.

특징

데이터베이스 관리 : 데이터베이스 생성, 나열, 세부 정보 가져오기 및 삭제
자격 증명 관리 : 데이터베이스 자격 증명을 생성하고 나열합니다.
지역 관리 : 데이터베이스 생성에 사용 가능한 지역 나열
SQL 쿼리 지원 : Nile 데이터베이스에서 직접 SQL 쿼리를 실행합니다.
MCP 프로토콜 지원 : 모델 컨텍스트 프로토콜의 전체 구현
유형 안전성 : 전체 유형 검사를 통해 TypeScript로 작성됨
오류 처리 : 포괄적인 오류 처리 및 사용자 친화적인 오류 메시지
테스트 커버리지 : Jest를 사용한 포괄적인 테스트 모음
환경 관리 : .env 파일에서 환경 변수 자동 로드
입력 검증 : Zod를 사용한 스키마 기반 입력 검증

설치

안정적인 버전을 설치하세요:

지엑스피1

최신 알파/미리보기 버전:

npm install @niledatabase/nile-mcp-server@alpha

이렇게 하면 node_modules 폴더에 @niledatabase/nile-mcp-server가 설치됩니다. 예: node_modules/@niledatabase/nile-mcp-server/dist/

수동 설치

# Clone the repository
git clone https://github.com/yourusername/nile-mcp-server.git
cd nile-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

다른 mcp 패키지 관리자

npx @michaellatman/mcp-get@latest 설치 @niledatabase/nile-mcp-server

서버 시작

서버를 시작하는 방법은 여러 가지가 있습니다.

직접 노드 실행 :
node dist/index.js
개발 모드 (자동 재구축 포함):
npm run dev

서버가 시작되고 MCP 프로토콜 메시지를 수신합니다. 다음과 같은 시작 로그가 표시됩니다.

환경 변수가 로드됨
서버 인스턴스가 생성되었습니다
도구가 초기화되었습니다
운송 연결 설정됨

서버를 중지하려면 Ctrl+C 누르세요.

서버가 실행 중인지 확인

서버가 성공적으로 시작되면 다음과 유사한 로그가 표시됩니다.

[info] Starting Nile MCP Server...
[info] Loading environment variables...
[info] Environment variables loaded successfully
[info] Creating server instance...
[info] Tools initialized successfully
[info] Setting up stdio transport...
[info] Server started successfully

이러한 로그가 나타나면 서버가 Claude Desktop의 명령을 수락할 준비가 된 것입니다.

구성

Nile 자격 증명을 사용하여 루트 디렉토리에 .env 파일을 만듭니다.

NILE_API_KEY=your_api_key_here
NILE_WORKSPACE_SLUG=your_workspace_slug

Nile API 키를 생성하려면 Nile 계정 에 로그인하고 왼쪽 상단의 작업 공간을 클릭한 다음 작업 공간을 선택하고 왼쪽 메뉴에서 보안 섹션으로 이동합니다.

Claude Desktop과 함께 사용

설정

아직 Claude Desktop을 설치하지 않았다면 설치하세요.
프로젝트를 빌드하세요:
npm run build
클로드 데스크톱 열기
설정 > MCP 서버로 이동하세요
"서버 추가"를 클릭하세요
다음 구성을 추가합니다.

{
  "mcpServers": {
    "nile-database": {
      "command": "node",
      "args": [
        "/path/to/your/nile-mcp-server/dist/index.js"
      ],
      "env": {
        "NILE_API_KEY": "your_api_key_here",
        "NILE_WORKSPACE_SLUG": "your_workspace_slug"
      }
    }
  }
}

바꾸다:

프로젝트 디렉토리의 절대 경로를 포함하는 /path/to/your/nile-mcp-server
your_api_key_here .
Nile 작업 공간 슬러그를 사용한 your_workspace_slug

커서와 함께 사용

설정

아직 Cursor를 설치하지 않았다면 설치하세요.
프로젝트를 빌드하세요:
npm run build
오픈 커서
설정(⌘,) > 기능 > MCP 서버로 이동하세요.
"새 MCP 서버 추가"를 클릭하세요
서버를 구성하세요:
- 이름: nile-database (또는 원하는 이름)
- 명령:
  env NILE_API_KEY=your_key NILE_WORKSPACE_SLUG=your_workspace node /absolute/path/to/nile-mcp-server/dist/index.js
  바꾸다:
  - your_key 에 Nile API 키를 추가하세요
  - Nile 작업 공간 슬러그를 사용한 your_workspace
  - /absolute/path/to 프로젝트의 실제 경로로 변경합니다.
"저장"을 클릭하세요
MCP 서버가 연결되었음을 나타내는 녹색 표시기가 표시되어야 합니다.
변경 사항을 적용하려면 커서를 다시 시작하세요.

서버 모드

서버는 두 가지 작동 모드를 지원합니다.

STDIO 모드(기본값)

기본 모드는 통신에 표준 입출력을 사용하므로 Claude Desktop 및 Cursor 통합과 호환됩니다.

SSE 모드

SSE(Server-Sent Events) 모드는 HTTP를 통한 실시간 이벤트 기반 통신을 가능하게 합니다.

SSE 모드를 활성화하려면:

.env 파일에서 MCP_SERVER_MODE=sse 설정하세요.
서버는 HTTP 서버를 시작합니다(기본 포트 3000)
SSE 엔드포인트에 연결: http://localhost:3000/sse
명령을 다음으로 보내세요: http://localhost:3000/messages

curl을 사용한 SSE 사용 예:

# In terminal 1 - Listen for events
curl -N http://localhost:3000/sse

# In terminal 2 - Send commands
curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "type": "function",
    "name": "list-databases",
    "parameters": {}
  }'

예시 프롬프트

Cursor에서 MCP 서버를 설정하면 자연어를 사용하여 나일 데이터베이스와 상호 작용할 수 있습니다. 다음은 몇 가지 프롬프트 예시입니다.

데이터베이스 관리

Create a new database named "my_app" in AWS_US_WEST_2 region

List all my databases

Get details for database "my_app"

Delete database "test_db"

테이블 만들기

Create a users table in my_app database with columns:
- tenant_id (UUID, references tenants)
- id (INTEGER)
- email (VARCHAR, unique per tenant)
- name (VARCHAR)
- created_at (TIMESTAMP)

Create a products table in my_app database with columns:
- tenant_id (UUID, references tenants)
- id (INTEGER)
- name (VARCHAR)
- price (DECIMAL)
- description (TEXT)
- created_at (TIMESTAMP)

데이터 쿼리

Execute this query on my_app database:
SELECT * FROM users WHERE tenant_id = 'your-tenant-id' LIMIT 5

Run this query on my_app:
INSERT INTO users (tenant_id, id, email, name) 
VALUES ('tenant-id', 1, 'user@example.com', 'John Doe')

Show me all products in my_app database with price > 100

스키마 관리

Show me the schema for the users table in my_app database

Add a new column 'status' to the users table in my_app database

Create an index on the email column of the users table in my_app

사용 가능한 도구

서버는 나일 데이터베이스와 상호 작용하기 위한 다음과 같은 도구를 제공합니다.

데이터베이스 관리

데이터베이스 생성
- 새로운 나일 데이터베이스를 생성합니다
- 매개변수:
  - name (문자열): 데이터베이스 이름
  - region (문자열): AWS_US_WEST_2 (오리건) 또는 AWS_EU_CENTRAL_1 (프랑크푸르트)
- 반환: ID, 이름, 지역 및 상태를 포함한 데이터베이스 세부 정보
- 예: "AWS_US_WEST_2에 'my-app'이라는 이름의 데이터베이스를 만듭니다."
목록-데이터베이스
- 작업 공간의 모든 데이터베이스를 나열합니다.
- 매개변수가 필요하지 않습니다
- 반환: ID, 이름, 지역 및 상태가 포함된 데이터베이스 목록
- 예: "내 모든 데이터베이스 나열"
get-database
- 특정 데이터베이스에 대한 자세한 정보를 가져옵니다.
- 매개변수:
  - name (문자열): 데이터베이스 이름
- 반환: API 호스트 및 DB 호스트를 포함한 자세한 데이터베이스 정보
- 예: "데이터베이스 'my-app'에 대한 세부 정보 가져오기"
데이터베이스 삭제
- 데이터베이스를 삭제합니다
- 매개변수:
  - name (문자열): 삭제할 데이터베이스의 이름
- 반환: 확인 메시지
- 예: "데이터베이스 'my-app' 삭제"

자격 증명 관리

목록-자격 증명
- 데이터베이스에 대한 모든 자격 증명을 나열합니다.
- 매개변수:
  - databaseName (문자열): 데이터베이스 이름
- 반환: ID, 사용자 이름 및 생성 날짜가 포함된 자격 증명 목록
- 예: "데이터베이스 'my-app'에 대한 자격 증명을 나열하세요"
자격 증명 생성
- 데이터베이스에 대한 새 자격 증명을 만듭니다.
- 매개변수:
  - databaseName (문자열): 데이터베이스 이름
- 반환: 사용자 이름 및 일회용 비밀번호를 포함한 새로운 자격 증명 세부 정보
- 예: "데이터베이스 'my-app'에 대한 새 자격 증명을 만듭니다."
- 참고: 비밀번호가 표시되면 저장해 두십시오. 다시 표시되지 않습니다.

지역 관리

목록-지역
- 데이터베이스 생성에 사용 가능한 모든 지역을 나열합니다.
- 매개변수가 필요하지 않습니다
- 반환: 사용 가능한 AWS 지역 목록
- 예: "어떤 지역에서 데이터베이스를 만들 수 있나요?"

SQL 쿼리 실행

실행-sql
- 나일 데이터베이스에서 SQL 쿼리를 실행합니다.
- 매개변수:
  - databaseName (문자열): 쿼리할 데이터베이스의 이름
  - query (문자열): 실행할 SQL 쿼리
  - connectionString (문자열, 선택 사항): 쿼리에 사용할 기존 연결 문자열
- 반환: 열 머리글과 행 개수가 포함된 마크다운 테이블 형식으로 쿼리 결과
- 특징:
  - 자동 자격 증명 관리(지정하지 않으면 새로 생성)
  - 데이터베이스에 대한 보안 SSL 연결
  - 마크다운 테이블로 포맷된 결과
  - 힌트가 포함된 자세한 오류 메시지
  - 기존 연결 문자열 사용 지원
- 예: "데이터베이스 'my-app'에서 SELECT * FROM users LIMIT 5 실행"

자원 관리

읽기 리소스
- 데이터베이스 리소스(테이블, 뷰 등)에 대한 스키마 정보를 읽습니다.
- 매개변수:
  - databaseName (문자열): 데이터베이스 이름
  - resourceName (문자열): 리소스(테이블/뷰)의 이름
- 반환: 다음을 포함한 자세한 스키마 정보:
  - 열 이름 및 유형
  - 기본 키와 인덱스
  - 외래 키 관계
  - 열 설명 및 제약 조건
- 예: "my-app의 users 테이블에 대한 스키마를 보여주세요"
목록-리소스
- 데이터베이스의 모든 리소스(테이블, 뷰)를 나열합니다.
- 매개변수:
  - databaseName (문자열): 데이터베이스 이름
- 반환: 모든 리소스와 해당 리소스의 유형 목록
- 예: "my-app 데이터베이스의 모든 테이블 나열"

세입자 관리

테넌트 목록
- 데이터베이스의 모든 테넌트를 나열합니다.
- 매개변수:
  - databaseName (문자열): 데이터베이스 이름
- 반환: ID 및 메타데이터가 포함된 테넌트 목록
- 예: "내 앱 데이터베이스의 모든 테넌트 표시"
테넌트 생성
- 데이터베이스에 새 테넌트를 생성합니다.
- 매개변수:
  - databaseName (문자열): 데이터베이스 이름
  - tenantName (문자열): 새 테넌트의 이름
- 반환: ID를 포함한 새 세입자 세부 정보
- 예: "my-app에 'acme-corp'라는 테넌트를 만듭니다"
삭제-테넌트
- 데이터베이스의 테넌트를 삭제합니다
- 매개변수:
  - databaseName (문자열): 데이터베이스 이름
  - tenantName (문자열): 테넌트의 이름
- 반환: 테넌트가 삭제된 경우 성공
- 예: "my-app에서 'acme-corp'라는 테넌트를 삭제합니다"

사용 예

다음은 Claude Desktop에서 사용할 수 있는 몇 가지 명령의 예입니다.

# Database Management
Please create a new database named "my-app" in the AWS_US_WEST_2 region.
Can you list all my databases?
Get the details for database "my-app".
Delete the database named "test-db".

# Connection String Management
Get a connection string for database "my-app".
# Connection string format: postgres://<user>:<password>@<region>.db.thenile.dev:5432/<database>
# Example: postgres://cred-123:password@us-west-2.db.thenile.dev:5432/my-app

# SQL Queries
Execute SELECT * FROM users LIMIT 5 on database "my-app"
Run this query on my-app database: SELECT COUNT(*) FROM orders WHERE status = 'completed'
Using connection string "postgres://user:pass@host:5432/db", execute this query on my-app: SELECT * FROM products WHERE price > 100

응답 형식

모든 도구는 표준화된 형식으로 응답을 반환합니다.

성공 응답에는 관련 데이터와 확인 메시지가 포함됩니다.
오류 응답에는 자세한 오류 메시지와 HTTP 상태 코드가 포함됩니다.
SQL 쿼리 결과는 마크다운 테이블로 포맷됩니다.
모든 응답은 Claude Desktop에서 쉽게 읽을 수 있도록 형식이 지정되어 있습니다.

오류 처리

서버는 다양한 오류 시나리오를 처리합니다.

잘못된 API 자격 증명
네트워크 연결 문제
잘못된 데이터베이스 이름 또는 지역
필수 매개변수가 없습니다
데이터베이스 작업 실패
유용한 힌트가 포함된 SQL 구문 오류
속도 제한 및 API 제한

문제 해결

클로드가 도구에 접근할 수 없다고 말하는 경우:
- 구성의 서버 경로가 올바른지 확인하세요
- 프로젝트가 빌드되었는지 확인하세요( npm run build )
- API 키와 작업 공간 슬러그가 올바른지 확인하세요.
- Claude Desktop을 다시 시작하세요
데이터베이스 생성에 실패하는 경우:
- API 키 권한을 확인하세요
- 작업 공간에서 데이터베이스 이름이 고유한지 확인하세요.
- 해당 지역이 지원되는 옵션 중 하나인지 확인하세요.
자격 증명 작업이 실패하는 경우:
- 데이터베이스가 존재하고 READY 상태인지 확인하세요.
- API 키에 필요한 권한이 있는지 확인하세요.

개발

프로젝트 구조

nile-mcp-server/
├── src/
│   ├── server.ts      # MCP server implementation
│   ├── tools.ts       # Tool implementations
│   ├── types.ts       # Type definitions
│   ├── logger.ts      # Logging utilities
│   ├── index.ts       # Entry point
│   └── __tests__/     # Test files
│       └── server.test.ts
├── dist/             # Compiled JavaScript
├── logs/            # Log files directory
├── .env             # Environment configuration
├── .gitignore       # Git ignore file
├── package.json     # Project dependencies
└── tsconfig.json    # TypeScript configuration

주요 파일

server.ts : 도구 등록 및 전송 처리를 포함한 메인 서버 구현
tools.ts : 모든 데이터베이스 작업 및 SQL 쿼리 실행 구현
types.ts : 데이터베이스 작업 및 응답을 위한 TypeScript 인터페이스
logger.ts : 일일 로테이션 및 디버그 지원을 갖춘 구조화된 로깅
index.ts : 서버 시작 및 환경 구성
server.test.ts : 모든 기능에 대한 포괄적인 테스트 모음

개발

# Install dependencies
npm install

# Build the project
npm run build

# Start the server in production mode
node dist/index.js

# Start the server using npm script
npm start

# Start in development mode with auto-rebuild
npm run dev

# Run tests
npm test

개발 스크립트

사용 가능한 npm 스크립트는 다음과 같습니다.

npm run build : TypeScript를 JavaScript로 컴파일합니다.
npm start : 서버를 프로덕션 모드로 시작합니다.
npm run dev : 자동 재구축을 통해 개발 모드로 서버를 시작합니다.
npm test : 테스트 모음을 실행합니다
npm run lint : 코드 품질 검사를 위해 ESLint를 실행합니다.
npm run clean : 빌드 아티팩트를 제거합니다.

테스트

이 프로젝트에는 다음을 포함하는 포괄적인 테스트 모음이 포함되어 있습니다.

도구 등록 및 스키마 검증
데이터베이스 관리 작업
연결 문자열 생성
SQL 쿼리 실행 및 오류 처리
응답 형식 및 오류 사례

다음을 사용하여 테스트를 실행합니다.

npm test

벌채 반출

서버는 다음과 같은 기능을 갖춘 구조화된 로깅을 사용합니다.

매일 회전하는 로그 파일
별도의 디버그 로그
타임스탬프가 포함된 JSON 형식 로그
개발을 위한 콘솔 출력
로그 카테고리: 정보, 오류, 디버그, API, SQL, 시작

특허

MIT 라이센스 - 자세한 내용은 라이센스를 참조하세요.

Integrations

특징

설치

수동 설치

다른 mcp 패키지 관리자

서버 시작

서버가 실행 중인지 확인

구성

Claude Desktop과 함께 사용

설정

커서와 함께 사용

설정

서버 모드

STDIO 모드(기본값)

SSE 모드

예시 프롬프트

데이터베이스 관리

테이블 만들기

데이터 쿼리

스키마 관리

사용 가능한 도구

데이터베이스 관리

자격 증명 관리

지역 관리

SQL 쿼리 실행

자원 관리

세입자 관리

사용 예

응답 형식

오류 처리

문제 해결

개발

프로젝트 구조

주요 파일

개발

개발 스크립트

테스트

벌채 반출

특허

관련 링크

Related Resources

Appeared in Searches