nile-mcp

Nileデータベースプラットフォーム用のモデルコンテキストプロトコル（MCP）サーバー実装。このサーバーにより、LLMアプリケーションは標準化されたインターフェースを介してNileプラットフォームと対話できるようになります。

特徴

• データベース管理: データベースの作成、一覧表示、詳細の取得、削除

• 資格情報管理: データベース資格情報の作成と一覧表示

• リージョン管理: データベース作成に利用可能なリージョンの一覧

• SQLクエリのサポート：Nileデータベースで直接SQLクエリを実行します。

• MCPプロトコルサポート: モデルコンテキストプロトコルの完全実装

• 型安全性: 完全な型チェックを備えたTypeScriptで記述されています

• エラー処理: 包括的なエラー処理とユーザーフレンドリーなエラーメッセージ

• テスト範囲: Jest を使用した包括的なテストスイート

• 環境管理: .env ファイルからの環境変数の自動読み込み

• 入力検証: Zodを使用したスキーマベースの入力検証

Related MCP server: mcp-db-server

インストール

安定バージョンをインストールします。

npm install @niledatabase/nile-mcp-server

最新のアルファ/プレビュー バージョン:

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

これにより、@niledatabase/nile-mcp-server が node_modules フォルダにインストールされます。例: 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パッケージマネージャー

1. npx @michaellatman/mcp-get@最新インストール @niledatabase/nile-mcp-server

サーバーの起動

サーバーを起動するにはいくつかの方法があります。

1. 直接ノード実行:

   node dist/index.js

2. 開発モード（自動再構築付き）:

   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での使用

設定

1. Claude Desktopをまだインストールしていない場合はインストールしてください

2. プロジェクトをビルドします。

   npm run build

3. クロードデスクトップを開く

4. 設定 > MCPサーバーへ移動

5. 「サーバーを追加」をクリックします

6. 次の構成を追加します。

