Convai Analytics

Name: Convai Analytics
Author: Conv-AI

本地服务

github.com数据与分析024 周前更新

代码仓库访问官网

关于 Convai Analytics

Convai Analytics 是面向 Convai Analytics 用户的本地 stdio MCP 服务，让 Agent 无需编写 SDK 脚本即可分析会话、延迟、可靠性、用量及提供方表现。工具返回结构化 JSON 和 Vega-Lite 图表规格。

主要功能

01汇总会话和分析指标
02查看会话时间线与交互追踪
03分析延迟并生成图表
04检查错误趋势和可靠性
05分析用量、并发及角色统计
06比较 TTS 提供方和 LLM 延迟

适用场景

01排查单次会话缓慢的原因
02跟踪延迟和错误趋势
03分析角色用量与活跃会话并发
04比较语音提供方或 LLM 模型表现

MCP 相关

本地 stdio MCP 服务使用 CONVAI_API_KEY 调用 Convai Analytics API，并向 MCP 客户端提供工具、提示词和资源。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "conv-ai-convai-analytics": {
      "command": "npx",
      "args": [
        "-y",
        "@convai/analytics-mcp"
      ],
      "env": {
        "CONVAI_API_KEY": "<CONVAI_API_KEY>",
        "CONVAI_ANALYTICS_BASE_URL": "<CONVAI_ANALYTICS_BASE_URL>"
      }
    }
  }
}

启动命令npx -y @convai/analytics-mcp

需要配置的环境变量

CONVAI_API_KEY密钥Convai API key for the account to query.

CONVAI_ANALYTICS_BASE_URLOptional analytics API base URL override.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@convai/analytics-mcp0.2.5stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
range	enum	否	相对时间范围。last_15m \| last_1h \| last_6h \| last_24h \| last_7d \| last_30d
appKey	string	否	可选的 Convai 应用密钥筛选条件。
characterId	string	否	可选的角色筛选条件。
experienceId	string	否	可选的体验筛选条件。

详细介绍

@convai/analytics-mcp

用于 Convai Analytics 的本地 stdio MCP 服务。

此软件包是 Convai Analytics 的推荐 Agent 接口。它让支持 MCP 的 Agent 无需编写自定义 SDK 脚本，即可回答有关 Convai 会话、延迟、可靠性、用量以及服务提供商／模型性能的问题。它封装了公开的 @convai/analytics TypeScript SDK，使用 CONVAI_API_KEY，并返回结构化 JSON 和 Vega-Lite 图表规范。

软件包：@convai/analytics-mcp

官方 MCP Registry 名称：io.github.Conv-AI/convai-analytics-mcp

安装和运行

export CONVAI_API_KEY="ck_live_your_key_here"
npx -y @convai/analytics-mcp@latest

可选：

export CONVAI_ANALYTICS_BASE_URL="https://analytics-api.convai.com/v1/analytics"

生产环境中请不要设置 CONVAI_ANALYTICS_BASE_URL。请勿将 API 密钥写入源代码、已提交的 MCP 配置、屏幕截图或日志中。

添加或更改 MCP 配置后，请重启 Claude Desktop、Claude Code、Cursor、Codex 或 MCP 宿主，以便重新加载服务命令和 CONVAI_API_KEY。

Claude Desktop

{
  "mcpServers": {
    "convai-analytics": {
      "command": "npx",
      "args": ["-y", "@convai/analytics-mcp@latest"],
      "env": {
        "CONVAI_API_KEY": "ck_live_your_key_here"
      }
    }
  }
}

保存此配置后，请退出并重新打开 Claude Desktop，以启动新的 MCP 服务。

Cursor / Codex 兼容的 MCP 客户端

使用相同的 stdio 命令：

{
  "command": "npx",
  "args": ["-y", "@convai/analytics-mcp@latest"],
  "env": {
    "CONVAI_API_KEY": "ck_live_your_key_here"
  }
}

对于 Claude Code、Cursor、Codex 兼容客户端和其他 stdio MCP 宿主，添加或更改 MCP 配置后，请重启客户端或启动新会话。

