VISUAL-MCP

MCPDemo - AI 駆動のデータ可視化と SQL Chat プラットフォーム

本プロジェクトは、**モデルコンテキストプロトコル（Model Context Protocol、MCP）**に基づく総合的なデータサービスプラットフォームです。データ可視化、SQL のスマートクエリ、リンク管理機能を統合しています。AI 駆動の自然言語処理により、データのクエリと可視化をより簡単かつ効率的に行えます。

1. 何に使えますか？

• 中国語／英語で「SQL Chat」と対話し、AI に SQL の作成と実行を任せられます。
• クエリ結果をワンクリックでグラフ（折れ線、棒、円、ヒートマップなど）に変換し、共有可能なリンクを生成できます。
• Dashboard でグラフをドラッグ＆ドロップして、自分だけの複数グラフのダッシュボードを作成できます。
• MCP 対応クライアントで「グラフ／SQL アシスタント」ツールソースとして利用できます。

2. オンラインで使う場合（自分でデプロイしない場合）

• ウェブサイトのホームページを開きます：http://mcp.zha-ji.cn
• SQL Chat を使う場合は、http://mcp.zha-ji.cn/sql に直接アクセスします。
• MCP エンドポイント（Cherry Studio などで使用）：http://mcp.zha-ji.cn/mcp

3. ローカルで実行する場合

1. Node.js 18+ をインストールします。（任意）MySQL と Redis もインストールできます。
2. ターミナルで次を実行します。

npm install
npm --prefix web install
cp .env.example .env  # 按需修改数据库/AI 配置
npm run dev           # 启动后端，默认 3000 端口
npm --prefix web run dev  # 启动前端，默认 5173 端口

3. ブラウザーで http://localhost:5173 を開けば完了です。

4. SQL Chat とグラフの一般的な使用手順

1. SQL Chat でデータベース接続を設定し、自然言語で指示を入力します（例：「日付別に直近 7 日間の注文数を集計」）。
2. AI に SQL の生成と実行を任せ、結果テーブルが正しいことを確認します。
3. 結果の上にある「可視化」ボタンをクリックします。
   • グラフの種類を選択します（迷った場合は「自動」を選択します）。
   • X 軸のフィールド（通常は時間または分類）と Y 軸のフィールド（通常は数値）を選択します。
4. 「グラフを生成」をクリックすると、グラフのリンクが作成されます。そのまま共有したり、Dashboard に追加したりできます。

5. MCP クライアント／AI CLI からの接続方法（簡易版）

5.1 共通の設定方法

Cherry Studio でも、その他の MCP／HTTP 対応 AI CLI でも、基本的な仕組みは同じです。

• MCP エンドポイント：http://mcp.zha-ji.cn/mcp または独自の http://localhost:3000/mcp。
• 必須リクエストヘッダー：
  • Content-Type: application/json
  • Accept: application/json, text/event-stream
  • AccessID／AccessKey
    • ウェブ版でアカウントを登録して取得するか、ローカルで /api/auth/register を呼び出して一組の認証情報を取得できます。
• クライアントで上記の URL とリクエストヘッダーを設定すると、会話中に次のツールが表示され、呼び出せるようになります。
  • create_visualization_chart（グラフを生成）

5.2 コマンドライン／curl を使う場合

一部の AI CLI（または独自のスクリプト）は、実際には HTTP リクエストを送信するものです。その場合は、まず curl でテストできます。

# 假设已经有 ACCESS_ID 和 ACCESS_KEY 两个环境变量

curl -N \
  -X POST "http://localhost:3000/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "AccessID: $ACCESS_ID" \
  -H "AccessKey: $ACCESS_KEY" \
  --data '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "create_visualization_chart",
      "arguments": {
        "data": [["学生1", 85], ["学生2", 92]],
        "schema": [
          { "name": "学生", "type": "string" },
          { "name": "分数", "type": "number" }
        ],
        "chartType": "auto",
        "title": "学生成绩分布"
      }
    }
  }'

上記のリクエスト本文は、MCP の tools/call 構造の例です。実際に使用する際は、AI CLI に MCP プロトコルに従って外側のフィールドを自動生成させることをおすすめします。arguments の内容（つまり data、schema、chartType など）だけを用意すれば十分です。

5.3 Windows PowerShell のヒント

PowerShell では、まず機密情報を環境変数に設定してから使用することをおすすめします。

$env:ACCESS_ID = "你的AccessID"
$env:ACCESS_KEY = "你的AccessKey"

curl -N `
  -X POST "http://localhost:3000/mcp" `
  -H "Content-Type: application/json" `
  -H "Accept: application/json, text/event-stream" `
  -H "AccessID: $env:ACCESS_ID" `
  -H "AccessKey: $env:ACCESS_KEY" `
  --data '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "create_visualization_chart",
      "arguments": {
        "data": [["学生1", 85], ["学生2", 92]],
        "schema": [
          { "name": "学生", "type": "string" },
          { "name": "分数", "type": "number" }
        ],
        "chartType": "auto",
        "title": "学生成绩分布"
      }
    }
  }'

このように設定すれば、使用する AI CLI が次の機能に対応している限り、

• MCP ソースの URL を指定する機能
• リクエストヘッダーをカスタマイズする機能
• （任意）tools/call に arguments を渡す機能 本プロジェクトを「リモートグラフ／SQL ツールソース」として接続できます。