Umami 分析 MCP 服务器

一个模型上下文协议（MCP）服务器，通过提供来自 Umami 的网站分析数据来增强 Claude 的功能。该服务器允许 Claude 分析用户行为、跟踪网站性能并提供数据驱动的见解。

代码库完全使用 Claude Sonnet 3.5 和 Cursor 生成。

它的功能

此服务器将 Claude 连接到您的 Umami 分析平台，支持：

• 分析用户旅程和行为模式
• 跟踪网站性能指标
• 监控实时访客活动
• 捕获和分析网页内容
• 基于历史分析数据生成见解

工作原理

服务器向 Claude 提供了以下工具以分析网站数据：

可用工具

• get_websites：检索您在 Umami 帐户中的网站及其 ID 列表
• get_website_stats：获取网站的关键指标，如页面浏览量、访客数量及跳出率
• get_website_metrics：分析特定指标，如URL、引荐来源、浏览器和地区
• get_pageview_series：在自定义时间间隔内获取按时间序列的页面浏览数据
• get_active_visitors：监控网站上的当前活跃访客数量
• get_session_ids：检索特定事件或时间段内的会话 ID
• get_tracking_data：获取特定会话 ID 的详细活动数据
• get_docs：对多个用户旅程进行语义搜索，返回与给定问题最相关的部分
• get_screenshot：捕获网页的视觉快照
• get_html：检索和分析网页的HTML源代码

每个工具都有描述及其可传递的参数列表。这些都是用来向 Claude 提供上下文信息以便其有效选择适当的工具及其正确参数。

大多数这些工具从 Umami API 直接拉取数据到 Claude 桌面，但 get_docs 添加了一个语义搜索步骤，以避免 Claude 上下文中窗口的问题且节省令牌用量。使用 Umami API 检索所有给定事件的用户旅程，然后将其分割成更小的部分，并使用 Hugging Face 中的开放源代码句子转换模型进行嵌入。根据问题， retrieval 最相关内容并返回给 Claude，从而分析网站中用户执行的具体操作和行为，这是传统数据可视化软件难以复制的功能。此嵌入和语义搜索的实现位于 src/analytics_service/embeddings.py 文件中。

此外，get_screenshot 和 get_html 工具使用开源的 Crawl4AI Web 爬虫检索给定网站的HTML源代码和截图。必须调整大小截图以减少其尺寸以避免 Claude 上下文中窗口问题。这可以为您提供有关网站结构和外观的上下文，使对提高站点性能的准确和相关推荐更加可能。Web 爬虫的实现位于 src/analytics_service/crawler.py 文件中。

设置指南

先决条件

• 安装 uv: pip install uv

1. Claude 桌面配置

   在您的 Claude 桌面配置文件中添加以下内容：

   • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json
   json 复制代码

   {
     "mcpServers": {
       "analytics_service": {
         "command": "uv",
         "args": [
           "--directory",
           "/path/to/analytics_service",
           "run",
           "analytics-service"
         ],
         "env": {
          "UMAMI_API_URL": "https://example.com",
          "UMAMI_USERNAME": "yourUmamiUsername",
          "UMAMI_PASSWORD": "yourUmamiPassword",
          "UMAMI_TEAM_ID": "yourUmamiTeamId"
        }
       }
     }
   }

   将 /path/to/analytics_service 替换为您自己的 analytics_service 目录的实际路径。

   对于 UMAMI_API_URL, 将 https://example.com 替换为您使用的Umami版本的URL（既可以是自主托管的，也可以是在 Umami Cloud 上托管的）。对于 UMAMI_USERNAME 和 UMAMI_PASSWORD，将其替换为您自己的Umami帐户凭证。对于 UMAMI_TEAM_ID，替换成您想要分析的团队ID。

2. 打开 Claude 桌面

当您打开 Claude 桌面时，它会自动开始连接到 analytics_service MCP 服务器。服务器初始化并安装正确的包可能需要几分钟，当服务器准备就绪时，您将在聊天窗口右侧看到 10 个可用的 MCP 工具。这以一个小锤子图标和旁边数字“10”表示。

此外，如果没有的话，强烈建议在 Claude 桌面的“功能预览”中启用“分析工具”。这将允许 Claude 为您构建控制面板以及其他您数据的可视化。为此，在左侧侧边栏中找到“功能预览”选项卡并在其中启用“分析工具”。LaTeX 渲染同样可以在同一个部分中启用。

如何使用服务器

开始前

最简单的启动方法是使用由服务器提供的“创建仪表板提示”。这是通过点击聊天窗口左下角的“附加至 MCP”按钮选中后，选择实现方式，然后选中的“Create Dashboard Prompt”。

这将引导您通过以下步骤创建用于您站点的仪表盘：

1. 分析目标站点的名称
2. 分析起始和结束日期
3. 网站所在时区

