Nile Mcp Server

Nile MCP Server

詳しくはこちら ↗️

Discord 🔵 ウェブサイト 🔵 問題報告

Nile データベースプラットフォーム向けの Model Context Protocol（MCP）サーバー実装です。このサーバーを使用すると、LLM アプリケーションは標準化されたインターフェースを通じて Nile プラットフォームとやり取りできます。

特長

• データベース管理：データベースの作成、一覧表示、詳細の取得、削除
• 認証情報管理：データベース認証情報の作成と一覧表示
• リージョン管理：データベース作成に利用できるリージョンの一覧表示
• SQL クエリのサポート：Nile データベースで SQL クエリを直接実行
• MCP プロトコルのサポート：Model Context Protocol を完全に実装
• 型安全性：完全な型チェックを備えた TypeScript で記述
• エラー処理：包括的なエラー処理とわかりやすいエラーメッセージ
• テストカバレッジ：Jest を使用した包括的なテストスイート
• 環境管理：.env ファイルから環境変数を自動的に読み込み
• 入力検証：Zod を使用したスキーマベースの入力検証

インストール

安定版をインストールします：

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@latest install @niledatabase/nile-mcp-server

サーバーの起動

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

1. Node から直接実行：

   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 からのコマンドを受け付ける準備ができています。

設定

ルートディレクトリに .env ファイルを作成し、Nile の認証情報を設定します。

NILE_API_KEY=your_api_key_here
NILE_WORKSPACE_SLUG=your_workspace_slug

Nile API キーを作成するには、Nile アカウントにログインし、左上の Workspaces をクリックしてワークスペースを選択し、左側のメニューから Security セクションに移動します。

Claude Desktop での使用

セットアップ

1. まだインストールしていない場合は、Claude Desktop をインストールします
2. プロジェクトをビルドします：

   npm run build
   

3. Claude Desktop を開きます
4. Settings > MCP Servers に移動します
5. 「Add Server」をクリックします
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 ワークスペースのスラッグに置き換えます

Cursor での使用

セットアップ

1. まだの場合は、Cursor をインストールします
2. プロジェクトをビルドします：

   npm run build
   

3. Cursor を開きます
4. Settings（⌘,）> Features > MCP Servers に移動します
5. 「Add New MCP Server」をクリックします
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. 「Save」をクリックします
8. MCP サーバーが接続されていることを示す緑色のインジケーターが表示されます
9. 変更を反映するため、Cursor を再起動します

サーバーモード

サーバーは、次の 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, '[email protected]', '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. create-database

   • 新しい Nile データベースを作成します
   • パラメーター：
     • name（string）：データベースの名前
     • region（string）：AWS_US_WEST_2（オレゴン）または AWS_EU_CENTRAL_1（フランクフルト）
   • 戻り値：ID、名前、リージョン、ステータスなどのデータベースの詳細
   • 例：「AWS_US_WEST_2 に「my-app」という名前のデータベースを作成して」

2. list-databases

   • ワークスペース内のすべてのデータベースを一覧表示します
   • パラメーターは不要です
   • 戻り値：ID、名前、リージョン、ステータスを含むデータベースの一覧
   • 例：「すべてのデータベースを一覧表示して」

3. get-database

   • 特定のデータベースの詳細情報を取得します
   • パラメーター：
     • name（string）：データベースの名前
   • 戻り値：API ホストや DB ホストなどのデータベースの詳細情報
   • 例：「データベース「my-app」の詳細を取得して」

4. delete-database

   • データベースを削除します
   • パラメーター：
     • name（string）：削除するデータベースの名前
   • 戻り値：確認メッセージ
   • 例：「データベース「my-app」を削除して」

認証情報の管理

1. list-credentials

   • データベースのすべての認証情報を一覧表示します
   • パラメーター：
     • databaseName（string）：データベースの名前
   • 戻り値：ID、ユーザー名、作成日を含む認証情報の一覧
   • 例：「データベース「my-app」の認証情報を一覧表示して」

