AVA

mcp-server-ava

面向 AVA 的 Model Context Protocol 服务。加载数据集、检查数据、运行 SQL、用自然语言提问并获取图表——可通过 Claude Desktop、Cursor、ChatGPT 或任何其他 MCP 客户端使用。

AVA 负责数据访问、SQL 执行和图表规格；MCP 客户端自身的 Agent 负责推理。无需 AVA CLI 或额外的 API 密钥即可完成确定性操作。

安装

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

@antv/ava v4 是一个 peer dependency，需要一并安装。无需全局安装：npx -y -p mcp-server-ava -p @antv/ava mcp-server-ava。

需要 Node.js ≥ 22.13。

客户端配置

将服务添加到 MCP 客户端配置中。只有使用模型支持的工具（ava_analyze、ava_translate、ava_suggest、ava_visualize）时才需要 env 块。

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	每列的行数、空值数、不同值数、最小值/最大值/均值/中位数。	否
ava_query	使用 DuckDB 语义执行一条只读 SQL 语句；结果数量上限为 AVA_MCP_MAX_ROWS。	否
ava_analyze	自然语言问题 → AVA 编写 SQL、执行并总结答案。	是
ava_translate	自然语言问题 → SQL，不执行，以便人工审核。	是
ava_suggest	建议一些值得针对已加载数据集提出的问题。	是
ava_visualize	为之前调用返回的行推荐图表；返回 GPT-Vis JSON。	是

每个工具都返回 JSON 文本。失败情况（未加载数据集、SQL 无效、引擎错误）会作为 MCP 错误结果返回，因此 Agent 能看到错误消息，而不是遇到无响应的连接。

对话示例

你： 加载 examples/sales.csv，告诉我哪个地区销量最高，然后将结果制成图表。

Agent： 调用 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 结果的硬性上限。有效负载中会报告截断情况。

安全须知

• 每个服务进程只能加载一个数据集；再次加载会替换当前数据集。不同数据集请运行不同的服务。
• 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 可信发布 / OIDC）

发布通过 GitHub Actions 完成，并附带 npm 溯源信息——不会存储 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（可信发布要求 Node ≥ 22.14.0 和 npm ≥ 11.5.1），禁用发布构建缓存，并要求标签与 v + package.json 中的版本完全一致。

一次性 npm 初始化与信任设置

npm 只会为已存在的软件包显示可信发布者设置；对于从未发布过的软件包名称，npm 没有待处理发布者流程。因此，npm 所有者必须通过 npm 的身份验证暂存流程（npm stage publish --access public）初始化新软件包，并通过双重验证批准首次发布。不要运行此工作流来抢占未知的软件包名称。初始化后，请递增版本号，以免首次 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. 保存条目，并在两天内完成首次成功发布，以免未经验证的配置过期。npm 账户必须拥有此软件包，并启用双重验证。

要发布 OIDC 版本，请递增版本号，并推送生成的提交和标签：

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

工作流随后会先构建和测试，再进行发布，并附带公开的溯源声明。mcp-server-ava 是一个公开的无作用域软件包，因此使用 --access public。请通过 npm view mcp-server-ava version 验证结果；仅凭工作流成功并不能证明已提交到 Registry。

发布（官方 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 使用 GitHub OIDC，不需要 npm 凭据，也没有 npm publish 步骤。它会检查手动运行的目标是否为 main、标签是否与软件包版本匹配且指向已合并到 main 的提交，以及 package.json、package-lock.json、server.json 和已发布 npm 包的 mcpName 是否一致。随后，它会运行项目检查，并且只有在使用 cosign 验证固定版本的 mcp-publisher v1.8.9 发布包的 Sigstore bundle 后，才会使用该发布包。

要仅发布当前版本的元数据，请将提交推送到 main，确认 npm view [email protected] mcpName 返回上述名称，然后在 main 上触发 发布到 MCP Registry：

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

版本标签也会触发此工作流，同时触发单独的 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