AVA

mcp-server-ava

Model Context Protocol サーバー。対象は AVA です。データセットを読み込み、調査し、SQL を実行し、自然言語で質問してチャートを取得できます。Claude Desktop、Cursor、ChatGPT、その他の MCP クライアントから利用できます。

データアクセス、SQL の実行、チャート仕様は AVA が担当し、推論は MCP クライアント自身のエージェントが行います。決定的な処理には AVA CLI も追加の API キーも不要です。

インストール

npm install -g mcp-server-ava @antv/ava

@antv/ava v4 はピア依存関係のため、併せてインストールしてください。グローバルにインストールせずに実行する場合：npx -y -p mcp-server-ava -p @antv/ava mcp-server-ava。

Node.js ≥ 22.13 が必要です。

クライアントの設定

MCP クライアントの設定にサーバーを追加します。env ブロックが必要なのは、モデルを使用するツール（ava_analyze、ava_translate、ava_suggest、ava_visualize）のみです。

Claude Desktop（claude_desktop_config.json）／Cursor（~/.cursor/mcp.json）／ほとんどのクライアント：

{
  "mcpServers": {
    "ava": {
      "command": "npx",
      "args": ["-y", "mcp-server-ava"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_MODEL": "gpt-4o-mini",
        "OPENAI_BASE_URL": "https://api.openai.com/v1",
        "AVA_MCP_MAX_ROWS": "200"
      }
    }
  }
}

OpenAI 互換のエンドポイントであれば利用できます。Azure、OpenRouter、ローカルの vLLM、または内部ゲートウェイを使用する場合は、OPENAI_BASE_URL を設定してください。

ツール

ツール	機能	モデルが必要
ava_load_data	インラインの CSV／JSON／テキスト、またはファイルパス（.csv、.json、.parquet、.xlsx）からデータを読み込みます。現在のデータセットを置き換え、スキーマを返します。	text のみ
ava_schema	テーブル名、カラム、型を返します。	いいえ
ava_profile	カラムごとの行数、NULL 値、個別値、最小値／最大値／平均値／中央値を返します。	いいえ
ava_query	DuckDB のセマンティクスに従って読み取り専用の SQL 文を 1 つ実行します。結果は AVA_MCP_MAX_ROWS 件までです。	いいえ
ava_analyze	自然言語の質問 → AVA が SQL を作成して実行し、回答を要約します。	はい
ava_translate	自然言語の質問 → SQL に変換します。実行はせず、人が確認できるようにします。	はい
ava_suggest	読み込み済みデータセットについて、質問する価値のある内容を提案します。	はい
ava_visualize	以前の呼び出しで取得した行に適したチャートを提案し、GPT-Vis JSON を返します。	はい

各ツールは JSON テキストを返します。失敗（データセット未読み込み、無効な SQL、エンジンエラーなど）は MCP エラー結果として返されるため、エージェントは接続が途切れるのではなく、メッセージを確認できます。

会話例

あなた： examples/sales.csv を読み込んで、最も売上が多い地域を教えてから、チャートにしてください。

エージェント： ava_load_data → ava_query（SELECT region, SUM(sales)…）→ ava_visualize を呼び出し、*「West が 13 個で最も売れています」*と回答して、チャート JSON を返します。

返されたチャートのレンダリング

ava_visualize が返すのは仕様であり、HTML ではありません。仕様を保存し、AVA CLI でレンダリングします。

npm install -g @antv/ava            # provides the `ava` binary
npx ava viz --spec @chart.json -o chart.html

設定

環境変数	デフォルト	備考
OPENAI_API_KEY	—	モデルを使用するツールを有効にします。設定されていない場合、明確なエラーを返します。
OPENAI_MODEL	gpt-4o-mini	エンドポイントで公開されている任意のチャットモデルを指定できます。
OPENAI_BASE_URL	OpenAI	OpenAI 互換のゲートウェイを指定します。
AVA_MCP_MAX_ROWS	200	query／analyze の結果に対する上限です。切り捨てが発生した場合は、ペイロードに報告されます。

安全に関する注意事項

• サーバープロセスごとに扱えるデータセットは 1 つです。再度読み込むと置き換えられます。データセットごとに別のサーバーを実行してください。
• SQL は読み取り専用です。書き込み、DDL、複数文のスクリプトはエンジンによって拒否されます。
• 結果は行数の上限で切り捨てられ、truncated: true が付加されます。
• 診断情報は stderr に出力されます。stdout は MCP プロトコル専用です。

開発

npm install
npm run build
npm test                              # vitest: in-memory MCP client over the real server
node scripts/smoke.mjs                # end-to-end over stdio against the built binary
OPENAI_API_KEY=... node scripts/smoke.mjs   # also exercises analyze + visualize

公開（npm Trusted Publishing / OIDC）

