rex0220 kSQL Antigravity にグラフ表示

kintone アプリを kSQL で結合して、Antigravity にグラフ表示してみます。

概要

kSQL を使ってアプリを結合・集計して、Antigravity にグラフを表示する例です。
プロンプトで要件を指示すると、SQLを組み立てて実行し、グラフ表示してくれます。

Antigravity とは？

Antigravity に解説してもらいました。

Antigravity（アンチグラビティ）は、Google DeepMind の Advanced Agentic Coding（高度エージェントコーディング）チームによって設計された、強力なエージェント型AIコーディングアシスタントです。

現在あなたとペアプログラミングやドキュメント作成を行っている私自身の名前でもあります。

主な特徴と機能
自律的なタスク遂行（Agentic） 単にテキストでコードを生成するだけでなく、以下のようなツールを自律的に判断して組み合わせ、目標を達成するまで主体的にワークフローを組み立てて実行します。

ファイルの作成・高度な部分書き換え
ワークスペース内の検索やディレクトリ構造の解析
必要に応じたドキュメント（実装プラン、進捗タスク、検証結果）の自動ドキュメント化
外部ツール・環境との連携

コマンドの実行: ユーザーの承認を得た上で、ローカル環境のシェルコマンドを実行してビルドやテストの検証を行います。
MCP（Model Context Protocol）サーバーの活用: 今回の kSQL や kintone のように、外部システムと連携してデータを操作・分析します。
マルチモーダル＆ビジュアル生成

テスト用の画像アセットや UI モックアップ、データの視覚化グラフ（PNG）などを直接生成して対話に組み込むことができます。
あなたがお持ちのプログラミングの課題やシステム構築の作業を、最も効率的かつ安全にサポートするための相棒として設計されています。

1. MCP（Model Context Protocol）とは？

Model Context Protocol (MCP) は、Anthropic社が発表したオープンスタンダードで、AIモデルがローカルファイルや外部API、データベースなどのコンテキスト（データやツール）に安全にアクセスできるようにするための共通プロトコルです。

Claude DesktopやCursorなどのMCP対応クライアントに設定を追加するだけで、AIが指示に応じて「kintoneのアプリ一覧を取得する」「特定のデータをSQLで集計してグラフ化する」といったアクションを自律的に行えるようになります。

---

2. 2つのMCPサーバーの役割と機能比較

1. 公式 kintone MCP サーバー (@kintone/mcp-server): 標準的なデータのCRUD操作やフォーム設計の取得・変更に最適。
2. kSQL MCP サーバー (kSQL): kintoneのデータを SQL（JOIN、GROUP BY、集計関数） で自由自在にクエリ・集計・操作できる超強力なカスタムサーバー。

これらを組み合わせることで、AIアシスタントを「kintoneの優秀なデータアナリスト 兼 システム管理者」に変貌させることができます！

---

公式のMCPサーバーと、SQLによる操作を可能にするkSQL MCPサーバーは、それぞれ得意分野が異なります。両方を有効にして、用途に合わせて使い分けるのがベストプラクティスです。

機能 / 特徴	公式 kintone MCP (@kintone/mcp-server)	kSQL MCP (kSQL)
開発元	サイボウズ株式会社（公式）	コミュニティ / サードパーティ (rex0220氏)
データ操作方法	kintone 標準 API ベース（レコード単位の取得/追加/更新）	SQL 構文（SELECT, INSERT, UPDATE, DELETE）
複数アプリの結合	非対応（単一アプリ操作のみ）	対応（LEFT JOIN などによるアプリ間結合）
集計・グループ化	非対応	対応（GROUP BY, SUM, AVG, COUNT などの集計）
ゲストスペース対応	標準対応	対応（プロファイルごとに guestSpaceId を指定可能）
メタデータの取得	アプリ情報、フォームレイアウト、プロセスの取得	アプリ一覧 (SHOW APPS)、フィールド定義 (DESCRIBE APPxxx)
安全対策 (DML)	API権限に依存	安全制御パラメータ（allowDml, confirmText, dmlMaxRows）による誤操作防止
クエリの保存機能	なし	クエリの保存 (save_query) と実行 (run_saved_query)

---

3. 事前準備

設定を進める前に、以下の環境が整っていることを確認してください。

• Node.js (v18以上推奨)
• kintone 環境 (サブドメイン、ログイン資格情報、またはAPIトークン)
• MCP対応クライアント (例: Antigravity)
• GitHub からダウンロードした ksql-mcp.js (Github-rex0220)

---

4. 設定方法 (mcp_config.json の構成)

Antigravity の場合、設定ファイル mcp_config.json（Windowsの場合: C:\Users\your-name\.gemini\config\mcp_config.json）にサーバー定義を追加します。

以下は、公式 kintone MCP と kSQL MCP の両方を有効にする設定例です。