一旦提供了这些信息，服务器将自动生成包含构建仪表盘说明的txt文件。
在文本窗口按下回车,Claude就可继续进行。然后你可以要求Claude对其仪表盘作出任何更改或添加任何其他可视化图表等。

自然语言使用
为了获得更可定制化的体验,您可以直接对Claude说话并指明您自己的要求,例如,您想在仪表盘上查看的数据以及您想选用的可视化样式。此外您可以进行用户旅程的分析以查明具体的痛点,并将来自您站点的截图提供给Claude以提供更多上下文。

完成您的请求所需的必要工具将会被Claude自动选择。只需以自然语言做出请求,Claude便会决定使用哪种工具。如果您想要查看所有可用的工具列表，您可以询问Claude为您提供它们或者单击聊天窗口底部右边的小钉图标的锤子。

创造您自己的提示

您还可以为自己经常使用的流程创建自己自定义的提示模板。
为此,您需要:

1. 为您的提示定义其模板结构
   要包括:

   • name: 是为提示定义一个独一无二的标识符。
   • description: 清楚解释什么提示的功能介绍
   • arguments : 所需输入值的名称和描述

   将其添加到list_prompts()函数 src/analytics_service/server.py:

   示例结构:

   py 复制代码

   @app.list_prompts()
   async def list_prompts():
       return [
           #...原有的提示...
           {
               "name": "您的提示名",
               "description": "提示功能简介",
               "arguments": [
                   {
                       "name": "参数名 1",
                       "description": "参数说明",
                       "required": True/False
                   },
                   {
                       "name": "参数名2",
                       "description": "参数说明",
                       "required": True/False
                   }
               ]
           }
       ]

2. 实现提示模板的逻辑
   在 get_prompt() 函数中实现新的提示逻辑,放在 src/analytics_service/server.py:

@app.get_prompt()
async def get_prompt(name:str, arguments:Any):
    #...现有的提示逻辑 ...
    if name == "提示名字":
        return {
            "messages": [
                {
                    "role": "user",
                    "content": {
                        "type": "text",
                        "text": f"模板文本包括 {arguments['参数名']} 参数值"
                    }
                }
            ]
        }

在定义提示消息时字段 "role"至关重要用于构造对话逻辑：

• 使用` "role":"user" " 表示模拟用户输入或者是提出问题。
• 使用 ` “role ":" assistant “ 表示 Claude 回复或指令。
• 使用 ` "role "：“system " 表示设定情景或者是提供高级别的指示。

在每条消息的 content 字段中需指定消息类型，可用的类型包括：

• "type ":" text " : 普通文本信息
• "type ": " resource"：如包含外部资源的消息比如文件、记录或者其他数据必须包括一个 resource 对象其中包含:
  • uri"：用于标示资源地址。
  • "text": 实际内容
  • "mimeType "：内容类型(例如:" text / plain ", " text / x - python ")。

即使资源的内容包括在 " text “字段中,使用 " resource“类型提供了几个重要的优点：

1. “内容类型认知感"：" mimeType”字段告诉 Claude 如何解析内容 (例如像Python代码,纯文本或其他形式内容)
2. “资源溯源跟踪”： uri 字段保存一个引用到该内容来自于哪里的信息 这一点可能有用用于:
   • 追迹数据资源的来源
   • 如果源发生改变允许更新
   • 提供有关资源的物理位置及其用途上下文内容
     3 " 结构化数据处理”： 资源格式允许对不同种类的结构保持一致的数据处理同时保持每个资源元数据。

以下是展示不同类型的角色和“resource”类型的例子:

"message": [
    {
        "role": "system",
        "content": {
            "type": "text",
            "text": "分析下面日志记录与代码查找潜在的错误。"
        }
    },
    {
        "role": "user",
        "content": {

"type": "resource",
                    "resource": {
                        " uri " : " logs : //recent "
                        " text ": "[2024 - 03 - 10 10:45:03] INFO: Successful connection",
                        "mimeType ": "text/plain"
                }
            }
        },
        {
            " role": " assistant ",
            " content ": {
                " type": " text ",
                " text ": " 我注意到有成功进行一次连结尝试，让我看下相关的代码。 "
            }
        },
        {
            "role": " user ",
            "content": {
                " type": " resource ",
                "resource":
                {
                     "uri":
                     " file : / /code.py ",    
                     "text":{
                          "text":
                           "def example () \n \t \ pass" 

                    },
                    "mimetype": " text / x - python "
               } 

              }
        }

    ]

}



  对于大部分提示来说使用带“user”的 “text” 类型已十分足够并允许 Claude 在回复中掌控且更具创造力。然而对于更加复杂的操作，多角色不同类型的消息将允许进行更加结构化的交流流和更多来自用户的控制。


 制作提示的一些最佳规范包括
  - 提示明确且重点突出
  - 钻研必要参数的验证要求  
      - 参数名为描述清晰明了一些例子可以列入参数叙述里
      - 建立有效的模板格式以指导 Claude
        讲解错误处理及其边缘状况测试提示使用各种输入样本