リリースは npm provenance を使用して GitHub Actions 経由で公開されます。NPM_TOKEN シークレットは保存されません。ワークフロー（.github/workflows/publish.yml）は、バージョンタグ（v*.*.*）または手動の workflow_dispatch 実行時にのみ起動し、contents: read と id-token: write を自身に付与したうえで、npm ci → 型チェック → ビルド → テスト → npm pack --dry-run → npm publish --provenance --access public を実行します。Node 24 と npm 11.21.2 を使用します（Trusted Publishing には Node ≥ 22.14.0 と npm ≥ 11.5.1 が必要です）。リリースビルドのキャッシュは無効にし、タグが v + package.json のバージョンと完全に一致することを必須とします。

npm の初回設定と信頼関係の構築

npm では、すでに存在するパッケージに対してのみ Trusted Publisher の設定を公開しています。まだ公開されたことのない名前には、公開待ちのパブリッシャー設定フローはありません。そのため、新しいパッケージは npm の認証済みステージングフロー（npm stage publish --access public）を通じて npm のオーナーが初回公開し、2FA でその最初のリリースを承認する必要があります。不明なパッケージ名を確保するために、このワークフローを手動で実行しないでください。初回公開後、バージョンを上げて、最初の OIDC リリースが初回公開時のバージョンを再公開しようとしないようにします。

パッケージが作成されたら、npmjs.com で信頼するパブリッシャーを設定します。

1. Packages → mcp-server-ava → Settings → Trusted publishing を開き、GitHub Actions を選択します。
2. 信頼するパブリッシャーのエントリーを追加します。
   • Organization or user: DoubleCore
   • Repository: mcp-server-ava
   • Workflow filename: publish.yml（ファイル名のみ。.github/workflows/publish.yml ではありません）
   • Environment: 空欄のままにします。ワークフローでは GitHub の環境を定義していません。
   • Allowed actions: npm publish を明示的に許可します。デフォルトの npm stage publish 権限だけでは、このワークフローの直接の公開コマンドを許可できません。
3. エントリーを保存し、未検証の設定が期限切れになる前の 2 日以内に、最初の公開を成功させます。npm アカウントはパッケージのオーナーであり、2FA が有効になっている必要があります。

OIDC リリースを作成するには、バージョンを上げて、変更したコミットとタグをプッシュします。

npm version patch   # or minor / major
git push --follow-tags

ワークフローは公開 provenance ステートメントを付けて公開する前に、ビルドとテストを実行します。mcp-server-ava は公開されているスコープなしのパッケージなので、--access public を指定しています。npm view mcp-server-ava version で結果を確認してください。ワークフローが成功しただけでは、レジストリへの登録が完了した証明にはなりません。

公開（公式 MCP Registry／GitHub OIDC）

server.json では、このサーバーの名前を io.github.DoubleCore/mcp-server-ava とし、現在、バージョン 0.1.3 を [email protected] の npm アーティファクトに対応付けています。GitHub OIDC の名前空間と npm の mcpName の比較では大文字と小文字が区別されるため、この正確な大文字・小文字の表記が必要です。同じ mcpName でそのアーティファクトが公開された後は、このバージョンの Registry メタデータを更新するために、npm のバージョンを再度上げたり、npm に再公開したりする必要はありません。

独立した .github/workflows/publish-mcp.yml は、npm 認証情報や npm publish のステップを使わず、GitHub OIDC を使用します。手動実行の対象が main であること、タグがパッケージのバージョンと一致し、main にマージされたコミットを指していること、さらに package.json、package-lock.json、server.json、公開済み npm の mcpName が一致することを確認します。その後、プロジェクトのチェックを実行し、cosign で Sigstore バンドルを検証してから、固定された mcp-publisher v1.8.9 のリリースを使用します。

現在のバージョンのメタデータのみをリリースするには、コミットを main にプッシュし、npm view [email protected] mcpName が上記の名前を返すことを確認してから、main で Publish to MCP Registry を実行します。

gh workflow run publish-mcp.yml --ref main

バージョンタグを付けると、別の npm リリースワークフローとともに、このワークフローも起動します。このワークフローは npm の完了を待ったり、npm に再公開したりすることはありません。タグの実行が新しい npm アーティファクトの公開確認より先に始まった場合は、安全に失敗させ、npm OIDC リリースの成功後に MCP ワークフローのみを再実行してください。今後のパッケージバージョンでは、package.json、両方のロックファイルのルートバージョン、server.json をまとめて更新してください。すでに公開済みの npm バージョンを再利用しないでください。

ワークフローの成功を、登録された証拠として扱うことはできません。実際の Registry API の応答を確認してください。

curl 'https://registry.modelcontextprotocol.io/v0.1/servers?search=mcp-server-ava'

ライセンス

MIT