SingleStore MCP Server

SingleStore MCP サーバー

SingleStore データベースとやり取りするための Model Context Protocol（MCP）サーバーです。このサーバーでは、テーブルのクエリ、スキーマの説明、ER 図の生成を行うツールを提供します。

特長

• データベース内のすべてのテーブルを一覧表示
• カスタム SQL クエリを実行
• スキーマやサンプルデータを含む詳細なテーブル情報を取得
• データベーススキーマの Mermaid ER 図を生成
• CA バンドルを自動取得する SSL サポート
• 適切なエラー処理と TypeScript の型安全性

前提条件

• Node.js 16 以降
• npm または yarn
• SingleStore データベースへのアクセス
• SingleStore CA バンドル（ポータルから自動取得）

インストール

Smithery 経由でインストール

Smithery 経由で Claude Desktop 用の SingleStore MCP サーバーを自動的にインストールするには：

npx -y @smithery/cli install @madhukarkumar/singlestore-mcp-server --client claude

1. リポジトリをクローンします：

git clone <repository-url>
cd mcp-server-singlestore

2. 依存関係をインストールします：

npm install

3. サーバーをビルドします：

npm run build

環境変数

必須の環境変数

データベースへの接続には、以下の環境変数が必要です：

SINGLESTORE_HOST=your-host.singlestore.com
SINGLESTORE_PORT=3306
SINGLESTORE_USER=your-username
SINGLESTORE_PASSWORD=your-password
SINGLESTORE_DATABASE=your-database

SingleStore データベースへの接続を確立するには、これらすべての環境変数が必要です。接続には SSL を使用し、SingleStore CA バンドルは SingleStore ポータルから自動的に取得されます。

オプションの環境変数

SSE（Server-Sent Events）プロトコルをサポートする場合：

SSE_ENABLED=true       # Enable the SSE HTTP server (default: false if not set)
SSE_PORT=3333          # HTTP port for the SSE server (default: 3333 if not set)

環境変数の設定

1. シェルで設定する場合： サーバーを実行する前に、ターミナルで変数を設定します：

   export SINGLESTORE_HOST=your-host.singlestore.com
   export SINGLESTORE_PORT=3306
   export SINGLESTORE_USER=your-username
   export SINGLESTORE_PASSWORD=your-password
   export SINGLESTORE_DATABASE=your-database
   

2. クライアント設定ファイルで設定する場合： 以下の統合セクションに示すように、MCP クライアント設定ファイルに変数を追加します。

使用方法

プロトコルのサポート

このサーバーは、クライアントとの連携に次の 2 つのプロトコルをサポートしています：

1. MCP プロトコル：stdio 通信を使用する標準の Model Context Protocol で、Claude Desktop、Windsurf、Cursor で使用されます。
2. SSE プロトコル：リアルタイムのデータストリーミングが必要なウェブベースのクライアントやアプリケーション向けの、HTTP を介した Server-Sent Events です。

どちらのプロトコルでも同じツールと機能を利用できるため、用途に応じて最適な連携方法を選択できます。

利用可能なツール

1. list_tables

   • データベース内のすべてのテーブルを一覧表示します
   • パラメーターは不要です

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "list_tables",
     arguments: {}
   })
   

2. query_table

   • カスタム SQL クエリを実行します
   • パラメーター：
     • query：SQL クエリ文字列

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "query_table",
     arguments: {
       query: "SELECT * FROM your_table LIMIT 5"
     }
   })
   

3. describe_table

   • テーブルの詳細情報を取得します
   • パラメーター：
     • table：テーブル名

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "describe_table",
     arguments: {
       table: "your_table"
     }
   })
   

4. generate_er_diagram

   • データベーススキーマの Mermaid ER 図を生成します
   • パラメーターは不要です

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "generate_er_diagram",
     arguments: {}
   })
   

5. run_read_query

   • データベースに対して読み取り専用（SELECT）クエリを実行します
   • パラメーター：
     • query：実行する SQL SELECT クエリ

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "run_read_query",
     arguments: {
       query: "SELECT * FROM your_table LIMIT 5"
     }
   })
   

6. create_table

   • 指定した列と制約を使用して、データベースに新しいテーブルを作成します
   • パラメーター：
     • table_name：作成するテーブルの名前
     • columns：列定義の配列
     • table_options：任意のテーブル設定

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "create_table",
     arguments: {
       table_name: "new_table",
       columns: [
         {
           name: "id",
           type: "INT",
           nullable: false,
           auto_increment: true
         },
         {
           name: "name",
           type: "VARCHAR(255)",
           nullable: false
         }
       ],
       table_options: {
         shard_key: ["id"],
         sort_key: ["name"]
       }
     }
   })
   