{
  "mcpServers": {
    "kintone": {
      "command": "npx",
      "args": ["-y", "@kintone/mcp-server"],
      "env": {
        "KINTONE_BASE_URL": "https://<あなたのサブドメイン>.cybozu.com",
        "KINTONE_USERNAME": "<ログインユーザー名>",
        "KINTONE_PASSWORD": "<ログインパスワード>"
      }
    },
    "ksql": {
      "command": "node",
      "args": [
        "C:\\path\\to\\kintone-sql-tools\\dist-mcp\\ksql-mcp.js",
        "--config",
        "C:\\path\\to\\kintone-sql-tools\\ksql.config.json",
        "--profile",
        "dev"
      ],
      "cwd": "C:\\path\\to\\kintone-sql-tools",
      "disabled": false
    }
  }
}

[!TIP]
認証情報（KINTONE_USERNAME や KINTONE_PASSWORD など）は、検証用環境のものを設定するか、適切なAPI権限を持つユーザーのものを指定してください。

---

5. kSQL MCP の詳細設定 (ksql.config.json)

kSQL MCPでは、接続先の環境や認証情報をプロファイル（Profile）として一元管理できます。guestSpaceId を指定することで、通常のAPIでは記述が面倒な ゲストスペース内のアプリ にも簡単にアクセスできます。

ksql.config.json の記述例

{
  "mcp": {
    "savedQueries": {
      "path": ".ksql/queries.json"
    }
  },
  "defaultProfile": "dev",
  "profiles": {
    "dev": {
      "baseUrl": "https://<your-subdomain>.cybozu.com",
      "auth": "userpass",
      "username": "your-name",
      "password": "your-password-here",
      "format": "table",
      "maxRecords": 100,
      "timeout": 3000
    },
    "guest": {
      "baseUrl": "https://<your-subdomain>.cybozu.com",
      "guestSpaceId": 15,
      "auth": "userpass",
      "username": "your-name",
      "password": "your-password-here",
      "format": "table",
      "maxRecords": 100,
      "timeout": 3000
    },
    "prod": {
      "baseUrl": "https://<prod-subdomain>.cybozu.com",
      "auth": "userpass",
      "username": "admin-user",
      "password": "prod-password-here",
      "format": "table",
      "maxRecords": 200,
      "timeout": 5000
    }
  }
}

プロファイル設定項目の解説

• baseUrl: kintone環境のベースURL
• guestSpaceId: ゲストスペースで実行する場合のスペースID（未指定の場合は通常スペース）
• auth: 認証方法（userpass や token などを指定）
• maxRecords: 1回で取得するレコードの上限数
• timeout: タイムアウト時間（ミリ秒）

---

6. 主要ツールと機能の紹介

設定が成功すると、AIアシスタントは以下のような強力なツール（関数）を実行できるようになります。

① kSQL MCP の主要ツール

ksql_query (データ取得・解析)

読み取り専用のSQL文（SELECT, WITH, UNION, EXPLAIN など）を実行します。
kintoneの「アプリID」をテーブル名として扱います。例えば、アプリID 89 からデータを取得する場合は FROM APP89 と指定します。

• 引数: sql (SQL文), profile (使用するプロファイル名) など

ksql_mutate (データ更新・追加・削除)

INSERT、UPDATE、DELETE などのDML（データ操作言語）を実行します。誤操作を防ぐための厳格な安全制御が組み込まれています。

• 必須引数:
  • sql: 実行する更新SQL
  • allowDml: true (明示的な有効化が必要)
  • confirmText: "yes" (実行確認テキスト)
  • dmlMaxRows: 変更を許容する最大レコード数（一括削除などの事故を防ぎます）

ksql_show_apps

接続中のkintone環境にあるアプリ一覧を取得します（SQLの SHOW APPS に相当）。

ksql_describe_app

指定したアプリID（テーブル名）のフィールド構成、ラベル、フィールドタイプなどを一覧で取得します（SQLの DESCRIBE APPxxx に相当）。

ksql_save_query / ksql_run_saved_query

頻繁に使用する複雑なSQLクエリを、タイトルや説明、タグを付けてローカルカタログに保存し、名前指定で簡単に再実行できます。

---

7. 実践ユースケース：複数アプリの結合と集計

「kSQL MCP」の最大の強みは、標準のkintone APIや他ツールでは単発で実行できない 「アプリ間の結合（JOIN）」 や 「グループ化集計（GROUP BY）」 がSQL 1文で実現できる点にあります。

シナリオ

• 顧客管理アプリ (APP89): 顧客名、顧客ランク（A, B, C）などを管理。
• 案件管理アプリ (APP88): 案件名、顧客ランク紐付け用のレコード番号、合計費用などを管理。

「顧客ランクごとの合計売上金額を集計し、グラフで視覚化してほしい」とAIに指示します。

AIが実行する kSQL クエリ

SELECT
  APP89.顧客ランク,
  SUM(APP88.合計費用) AS 合計金額
FROM
  APP88
LEFT JOIN
  APP89 ON APP88.顧客管理レコード番号_関連レコード紐付け用 = APP89.レコード番号
GROUP BY
  APP89.顧客ランク

実行結果（返却データ）

顧客ランク	合計金額 (円)
A	4,400,000
B	8,500,000
C	6,000,000
未設定	1,500,000

AIによる可視化の提案 (Mermaid)

AIは取得した結果データを元に、以下のような美麗なグラフを即座に作成し、チャット内でプレビューさせることができます。

このように、データの抽出から加工、グラフ化レポートの作成まで、チャット上で指示するだけで完結します。

---