{
  "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 API キーを入力します

• your_workspace_slug Nile ワークスペースのスラッグに置き換えます

カーソルの使用

設定

1. まだインストールしていない場合は、 Cursorをインストールしてください。

2. プロジェクトをビルドします。

   npm run build

3. オープンカーソル

4. 設定 (⌘,) > 機能 > MCP サーバーに移動します。

5. 「新しいMCPサーバーを追加」をクリックします

6. サーバーを構成します。

   • 名前: 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 キーに置き換えます

     • your_workspace Nile ワークスペースのスラッグに置き換えます

     • /absolute/path/toプロジェクトの実際のパスに置き換えます

7. 「保存」をクリック

8. MCPサーバーが接続されていることを示す緑色のインジケーターが表示されます。

9. 変更を有効にするにはカーソルを再起動してください

サーバーモード

サーバーは次の 2 つの動作モードをサポートしています。

STDIO モード (デフォルト)

デフォルト モードでは通信に標準入出力が使用されるため、Claude Desktop および Cursor の統合と互換性があります。

SSEモード

Server-Sent Events (SSE) モードでは、HTTP 経由のリアルタイムのイベント駆動型通信が可能になります。

SSE モードを有効にするには:

1. .envファイルでMCP_SERVER_MODE=sseを設定します

2. サーバーはHTTPサーバーを起動します（デフォルトポート3000）

3. SSEエンドポイントに接続します: http://localhost:3000/sse

4. コマンドの送信先: 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サーバーを設定すると、自然言語を使ってNileデータベースと対話できるようになります。以下にプロンプトの例を示します。

データベース管理

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

利用可能なツール

サーバーは、Nile データベースと対話するための次のツールを提供します。

データベース管理

1. データベースの作成

   • 新しいNileデータベースを作成する

   • パラメータ:

     • name (文字列): データベースの名前

     • region （文字列）： AWS_US_WEST_2 （オレゴン）またはAWS_EU_CENTRAL_1 （フランクフルト）のいずれか

   • 返される値: ID、名前、地域、ステータスなどのデータベースの詳細

   • 例:「AWS_US_WEST_2 に 'my-app' という名前のデータベースを作成する」

2. データベース一覧

   • ワークスペース内のすべてのデータベースを一覧表示します

   • パラメータは必要ありません

   • 戻り値: ID、名前、リージョン、ステータスを含むデータベースのリスト

   • 例:「すべてのデータベースを一覧表示する」

3. データベースを取得する

   • 特定のデータベースに関する詳細情報を取得します

   • パラメータ:

     • name (文字列): データベースの名前

   • 戻り値: APIホストとDBホストを含む詳細なデータベース情報

   • 例:「データベース 'my-app' の詳細を取得する」

4. データベースの削除

   • データベースを削除します

   • パラメータ:

     • name (文字列): 削除するデータベースの名前

   • 戻り値: 確認メッセージ

   • 例:「データベース 'my-app' を削除する」

資格情報管理

1. 資格情報リスト

   • データベースのすべての資格情報を一覧表示します

   • パラメータ:

     • databaseName (文字列): データベースの名前

   • 戻り値: ID、ユーザー名、作成日を含む資格情報のリスト

   • 例:「データベース 'my-app' の資格情報を一覧表示する」

2. 資格情報の作成

   • データベースの新しい資格情報を作成します

   • パラメータ:

     • databaseName (文字列): データベースの名前

   • 戻り値: ユーザー名とワンタイムパスワードを含む新しい認証情報の詳細

   • 例:「データベース 'my-app' の新しい資格情報を作成する」

   • 注: パスワードは再度表示されないため、表示されたら保存してください。

地域管理

1. リスト領域

   • データベースの作成に利用可能なすべてのリージョンを一覧表示します

   • パラメータは必要ありません

   • 戻り値: 利用可能なAWSリージョンのリスト

   • 例: 「データベースの作成に使用できるリージョンはどこですか?」

SQLクエリ実行

1. SQL実行

   • NileデータベースでSQLクエリを実行します

   • パラメータ:

     • databaseName (文字列): クエリするデータベースの名前

     • query (文字列): 実行するSQLクエリ

     • connectionString (文字列、オプション): クエリに使用する既存の接続文字列

   • 戻り値: 列ヘッダーと行数を含むマークダウンテーブルとしてフォーマットされたクエリ結果

   • 特徴：

     • 自動認証情報管理（指定されていない場合は新規作成）

     • データベースへの安全なSSL接続

     • 結果はマークダウンテーブルとしてフォーマットされます

     • ヒント付きの詳細なエラーメッセージ

     • 既存の接続文字列の使用のサポート

   • 例:「データベース 'my-app' で SELECT * FROM users LIMIT 5 を実行する」

リソース管理

1. リソースの読み取り

   • データベース リソース (テーブル、ビューなど) のスキーマ情報を読み取ります。

   • パラメータ:

     • databaseName (文字列): データベースの名前

     • resourceName (文字列): リソースの名前 (テーブル/ビュー)

   • 返される値: 次の詳細なスキーマ情報:

     • 列名と型

     • 主キーとインデックス

     • 外部キー関係

     • 列の説明と制約

   • 例:「my-app の users テーブルのスキーマを表示してください」

2. リストリソース

   • データベース内のすべてのリソース（テーブル、ビュー）を一覧表示します

   • パラメータ:

     • databaseName (文字列): データベースの名前

   • 戻り値: すべてのリソースとそのタイプの一覧

   • 例:「my-app データベース内のすべてのテーブルを一覧表示する」

テナント管理

1. テナントリスト

   • データベース内のすべてのテナントを一覧表示します

   • パラメータ:

     • databaseName (文字列): データベースの名前

   • 戻り値: IDとメタデータを含むテナントのリスト

   • 例:「my-app データベース内のすべてのテナントを表示する」

2. テナント作成

   • データベースに新しいテナントを作成します

   • パラメータ:

     • databaseName (文字列): データベースの名前

     • tenantName (文字列): 新しいテナントの名前

   • 戻り値: IDを含む新しいテナントの詳細

   • 例:「my-app に 'acme-corp' という名前のテナントを作成する」

3. テナントの削除

   • データベース内のテナントを削除します

   • パラメータ:

     • 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制限

トラブルシューティング

1. Claude がツールにアクセスできないと言った場合:

   • 構成内のサーバーパスが正しいことを確認してください

   • プロジェクトがビルドされていることを確認する ( npm run build )

   • APIキーとワークスペーススラッグが正しいことを確認してください

   • Claudeデスクトップを再起動します

2. データベースの作成に失敗した場合:

   • APIキーの権限を確認する

   • データベース名がワークスペース内で一意であることを確認してください

   • 地域がサポートされているオプションの1つであることを確認します

3. 資格情報の操作が失敗した場合:

   • データベースが存在し、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 ライセンス - 詳細についてはライセンスを参照してください。

関連リンク

• モデルコンテキストプロトコル

• ナイルデータベース

• クロードデスクトップ

• カーソル