7. generate_synthetic_data

   • 既存のテーブルに合成データを生成して挿入します
   • パラメーター：
     • table：データを挿入するテーブルの名前
     • count：生成する行数（デフォルト：100）
     • column_generators：特定の列に対するカスタムジェネレーター
     • batch_size：各バッチで挿入する行数（デフォルト：1000）

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "generate_synthetic_data",
     arguments: {
       table: "customers",
       count: 1000,
       column_generators: {
         "customer_id": {
           "type": "sequence",
           "start": 1000
         },
         "status": {
           "type": "values",
           "values": ["active", "inactive", "pending"]
         },
         "signup_date": {
           "type": "formula",
           "formula": "NOW() - INTERVAL FLOOR(RAND() * 365) DAY"
         }
       },
       batch_size: 500
     }
   })
   

8. optimize_sql

   • PROFILE を使用して SQL クエリを分析し、最適化の推奨事項を提示します
   • パラメーター：
     • query：分析および最適化する SQL クエリ

   use_mcp_tool({
     server_name: "singlestore",
     tool_name: "optimize_sql",
     arguments: {
       query: "SELECT * FROM customers JOIN orders ON customers.id = orders.customer_id WHERE region = 'west'"
     }
   })
   

   • レスポンスには以下が含まれます：
     • 元のクエリ
     • パフォーマンスプロファイルの概要（合計実行時間、コンパイル時間、実行時間）
     • 検出されたボトルネックの一覧
     • 影響度（高／中／低）付きの最適化の推奨事項
     • インデックス、結合、メモリ使用量、その他の最適化に関する提案

スタンドアロンでの実行

1. サーバーをビルドします：

npm run build

2. MCP プロトコルのみでサーバーを実行します：

node build/index.js

3. MCP プロトコルと SSE プロトコルの両方でサーバーを実行します：

SSE_ENABLED=true SSE_PORT=3333 node build/index.js

SSE プロトコルの使用

SSE が有効な場合、サーバーは次の HTTP エンドポイントを公開します：

1. ルートエンドポイント

   GET /
   

   サーバー情報と利用可能なエンドポイントを返します。

2. ヘルスチェック

   GET /health
   

   サーバーのステータス情報を返します。

3. SSE 接続

   GET /sse
   

   リアルタイム更新用の Server-Sent Events 接続を確立します。

4. ツールの一覧表示

   GET /tools
   

   MCP の list_tools 機能と同じく、利用可能なすべてのツールの一覧を返します。

   MCP Inspector との互換性のため、POST リクエストにも対応しています：

   POST /tools
   Content-Type: application/json
   
   {
     "jsonrpc": "2.0",
     "id": "request-id",
     "method": "mcp.list_tools",
     "params": {}
   }
   

5. ツールの呼び出し

   POST /call-tool
   Content-Type: application/json
   
   {
     "name": "tool_name",
     "arguments": {
       "param1": "value1",
       "param2": "value2"
     },
     "client_id": "optional_sse_client_id_for_streaming_response"
   }
   

   指定された引数でツールを実行します。

   • client_id が指定されている場合、レスポンスはその SSE クライアントにストリーミングされます。
   • client_id が省略されている場合、レスポンスは HTTP レスポンスで直接返されます。

   MCP Inspector との互換性のため、標準の MCP 形式にも対応しています：

   POST /call-tool
   Content-Type: application/json
   
   {
     "jsonrpc": "2.0",
     "id": "request-id",
     "method": "mcp.call_tool",
     "params": {
       "name": "tool_name",
       "arguments": {
         "param1": "value1",
         "param2": "value2"
       },
       "_meta": {
         "client_id": "optional_sse_client_id_for_streaming_response"
       }
     }
   }
   

SSE イベントの種類

SSE 接続を使用すると、サーバーは次の種類のイベントを送信します：

1. message（名前なしイベント）：SSE 接続が正常に確立されたときに送信されます。
2. open：接続の確立を示す追加イベントです。
3. message：ツールの開始、結果、エラーのイベントを含む、すべての MCP プロトコルメッセージに使用されます。