2. create-credential

   • データベースの新しい認証情報を作成します
   • パラメーター：
     • databaseName（string）：データベースの名前
   • 戻り値：ユーザー名や一度限りのパスワードなど、新しい認証情報の詳細
   • 例：「データベース「my-app」の新しい認証情報を作成して」
   • 注意：パスワードは再表示されないため、表示されたときに保存してください

リージョン管理

1. list-regions
   • データベースの作成に利用可能なすべてのリージョンを一覧表示します
   • パラメーターは不要です
   • 戻り値：利用可能な AWS リージョンの一覧
   • 例：「データベースの作成に利用できるリージョンは？」

SQL クエリの実行

1. execute-sql
   • Nile データベースで SQL クエリを実行します
   • パラメーター：
     • databaseName (string)：クエリ対象のデータベース名
     • query (string)：実行する SQL クエリ
     • connectionString (string, optional)：クエリに使用する既存の接続文字列
   • 戻り値：列ヘッダーと行数を含む Markdown テーブル形式のクエリ結果
   • 機能：
     • 認証情報を自動管理します（指定されていない場合は新規作成します）
     • データベースへの安全な SSL 接続
     • 結果を Markdown テーブル形式で表示します
     • ヒント付きの詳細なエラーメッセージ
     • 既存の接続文字列を使用できます
   • 例：「データベース 'my-app' で SELECT * FROM users LIMIT 5 を実行」

リソース管理

1. read-resource

   • データベースリソース（テーブル、ビューなど）のスキーマ情報を読み取ります
   • パラメーター：
     • databaseName (string)：データベース名
     • resourceName (string)：リソース（テーブル／ビュー）の名前
   • 戻り値：以下を含む詳細なスキーマ情報：
     • 列名と型
     • 主キーとインデックス
     • 外部キーの関連
     • 列の説明と制約
   • 例：「my-app の users テーブルのスキーマを表示」

2. list-resources

   • データベース内のすべてのリソース（テーブル、ビュー）を一覧表示します
   • パラメーター：
     • databaseName (string)：データベース名
   • 戻り値：種類を含むすべてのリソースの一覧
   • 例：「my-app データベースのすべてのテーブルを一覧表示」

テナント管理

1. list-tenants

   • データベース内のすべてのテナントを一覧表示します
   • パラメーター：
     • databaseName (string)：データベース名
   • 戻り値：ID とメタデータを含むテナントの一覧
   • 例：「my-app データベース内のすべてのテナントを表示」

2. create-tenant

   • データベースに新しいテナントを作成します
   • パラメーター：
     • databaseName (string)：データベース名
     • tenantName (string)：新しいテナントの名前
   • 戻り値：ID を含む新しいテナントの詳細
   • 例：「my-app に 'acme-corp' という名前のテナントを作成」

3. delete-tenant

   • データベース内のテナントを削除します
   • パラメーター：
     • databaseName (string)：データベース名
     • tenantName (string)：テナント名
   • 戻り値：テナントが削除された場合に成功を返します
   • 例：「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:[email protected]: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 クエリの結果は Markdown テーブル形式で表示されます
• すべての応答は Claude Desktop で読みやすい形式になっています

エラー処理

サーバーは、次のようなさまざまなエラー状況に対応します。

• API 認証情報が無効
• ネットワーク接続の問題
• データベース名またはリージョンが無効
• 必須パラメーターの不足
• データベース操作の失敗
• ヒント付きの SQL 構文エラー
• レート制限と API の制約

トラブルシューティング

1. Claude がツールにアクセスできないと表示する場合：

   • 設定内のサーバーパスが正しいことを確認します
   • プロジェクトがビルドされていることを確認します（npm run build）
   • API キーとワークスペーススラッグが正しいことを確認します
   • Claude Desktop を再起動します

2. データベースの作成に失敗する場合：

   • API キーの権限を確認します
   • ワークスペース内でデータベース名が一意であることを確認します
   • リージョンがサポート対象の選択肢のいずれかであることを確認します

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 形式ログ
• 開発用のコンソール出力
• ログカテゴリ：info、error、debug、api、sql、startup

ライセンス

MIT ライセンス。詳細は LICENSE をご覧ください。

関連リンク

• Model Context Protocol
• Nile Database
• Claude Desktop
• Cursor