Countly MCP服务器

一种模型上下文协议（MCP）服务器 Countly分析平台该服务器使AI助手和MCP客户端能够与Countly的分析数据交互，管理应用程序，查看仪表板，跟踪事件，并执行全面的分析操作。

关于Countly

Countly是一个开源的企业级产品分析平台。它有助于跟踪用户行为，监控应用程序性能，并深入了解用户参与度。此MCP服务器通过标准协议接口提供对Countly所有主要功能的编程访问。

什么是MCP？

模型上下文协议（MCP）是一种开放协议，可实现人工智能应用程序和外部数据源之间的无缝集成。该服务器实现了MCP，允许像Claude这样的人工智能助手通过对话自然地与您的Countly分析数据进行交互。

需求

服务器要求

Node.js 18+ （适用于本地安装）或 码头工人 （推荐）
计数服务器：访问Countly实例（云或自托管）
身份验证令牌：具有适当权限的有效Countly身份验证令牌

客户需求

MCP协议版本: 2025-03-26 （流式HTTP规范）
兼容客户端:

- VS代码MCP扩展（最新版本） - Claude Desktop（支持2025-03-26规范的最新版本） - 任何实现流式HTTP传输协议的MCP客户端

⚠️ 备注：对于SSE类型，此服务器使用 StreamableHTTPServerTransport 其实现了现代MCP规范（2025-03-26）。仅支持传统SSE协议（2024-11-05）的旧MCP客户端不兼容。请确保您的MCP客户端是最新的。

特性

133工具 跨越30个类别，实现全面的Countly运营
资源对于AI上下文-访问只读Countly数据（应用程序配置、事件模式、分析概述）
提示用于常见任务-用于碰撞分析、交战报告等的预构建模板
多种运输方式：支持stdio（推荐）和HTTP/SSE连接
灵活的身份验证：环境变量、HTTP标头、URL参数或令牌文件
插件感知：根据可用的Countly插件自动检测并启用工具
Docker支持：支持多架构的预构建Docker镜像（amd64、arm64）
匿名分析：可选的使用情况跟踪（默认情况下禁用），以帮助改进服务器

MCP能力

此服务器实现了完整的MCP规范，支持：

工具（133个可用）

执行Countly操作，如分析查询、应用程序管理、崩溃分析等。

资源

人工智能环境下Countly数据的只读访问：

countly://app/{app_id}/config -应用程序配置和元数据
countly://app/{app_id}/events -事件定义和模式
countly://app/{app_id}/overview -当前分析概述及关键指标

资源为AI助手提供上下文，而不需要工具调用，使对话更加高效。

提示

以斜线命令形式公开的预构建分析模板：

analyze_crash_trends -分析崩溃和错误模式
generate_engagement_report -全面的用户参与度分析
compare_app_versions -比较不同版本之间的性能
user_retention_analysis -分析保留模式和队列
funnel_optimization -转化漏斗分析及建议
event_health_check -事件跟踪实施质量检查
identify_churn_risk -查找参与度下降的用户
performance_dashboard -综合性能概述

提示自动引导AI助手完成复杂的多步骤工作流程。

🔐 多种身份验证方法（HTTP标头、环境变量、基于文件）
📊 全国API全面访问
⚙️ 细粒度工具配置，按类别进行CRUD操作控制
🐳 Docker支持生产就绪配置
🔄 支持stdio和HTTP传输
🏥 内置健康检查
🔒 使用加密安全的会话ID进行安全令牌处理
🌐 多客户端支持，每个客户端传递凭据
🚨 增强的错误处理 带有详细的API错误消息

快速开始

先决条件

在开始之前，请确保您已经：

访问Countly实例（云或自托管）
具有适当权限的有效Countly身份验证令牌
Node.js 18+（用于本地安装）或Docker（推荐）
MCP客户端支持协议版本2025-03-26（流式HTTP）

使用npx（无需安装）

直接使用以下命令运行已发布的包 npx --无需克隆或构建：