すべてのイベントは、MCP プロトコルで使用される JSON-RPC 2.0 形式に従います。MCP Inspector およびほとんどの SSE クライアントライブラリとの互換性を確保するため、標準の message イベントタイプを使用します。

JavaScript クライアントの例

// Connect to SSE endpoint
const eventSource = new EventSource('http://localhost:3333/sse');
let clientId = null;

// Handle connection establishment via unnamed event
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'connection_established') {
    clientId = data.clientId;
    console.log(`Connected with client ID: ${clientId}`);
  }
};

// Handle open event
eventSource.addEventListener('open', (event) => {
  console.log('SSE connection opened via open event');
});

// Handle all MCP messages
eventSource.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  
  if (data.jsonrpc === '2.0') {
    if (data.result) {
      console.log('Tool result:', data.result);
    } else if (data.error) {
      console.error('Tool error:', data.error);
    } else if (data.method === 'mcp.call_tool.update') {
      console.log('Tool update:', data.params);
    }
  }
});

// Call a tool with streaming response (custom format)
async function callTool(name, args) {
  const response = await fetch('http://localhost:3333/call-tool', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: name,
      arguments: args,
      client_id: clientId
    })
  });
  return response.json();
}

// Call a tool with streaming response (MCP format)
async function callToolMcp(name, args) {
  const response = await fetch('http://localhost:3333/call-tool', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 'request-' + Date.now(),
      method: 'mcp.call_tool',
      params: {
        name: name,
        arguments: args,
        _meta: {
          client_id: clientId
        }
      }
    })
  });
  return response.json();
}

// Example usage
callTool('list_tables', {})
  .then(response => console.log('Request accepted:', response));

MCP Inspector での使用方法

MCP Inspector は、MCP サーバーのテストとデバッグに使うブラウザーベースのツールです。このサーバーで使用するには、次の手順を実行します。

1. サーバーと MCP Inspector の両方を、1 つのコマンドで起動します。

   npm run inspector
   

   または、サーバーだけを次のコマンドで起動します。

   npm run start:inspector
   

2. MCP Inspector を個別にインストールして実行します。

   npx @modelcontextprotocol/inspector
   

   Inspector がデフォルトのブラウザーで開きます。

3. MCP Inspector が開いたら、次の操作を行います。

   a. 接続フィールドに URL を入力します。

   http://localhost:8081
   

   注：実際のポートは設定によって異なる場合があります。使用されている実際のポートは、サーバーの起動ログで確認してください。サーバーには次のように表示されます。

   MCP SingleStore SSE server listening on port XXXX
   

   b. トランスポートの種類として「SSE」が選択されていることを確認します。

   c. 「Connect」をクリックします。

4. 接続に問題が発生した場合は、次の方法をお試しください。

   a. 特定のエンドポイントへの接続を試します。

   http://localhost:8081/stream
   

   b. お使いのマシンの実際の IP アドレスを使用してみます。

   http://192.168.1.x:8081
   

   c. Docker で実行している場合：

   http://host.docker.internal:8081
   

5. 接続の問題をデバッグする：

   a. ブラウザーで http://localhost:8081 にアクセスし、サーバーが実行中であることを確認します。

   b. サーバーログで接続の試行を確認します。

   c. サーバーと Inspector の両方を再起動してみます。

   d. ポート 8081 が他のサービスで使用されていないことを確認します。

   e. 次のスクリプトで SSE 接続をテストします。

   npm run test:sse
   

   または、curl で手動で実行します。

   curl -N http://localhost:8081/sse
   

   f. ファイアウォールの設定で、ポート 8081 への接続が許可されていることを確認します。

6. 接続すると、Inspector に利用可能なすべてのツールが表示され、対話形式でテストできるようになります。

⚠️ 注：MCP Inspector を使用する場合は、http:// プレフィックスを含む完全な URL を使用する必要があります。

MCP クライアントとの統合

Claude Desktop へのインストール

1. 次の場所にある Claude Desktop の設定ファイルに、サーバーの設定を追加します。
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "singlestore": {
      "command": "node",
      "args": ["path/to/mcp-server-singlestore/build/index.js"],
      "env": {
        "SINGLESTORE_HOST": "your-host.singlestore.com",
        "SINGLESTORE_PORT": "3306",
        "SINGLESTORE_USER": "your-username",
        "SINGLESTORE_PASSWORD": "your-password",
        "SINGLESTORE_DATABASE": "your-database",
        "SSE_ENABLED": "true",
        "SSE_PORT": "3333"
      }
    }
  }
}

