nile-mcp

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

特徴

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

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

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

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

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

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

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

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

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

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

インストール

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

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

これにより、@niledatabase/nile-mcp-server が node_modules フォルダにインストールされます。例: node_modules/@niledatabase/nile-mcp-server/dist/

手動インストール

その他のmcpパッケージマネージャー

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

サーバーの起動

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

1. 直接ノード実行:

   node dist/index.js

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

   npm run dev

サーバーが起動し、MCPプロトコルメッセージをリッスンします。起動ログに以下の内容が表示されます。

• 環境変数が読み込まれました

• サーバーインスタンスが作成されました

• ツールが初期化されました

• トランスポート接続が確立されました

サーバーを停止するには、 Ctrl+Cを押します。

サーバーが実行中であることを確認する

サーバーが正常に起動すると、次のようなログが表示されます。

これらのログが表示された場合、サーバーは Claude Desktop からのコマンドを受け入れる準備ができています。

構成

Nile の資格情報を使用して、ルート ディレクトリに.envファイルを作成します。

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

Claude Desktopでの使用

設定

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

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

   npm run build

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

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

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

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

交換する：

• /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 の使用例:

プロンプトの例

CursorでMCPサーバーを設定すると、自然言語を使ってNileデータベースと対話できるようになります。以下にプロンプトの例を示します。

データベース管理

テーブルの作成

データのクエリ

スキーマ管理

利用可能なツール

サーバーは、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 で使用できるコマンドの例を次に示します。

応答フォーマット

すべてのツールは、標準化された形式で応答を返します。

• 成功応答には関連データと確認メッセージが含まれます

• エラー応答には、詳細なエラーメッセージとHTTPステータスコードが含まれます。

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

• すべての回答はClaude Desktopで読みやすいようにフォーマットされています

エラー処理

サーバーはさまざまなエラー シナリオを処理します。

• 無効なAPI認証情報

• ネットワーク接続の問題

• 無効なデータベース名またはリージョン

• 必要なパラメータが不足しています

• データベース操作の失敗

• 役立つヒント付きのSQL構文エラー

• レート制限とAPI制限

トラブルシューティング

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

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

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

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

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

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

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

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

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

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

   • データベースが存在し、READY状態であることを確認します

   • APIキーに必要な権限があることを確認してください

発達

プロジェクト構造

キーファイル

• server.ts : ツール登録とトランスポート処理を備えたメインサーバーの実装

• tools.ts : すべてのデータベース操作とSQLクエリ実行の実装

• types.ts : データベース操作と応答のための TypeScript インターフェース

• logger.ts : 毎日のローテーションとデバッグサポートを備えた構造化ログ

• index.ts : サーバーの起動と環境設定

• server.test.ts : すべての機能に対する包括的なテストスイート

発達

開発スクリプト

次の npm スクリプトが利用可能です。

• npm run build : TypeScript を JavaScript にコンパイルする

• npm start : サーバーを本番モードで起動します

• npm run dev : 自動再構築付きの開発モードでサーバーを起動します

• npm test : テストスイートを実行する

• npm run lint : コード品質チェックのために ESLint を実行する

• npm run clean : ビルド成果物を削除する

テスト

このプロジェクトには、以下をカバーする包括的なテスト スイートが含まれています。

• ツールの登録とスキーマの検証

• データベース管理操作

• 接続文字列の生成

• SQLクエリの実行とエラー処理

• レスポンスのフォーマットとエラーケース

次のようにテストを実行します。

ログ記録

サーバーは、次の機能を備えた構造化ログを使用します。

• 毎日ローテーションするログファイル

• 個別のデバッグログ

• タイムスタンプ付きのJSON形式のログ

• 開発用コンソール出力

• ログ カテゴリ: 情報、エラー、デバッグ、API、SQL、スタートアップ

ライセンス

MIT ライセンス - 詳細についてはライセンスを参照してください。

関連リンク

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

• ナイルデータベース

• クロードデスクトップ

• カーソル