# stdio mode (for MCP clients like Claude Desktop, VS Code)
COUNTLY_SERVER_URL=https://your-countly-instance.com \
COUNTLY_AUTH_TOKEN=your-countly-auth-token \
npx -y countly-mcp-server

# HTTP mode
COUNTLY_SERVER_URL=https://your-countly-instance.com \
COUNTLY_AUTH_TOKEN=your-countly-auth-token \
npx -y countly-mcp-server --http

MCP客户端配置示例（stdio）：

{
  "mcpServers": {
    "countly": {
      "command": "npx",
      "args": ["-y", "countly-mcp-server"],
      "env": {
        "COUNTLY_SERVER_URL": "https://your-countly-instance.com",
        "COUNTLY_AUTH_TOKEN": "your-countly-auth-token"
      }
    }
  }
}

使用Docker（推荐）

创建令牌文件：

   echo "your-countly-auth-token" > countly_token.txt

创建一个 .env 文件：

   cp .env.example .env
   # Edit .env and set your COUNTLY_SERVER_URL

使用Docker Compose运行：

   docker-compose up -d

访问服务器：

- HTTP/SSE模式： http://localhost:3000/mcp - 健康检查： http://localhost:3000/health - 默认端口：3000（可配置）

使用Docker运行

docker run -d \
  --name countly-mcp-server \
  -p 3000:3000 \
  -e COUNTLY_SERVER_URL=https://your-countly-instance.com \
  -e COUNTLY_AUTH_TOKEN_FILE=/run/secrets/countly_token \
  -v $(pwd)/countly_token.txt:/run/secrets/countly_token:ro \
  countly-mcp-server

使用Node.js

安装依赖项：

   npm install

构建项目：

   npm run build

配置环境：

   cp .env.example .env
   # Edit .env with your settings

运行服务器：

   # HTTP mode
   npm start

   # stdio mode (for MCP clients)
   npm run start:stdio

认证

服务器支持多种身份验证方法（按优先级顺序）：

HTTP 头 （建议用于HTTP/SSE传输）

- 通过 X-Countly-Server-Url 和 X-Countly-Auth-Token 标头 - 支持VS Code MCP扩展和其他HTTP客户端 - 看 VS代码MCP配置详情

URL参数 （HTTP/SSE传输的替代方案）

- 作为查询字符串传递： ?server_url=https://your-server.count.ly&auth_token=your-api-key - 适用于快速测试或不支持自定义标头的工具 - 不如headers安全，尽可能使用headers

工具参数

- 通过as countly_auth_token 单个工具调用中的参数

环境变量

- 集 COUNTLY_AUTH_TOKEN 在环境中 - 建议用于stdio传输模式

令牌文件 （推荐用于生产）

- 集 COUNTLY_AUTH_TOKEN_FILE 指向包含令牌的文件 - 与Docker秘密有用

配置

环境变量

变量	必填	默认	描述
`COUNTLY_SERVER_URL`	是的	`https://api.count.ly`	您的Countly服务器URL
`COUNTLY_AUTH_TOKEN`	无\*	-	身份验证令牌（直接）
`COUNTLY_AUTH_TOKEN_FILE`	无\*	-	包含身份验证令牌的文件路径
`COUNTLY_TIMEOUT`	没有	`30000`	请求超时（毫秒）
`ENABLE_ANALYTICS`	没有	`false`	启用匿名使用分析（设置为 `true` 选择加入）
`COUNTLY_TOOLS_{CATEGORY}`	没有	`ALL`	按类别控制可用工具（见下文）
`COUNTLY_TOOLS_ALL`	没有	`ALL`	所有类别的默认权限
`COUNTLY_CORS_ALLOWED_ORIGINS`	没有	`*`	允许的CORS源（HTTP传输）的逗号分隔列表。保持未设置或 `*` 广泛开放；在生产中使用特定的来源（例如。 `https://app.example.com,https://dash.example.com`).
`COUNTLY_RATE_LIMIT_RPM`	没有	`120`	每分钟每IP请求数 `/mcp` 端点（HTTP传输）。设置为 `0` 禁用。
`COUNTLY_TRUST_PROXY`	没有	`false`	何时 `true`，使用 `X-Forwarded-For` 对于速率限制客户端IP。仅当服务器位于设置此标头的受信任反向代理之后时启用。
`COUNTLY_MAX_BODY_BYTES`	没有	`1048576`	接受的最大请求正文大小 `/mcp` （HTTP传输）。超过限额的请求得到 `413 Payload Too Large`。设置为 `0` 禁用。
`COUNTLY_MAX_CONCURRENT_PER_IP`	没有	`50`	每个客户端IP的最大同时TCP连接数（HTTP传输）。超限连接被丢弃。设置为 `0` 禁用。
`COUNTLY_REQUEST_LOG`	没有	`false`	何时 `true`，向stderr发出每个请求一行NDJSON(`{ts, ip, method, path, status, durationMs, rateLimitHit}`).可用于管道连接到日志聚合器以发现滥用模式。