安全模型

此服务面向客户，设计上可公开安全使用：

它仅通过 @convai/analytics 调用公开的 Convai Analytics API。
它不接受账户覆盖参数、服务凭据、数据库 URL 或其他内部访问路径。
账户范围限制、计划权限控制和配额执行均由托管分析 API 在服务端负责。
工具结果经过清理，不会在错误信息中回显 CONVAI_API_KEY。

工具

核心和账户工具：

get_summary
get_metrics_catalog
list_sessions
get_session_timeline
get_interaction_trace

延迟工具：

get_p95_latency_over_time
get_latency_percentile_series
get_latency_percentile_chart
get_latency_threshold_chart
get_latency_heatmap_chart
get_component_latency_breakdown
generate_component_latency_chart
find_component_latency_bottlenecks
generate_interaction_waterfall
explain_slow_session

可靠性工具：

get_error_trend
generate_error_trend_chart
get_error_breakdown
generate_error_breakdown_chart
get_dropped_error_persist_trend
generate_dropped_error_persist_chart
generate_reliability_summary_chart
generate_reliability_trends_chart

这些可靠性工具使用当前可用的错误和持久化丢弃指标。如果 Agent 请求状态分布，只有在返回的行中包含实际的非空状态分组时，才使用 group_by=status；否则请说明该时间范围内没有可用的带状态标签的聚合遥测数据。

用量和并发工具：

get_usage_trends
generate_usage_trends_chart
get_character_usage_leaderboard
generate_character_usage_chart
generate_session_duration_scatter
estimate_active_session_concurrency
generate_active_session_concurrency_chart
generate_peak_concurrency_chart

服务提供商和模型工具：

get_tts_provider_attribution
generate_tts_provider_chart
get_llm_model_latency
generate_llm_model_latency_chart
compare_providers

受计划限制的高级工具：

detect_regressions
advanced_query

对于返回 402/403 响应的受计划限制工具，工具会返回带类型的 MCP 工具错误，并在消息中说明所需的计划。

提示词

该服务提供常见客户问题的提示词模板：

why_was_this_session_slow
aggregate_latency_distribution
p95_latency_trend
component_bottlenecks
trace_explanation
error_rate_trends
provider_comparison
usage_summary

资源

convai://analytics/docs/concepts
convai://analytics/docs/metrics-reference
convai://analytics/docs/authentication
convai://analytics/catalog

当 CONVAI_API_KEY 可用时，目录资源会获取调用方的账户目录。

示例问题

How many interactions and unique end users did I have in the last 30 days?
Break it down by character and generate a usage trend chart.

Show aggregate P50/P95/P99 voice.user_to_bot_latency for production readiness sign-off.
Add a 3000 ms p95 threshold line and summarize the worst buckets.

Explain why session s_123 was slow and generate an interaction waterfall if there is a traceable interaction.

Show reliability trends, errors by component, and dropped error-persistence events.

Estimate active session concurrency and show the peak concurrency chart.

本地开发

在仓库根目录中：

make mcp-install
make mcp-lint
make mcp-test
make mcp-build
make mcp-smoke

使用你自己的密钥对生产环境进行实时冒烟测试：

export CONVAI_API_KEY="ck_live_your_key_here"
export CONVAI_ANALYTICS_BASE_URL="https://analytics-api.convai.com/v1/analytics"
export CONVAI_ANALYTICS_E2E_RANGE="last_30d"
cd packages/mcp
npm run e2e:prod

对于近期没有流量的账户，实时冒烟测试接受空数据，并将受套餐限制的 402/403 响应视为有效的受限结果。

发现

规范的 MCP 注册表清单是 server.json。该服务已发布到 npm 和 Official MCP Registry。其他目录和市场（例如 GitHub MCP Registry、Smithery、Glama、PulseMCP、mcp.so 和 Docker MCP Catalog）可以引用相同的软件包和注册表元数据。

支持 Markdown

登录后评论