SSE_ENABLED と SSE_PORT の変数は任意です。標準の MCP プロトコルと併せて、SSE をサポートする HTTP サーバーを有効にする場合に指定してください。

2. Claude Desktop アプリを再起動します。

3. Claude との会話で、次のように SingleStore MCP サーバーを使用できるようになります。

use_mcp_tool({
  server_name: "singlestore",
  tool_name: "list_tables",
  arguments: {}
})

Windsurf へのインストール

1. 次の場所にある Windsurf の設定ファイルに、サーバーの設定を追加します。
   • macOS：~/Library/Application Support/Windsurf/config.json
   • Windows：%APPDATA%\Windsurf\config.json

{
  "mcpServers": {
    "singlestore": {
      "command": "node",
      "args": ["path/to/mcp-server-singlestore/build/index.js"],
      "env": {
        "SINGLESTORE_HOST": "your-host.singlestore.com",
        "SINGLESTORE_PORT": "3306",
        "SINGLESTORE_USER": "your-username",
        "SINGLESTORE_PASSWORD": "your-password",
        "SINGLESTORE_DATABASE": "your-database",
        "SSE_ENABLED": "true",
        "SSE_PORT": "3333"
      }
    }
  }
}

SSE_ENABLED と SSE_PORT の変数は任意ですが、SSE HTTP サーバーを通じて追加機能を利用できます。

2. Windsurf を再起動します。

3. Windsurf で Claude と会話すると、Claude がデータベース情報にアクセスする必要があるときに、SingleStore MCP ツールが自動的に利用可能になります。

Cursor へのインストール

1. Cursor の設定にサーバーの設定を追加します。
   • Cursor を開きます。
   • Settings（歯車アイコン）> Extensions > Claude AI > MCP Servers の順に移動します。
   • 次の設定で新しい MCP サーバーを追加します。

{
  "singlestore": {
    "command": "node",
    "args": ["path/to/mcp-server-singlestore/build/index.js"],
    "env": {
      "SINGLESTORE_HOST": "your-host.singlestore.com",
      "SINGLESTORE_PORT": "3306",
      "SINGLESTORE_USER": "your-username",
      "SINGLESTORE_PASSWORD": "your-password",
      "SINGLESTORE_DATABASE": "your-database",
      "SSE_ENABLED": "true",
      "SSE_PORT": "3333"
    }
  }
}

SSE_ENABLED と SSE_PORT を指定すると、ウェブアプリケーションが HTTP 経由でサーバーに接続し、Server-Sent Events を通じてリアルタイムの更新を受信できるようになります。

2. Cursor を再起動します。

3. Cursor 内で Claude AI を使用すると、データベース操作に SingleStore MCP ツールを利用できます。

セキュリティに関する考慮事項

1. 認証情報をバージョン管理に決してコミットしないでください。
2. 環境変数または安全な設定管理を使用してください。
3. 本番環境では、コネクションプーリングの仕組みの利用を検討してください。
4. SingleStore で適切なアクセス制御とユーザー権限を設定してください。
5. SingleStore CA バンドルを最新の状態に保ってください。

開発

プロジェクト構成

mcp-server-singlestore/
├── src/
│   └── index.ts      # Main server implementation
├── package.json
├── tsconfig.json
├── README.md
└── CHANGELOG.md

ビルド

npm run build

テスト

npm test

トラブルシューティング

1. 接続に関する問題

   • 環境変数の認証情報とホスト情報を確認します
   • SSL の設定を確認します
   • ネットワークからデータベースにアクセスできることを確認します
   • SingleStore データベースへのアウトバウンド接続を許可するよう、ファイアウォールの設定を確認します

2. ビルドに関する問題

   • node_modules を削除して、依存関係を再インストールします
   • TypeScript の設定を確認します
   • Node.js のバージョン互換性を確認します（16 以降である必要があります）

3. MCP 統合に関する問題

   • クライアント設定で、サーバーの build/index.js ファイルへのパスが正しいことを確認します
   • クライアント設定ですべての環境変数が適切に設定されていることを確認します
   • 設定を変更した後、クライアントアプリケーションを再起動します
   • MCP サーバーに関連するエラーメッセージがないか、クライアントのログを確認します
   • まずサーバーを単独で実行し、クライアント外でも動作することを確認します

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. プルリクエストを作成します

ライセンス

MIT ライセンス - 詳細は LICENSE ファイルを参照してください