\*必须至少配置一种身份验证方法

分析跟踪（可选）

MCP服务器包括可选的匿名使用分析，以帮助改进产品。分析是 默认情况下禁用 并且可以通过 ENABLE_ANALYTICS=true 环境变量。

跟踪内容：

使用的传输类型（stdio与HTTP）
工具执行指标（成功/失败、持续时间、工具名称）
使用的身份验证方法（标头、环境变量、文件、参数）
HTTP端点访问模式
错误发生（类型和消息，无敏感数据）
服务器启动/停止事件
A. 截断不透明哈希 您的Countly服务器URL（64位SHA-256前缀），作为附件 server 每个事件上的分段——用于不同的服务器聚合。原始URL永远不会发送。

未跟踪的内容：

身份验证令牌或凭据
原始Countly服务器URL或域（仅不透明 server 上面的哈希）
用户数据或分析内容
个人信息
IP地址或客户端标识符
工具参数或请求/响应体

隐私和设备ID: 所有分析都汇总在一个设备ID下 "mcp" --Countly无法仅通过设备ID区分单个操作员。唯一的每次部署信号是 server 事件哈希，这是标准化服务器URL的截断SHA-256。哈希是故意粗略的（64位），服务器URL是低熵的，因此不要假设哈希对于云模式是不可测的；它是为了聚合，而不是保密。

要选择加入：

export ENABLE_ANALYTICS=true

或者在你的 .env 文件：

ENABLE_ANALYTICS=true

工具配置

服务器支持对哪些MCP工具可用以及它们可以执行哪些CRUD操作进行细粒度控制。这对于安全、治理或创建只读部署非常有用。

使用环境变量按类别配置工具：

# Format: COUNTLY_TOOLS_{CATEGORY}=CRUD
# Where CRUD letters represent: Create, Read, Update, Delete operations

# Examples:
COUNTLY_TOOLS_APPS=CR          # Apps: Create and Read only
COUNTLY_TOOLS_DATABASE=R       # Database: Read-only access
COUNTLY_TOOLS_CRASHES=CRUD     # Crashes: Full access
COUNTLY_TOOLS_ALERTS=NONE      # Alerts: Completely disabled

# Set default for all categories:
COUNTLY_TOOLS_ALL=R            # Read-only mode for all tools

可用类别：

CORE -核心工具（ping、get_version、get_plugins）（3个工具）
APPS -应用程序管理（6个工具）
ANALYTICS -分析数据检索（7个工具）
CRASHES -崩溃分析和管理（10个工具）
NOTES -笔记管理（3个工具）
EVENTS -事件配置（1个工具）
ALERTS -警报管理（3个工具）
VIEWS -视图分析（3个工具）
DATABASE -直接数据库访问（6个工具）
DASHBOARD_USERS -仪表板用户管理（1个工具）
APP_USERS -应用用户管理（3个工具）

总计：11个类别的42个工具

有关完整的文档、示例和每个工具的CRUD映射，请参阅 工具_配置.md.

安全和生产强化

HTTP传输被设计为既可用作面向公众的MCP 端点（例如。 mcp.count.ly)以及作为自托管的单租户服务器。默认值有利于兼容性；运营商应该选择更严格的以下设置基于其部署模型。

多租户隔离

HTTP传输可以安全地与多个并发客户端一起使用不同的Countly身份验证令牌。每个请求都有自己的出站轴实例与 countly-token 内置标题和每个租户的应用程序缓存由SHA-256（令牌）键控，因此一个租户的应用程序不能泄露到另一租户 resolveAppId 查找。

此操作不需要操作员配置。

服务器端请求伪造

呼叫者提供的服务器URL（通过 X-Countly-Server-Url 标题或 ?server_url= 查询参数）根据SSRF数据列表进行验证-- 环回、链路本地、RFC 1918、运营商级NAT、云元数据端点(169.254.169.254), .local/.localhost，以及非HTTP（S）方案以400分被拒绝。这是一个语法检查；防御反对DNS重新绑定仍然需要对服务器进行出口防火墙。

URL中的凭据已弃用

通过以下方式传递身份验证令牌 ?auth_token= 支持向后兼容性，但会向stderr发出速率受限的安全警告。 URL中的令牌泄漏到访问日志、浏览器历史记录和Referer中标题。将呼叫者迁移到 X-Countly-Auth-Token --URL参数支持将在未来的版本中删除。

速率限制

这 /mcp 端点有一个每IP滑动窗口速率限制器，默认值每分钟120个请求。通过调谐 COUNTLY_RATE_LIMIT_RPM= （设置为 0 禁用）。在受信任的反向代理后面，设置 COUNTLY_TRUST_PROXY=true 所以第一个 X-Forwarded-For hop用作客户端IP。

资源枯竭防御

在应用程序级别速率限制之上分层的附加保护：

请求车身盖 (COUNTLY_MAX_BODY_BYTES，默认值为1 MiB）-- 413 Payload Too Large +超大车身导致插座损坏。都检查过了

预先通过 Content-Length 和流线型（用于大块/躺着客户）。

每个IP并发连接上限 (COUNTLY_MAX_CONCURRENT_PER_IP,

默认值50）--在TLS之前丢弃超限TCP连接握手，关闭缓慢的洛里斯放大器。

服务器超时 — requestTimeout=30s, headersTimeout=10s,

keepAliveTimeout=5s, timeout=60s.慢速客户端无法保留套接字无限期开放。

对于希望使用每个请求的审核日志进行滥用检测的操作员，请设置 COUNTLY_REQUEST_LOG=true。服务器将发出一行NDJSON 对stderr的请求，仅包含env var中列出的字段表——没有身份验证令牌，没有正文，没有标头。

跨域资源共享

默认值为 Access-Control-Allow-Origin: * 因此，基于浏览器的MCP 来自任何来源的客户端都可以连接。如果您的部署只需要为特定来源提供服务，将其锁定：

COUNTLY_CORS_ALLOWED_ORIGINS="https://dash.example.com,https://ops.example.com"

然后，服务器将只回显允许的源并添加 Vary: Origin. 来自不允许的出发地的飞行前请求得到403。

自托管单租户部署

如果您将其作为单租户服务器运行（例如。 docker run 在一个您自己的人工智能助理的VPS），首选以下之一：

仅绑定到本地主机 并通过SSH隧道：

docker run -p 127.0.0.1:3000:3000 ...

在反向代理后绑定 （Caddy、Nginx、Traefik）终止

TLS，在需要时添加身份验证，并设置受信任的 X-Forwarded-For （然后设置 COUNTLY_TRUST_PROXY=true).

默认的Dockerfile绑定到 0.0.0.0:3000 所以它在一个没有额外标志的容器。这意味着 docker run -p 3000:3000 ... 将MCP端点暴露给公共互联网——使用显式的本地绑定、反向代理或外部防火墙（如果不是这样）想要。

遥测

分析是 默认情况下禁用.选择加入 ENABLE_ANALYTICS=true. 从未发送任何身份验证令牌、服务器URL或工具参数到 stats.count.ly；发送到分析SDK的错误消息为针对令牌形状的子字符串进行了编辑。

Docker部署

Docker 中心

从Docker Hub中提取镜像：

docker pull countly/countly-mcp-server:latest

本地建设

docker build -t countly-mcp-server .

Docker Compose

包括 docker-compose.yml 提供生产就绪设置，包括：

用于安全令牌存储的Docker秘密
健康检查
资源限制
自动重新启动
正确的日志配置

Docker Swarm/Kubernetes

对于精心编排的部署，请使用外部机密：

Docker Swarm：

# Create secret
echo "your-token" | docker secret create countly_token -

# Deploy stack
docker stack deploy -c docker-compose.yml countly

库贝内特斯：

apiVersion: v1
kind: Secret
metadata:
  name: countly-token
type: Opaque
stringData:
  token: your-countly-auth-token
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: countly-mcp-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: countly-mcp-server
  template:
    metadata:
      labels:
        app: countly-mcp-server
    spec:
      containers:
      - name: countly-mcp-server
        image: countly-mcp-server:latest
        ports:
        - containerPort: 3000
        env:
        - name: COUNTLY_SERVER_URL
          value: "https://your-countly-instance.com"
        - name: COUNTLY_AUTH_TOKEN_FILE
          value: "/run/secrets/countly_token"
        volumeMounts:
        - name: token
          mountPath: /run/secrets
          readOnly: true
      volumes:
      - name: token
        secret:
          secretName: countly-token
          items:
          - key: token
            path: countly_token

MCP客户端配置

克劳德桌面

最常见的用例是Claude Desktop。添加到您的Claude配置文件中：

位置:

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json

使用Docker：

{
  "mcpServers": {
    "countly": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "COUNTLY_SERVER_URL=https://your-countly-instance.com",
        "-e", "COUNTLY_AUTH_TOKEN=your-token-here",
        "countly-mcp-server",
        "node", "build/index.js"
      ]
    }
  }
}

使用本地安装：

{
  "mcpServers": {
    "countly": {
      "command": "node",
      "args": ["/path/to/countly-mcp-server/build/index.js"],
      "env": {
        "COUNTLY_SERVER_URL": "https://your-countly-instance.com",
        "COUNTLY_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

使用环境变量作为令牌（可选）：

{
  "mcpServers": {
    "countly": {
      "command": "node",
      "args": ["/path/to/countly-mcp-server/build/index.js"],
      "env": {
        "COUNTLY_SERVER_URL": "https://your-countly-instance.com",
        "COUNTLY_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

其他MCP客户端

此服务器与支持以下功能的任何MCP客户端兼容：

stdio传输 （默认）-对于本地/桌面客户端（使用环境变量进行身份验证）
HTTP/SSE传输 -对于基于web或远程客户端（使用HTTP标头进行身份验证）

对于HTTP模式，客户端应连接到： http://your-server:3000/mcp

可用工具

该服务器提供30个类别的134个工具，用于全面的Countly集成：

核心工具（兼容OpenAI/ChatGPT）

ping -检查Countly服务器是否正常且可访问
get_version -检查服务器上运行的Countly版本
get_plugins -获取服务器上已安装插件的列表

应用程序管理

apps_list -列出所有应用程序
apps_get_by_name -按名称获取应用程序详细信息
apps_create -创建新应用程序
apps_update -更新应用程序设置
apps_delete -删除应用程序
apps_reset -重置应用程序数据

分析和仪表板

get_analytics_data -按预定义方法（位置、运营商、设备等）分析数据细分。对于多段故障，请使用钻孔工具
app_analytics_summary -一般应用程序摘要和分析概述
slipping_users -识别不活跃的应用程序用户
session_frequency -跨时间段的会话频率分布（f=0：第一个会话，f=1:1-24h，f=2:1天，直到f=11:30+天）
user_loyalty -用户忠诚度数据显示忠诚度桶中的会话计数分布（1个会话、2个会话、3-5、6-9、10-19、20-49、50-99、100-499、500+）
session_durations -跨持续时间桶的会话持续时间分布（0-10秒、11-30秒、31-60秒、1-3分钟、3-10分钟、10-30分钟、30-60分钟、1+小时）

事件

events_create -使用元数据和配置定义事件
events_list -列出所有事件及其分段，包括具有精确数据库结构的内部Countly事件
get_events_data -基本事件数据工具。如果提供了事件，则显示每个时间段的事件细分。如果未提供事件，则显示该期间的所有事件总数据。要按分段对事件进行分段，您需要使用钻取工具。

仪表板用户管理

dashboard_users -列出所有仪表板用户（访问Countly仪表板的管理员/管理用户）

应用用户管理

apps_create_user -创建应用程序用户（在应用程序中跟踪最终用户）
apps_delete_user -删除应用程序用户（最终用户）
export_app_users -导出应用程序用户数据（最终用户）

警报和通知

alerts_create -创建警报配置
alerts_delete -删除警报
alerts_list -列出所有警报

备注

notes_list -列出所有仪表板注释
notes_create -创建笔记
notes_delete -删除注释

数据库操作

databases_list -列出可用数据库
databases_query -查询数据库集合
databases_document -获取特定文档
collections_aggregate -运行聚合管道
collections_indexes -查看集合索引
databases_stats -数据库统计

崩溃分析

crash_groups_list -列出应用程序的崩溃组
crashes_stats_get -获取碰撞统计数据和图表
crashes_get -查看碰撞详细信息
crashes_resolve -将碰撞标记为已解决
uncrashes_resolve -将碰撞标记为未解决
crashes_hide -从视图中隐藏碰撞
crashes_show -显示隐藏的崩溃
crashes_comment_add -向crash添加评论
crashes_comment_update -编辑崩溃评论
crashes_comment_delete -删除崩溃评论

钻孔分段（要求 `drill` 插件）

queriable_fields_list -获取可用的细分属性
run_query -使用过滤器和时间段运行钻取查询
drill_bookmarks_list -列出已保存的分段查询
drill_bookmarks_create -保存分段查询
drill_bookmarks_delete -删除已保存的查询

用户配置文件（需要 `users` 插件）

user_profiles_query -使用MongoDB过滤器查询用户
user_profiles_breakdown -按属性细分用户数量
user_profiles_get -按UID获取特定用户详细信息

队列（要求 `cohorts` 插件）

cohorts_list -列出所有具有过滤功能的用户群
cohorts_data -获取一段时间内的队列数据
cohorts_create -基于用户行为创建行为队列
cohorts_update -更新队列配置
cohorts_delete -删除队列

漏斗（需要 `funnels` 插件）

funnels_list -列出所有转换漏斗
funnels_data -通过过滤获取漏斗分析数据
funnels_step_users -获取达到特定步骤的用户
funnels_dropoff_users -让用户在步骤之间退出
funnels_create -使用事件序列创建转化漏斗
funnels_update -更新漏斗配置
funnels_delete -删除漏斗

公式（必需 `formulas` 插件）

formulas_run -使用过滤器和分段对指标（会话、事件、用户）运行数学公式
formulas_list -列出所有已保存的公式
formulas_delete -删除已保存的公式

实时/并发用户（需要 `concurrent_users` 插件）

live_users -获取当前在线用户数和当前新用户数
live_metrics -按国家、设备和运营商获取当前在线用户的细分
live_last_hour -获取过去一小时的逐分钟数据（60个数据点）
live_last_day -获取最后一天的逐小时数据（24个数据点）
live_last_30_days -获取过去30天的每日数据（30个数据点）
live_overall -获取在线用户的最大值（峰值并发使用记录）

保留（要求 `retention_segments` 插件）

retention -获取显示连续事件条纹的保留数据。支持三种类型：完整（严格-第一次跳过时中断）、经典（第N天-独立特定天数）、无限制（宽松-任何返回计数）

远程配置（需要 `remote-config` 插件）

remote_configs_list -列出所有远程配置参数和条件
remote_config_conditions_add -使用MongoDB查询添加用户细分条件
remote_config_conditions_update -更新现有条件标准
remote_config_conditions_delete -删除条件（如果未使用）
remote_config_parameters_add -添加具有默认值和条件值的参数
remote_config_parameters_update -更新参数值、条件或状态
remote_config_parameters_delete -删除参数

A/B测试（要求 `ab-testing` 插件）

ab_experiments_list -列出所有A/B测试实验的状态和结果
ab_experiments_details -获取详细的实验信息，包括变量和统计显著性
ab_experiments_create -使用变体、用户定位和目标创建新的实验
ab_experiments_start -开始实验以开始收集数据
ab_experiments_stop -停止运行实验
ab_experiments_delete -删除实验及其所有数据

记录器（必需 `logger` 插件）

sdk_logs_list -列出SDK发送到服务器进行调试和监控的传入数据日志

SDK（需要 `sdks` 插件）

sdk_stats_get -获取SDK发送数据的统计信息（名称、版本、请求类型、健康检查）
sdk_config_get -获取控制SDK行为和启用功能的SDK配置设置

合规中心（需要 `compliance-hub` 插件）

consents_stats -获取汇总的同意统计数据，显示用户何时给予了哪些同意
consents_list -列出特定用户及其同意状态
consents_history_search -搜索具有详细审计跟踪的同意历史记录

筛选规则（必需 `blocks` 插件）

filtering_rules_list -列出过滤传入请求的所有阻止规则
filtering_rules_create -根据MongoDB条件（IP、版本、设备属性）创建阻止请求的规则
filtering_rules_update -更新现有阻止规则配置
filtering_rules_delete -删除阻止规则

数据点（需要 `server-stats` 插件）

datapoints_stats -根据数据点类型获取每个应用程序收集的数据点。数据点测量收集的数据，并与服务器规格和计费相关联。
datapoints_top_apps -获取按数据点收集排名的顶级应用程序，以了解数据使用和计费情况
datapoints_punch_card -获取显示服务器负载模式的每小时数据点细分穿孔卡，以进行容量规划

服务器日志（需要 `errorlogs` 插件）

server_logs_files_list -列出可用的服务器日志文件（仅在非Docker部署中可用）
server_logs_contents -获取特定服务器日志文件的内容以进行调试和监控（仅在非Docker部署中可用）

电子邮件报告（必填 `reports` 插件）

email_reports_list -列出为应用程序配置的所有电子邮件报告
email_reports_core_create -使用分析、事件、崩溃和星级等指标创建核心电子邮件报告
email_reports_dashboard_create -为特定仪表板创建仪表板电子邮件报告
email_reports_update -更新现有电子邮件报告配置
email_reports_preview -在发送之前预览电子邮件报告，查看其外观
email_reports_send -手动触发立即发送电子邮件报告
email_reports_delete -删除电子邮件报告配置

仪表板（需要 `dashboards` 插件）

dashboards_list -列出所有可用的仪表板（带可选的仅模式参数）
dashboards_data -通过时间段过滤获取特定仪表板的小部件和数据
dashboards_create -使用共享设置、自动刷新配置和主题创建新的仪表板
dashboards_update -更新仪表板配置（名称、共享、刷新率、主题）
dashboards_delete -按ID删除仪表板
dashboards_widget_add -将小部件添加到具有完整配置（标题、功能、小部件类型、应用程序、指标、可视化）的仪表板中
dashboards_update_widget -更新网格布局中的小部件位置和大小
dashboards_widget_remove -从仪表板中删除小部件

一天中的时间（必填 `times-of-day` 插件）

times_of_day -获取特定事件的用户当地时间的行为模式。显示用户在一天（按小时）和一周（按天）中最活跃的时间。有助于了解最佳参与时间和日程安排。

挂钩（需要 `hooks` 插件）

hooks_list -列出为应用程序配置的所有webhooks。显示触发器、效果和配置详细信息。
hooks_test -在创建钩子配置之前，使用模拟数据对其进行测试。这有助于验证触发条件和效果操作。
hooks_create -使用各种触发类型（IncomingDataTrigger、APIEndPointTrigger、InternalEventTrigger、ScheduledTrigger）和效果（HTTPEffect、EmailEffect、CustomCodeEffect）创建新的webhook/hook。
hooks_update -更新现有的webhook/hook配置。
hooks_delete -按ID删除webhook/hook。
hooks_internal_triggers_get -获取可用的内部Countly事件列表，这些事件可用作钩子的触发器（例如，/crash/new、/comporary/enter、/i/apps/create）。

所有工具都支持通过以下方式进行灵活的应用程序识别 app_id 或 app_name 参数。

健康检查

服务器包括一个健康检查端点，位于 /health （仅限HTTP模式）：

curl http://localhost:3000/health

答复：

{
  "status": "healthy",
  "timestamp": "2025-10-10T12:00:00.000Z"
}

服务器发现

服务器提供 .well-known 自动配置的发现端点（仅限HTTP模式）：

curl http://localhost:3000/.well-known/mcp-manifest.json

此清单提供服务器元数据，包括：

服务器名称、版本和描述
支持的MCP协议版本
可用端点（MCP、健康等）
支持的传输（stdio、HTTP/SSE）
服务器功能（工具数量、类别、功能）
认证方法
文档链接
存储库信息

MCP客户端可以使用此端点进行自动服务器发现和功能检测。

MCP端点

在HTTP模式下运行时，MCP协议端点在以下位置可用：

路径: /mcp
运输：服务器发送事件（SSE）
完整URL: http://localhost:3000/mcp

此端点使用SSE传输方法处理所有MCP协议通信。

项目结构

countly-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── docs/                 # Additional documentation
├── .env.example          # Environment configuration template
├── docker-compose.yml    # Docker Compose configuration
├── Dockerfile            # Docker image definition
├── DOCKER.md             # Detailed Docker deployment guide
└── README.md             # This file

发展

观看模式

npm run dev

测试

运行自动化测试：

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run tests for CI
npm run test:ci

测试文件：

看 docs/TEST.md 获取完整的测试指南
看 docs/TESTING_SUMMARY.md 用于测试策略

当前覆盖范围：

身份验证和凭证处理
工具处理程序和参数验证
HTTP客户端配置
传输层（stdio和HTTP/SSE）
端到端服务器连接
错误处理

______________________________________________________________________

从不提交代币 到版本控制
使用Docker秘密 或生产环境变量
限制文件权限 关于令牌文件(chmod 600)
使用HTTPS 用于Countly服务器连接
旋转令牌 定期
使用只读挂载 用于Docker中的令牌文件

故障排除

连接问题

# Test connectivity
curl https://your-countly-instance.com/o/apps/mine?auth_token=your-token

# Check Docker logs
docker logs countly-mcp-server

# Check container health
docker ps

身份验证错误

验证您的令牌，并确保它在Countly中具有适当的权限。

许可证

麻省理工学院

支持

对于问题和疑问：

GitHub问题： countly/countly mcp服务器
社区： https://community.count.ly

CI/CD

本项目使用GitHub Actions进行自动化测试和部署：

自动化测试：对每个pull请求运行并推送到main/develop

- 跨Node.js 18、20和22的测试 - TypeScript编译验证 - 测试覆盖率报告 - 建立烟雾测试

Docker发布：基于版本标记的自动构建(v*.*.*)

- 多架构支持（amd64、arm64） - 自动更新最新标签 - 发布前必须通过测试

看了解详情。

贡献

欢迎投稿！请在提交PR之前阅读我们的投稿指南。

开发工作流程：

分叉存储库
创建要素分支
进行更改并添加测试
跑 npm test 本地
提交拉取请求
GitHub Actions将自动运行测试
处理任何反馈并确保测试通过

Countly MCP Server

快速接入

详细介绍